major fixes to withdrawal state diagram

1 files changed, 75 insertions, 20 deletions

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index df132ac4..e2a04820 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -152,56 +152,108 @@ Part of a withdrawal process or peer-to-peer push credit.
 Transaction Type: Withdrawal
 ----------------------------
 
-* ``initial(bank-register-reserve)``
+* ``pending(bank-register-reserve)``
 
   Initial state for bank-integrated withdrawals.  The wallet submits the reserve public key
-  and selected exchange to the bank (via the bank integration API).
+  and selected exchange to the bank (via the bank integration API).  Note that if the
+  user aborts at this stage, we do not know if the bank is in the confirmation stage,
+  so we must still *try* to abort the transaction at the bank.
 
   * ``[processed-success] => pending(bank-confirming)``
-  * ``[processed-error(bank-aborted)] => aborted(bank-to-wallet)``
+  * ``[processed-error] => aborted(bank-to-wallet)``
+  * ``[action:abort] => aborting(bank-to-wallet)``
 
 * ``pending(bank-confirming)``
 
-  The wallet waits until the bank has confirmed the withdrawal operation; usually
-  the user has to complete a 2FA step to confirm that the money is wired to the chosen
-  exchange.
-
-  (??) is this needed? let say that the money is wired but the signal
-  never of the bank confirmation reached the wallet, what should happen?
-
-  * ``[poll-success] => pending(exchange-wait-reserve)``
+  The wallet waits until the bank has confirmed the withdrawal operation;
+  usually the user has to complete a 2FA step to *approve* that the money is
+  wired to the chosen exchange.  Note that the user's *approve* action is done
+  in the bank's user interface and not the wallet's user interface. The wallet
+  internally merely *polls* for the success or failure of the approve action.
+  The wallet **may** occasionally (after some initial delay, especially on
+  failures from the bank-poll to return any result) long-poll for the reserve
+  status and, if successful, may then directly jump to
+  ``pending(withdrawing-coins)`` if the reserve is filled even if the poll at
+  the bank did not return success or failure.
+
+  * ``[bank-poll-success] => pending(exchange-wait-reserve)``
+  * ``[bank-poll-denied] => aborted(wallet-to-bank)``
+  * ``[exchange-poll-success] => pending(withdrawing-coins)``
   * ``[action:abort] => aborting(wallet-to-bank)``
 
-* ``initial(manual-withdraw)``
-
-  * ``[process-success] => pending(exchange-wait-reserve)``: reserve created
-
 * ``pending(exchange-wait-reserve)``
 
-  Initial state for manual withdrawals.
+  Initial state for manual withdrawals.  Here, the wallet long-polls the
+  exchange for the reserve status, waiting for the wire transfer to arrive
+  at the exchange.
 
-  * ``[poll-success] => pending(withdrawing-coins)``
+  * ``[exchange-poll-success] => pending(withdrawing-coins)``
+  * ``[action:abort] => aborted(after-wired)``
 
 * ``pending(withdrawing-coins)``
 
+  State where we are finally withdrawing the actual coins. Depending on
+  the AML and KYC thresholds, we may at any time transition into a
+  holding pattern on the AML or KYC checks of the exchange.
+
   * ``[processed-success] => done``
   * ``[processed-kyc-required] => pending(kyc-required)``
+  * ``[processed-aml-required] => pending(aml-required)``
+  * ``[action:abort] => aborted(partially-withdrawn)``
 
 * ``pending(kyc-required)``
 
+  State where the user needs to provide some identity data to pass a KYC
+  check.  The wallet only shows the user the link for starting the KYC
+  process and long-polls the exchange in anticipation of the user
+  completing the KYC requirement.
+
+  * ``[poll-success] => pending(withdrawing-coins)``
+  * ``[action:abort] => aborted(partially-withdrawn)``
+
+* ``pending(aml-required)``
+
+  State where the wallet needs to wait for completion of an AML process
+  by an AML officer of the exchange. The wallet shows that the AML process
+  is pending at the exchange and long-polls for it to complete. The user
+  is urged to simply wait.
+
   * ``[poll-success] => pending(withdrawing-coins)``
+  * ``[action:abort] => aborted(partially-withdrawn)``
+
+* ``pending(aml-frozen)``
+
+  State where the wallet informs the user that their funds were frozen
+  due to an AML decision.  The user is urged to contact the exchange
+  operator's AML department out-of-band.  The wallet long-polls in
+  anticipation of the account being unfrozen.
+
+  * ``[poll-success] => pending(withdrawing-coins)``
+  * ``[action:abort] => aborted(partially-withdrawn)``
 
 * ``aborting(wallet-to-bank)``
 
+  The user aborted the withdraw operation in the wallet.
+  The wallet must now try to signal the bank that the wire
+  transfer should no longer be performed.  Note that it
+  is possible that the bank registration never succeeded
+  (if the user aborted us during ``pending(bank-register-service)``)
+  and in this case we get an ``unknown transaction`` failure here.
+  It is also theoretically possible that the user approved the
+  transaction in the bank while simultaneously aborting in the
+  wallet. In this case, we transition to ``aborted(after-wired)``.
+
   * ``[processed-success] => aborted(wallet-to-bank)``
   * ``[processed-error(already-confirmed)] => aborted(after-wired)``
-
-* ``aborted(bank-to-wallet)``: The bank notified the wallet that the withdrawal
-  was aborted on the side of the bank and won't proceed.
+  * ``[processed-error(unknown-transaction)] => aborted(bank-to-wallet)``
 
 * ``aborted(wallet-to-bank)``: The wallet notified the bank that the withdrawal
   should be aborted, before any money was wired.
 
+* ``aborted(bank-to-wallet)``: The bank notified the wallet that the withdrawal
+  was denied on the side of the bank (or the request never succeeded in the
+  first place) and won't proceed.
+
 * ``aborted(after-wired)``:
 
   In this state, the wallet should show to the user that the money from the withdrawal
@@ -227,6 +279,9 @@ Transaction Type: Withdrawal
 .. image:: ../transaction-withdrawal-states.png
   :width: 800
 
+Transitions relating to deletion, suspending and resuming are not
+shown in the above diagram to keep it on point.
+
 
 Transaction Type: Payment to Merchant
 -------------------------------------