From eb726cc8f7b5f5b2fd4e0bdcec727536ae236430 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sun, 9 Apr 2023 14:09:03 +0200
Subject: spec deposit

---
 .../037-wallet-transactions-lifecycle.rst          | 72 +++++++++++++++-------
 1 file changed, 51 insertions(+), 21 deletions(-)

(limited to 'design-documents')

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index f9db090f..1b1da800 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -517,7 +517,7 @@ the same as if the double-spending transaction had been deleted by the user.
   fresh coins are preserved.
 
 .. image:: ../transaction-refresh-states.png
-  :width: 400
+  :width: 250
 
 
 
@@ -602,49 +602,79 @@ Transaction Type: Deposit
 
 * ``initial``
 
-  Deposit is created, effective amount is removed from balance
+  This is the initial state where the user is asked to specify the target bank account and amount to be deposited.
 
-  * ``[processed-success] => pending(submit-deposit)``: reserve created
-  * ``[action:abort] => aborted``
+  * ``[action:form-data] => pending(submit-deposit)``: user supplied deposit request details
 
-* ``pending(submit-deposit)``
+* ``pending(deposit)``
 
-Submit coin by coin (or in bulk groups) until deposit is completed.
+  We deposit the amount coin-by-coin (or in bulk groups) until deposit is completed.
 
-  * ``[action:abort] => aborting(refund)``
+  * ``[action:suspend] => suspended(submit-deposit)``
   * ``[processed-success] => pending(track)``
-  * ``[processed-error] => aborting(refresh)``
+  * ``[processed-failure] => aborting(refund)``
+
+* ``suspended(deposit)``
+
+  The user suspended our ongoing deposit operation.
+
+  * ``[action:resume] => pending(deposit)``
+  * ``[action:abort] => aborting(refund)``
 
 * ``pending(track)``
 
-All the coins were submitted, waiting to be wired.
+  All the coins were submitted, waiting to be wired.
 
   * ``[poll-success] => done``
-  * ``[action:abort] => aborting(partially-wired)``
+  * ``[action:abort] => aborting(refund)``
 
 * ``aborting(refund)``
 
-Trying to get the deposited amount back from the exchange.
+  Wallet should try to get the deposited amount back from the exchange (by submitting a refund).
 
-  ``[processed-success] => aborting(refresh)``
-  ``[processed-error] => aborting(refresh)`` XXX Shouldn't this be some error state?
-(??) why it moves to the same state?
+  * ``[action:suspend] => suspended(refund)``
+  * ``[processed-success] => aborting(refresh)``
+  * ``[processed-error] => aborting(refresh)``: Even if the refund attempt failed, maybe the deposit failed as well and we can still succeed with a refresh.
 
-* ``aborting(partially-wired)``
+* ``suspended(refund)``
 
-Should cancel all pending wire transfer.
-
-  ``[processed-success] => aborting(refund)``
-  ``[processed-error] => aborting(refresh)`` XXX Shouldn't this be some error state?
+  The user suspended us while we were trying to get a refund.
 
+  * ``[action:resume] => aborting(refund)``
+  * ``[action:delete] => deleted``
 
 * ``aborting(refresh)``
 
-  ``[processed-success] => aborted``
-  ``[processed-error] => failed``
+  * ``[action:suspend] => suspended(refresh)``
+  * ``[processed-success] => aborted``
+  * ``[processed-error] => failed``
+
+* ``suspended(refresh)``
+
+  The user suspended us while we were trying to do the refresh.
+
+  * ``[action:resume] => aborting(refresh)``
+  * ``[action:delete] => deleted``
+
+* ``aborted``
+
+  The operation was aborted, some funds may have been lost (to fees or deposited anyway).
+
+  * ``[action:delete] => deleted``
 
 * ``done``
 
+  The deposit operation completed.
+
+  * ``[action:delete] => deleted``
+
+* ``deleted``
+
+  All memory of the deposit operation is lost.
+
+.. image:: ../transaction-deposit-states.png
+  :width: 400
+
 
 Transaction Type: Peer Push Debit
 ---------------------------------
-- 
cgit v1.2.3