taler-docs

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

spec refresh

Diffstat:
M
Makefile
 | 
4
+++-
M
design-documents/037-wallet-transactions-lifecycle.rst
 | 
44
+++++++++++++++++++++++++++++++++-----------
A
transaction-refresh-states.dot
 | 
19
+++++++++++++++++++

3 files changed, 55 insertions(+), 12 deletions(-)
diff --git 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
@@ -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
@@ -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"];
+
+}