[taler-docs] branch master updated: major fixes to withdrawal state diagram

[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 343f392  major fixes to withdrawal state diagram
343f392 is described below

commit 343f392149caadaf8e4209863364a61672f5c876
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Apr 8 20:44:13 2023 +0200

    major fixes to withdrawal state diagram
---
 .../037-wallet-transactions-lifecycle.rst          | 95 +++++++++++++++++-----
 transaction-withdrawal-states.dot                  | 17 ++--
 2 files changed, 87 insertions(+), 25 deletions(-)

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index df132ac..e2a0482 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
 -------------------------------------
diff --git a/transaction-withdrawal-states.dot 
b/transaction-withdrawal-states.dot
index 04d8778..18a80ea 100644
--- a/transaction-withdrawal-states.dot
+++ b/transaction-withdrawal-states.dot
@@ -23,11 +23,12 @@ digraph G {
     rank = same; aborted_b2w; aborted_w2b; aborted_aw; aborted_pw;
   }
 
-  initial->pending_brr [label="bank integrated withdraw"];
-  initial->pending_ewr [label="manual withdraw"];
+  initial->pending_brr [color="blue", label="bank integrated withdraw"];
+  initial->pending_ewr [color="blue", xlabel="manual withdraw"];
   pending_brr->pending_bc;
-  pending_bc->pending_ewr;
-  pending_ewr->pending_wc;
+  pending_bc->pending_ewr [label="bank-poll:\napproved"];
+  pending_bc->pending_wc [xlabel="exchange-poll:\nreserve 
ready",style="dotted"];
+  pending_ewr->pending_wc [label="exchange-poll:\nreserve ready"];
   pending_wc->pending_kyc;
   pending_wc->pending_aml;
   pending_kyc->pending_wc [color="blue",label="kyc"];
@@ -37,9 +38,15 @@ digraph G {
   pending_kyc->aborted_pw [color="blue", label="abort"];
   pending_aml->aborted_pw [color="blue", label="abort"];
   pending_frz->aborted_pw [color="blue", label="abort"];
-  pending_brr->aborted_b2w [color="blue", label="abort"];
+
+  pending_brr->aborting_w2b [color="blue", label="abort"];
+  pending_brr->aborted_b2w [color="red", label="error"];
+
   pending_bc->aborting_w2b [color="blue", label="abort"];
+  pending_bc->aborted_b2w [label="bank-poll:\ndenied"];
   aborting_w2b->aborted_w2b;
+  aborting_w2b->aborted_aw [color="red", label="error(already-confirmed)"];
+  aborting_w2b->aborted_b2w [color="red", label="error(unknown-transaction)"];
   pending_ewr->aborted_aw [color="blue", label="abort"];
   pending_wc->aborted_pw [color="blue", label="abort"];
 

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