[taler-docs] branch master updated: DD37, first part

[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 8788ed0  DD37, first part
8788ed0 is described below

commit 8788ed0dcaa8c3459ba22ff7351254a1c830739e
Author: Florian Dold <florian@dold.me>
AuthorDate: Mon Feb 13 19:32:55 2023 +0100

    DD37, first part
---
 .../037-wallet-transactions-lifecycle.rst          | 146 +++++++++++++++++++++
 design-documents/index.rst                         |   1 +
 2 files changed, 147 insertions(+)

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
new file mode 100644
index 0000000..f4e19c6
--- /dev/null
+++ 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
index 4d17360..34da2f4 100644
--- 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

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