From 80c8a960dba8d1d28954768031396723ca4d1f04 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sun, 9 Apr 2023 18:09:21 +0200
Subject: work invoicing for DD37

---
 .../037-wallet-transactions-lifecycle.rst          | 102 ++++++++++++++++-----
 1 file changed, 81 insertions(+), 21 deletions(-)

(limited to 'design-documents')

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index 1aa959f4..58fd2c14 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -941,45 +941,105 @@ States and transitions:
 Transaction Type: Peer Pull Credit
 ----------------------------------
 
-TODO: Also specify variant where account reserve needs to be created / funded first.
-?? which is this case?
+TODO: Also specify variant where account reserve needs to be created / funded first (Note: post 1.0-feature).
 
 * ``initial``
 
-  Wallet created the transaction
+  In this state, the user is asked to specify details about the invoice.
 
-  * ``[action:success] => pending(purse-created)``
+  * ``[action:form-data] => pending(purse-create)``: The wallet is creating a purse.
 
-* ``pending(purse-created)``
+* ``pending(purse-create)``
 
-  In this state, the purse is created (already in a merged state, with the initiator providing the reserve).
+  * ``[process-success] => pending(qr-ready)``: The wallet has created the purse.
+  * ``[process-failure] => aborted``: The purse creation failed.
+  * ``[action:delete] => deleted``: The user aborted the operation.
+    FIXME(CG): May want to go into ``aborting(delete-purse)`` instead to make
+    sure the purse is not left behind.
 
-  * ``[action:success] => pending(wait-deposit)``:
-  * ``[action:abort] => aborted``: At this stage, it's safe to just abort.
+* ``pending(qr-ready)``
 
-    CG: is this not 'suspend' (safe to resume!). Also, deletion transitions are missing.
+  In this state, the user can send / show the ``taler://`` URI or QR code to
+  somebody else.
+
+  * ``[action:abort] => aborting(delete-purse)``: The user aborts the P2P payment.
+  * ``[purse-timeout] => aborted``: The other party was too slow and the purse
+    has now expired.
+  * ``[poll-success] => pending(withdraw)``: The other party has made the payment.
+  * ``[poll-error] => aborting(delete-purse)``: The exchange claims that there
+    is a permanent error regarding the purse.  We should try to delete it.
+
+* ``aborting(delete-purse)``
 
-* ``pending(wait-deposit)``
+  We are cleaning up the purse after the operation failed or was aborted by
+  the user.
 
-  We're waiting for the other party to pay into the pre-merged purse.
+  * ``[failure:already-merged] => pending(withdraw)``: Too late to abort, the
+    other side already paid the invoice.
+  * ``[process-success] => aborted``: The wallet has deleted the purse.
+  * ``[failure:other] => aborted``: The purse deletion failed; we are
+    nevertheless done.
+  * ``[action:force-abort] => aborted``: Money may be lost if it was deposited
+    into the purse in the meantime.
 
-  * ``[action:abort] => aborting(delete-purse)``: At this stage, it's safe to just abort.
-  * ``[process-failed(expired)] => failed(expired)``
+* ``aborted``
+
+  The invoicing process ended without success.
+
+  * ``[action:delete] => deleted``
+
+* ``pending(withdraw)``
 
-* ``pending(withdrawing)``
+  The wallet is withdrawing the money paid for the invoice.
 
   * ``[processed-success] => done``
-  * ``[processed-kyc-required] => pending(kyc-required)``
+  * ``[failure] => failed``
+  * ``[processed-kyc] => pending(kyc)``
+  * ``[processed-aml] => pending(aml)``
+  * ``[action:suspend] => suspended(withdraw)``
 
-* ``pending(kyc-required)``
+* ``pending(kyc)``
 
-  * ``[poll-success] => pending(withdrawing)``
+  The user must supply KYC information before withdrawing can continue.
 
-* ``aborting(delete-purse)``
+  * ``[poll-success] => pending(withdraw)``
+  * ``[action:suspend] => suspended(kyc)``
 
-  * ``[processed-success] => aborted``
-  * ``[processed-failed(was-merged)] => done``
-  * ``[processed-failed(expired)] => failed(expired)``
+* ``suspended(kyc)``
+
+  The user suspended waiting for the KYC operation to complete.
+
+  * ``[action:resume] => pending(kyc)``
+  * ``[action:force-delete] => deleted``
+
+* ``pending(aml)``
+
+  The user must await a positive exchange AML decision.
+
+  * ``[poll-success] => pending(withdraw)``
+  * ``[action:suspend] => suspended(aml)``
+
+* ``suspended(aml)``
+
+  The user suspended waiting for the AML decision to be successful.
+
+  * ``[action:resume] => pending(aml)``
+  * ``[action:force-delete] => deleted``
+
+* ``failed``
+
+  Obtaining the money for the invoce failed. This is likely a case for the
+  auditor.
+
+  * ``[action:delete] => deleted``
+
+* ``done``
+
+  The invoice was successfully paid.
+
+  * ``[action:delete] => deleted``
+
+* ``deleted``
 
 
 Transaction Type: Peer Pull Debit
-- 
cgit v1.2.3