[taler-docs] branch master updated: spec refresh

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new e47b50f  spec refresh
e47b50f is described below

commit e47b50f56474b296764d45fbf6d96896c4de2d85
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Apr 9 12:02:18 2023 +0200

    spec refresh
---
 Makefile                                           |  4 +-
 .../037-wallet-transactions-lifecycle.rst          | 44 ++++++++++++++++------
 transaction-refresh-states.dot                     | 19 ++++++++++
 3 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/Makefile b/Makefile
index 96ed511..4cd644b 100644
--- a/Makefile
+++ b/Makefile
@@ -61,6 +61,8 @@ transaction-payment-states.png: transaction-payment-states.dot
        dot -Tpng transaction-payment-states.dot > 
transaction-payment-states.png
 transaction-refund-states.png: transaction-refund-states.dot
        dot -Tpng transaction-refund-states.dot > transaction-refund-states.png
+transaction-refresh-states.png: transaction-refresh-states.dot
+       dot -Tpng transaction-refresh-states.dot > 
transaction-refresh-states.png
 coin.png: coin.dot
        dot -Tpng coin.dot > coin.png
 deposit.png: deposit.dot
@@ -68,7 +70,7 @@ deposit.png: deposit.dot
 reserve.png: reserve.dot
        dot -Tpng reserve.dot > reserve.png
 
-diagrams: arch-api.png coin.png deposit.png reserve.png 
transaction-common-states.png transaction-withdrawal-states.png 
transaction-payment-states.png transaction-refund-states.png
+diagrams: arch-api.png coin.png deposit.png reserve.png 
transaction-common-states.png transaction-withdrawal-states.png 
transaction-payment-states.png transaction-refund-states.png 
transaction-refresh-states.png
 
 
 # The html-linked builder does not support caching, so we
diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index 7001e28..bacfff0 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -477,24 +477,46 @@ A refund is a pseudo-transaction that is always 
associated with a merchant payme
 Transaction Type: Refresh
 -------------------------
 
-XXX: If we have to adjust the refund amount (because a coin has fewer funds on
-it than we expect), what is the resulting state of the whole refresh?
-
-CG: first the pending balance is decreased by the reduced amount, and then of
-course the final balance. The coin transaction responsible for the reduction
-in funds is historic (and we don't have details), so that just changes the 
total
-available balance in the wallet, but without an associated history entry (as we
-cannot give details).
+This is about refreshes that are triggered via coin expiration or as part of
+getting change after making a payment.  In the first case, the refresh
+transaction is forever shown as a separate transaction in the history unless
+it did not affect the wallet balance (in which case we hide it). In the second
+case, the refresh transaction is folded into the payment transaction upon
+completion, so that the balance changes are included in the fees of the
+transaction that caused us to obtain change.
+
+If we have to adjust the refund amount (because a coin has fewer funds on it
+than we expect) the transaction only shows the changes due to the refresh, and
+we merely adjust the current balance of the wallet but without giving any
+justification (as we cannot give details we do not have). So this will look
+the same as if the double-spending transaction had been deleted by the user.
 
 * ``pending``
 
+  A refresh operation is pending.
+
   * ``[processed-success] => done``
-  * ``[action:abort] => aborted``: Money that has not been refreshed yet is 
lost.
+  * ``[action:suspend] => suspended``
+
+* ``suspended``
+
+  A refresh operation was suspended by the user.
+
+  * ``[action:resume] => pending``
+  * ``[action:delete] => deleted``
 
 * ``done``
 
-(??) should this be like ``pending(exchange-wait-reserve)`` from withdraw?
-(??) can refresh trigger kyc?
+  The refresh operation completed.
+
+* ``deleted``
+
+  All memory of the refresh operation is lost, but of course the resulting
+  fresh coins are preserved.
+
+.. image:: ../transaction-refresh-states.png
+  :width: 800
+
 
 
 Transaction Type: Tip
diff --git a/transaction-refresh-states.dot b/transaction-refresh-states.dot
new file mode 100644
index 0000000..1296e4b
--- /dev/null
+++ b/transaction-refresh-states.dot
@@ -0,0 +1,19 @@
+digraph G {
+
+  initial[label="", shape="circle"];
+  pending[label="pending"];
+  suspended[label="suspended", shape="box"];
+  done[label="done", shape="box"];
+  deleted[label="deleted", shape="box"];
+
+  initial->pending [color="blue", label="trigger"];
+
+  pending->done;
+  pending->suspended [color="blue", label="suspend"];
+
+  suspended->pending [color="blue", label="resume"];
+  suspended->deleted [color="blue", label="delete"];
+
+  done->deleted [color="blue", label="delete"];
+
+}

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.