[taler-docs] branch master updated: get rid of cancel, write down discussion points

[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 fe99c01  get rid of cancel, write down discussion points
fe99c01 is described below

commit fe99c01b4a6ce8c3098612566a07b7e1eac81d47
Author: Florian Dold <florian@dold.me>
AuthorDate: Mon Apr 24 23:14:23 2023 +0200

    get rid of cancel, write down discussion points
---
 .../037-wallet-transactions-lifecycle.rst          | 71 ++++++++--------------
 1 file changed, 26 insertions(+), 45 deletions(-)

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst 
b/design-documents/037-wallet-transactions-lifecycle.rst
index e89c91c..289bf50 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -17,16 +17,13 @@ should have some common actions that work uniformly across 
all transactions.
 Proposed Solution
 =================
 
+
 Common States
 -------------
 
 The following states apply to multiple different transactions.  Only pending
 and aborting have transaction-specific sub-states, denoted by 
``state(substate)``.
 
-``initial``: The initial state is the result a user interaction. A transaction
-may have more than one initial state (if it is started in multiple ways) or 
none
-(if it's the result of another process).
-
 ``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. Any pending state can be suspended and resumed.
@@ -58,9 +55,9 @@ include more information information relevant to the 
transaction in `abortReason
 ``suspended``: Similar to a ``aborted`` transaction, but the transaction was 
could be
 resumed and may then still succeed.
 
-``failed``: Similar to ``done``, but the transaction could not even be aborted
-properly.  The user may have lost money. This is likely a case for a report to
-the auditor.
+``failed``: Similar to ``done``, but the transaction could be completed or
+possible not even be aborted properly.  The user may have lost money.  In some
+cases, a report to the auditor would make sense in this state.
 
 ``deleted``: A ``deleted`` state is always a final state.  We only use this
 state for illustrative purposes. In the implementation, the data associated
@@ -111,11 +108,6 @@ actively abort the transaction (e.g. to avoid losing 
money) and puts it in an
 ``failed`` state. May result in an ultimate loss of funds (beyond fees) to the
 user and thus requires additional consent.
 
-``[action:cancel]``: Like an ``abort``, except that it results in the deletion
-of the transaction state as there is nothing useful to be kept around.  Should
-be used instead of ``delete`` if there was no transaction history state yet
-that could be deleted.
-
 ``[action:delete]``: Deleting a transaction completely deletes the transaction
 from the database.  Depending on the type of transaction, some of the other
 data *resulting* from the transaction might still survive deletion. For
@@ -128,7 +120,7 @@ state. May result in an ultimate loss of funds (beyond 
fees) to the user and
 thus requires additional consent.
 
 
-Whether aborting, cancelling, deleting or suspending are possible depends on
+Whether aborting, deleting or suspending are possible depends on
 the transaction type, and usually only one of the four choices should be
 offered.
 
@@ -179,8 +171,9 @@ Transaction Type: Withdrawal
   so we must still *try* to abort the transaction at the bank.
 
   * ``[processed-success] => pending(bank-confirming)``
-  * ``[processed-error] => deleted``: We show a transient warning.
-  * ``[action:cancel] => aborting(bank-to-wallet)``
+  * ``[processed-error] => failed``: On permanent errors (like 404 for the 
withdrawal operation),
+    the wallet gives up.
+  * ``[action:abort] => aborting(bank-to-wallet)``
 
 * ``pending(bank-confirming)``
 
@@ -198,7 +191,7 @@ Transaction Type: Withdrawal
   * ``[bank-poll-success] => pending(exchange-wait-reserve)``
   * ``[bank-poll-denied] => deleted``: We show a transient message that the 
operation was denied in the bank.
   * ``[exchange-poll-success] => pending(withdrawing-coins)``
-  * ``[action:cancel] => aborting(wallet-to-bank)``
+  * ``[action:abort] => aborting(wallet-to-bank)``
 
 * ``aborting(wallet-to-bank)``
 
@@ -653,14 +646,9 @@ Transaction Type: Tip
 Transaction Type: Deposit
 -------------------------
 
-* ``initial``
-
-  This is the initial state where the user is asked to specify the target bank 
account and amount to be deposited.
-
-  * ``[action:form-data] => pending(submit-deposit)``: user supplied deposit 
request details
-
 * ``pending(deposit)``
 
+  Initial state for deposit transactions.
   We deposit the amount coin-by-coin (or in bulk groups) until deposit is 
completed.
 
   * ``[action:suspend] => suspended(submit-deposit)``
@@ -767,14 +755,10 @@ to another wallet.
 
 States and transitions:
 
-* ``initial``
-
-  In this state, the user is asked to specify details about the payment.
-
-  * ``[action:form-data] => pending(purse-create)``: The wallet is creating a 
purse.
-
 * ``pending(purse-create)``
 
+  The wallet is creating a purse. Initial state.
+
   * ``[process-success] => pending(qr-ready)``: The wallet has created the 
purse.
   * ``[process-failure] => aborting(refund)``: The purse creation failed.
   * ``[action:suspend] => suspended(purse-create)``: The user suspended the 
operation.
@@ -975,17 +959,13 @@ Transaction Type: Peer Pull Credit
 
 TODO: Also specify variant where account reserve needs to be created / funded 
first (Note: post 1.0-feature).
 
-* ``initial``
-
-  In this state, the user is asked to specify details about the invoice.
-
-  * ``[action:form-data] => pending(purse-create)``: The wallet is creating a 
purse.
-
 * ``pending(purse-create)``
 
+  The wallet is creating a purse. Initial state.
+
   * ``[process-success] => pending(qr-ready)``: The wallet has created the 
purse.
   * ``[process-failure] => deleted``: The purse creation failed. We only show 
a transient error.
-  * ``[action:cancel] => deleted``: The user aborted the operation.
+  * ``[action:abort] => deleted``: The user aborted the operation.
 
 * ``pending(qr-ready)``
 
@@ -1085,15 +1065,9 @@ TODO: Also specify variant where account reserve needs 
to be created / funded fi
 Transaction Type: Peer Pull Debit
 ---------------------------------
 
-* ``initial``
-
-  Initial state where we encounter the taler:// URI.
-
-  * ``[trigger] => pending(download)``
-
 * ``pending(download)``
 
-  We are downloading the information about the invoice.
+  We are downloading the information about the invoice.  Initial state.
 
   * ``[action:suspend] => suspended(download)``
   * ``[success] => pending(user)``
@@ -1103,7 +1077,7 @@ Transaction Type: Peer Pull Debit
   User suspended downloading the information about the invoice.
 
   * ``[action:resume] => pending(download)``
-  * ``[action:cancel] => deleted``
+  * ``[action:delete] => deleted``
 
 * ``pending(user)``
 
@@ -1111,7 +1085,7 @@ Transaction Type: Peer Pull Debit
   the user to confirm.
 
   * ``[action:confirm-pay] => pending(submit-payment)``
-  * ``[action:cancel] => deleted``
+  * ``[action:delete] => deleted``
   * ``[timeout] => aborted``
 
 * ``pending(deposit)``
@@ -1200,4 +1174,11 @@ Drawbacks
 Discussion / Q&A
 ================
 
-(This should be filled in with results from discussions on mailing lists / 
personal communication.)
+* The diagrams only show what is happening **after** the wallet
+  has created the transaction.  It is possible that network requests
+  are happening before that, but they are not considered to be part
+  of the transaction.
+* We have decided against a `cancel` state, because it resulted
+  in too much complexity.  Instead of doing a direct `cancel`,
+  the user has to go to the transaction and abort and/or delete
+  it.

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