From 73c10807b6c64cfc9cefa7d1cd44374e6ee148cc Mon Sep 17 00:00:00 2001 From: Özgür Kesim Date: Thu, 12 Oct 2023 11:57:06 +0200 Subject: [DD 037] Added age-withdraw to the state diagram --- .../037-wallet-transactions-lifecycle.rst | 52 +++++++++++++++------- 1 file changed, 35 insertions(+), 17 deletions(-) (limited to 'design-documents') 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 -- cgit v1.2.3