[taler-docs] branch master updated: [DD 037] Added age-withdraw to the state diagram

[gnunet]

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

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 73c10807 [DD 037] Added age-withdraw to the state diagram
73c10807 is described below

commit 73c10807b6c64cfc9cefa7d1cd44374e6ee148cc
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Thu Oct 12 11:57:06 2023 +0200

    [DD 037] Added age-withdraw to the state diagram
---
 .../037-wallet-transactions-lifecycle.rst          | 52 +++++++++++++++-------
 images/transaction-withdrawal-states.dot           |  7 ++-
 2 files changed, 41 insertions(+), 18 deletions(-)

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index 9d749595..b10d74ab 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -194,12 +194,14 @@ Transaction Type: Withdrawal
   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(withdraw-coins)`` if the reserve is filled even if the poll at
-  the bank did not return success or failure.
+  ``pending(withdraw-coins:*)`` if the reserve is filled even if the poll at
+  the bank did not return success or failure (there are two variants of
+  withdraw, see below).
+
 
   * ``[bank-poll-success] => pending(exchange-wait-reserve)``
   * ``[bank-aborted] => aborted``: Bank denied the operation.
-  * ``[exchange-poll-success] => pending(withdraw-coins)``:  Optional
+  * ``[exchange-poll-success] => pending(withdraw-coins:*)``:  Optional
     short-cut transition. Exchange was faster than the bank.
   * ``[action:abort] => aborting(bank)``
 
@@ -212,8 +214,8 @@ Transaction Type: Withdrawal
   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
-  ``suspended(exchange-wait-reserve)`` (treating the ``abort`` action as a 
``suspend``
-  action).
+  ``suspended(exchange-wait-reserve)`` (treating the ``abort`` action as a
+  ``suspend`` action).
 
   * ``[processed-success] => aborted``
   * ``[processed-error(already-confirmed)] => 
suspended(exchange-wait-reserve)``: We
@@ -240,23 +242,40 @@ Transaction Type: Withdrawal
   exchange for the reserve status, waiting for the wire transfer to arrive
   at the exchange.
 
-  * ``[exchange-poll-success] => pending(withdraw-coins)``
+  * ``[exchange-poll-success] => pending(withdraw-coins:*)``
   * ``[action:suspend] => suspended(exchange-wait-reserve)``
 
-* ``pending(withdraw-coins)``
+  
+
+* ``pending(withdraw-coins:{batch|age}-withdraw)``
 
-  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.
+  State where we are finally withdrawing the actual coins.  The state is in one
+  of two variants: ``:batch-withdraw`` or ``:age-withdraw``.  The later is
+  required when the reserve has a date of birth (resulting a KYC process) that
+  is below the threshold of the largest allowed age and the wallet has to proof
+  to the exchange that appropriate age-restrictions have been applied to the
+  planchets.  Note that ``age-withdraw`` is a protocoll consisting of two
+  phases: a commitment and a reveal phase.
+  
+  From state ``exchange-wait-reserve`` the wallet can transition into either
+  withdraw-variant.  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.  However, transitions from ``withdraw-coins:*`` to ``kyc`` and
+  ``aml`` can only return to the previous withdraw-variant.
+
+  In the state ``:batch-withdraw``, the withdraw can fail because the reserve
+  has a date of birth and therefore the wallet is required to execute the
+  ``age-withdraw`` protocol.
 
   It is possible that the selected denominations expired.
   In that case, the wallet will re-select denominations.
 
+  * ``[age-withdraw-required] => pending(withdraw-coins:age-withdraw)``
   * ``[processed-success] => done``
   * ``[processed-kyc-required] => pending(kyc)``
   * ``[processed-aml-required] => pending(aml)``
   * ``[reserve-expired] => expired(reserve)``
-  * ``[action:suspend] => suspended(withdraw-coins)``
+  * ``[action:suspend] => suspended(withdraw-coins:*)``
 
 * ``pending(kyc)``
 
@@ -265,7 +284,7 @@ Transaction Type: Withdrawal
   process and long-polls the exchange in anticipation of the user
   completing the KYC requirement.
 
-  * ``[poll-success] => pending(withdraw-coins)``
+  * ``[poll-success] => pending(withdraw-coins:*)``
   * ``[action:suspend] => suspended(kyc)``
 
 * ``suspended(kyc)``
@@ -290,7 +309,7 @@ Transaction Type: Withdrawal
   In any case, the wallet long-polls for the AML decision to be made or change
   (possibly at a lower frequeny in case of a freeze).
 
-  * ``[poll-success] => pending(withdraw-coins)``
+  * ``[poll-success] => pending(withdraw-coins:*)``
   * ``[action:suspend] => suspended(aml)``
 
 * ``suspended(aml)``
@@ -310,8 +329,8 @@ Transaction Type: Withdrawal
 
   * ``[action:delete] => deleted``
   * ``[action:resume] => pending(exchange-wait-reserve)``
-
-* ``done``
+    
+* ``withdraw-done``
 
   The withdrawal operation is complete.
 
@@ -323,8 +342,7 @@ Transaction Type: Withdrawal
   So this mostly removes the entry from the visible transaction history.
   Only once all coins were spent, the withdraw is fully removed.
 
-
-.. image:: ../images/transaction-withdrawal-states.png
+.. graphviz:: ../images/transaction-withdrawal-states.dot
 
 
 Transaction Type: Payment to Merchant
diff --git a/images/transaction-withdrawal-states.dot 
b/images/transaction-withdrawal-states.dot
index 9163c889..ea32c5ba 100644
--- a/images/transaction-withdrawal-states.dot
+++ b/images/transaction-withdrawal-states.dot
@@ -1,10 +1,11 @@
 digraph G {
+  compound=true;
   initial_manual[label="", xlabel="manual" shape="circle"];
   initial_bank[label="", xlabel="bank-integrated" shape="circle"];
   pending_brr[label="bank-register-reserve"];
   pending_bc[label="bank-confirm"];
   pending_ewr[label="exchange-wait-reserve"];
-  pending_wc[label="withdraw-coins"];
+  pending_wc[label="{<batch>batch-|<age>age-}|<wc>withdraw-coins", 
shape="Mrecord" ];
   pending_kyc[label="kyc"];
   pending_aml[label="aml"];
   done[label="done", shape="box"];
@@ -24,6 +25,10 @@ digraph G {
     rank = same; done; aborted_bank;
   }
 
+  subgraph {
+    pending_wc:batch:w->pending_wc:age:w[color="red"];
+  }
+
   initial_bank->pending_brr;
   initial_manual->pending_ewr;
   pending_brr->pending_bc [color="green"];

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