commit d1aecb3344e5ade5ca10f483a51eb58b0203c7f2
parent 94ba7741baf141cd2241119852db15a45eef4a22
Author: Florian Dold <florian@dold.me>
Date: Thu, 16 Feb 2023 20:01:16 +0100
document peer push debit lifecycle
Diffstat:
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
@@ -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
