[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated (a7dd26c -> 160809d)
From: |
gnunet |
Subject: |
[taler-docs] branch master updated (a7dd26c -> 160809d) |
Date: |
Sat, 08 Apr 2023 17:47:10 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a change to branch master
in repository docs.
from a7dd26c address /pay documentation for #6952
new c68cb55 whitespace
new 160809d redo diagram in dot
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
Makefile | 4 +-
.../037-wallet-transactions-lifecycle.rst | 104 ++++++++++++---------
transaction-common-states.dot | 28 ++++++
3 files changed, 93 insertions(+), 43 deletions(-)
create mode 100644 transaction-common-states.dot
diff --git a/Makefile b/Makefile
index 6bb8992..cb844de 100644
--- a/Makefile
+++ b/Makefile
@@ -53,6 +53,8 @@ clean:
arch-api.png: arch-api.dot
dot -Tpng arch-api.dot > arch-api.png
+transaction-common-states.png: transaction-common-states.dot
+ dot -Tpng transaction-common-states.dot > transaction-common-states.png
coin.png: coin.dot
dot -Tpng coin.dot > coin.png
deposit.png: deposit.dot
@@ -60,7 +62,7 @@ deposit.png: deposit.dot
reserve.png: reserve.dot
dot -Tpng reserve.dot > reserve.png
-diagrams: arch-api.png coin.png
+diagrams: arch-api.png coin.png deposit.png reserve.png
transaction-common-states.png
# The html-linked builder does not support caching, so we
diff --git a/design-documents/037-wallet-transactions-lifecycle.rst
b/design-documents/037-wallet-transactions-lifecycle.rst
index 3cc807e..64ec242 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -21,9 +21,9 @@ 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)
+``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
@@ -31,12 +31,13 @@ is finished. Any pending state can be suspended and resumed.
There are some other distinctions for pending transactions:
-* long-polling vs exponential backoff: A pending transaction is either waiting
+* 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 network
interaction
is literally active in transmission or the external service successfully
- communicated that it is not ready yet) or has a ``lastError``, which is a
``TalerErrorDetails``
+ communicated that it is not ready yet and this is perfectly normal)
+ or has a ``lastError``, which is a ``TalerErrorDetails``
object with details about what happened during the last attempt to proceed
with the transaction.
@@ -47,19 +48,19 @@ never has a ``lastError`` but is considered successful.
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.
-``aborted``: Similar to a ``done`` transaction, but the transaction was
successfully aborted
-instead of successfully finished. It will have the information of when
(timestamp) it was
+``aborted``: Similar to ``done``, but the transaction was successfully aborted
+instead of successfully finished. It will have the information of when
(timestamp) it was
aborted and in which pending sub-state the abort action was initiated. Also,
we can
-include more information information relevant to the transaction in
`abortReason`
+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
successfully.
+``failed``: Similar to ``done``, but the transaction could not even be aborted
properly.
``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.
+with the transaction would be literally deleted.
Common Transitions
@@ -67,12 +68,12 @@ Common Transitions
Transitions are actions or other events.
-``[action:delete]``: Deleting a transaction (also called "forgetting" in the
UI)
-completely deletes the transaction in the database. Depending on the type of
+``[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 example, deleting a withdrawal transaction does not
delete already successfully withdrawn coins. Deleting is only safe (no money
lost)
-on initial and final state (failed, aborted, done)
+on initial and final states (failed, aborted, done).
``[action:retry]``: Retrying a transaction *(1.)* stops ongoing long-polling
requests for the transaction *(2.)* resets the retry timeout *(3.)* re-runs the
@@ -83,47 +84,63 @@ states: ``pending(*)`` and ``aborting(*)``.
Should we show the retry timeout in the UI somewhere? Should we show it in
dev mode?
- SEBASJM: Since the wallet will retry anyway, maybe is better if we replace
the "retry"
- button with a "try now" button and a side text "retrying in xxx seconds"
-
-``[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
+ SEBASJM: Since the wallet will retry anyway, maybe is better if we replace
the "retry"
+ button with a "try now" button and a side text "retrying in xxx seconds".
+
+ CG: Instead of a side text, this *might* make a good mouse-over hint for
+ a "retry" (or "try now") button. I would not make this overly visible with
+ side-text as the information is not that important. The text should also be
+ "retrying next at XXX" using an absolute time XXX --- otherwise the UI would
+ be way too busy recomputing/updating all of these strings: Using an
absolute time,
+ we only have to redraw anything once a retry actually happened. Given that
+ retries should basically never be > 24h (we can impose a hard cap), the
absolute
+ time can just be in the format HH:MM:SS (without day).
+
+``[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.
-``[action:suspend]``: Suspends a pending transaction, stopping any associated
network activities, but with a chance of trying
-again at a later time. This could be useful if a user needs to save battery
power or bandwidth and an operation is expected
-to take longer (such as a backup, recovery or very large withdrawal operation).
+``[action:suspend]``: Suspends a pending transaction, stopping any associated
+network activities, but with a chance of trying again at a later time. This
+could be useful if a user needs to save battery power or bandwidth and an
+operation is expected to take longer (such as a backup, recovery or very large
+withdrawal operation).
-``[action:resume]``: Suspended transactions may be resumed, placing them back
into a pending state.
+``[action:resume]``: Suspended transactions may be resumed, placing them back
+into a pending state.
-``[action:abort-force]``: Directly puts an ``aborting`` transaction into the
``failed`` state.
+``[action:abort-force]``: Directly puts an ``aborting`` transaction into the
+``failed`` state.
-Whether aborting or resuming is possible depends on the transaction type, and
usually only one
-of the two choices should be offered.
+Whether aborting or resuming are possible depends on the transaction type, and
+usually only one of the two choices should be offered.
-.. image:: ../transaction-common-states.svg
+.. image:: ../transaction-common-states.png
:width: 400
-Boxed label means end state, where it is safe to delete the transaction record
since no work is due.
-Blue arrows means mean user-triggered actions
+Boxed labels indicate an end state in which it is safe to delete the
+transaction record since no work is due.
+
+Blue arrows are used for user-triggered actions (via UI buttons).
+
Common pending sub-states
----------------------------------
+-------------------------
During the pending state the transaction can go through several sub-states
before
-reaching a final state. Some of this sub-states are shared between different
+reaching a final state. Some of this sub-states are shared between different
transaction types:
``kyc-required``: The transaction can't proceed because the user needs to
actively
-finish a KYC process. Part of a withdrawal process or peer-to-peer push
credit.
+finish a KYC process. Part of a withdrawal process or peer-to-peer push credit.
``aml-required``: The transaction can't proceed because the user needs to wait
for
-the exchange operator to conclude an AML investigation by the staff at the
exchange.
-The user is not expected to take any action and should just wait for the
investigation
+the exchange operator to conclude an AML investigation by the staff at the
exchange.
+The user is not expected to take any action and should just wait for the
investigation
to conclude. Part of a withdrawal process or peer-to-peer push credit.
``aml-frozen``: The staff at the exchange decided that the account needed to
be frozen.
@@ -162,7 +179,7 @@ user. So special-casing this and testing this is IMO just
not worth it.
exchange.
(??) is this needed? let say that the money is wired but the signal
- never of the bank confirmation reached the wallet, what should happen?
+ never of the bank confirmation reached the wallet, what should happen?
* ``[poll-success] => pending(exchange-wait-reserve)``
* ``[action:abort] => aborting(wallet-to-bank)``
@@ -205,7 +222,7 @@ user. So special-casing this and testing this is IMO just
not worth it.
* ``aborted(partially-withdrawn)``:
In this state, the wallet should show how much money arrived into the wallet
- and the rest of the money will be sent back to the originating bank account
+ and the rest of the money will be sent back to the originating bank account
after ``$closing_delay``.
* ``done``
@@ -254,7 +271,7 @@ instructedAmount, effectiveAmount and the affectedAmount
(partially effective am
of transitioning the UI into a ``pending(repurchase-session-reset)``
on a different transaction (which before was in ``done``).
- (??) should not reset another transaction?
+ (??) should not reset another transaction?
* ``pending(proposed)``
@@ -284,7 +301,7 @@ Submit coin by coin (or in bulk groups) until payment is
complete.
* ``pending(refundable)``
-The payment succeed but if auto-refund-check is active it will be checking for
refunds
+The payment succeed but if auto-refund-check is active it will be checking for
refunds
* ``[auto-refund-timeout] => done``
@@ -334,7 +351,7 @@ A refund is a pseudo-transaction that is always associated
with a merchant payme
A failed refund can technically still transition to ``done``, because the
wallet
doesn't query some refund resource, but the purchase for refunds. Thus, a
previously
- failed refund can suddenly transition to ``done``.
+ failed refund can suddenly transition to ``done``.
(??) separate transient error vs permanent error ?
@@ -409,7 +426,7 @@ Submit coin by coin (or in bulk groups) until deposit is
completed.
* ``[action:abort] => aborting(refund)``
* ``[processed-success] => pending(track)``
- * ``[processed-error] => aborting(refresh)``
+ * ``[processed-error] => aborting(refresh)``
* ``pending(track)``
@@ -605,7 +622,7 @@ Wallet read the taler:// URI
* ``pending(refundable)``
-The payment succeed but if auto-refund-check is active it will be checking for
refunds
+The payment succeed but if auto-refund-check is active it will be checking for
refunds
* ``[auto-refund-timeout] => done``
@@ -627,7 +644,10 @@ The payment succeed but if auto-refund-check is active it
will be checking for r
Alternatives
============
-* each transaction could be treated completely separately
+* Each transaction could be treated completely separately; however, uniform
+ terminology for actions (and thus button labels) is likely more helpful for
+ the user experience.
+
Drawbacks
=========
diff --git a/transaction-common-states.dot b/transaction-common-states.dot
new file mode 100644
index 0000000..890cc23
--- /dev/null
+++ b/transaction-common-states.dot
@@ -0,0 +1,28 @@
+digraph G {
+
+ initial[label="", shape="circle"];
+ pending[label="pending"];
+ done[label="done", shape="box"];
+ aborted[label="aborted", shape="box"];
+ aborting[label="aborting"];
+ failed[label="failed", shape="box"];
+ suspended[label="suspended"];
+
+ subgraph {
+ rank = same; pending;suspended;
+ }
+
+ subgraph {
+ rank = same; done; aborted; failed;
+ }
+
+ initial->pending;
+ pending->suspended [color="blue",label="suspend"];
+ suspended->pending [color="blue",label="resume"];
+ pending->done [color="green",label="success"];
+ pending->failed [color="red",label="error"];
+ pending->aborting [color="blue",label="abort"];
+ pending->aborted [color="blue",label="abort"];
+ aborting->aborted [color="green",label="success"];
+ aborting->failed [color="red",label="error"];
+}
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated (a7dd26c -> 160809d),
gnunet <=