[taler-docs] branch master updated: document peer push debit lifecycle

[gnunet]

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

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new d1aecb3  document peer push debit lifecycle
d1aecb3 is described below

commit d1aecb3344e5ade5ca10f483a51eb58b0203c7f2
Author: Florian Dold <florian@dold.me>
AuthorDate: Thu Feb 16 20:01:16 2023 +0100

    document peer push debit lifecycle
---
 .../037-wallet-transactions-lifecycle.rst          | 99 +++++++++++++++++-----
 1 file changed, 77 insertions(+), 22 deletions(-)

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index 6c6e1bb..a79f7d7 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -18,10 +18,11 @@ Proposed Solution
 Common States
 -------------
 
-**pending**: A pending transaction waits for some external event/service.
+The following states apply to multiple different transactions.  They can
+have transaction-specific sub-states, denoted by ``state(substate)``.
+
+``pending``: A pending transaction waits for some external event/service.
 The transaction stays pending until its change on the wallet's material 
balance is finished.
-If the transaction has affected the wallet's balance but is still waiting for 
some external
-money transfer that the wallet does not directly affect, the state will 
instead be ``monitoring``. 
 
 There are some other distinctions for pending transactions:
 
@@ -33,53 +34,60 @@ There are some other distinctions for pending transactions:
   object with details about what happened during the last attempt to proceed
   with the transaction.
 
-**done**: A transaction that is done does not require any more processing.  It 
also
+``done``: A transaction that is done does not require any more processing.  It 
also
 never has a ``lastError`` but is considered successful.
 
-**aborting**: Similar to a pending transaction, but instead of taking active 
steps to
+``aborting``: Similar to a pending transaction, but instead of taking active 
steps to
 complete the transaction, the wallet is taking active steps to abort it. The 
``lastError``
 indicates errors the wallet experienced while taking active steps to abort the 
transaction.
 
 .. attention::
   Should there be an abortReason for aborted transactions?
 
-**aborted**: Similar to a ``done`` transaction, but the transaction was 
successfully aborted
+``aborted``: Similar to a ``done`` transaction, but the transaction was 
successfully aborted
 instead of successfully finished.
 
-**failed**: Similar to ``done``, but the transaction could not even be aborted 
successfully.
+``failed``: Similar to ``done``, but the transaction could not even be aborted 
successfully.
 
-**kyc-required**: The transaction can't proceed because the user needs to 
actively
+``kyc-required``: The transaction can't proceed because the user needs to 
actively
 finish a KYC process.
 
-**monitoring**: A transaction is in principle finished (has affected the 
wallet balance), but still waiting for some external
-event to occur to be fully finished.  For example, the money transfer by the 
exchange to a bank account after a deposit,
-or another wallet claiming a p2p push payment that our wallet initiated.  Some 
transactions (e.g. p2p push payments)
-can still be aborted in the ``monitoring`` state, and as a result the 
transaction is basically reverted.
+``updating``: A ``done`` transaction can transition in the ``updating`` state
+when there is a potential update for the transaction, for example a refund.
+This change will be reflected in new transactions, not in modifications to the
+old transaction.
+
+``deleted``: A ``deleted`` state is always a final state.  We only use this
+state for illustrative purposes. In the implementation, the data associated
+with the transaction would be deleted.
+
 
+Common Transitions
+------------------
 
-Common Actions
---------------
+Transitions are actions or other events.
 
-**Delete**: Deleting a transaction (also called "forgetting" in the UI)
+``[action:delete]``: Deleting a transaction (also called "forgetting" in the 
UI)
 completely deletes the transaction in the database.  Depending on the type of
 transaction, some of the other data *resulting* from the transaction might
 still survive deletion. For example, deleting a withdrawal transaction does not
 delete withdrawn coins.
 
-**Retry**: Retrying a transaction *(1.)* stops ongoing longpolling requests for
-the transaction *(2.)* resets the retry timeout *(3.)* re-runs the handler to
-process the transaction.
+``[action:retry]``: Retrying a transaction *(1.)* stops ongoing longpolling
+requests for the transaction *(2.)* resets the retry timeout *(3.)* re-runs the
+handler to process the transaction. Retries are always possible the following
+states: ``pending(*)``, ``kyc-required(*)``, ``updating(*)``, ``aborting(*)``.
 
 .. attention::
 
    Should we show the retry timeout in the UI somewhere?  Should we show it in 
dev mode?
 
-**Abort**: Aborting a transaction either directly stops processing for the 
transaction and puts it in an ``aborted`` state
+``[action:abort]``: Aborting a transaction either directly stops processing 
for the transaction and puts it in an ``aborted`` state
 or starts the necessary steps to actively abort the transaction (e.g. to avoid 
losing money) and puts it in an ``aborting`` state.
 
-**Resume**: Some aborted transactions may be resumed.  Whether resuming is 
possible depends on the transaction type.
+``[action:resume]``: Some aborted transactions may be resumed.  Whether 
resuming is possible depends on the transaction type.
 
-**Give up**: Giving up puts an ``aborting`` transaction into the ``failed`` 
state.
+``[action:give-up]``: Giving up puts an ``aborting`` transaction into the 
``failed`` state.
 
 Transaction Type: Withdrawal
 ----------------------------
@@ -114,7 +122,54 @@ TBD.
 Transaction Type: Peer Push Debit
 ---------------------------------
 
-TBD.
+Peer Push Debit transactions are created when the user wants to transfer money
+to another wallet.
+
+States and transitions:
+
+* ``pending(initial)``
+
+  In this state, the user is not yet able to send the payment to somebody else.
+
+  * ``[action:abort] => aborted``: The payment is aborted early, before the 
wallet even had the chance to create a purse.
+    No fees are incurred.
+  * ``[action:delete] => deleted``: No funds are lost.
+  * ``[processsing-success] => pending(purse-created)``: The wallet was able 
to successfully create a purse.
+
+* ``pending(purse-created)``
+
+  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. The wallet tries to reclaim money in the purse.
+  * ``[purse-timeout] => aborting(refresh)``: The other party was too slow.
+  * ``[poll-success] => done``: The other party has accepted the payment.
+
+* ``aborting(delete-purse)``
+
+  * ``[processed-success] => aborting(refresh)``: The purse was deleted 
successfully, and refunded coins must be refreshed.
+  * ``[processed-failed] => ...``: Permanent failure when trying to delete the 
reserve.
+
+    * If purse is already merged: ``=> done``
+    * Otherwise: ``=> failed`` XXX: Do we still try to refresh?
+
+  * ``[action:give-up] => failed``
+
+* ``aborting(refresh)``
+
+  * ``[processed] => aborted)``: Aborting was successful, money was reclaimed
+  * ``[action:give-up] => failed``: XXX will this abort the refresh session?
+
+* ``done``
+
+  * ``[action:delete]`` No money should be lost in this case.
+
+* ``aborted``
+
+  * ``[action:delete]`` No additional money is lost other than fees from 
aborting/refreshing.
+
+* ``failed``
+
+  * ``[action:delete]``: Money will be lost.
 
 
 Transaction Type: Peer Push Credit

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