[taler-docs] branch master updated: more spec work on dd37

[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 eaa7265  more spec work on dd37
eaa7265 is described below

commit eaa726572e42adc623190f4922d0bd0d6363b5b9
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Apr 9 11:43:11 2023 +0200

    more spec work on dd37
---
 Makefile                                           |   4 +-
 .../037-wallet-transactions-lifecycle.rst          | 175 +++++++++++++--------
 transaction-payment-states.dot                     |  16 +-
 transaction-refund-states.dot                      |  51 ++++++
 transaction-withdrawal-states.dot                  |  60 ++++---
 5 files changed, 208 insertions(+), 98 deletions(-)

diff --git a/Makefile b/Makefile
index b3e04e2..96ed511 100644
--- a/Makefile
+++ b/Makefile
@@ -59,6 +59,8 @@ transaction-withdrawal-states.png: 
transaction-withdrawal-states.dot
        dot -Tpng transaction-withdrawal-states.dot > 
transaction-withdrawal-states.png
 transaction-payment-states.png: transaction-payment-states.dot
        dot -Tpng transaction-payment-states.dot > 
transaction-payment-states.png
+transaction-refund-states.png: transaction-refund-states.dot
+       dot -Tpng transaction-refund-states.dot > transaction-refund-states.png
 coin.png: coin.dot
        dot -Tpng coin.dot > coin.png
 deposit.png: deposit.dot
@@ -66,7 +68,7 @@ deposit.png: deposit.dot
 reserve.png: reserve.dot
        dot -Tpng reserve.dot > reserve.png
 
-diagrams: arch-api.png coin.png deposit.png reserve.png 
transaction-common-states.png transaction-withdrawal-states.png 
transaction-payment-states.png
+diagrams: arch-api.png coin.png deposit.png reserve.png 
transaction-common-states.png transaction-withdrawal-states.png 
transaction-payment-states.png transaction-refund-states.png
 
 
 # The html-linked builder does not support caching, so we
diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index 366079a..7001e28 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -160,7 +160,7 @@ Transaction Type: Withdrawal
   so we must still *try* to abort the transaction at the bank.
 
   * ``[processed-success] => pending(bank-confirming)``
-  * ``[processed-error] => aborted(bank-to-wallet)``
+  * ``[processed-error] => deleted``: We show a transient warning.
   * ``[action:abort] => aborting(bank-to-wallet)``
 
 * ``pending(bank-confirming)``
@@ -177,10 +177,35 @@ Transaction Type: Withdrawal
   the bank did not return success or failure.
 
   * ``[bank-poll-success] => pending(exchange-wait-reserve)``
-  * ``[bank-poll-denied] => aborted(wallet-to-bank)``
+  * ``[bank-poll-denied] => deleted``: We show a transient message that the 
operation was denied in the bank.
   * ``[exchange-poll-success] => pending(withdrawing-coins)``
   * ``[action:abort] => aborting(wallet-to-bank)``
 
+* ``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
+  ``suspended(after-wired)`` (treating the ``abort`` action as a ``suspend``
+  action).
+
+  * ``[processed-success] => deleted``: We show a transient message that the 
operation was aborted.
+  * ``[processed-error(already-confirmed)] => suspended(after-wired)``: We 
keep a transaction history entry reminding the user about when the already 
wired funds will be returned.
+  * ``[processed-error(unknown-transaction)] => deleted``
+
+* ``suspended(after-wired)``
+
+  In this state, the wallet should show to the user that the money from the 
withdrawal
+  reserve will be sent back to the originating bank account after 
``$closing_delay``.
+  Note that the ``resume`` action should be disabled after ``$closing_delay``.
+
+  * ``[action:delete] => deleted``
+  * ``[action:resume] => pending(exchange-wait-reserve)``
+
 * ``pending(exchange-wait-reserve)``
 
   Initial state for manual withdrawals.  Here, the wallet long-polls the
@@ -188,7 +213,15 @@ Transaction Type: Withdrawal
   at the exchange.
 
   * ``[exchange-poll-success] => pending(withdrawing-coins)``
-  * ``[action:abort] => aborted(after-wired)``
+  * ``[action:suspend] => suspended(after-wired)``
+
+* ``suspended(after-wired)``
+
+  State where funds were (presumably) wired to the exchange but the wallet
+  was asked to not proceed with the withdraw, but we still resume.
+
+  * ``[action:resume] => pending(exchange-wait-reserves)``
+  * ``[action:delete] => deleted``
 
 * ``pending(withdrawing-coins)``
 
@@ -197,11 +230,11 @@ Transaction Type: Withdrawal
   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)``
+  * ``[processed-kyc-required] => pending(kyc)``
+  * ``[processed-aml-required] => pending(aml)``
+  * ``[action:suspend] => suspended(withdrawing-coins)``
 
