commit 8788ed0dcaa8c3459ba22ff7351254a1c830739e
parent 823a4d4e2c370cce883b8b31aefd2399784d1951
Author: Florian Dold <florian@dold.me>
Date: Mon, 13 Feb 2023 19:32:55 +0100
DD37, first part
Diffstat:
2 files changed, 147 insertions(+), 0 deletions(-)
diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -0,0 +1,146 @@
+DD 37: Wallet Transaction Lifecycle
+###################################
+
+Summary
+=======
+
+This design doc discusses the lifecycle of transactions in wallet-core.
+
+Motivation
+==========
+
+The transactions in wallet-core all should have an associated state machine. All transactions
+should have some common actions that work uniformly across all transactions.
+
+Proposed Solution
+=================
+
+Common States
+-------------
+
+**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:
+
+* long-polling vs exponential backoff: A pending transaction is either waiting
+ on an external service by making a long-polling request or by repeating requests
+ with exponential back-off.
+* ``lastError``: A pending transaction is either clean (i.e. the external service successfully
+ communicated that it is not ready yet) or has a ``lastError``, which is a ``TalerErrorDetails``
+ 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
+never has a ``lastError`` but is considered successful.
+
+**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.
+
+.. warning::
+ Consensus required: Should there be an abortReason for aborted transactions?
+
+**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.
+
+**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.
+
+
+Common Actions
+--------------
+
+**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.
+
+.. 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
+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.
+
+**Give up**: Giving up puts an ``aborting`` transaction into the ``failed`` state.
+
+Transaction Type: Withdrawal
+----------------------------
+
+TBD.
+
+Transaction Type: Payment to Merchant
+-------------------------------------
+
+TBD.
+
+Transaction Type: Refund
+------------------------
+
+TBD.
+
+Transaction Type: Refresh
+-------------------------
+
+TBD.
+
+Transaction Type: Tip
+---------------------
+
+TBD.
+
+Transaction Type: Deposit
+-------------------------
+
+TBD.
+
+Transaction Type: Peer Push Debit
+---------------------------------
+
+TBD.
+
+
+Transaction Type: Peer Push Credit
+----------------------------------
+
+TBD.
+
+Transaction Type: Peer Pull Credit
+----------------------------------
+
+TBD.
+
+Transaction Type: Peer Pull Debit
+---------------------------------
+
+TBD.
+
+Alternatives
+============
+
+* each transaction could be treated completely separately
+
+Drawbacks
+=========
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -45,4 +45,5 @@ and protocol.
034-wallet-db-migration
035-regional-currencies
036-currency-conversion-service
+ 037-wallet-transactions-lifecycle.rst
999-template