-* ``pending(kyc-required)``
+* ``pending(kyc)``
 
   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
@@ -209,64 +242,55 @@ Transaction Type: Withdrawal
   completing the KYC requirement.
 
   * ``[poll-success] => pending(withdrawing-coins)``
-  * ``[action:abort] => aborted(partially-withdrawn)``
+  * ``[action:suspend] => suspended(kyc)``
 
-* ``pending(aml-required)``
+* ``suspended(kyc)``
 
-  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.
+  State where the user needs to provide some identity data to pass a KYC
+  check, but the long-polling was explicitly stopped. The user can
+  choose to resume or delete.
 
-  * ``[poll-success] => pending(withdrawing-coins)``
-  * ``[action:abort] => aborted(partially-withdrawn)``
+  * ``[action:delete] => deleted``
+  * ``[action:resume] => pending(kyc)``
 
-* ``pending(aml-frozen)``
+* ``pending(aml)``
 
-  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.
+  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
+  blocking progress. The message shown should distinguish between a mere
+  pending AML process and an AML freezing decision in terms of the message
+  shown to the user. If the AML decision is pending at the exchange, he user
+  should be urged to simply wait.  If the funds were frozen, 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.
+  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(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)``
-  * ``[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.
+  * ``[action:suspend] => suspended(aml)``
 
-* ``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.
+* ``suspended(aml)``
 
-* ``aborted(after-wired)``:
+  State where the user needs to await some AML decision by the exchange.
+  The long-polling was explicitly stopped. The user can choose to resume or 
delete.
 
-  In this state, the wallet should show to the user that the money from the 
withdrawal
-  reserve will be sent back to the originating bank account after 
``$closing_delay``.
+  * ``[action:delete] => deleted``
+  * ``[action:resume] => pending(aml)``
 
-* ``aborted(partially-withdrawn)``:
+* ``suspended(withdrawing-coins)``
 
   In this state, the wallet should show how much money arrived into the wallet
   and the rest of the money will be sent back to the originating bank account
-  after ``$closing_delay``.
+  after ``$closing_delay``.  Note that the ``resume`` action should be
+  disabled after ``$closing_delay``.
+
+  * ``[action:delete] => deleted``
+  * ``[action:resume] => pending(exchange-wait-reserve)``
 
 * ``done``
 
+  The withdrawal operation is complete.
+
   * ``[action:delete] => deleted``
 
 * ``deleted``
@@ -279,16 +303,13 @@ 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
 -------------------------------------
 
 * ``pending(claim-proposal)``
 
-  Initial state. Download (claim) the proposal from the merchant.  Can fail if
+  We received a ``pay`` URI. Download (claim) the proposal from the merchant.  
Can fail if
   the proposal was already claimed by someone else.  If repurchase detection
   tells us that we already paid for this product, we go immediately to
   ``delete`` state for this transaction, but with a side-effect of
@@ -380,7 +401,6 @@ Transaction Type: Payment to Merchant
   The purchase is completed.
 
   * ``[action:delete] => deleted``
-  * ``[refund URI trigger] => aborting(refund)`` -- A refund was initiated for 
the purchase.
   * ``[repurchase] => pending(repurchase-session-reset)`` -- Another offer 
became pending for this product.
 
 * ``pending(repurchase-session-reset)``
@@ -407,29 +427,52 @@ Transaction Type: Refund
 
 A refund is a pseudo-transaction that is always associated with a merchant 
payment transaction.
 
-* ``initial``
+* ``pending(lookup-refund)``
 
-  The wallet has downloaded metadata for the refund from the merchant and
-  stored it in the database.  The user needs to accept/refuse it.
+  We received a ``refund`` URI. Download refund details (like the amount) from 
the merchant.  If the merchant responds with a permanent failure, we only show 
a transient warning and delete the transaction.
 
-  * ``[processed-success] => pending``: the refund is accepted
-  * ``[processed-abort] => aborted`` : the refund is not accepted
+  * ``[success] => pending(user-accept)``
+  * ``[action:suspend] => suspended(lookup-refund)``
+  * ``[failure] => deleted``
 
-* ``pending``
+* ``suspended(lookup-refund)``
+
+  The user suspended while we were looking up the refund details. Allow 
resuming or permanent deletion.
 
-  A refund is pending when the merchant is getting a non-permanent error from
-  the exchange (and relaying that error response to the wallet).
+  * ``[action:resume] => pending(lookup-refund)``
+  * ``[action:delete] => deleted``
+
+* ``pending(user-accept)``
+
+  The wallet has downloaded metadata for the refund from the merchant and 
stored it in the database.  The user needs to accept/refuse it.
+
+  * ``[action:accept] => pending(merchant)``: the refund is accepted
+  * ``[action:delete] => deleted`` : the refund is not accepted
+
+* ``pending(merchant)``
+
+  A refund is pending in this state while we are waiting for the merchant to 
get a successful response from the exchange (and relaying that error response 
to the wallet).
+
+  * ``[action:suspend] => suspended(merchant)``
+  * ``[processed-success] => pending(refresh)``
+  * ``[processed-error] => failed``: we received a permanent failure (such as 
money already wired to the merchant)
+
+* ``pending(refresh)``
+
+  The wallet is now refreshing the coins.
 
   * ``[processed-success] => done``
-  * ``[processed-error] => failed``
+  * ``[action:suspend] => suspended(refresh)``
+  * ``[processed-error] => failed``: we received a permanent failure.
+
 
 * ``failed``
 
-  A failed refund can technically still transition to ``done``, because the 
wallet
-  doesn't query some refund resource, but the purchase for refunds.  Thus, a 
previously
-  failed refund can suddenly transition to ``done``.
+  The refund failed permanently.
+
+.. image:: ../transaction-refund-states.png
+  :width: 800
 
-  (??) separate transient error vs permanent error ?
 
 Transaction Type: Refresh
 -------------------------
diff --git a/transaction-payment-states.dot b/transaction-payment-states.dot
index 066fb02..9dbecae 100644
--- a/transaction-payment-states.dot
+++ b/transaction-payment-states.dot
@@ -23,22 +23,20 @@ digraph G {
   pending_dp->deleted [label="repurchase\ndetected"];
   pending_dp->deleted [color="red", label="already\nclaimed"];
   pending_dp->deleted [color="red", label="invalid\nproposal"];
-  pending_pr->pending_sp [color="blue", label="action:pay-accept"];
-  pending_pr->aborting_unclaim [color="blue", label="action:pay-refuse"];
+  pending_pr->pending_sp [color="blue", label="pay-accept"];
+  pending_pr->aborting_unclaim [color="blue", label="pay-refuse"];
   pending_pr->deleted [label="expired"];
   pending_sp->pending_rf;
-  pending_sp->aborting_refund [color="blue", label="action:abort"];  
pending_sp->aborting_refund [color="red", label="insufficient balance"];
+  pending_sp->aborting_refund [color="blue", label="abort"];  
pending_sp->aborting_refund [color="red", label="insufficient balance"];
   pending_rf->aborting_refund [label="long-poll:refund"];
-  done->aborting_refund [color="purple", xlabel="refund URI trigger"];
-  aborted_refund->aborting_refund [color="purple", label="refund URI trigger"];
   aborting_refund->aborting_refresh;
   aborting_refund->aborted_refund [color="red", label="failure"];
   aborting_refresh->aborted_refund;
-  aborted_refund->deleted [color="blue", label="action:delete"];
+  aborted_refund->deleted [color="blue", label="delete"];
   pending_rf->done [label="timeout"];
-  pending_rf->done [color="blue", label="action:abort"];
+  pending_rf->done [color="blue", label="abort"];
   aborting_unclaim->deleted;
-  done->deleted [color="blue", xlabel="action:delete"];
+  done->deleted [color="blue", xlabel="delete"];
   done->pending_re [color="purple", label="repurchase"];
-  pending_re->done [color="blue", label="action:abort"];
+  pending_re->done [color="blue", label="abort"];
 }
diff --git a/transaction-refund-states.dot b/transaction-refund-states.dot
new file mode 100644
index 0000000..0becc9c
--- /dev/null
+++ b/transaction-refund-states.dot
@@ -0,0 +1,51 @@
+digraph G {
+
+  initial[label="", shape="circle"];
+  pending_in[label="pending(lookup-refund)"];
+  pending_ar[label="pending(user-accept)"];
+  pending_me[label="pending(merchant)"];
+  pending_re[label="pending(refresh)"];
+  suspended_in[label="suspended(lookup-refund)"];
+  suspended_me[label="suspended(merchant)"];
+  suspended_re[label="suspended(refresh)"];
+  done[label="done", shape="box"];
+  deleted[label="deleted", shape="box"];
+  failed[label="failed", shape="box"];
+
+  subgraph {
+    rank = same; pending_in; pending_ar; pending_me; pending_re;
+  }
+  subgraph {
+    rank = same; suspended_in; suspended_me; suspended_re; done;
+  }
+
+  initial->pending_in [color="blue", label="URI trigger"];
+
+  pending_in->pending_ar;
+  pending_in->suspended_in [color="blue", label="suspend"];
+
+  suspended_in->pending_in [color="blue", label="resume"];
+  suspended_in->deleted [color="blue", label="delete"];
+
+  pending_ar->pending_me [color="blue", label="accept"];
+  pending_ar->deleted [color="blue", label="delete"];
+
+  pending_me->pending_re;
+  pending_me->suspended_me [color="blue", label="suspend"];
+  pending_me->failed [color="red", label="failure"];
+
+  suspended_me->pending_me [color="blue", label="resume"];
+  suspended_me->deleted [color="blue", label="delete"];
+
+  pending_re->suspended_re [color="blue", label="suspend"];
+  pending_re->done;
+  pending_re->failed [color="red", label="failure"];
+
+  suspended_re->pending_re [color="blue", label="resume"];
+  suspended_re->deleted [color="blue", label="delete"];
+
+  done->deleted [color="blue", label="delete"];
+
+  failed->deleted [color="blue", label="delete"];
+
+}
diff --git a/transaction-withdrawal-states.dot 
b/transaction-withdrawal-states.dot
index 18a80ea..adfa61d 100644
--- a/transaction-withdrawal-states.dot
+++ b/transaction-withdrawal-states.dot
@@ -1,54 +1,70 @@
 digraph G {
 
   initial[label="", shape="circle"];
+  suspended_wc[label="suspended(withdrawing-coins)", shape="box"];
   pending_brr[label="pending(bank-register-reserve)"];
   pending_bc[label="pending(bank-confirming)"];
   pending_ewr[label="pending(exchange-wait-reserve)"];
   pending_wc[label="pending(withdrawing-coins)"];
-  pending_kyc[label="pending(kyc-required)"];
-  pending_aml[label="pending(aml-required)"];
-  pending_frz[label="pending(aml-frozen)"];
+  pending_kyc[label="pending(kyc)", shape="box"];
+  pending_aml[label="pending(aml)"];
   done[label="done", shape="box"];
-  aborted_b2w[label="aborted(bank-to-wallet)", shape="box"];
-  aborted_w2b[label="aborted(wallet-to-bank)", shape="box"];
-  aborted_aw[label="aborted(after-wired)", shape="box"];
-  aborted_pw[label="aborted(partially-withdrawn)", shape="box"];
+  suspended_aw[label="suspended(after-wired)", shape="box"];
+  suspended_aml[label="suspended(aml)", shape="box"];
+  suspended_kyc[label="suspended(kyc)", shape="box"];
   aborting_w2b[label="aborting(wallet-to-bank)"];
+  deleted[label="deleted", shape="box"];
 
   subgraph {
     rank = same; pending_brr; pending_bc; pending_ewr; pending_wc; done;
   }
 
   subgraph {
-    rank = same; aborted_b2w; aborted_w2b; aborted_aw; aborted_pw;
+    rank = same; suspended_wc; suspended_aw; suspended_aml; suspended_kyc;
+  }
+
+  subgraph {
+    rank = same; aborting_w2b; pending_aml; pending_kyc;
   }
 
   initial->pending_brr [color="blue", label="bank integrated withdraw"];
   initial->pending_ewr [color="blue", xlabel="manual withdraw"];
   pending_brr->pending_bc;
+  pending_brr->aborting_w2b [color="blue", label="abort"];
+  pending_brr->deleted [color="red", label="error"];
+
   pending_bc->pending_ewr [label="bank-poll:\napproved"];
   pending_bc->pending_wc [xlabel="exchange-poll:\nreserve 
ready",style="dotted"];
+  pending_bc->aborting_w2b [color="blue", label="abort"];
+  pending_bc->deleted [label="bank-poll:\ndenied"];
+
   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"];
   pending_aml->pending_wc [color="purple",label="approve"];
-  pending_aml->pending_frz [color="purple",label="freeze"];
-  pending_frz->pending_wc [color="purple",label="approve"];
-  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_kyc->suspended_kyc [color="blue", label="suspend"];
+  pending_aml->suspended_aml [color="blue", label="suspend"];
+  suspended_aml->pending_aml [color="blue", label="resume"];
+  suspended_kyc->pending_kyc [color="blue", label="resume"];
 
-  pending_brr->aborting_w2b [color="blue", label="abort"];
-  pending_brr->aborted_b2w [color="red", label="error"];
+  aborting_w2b->deleted;
+  aborting_w2b->suspended_aw [color="red", label="error(already-confirmed)"];
+  aborting_w2b->deleted [color="red", label="error(unknown-transaction)"];
 
-  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"];
+  pending_ewr->suspended_aw [color="blue", label="suspend"];
+
+  suspended_aw->pending_ewr [color="blue", label="resume"];
+  suspended_aw->deleted [color="blue", label="delete"];
+
+  pending_wc->suspended_wc [color="blue", label="suspend"];
+  suspended_wc->pending_wc [color="blue", label="resume"];
+
+
+  done->deleted [color="blue", label="delete"];
+  suspended_aml->deleted [color="blue", label="delete"];
+  suspended_kyc->deleted [color="blue", label="delete"];
+  suspended_wc->deleted [color="blue", label="delete"];
 
   pending_wc->done;
 }

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