spec push debit

1 files changed, 57 insertions, 18 deletions

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index 7924295f..a08fe07f 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -686,43 +686,82 @@ States and transitions:
 
 * ``initial``
 
-  In this state, the user is not yet able to send the payment to somebody else.
+  In this state, the user is asked to specify details about the payment.
 
-  * ``[action:abort] => aborted``: The payment is aborted early, before the wallet even had the chance to create a purse.
-    No fees are incurred.
-  * ``[processing-success] => pending(purse-created)``: The wallet was able to successfully create a purse.
+  * ``[action:form-data] => pending(purse-create)``: The wallet is creating a purse.
 
-* ``pending(purse-created)``
+* ``pending(purse-create)``
+
+  * ``[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.
+
+* ``suspended(purse-create)``
+
+  * ``[action:resume] => pending(purse-create)``: The user resumed the operation.
+  * ``[action:abort] => aborting(refund)``: The user aborted the operation.
+
+* ``pending(qr-ready)``
 
   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.
+  * ``[purse-timeout] => aborting(refresh)``: The other party was too slow and the purse has now expired.
   * ``[poll-success] => pending(refundable)``: The other party has accepted the payment.
-  * ``[poll-error] => aborting(refresh)``: The exchange claims that there is a permanent error regarding the purse.
+  * ``[poll-error] => aborting(refresh)``: The exchange claims that there is a permanent error regarding the purse.  (FIXME(CG): not clear that this is the best transition! Could also go to ``aborting(refund)`` or ``aborting(delete-purse)``; best choice may depend on the specific error returned.)
 
 * ``aborting(delete-purse)``
 
+  The wallet is deleting the purse to prevent the receiver from merging it and to reclaim the funds in it.
+
   * ``[processed-success] => aborting(refresh)``: The purse was deleted successfully, and refunded coins must be refreshed.
   * ``[processed-failed(already-merged)] => done``: The other party claimed the funds faster that we were able to abort.
   * ``[processed-failed(other)] => aborting(refresh)``:  The exchange reports a permanent error.  We still try to refresh.
-  * ``[action:abort-force] => failed``
+  * ``[action:abort-force] => failed``: The user explicitly asked us to give up and accepted the possible loss of funds.
+
+* ``aborting(refund)``
+
+  We abandon the purse that was never fully funded and ask for the deposited coins to be refunded.
+
+  * ``[processed-success] => aborting(refresh)``: After the refund, we still need to refresh the coins.
+  * ``[processed-failure] => aborting(refresh)``: The refund failed, we still try to refresh the coins.
 
 * ``aborting(refresh)``
 
-  * ``[processed-success] => aborted)``: Refresh group finished. Aborting was successful, money was reclaimed
-  * ``[processed-failed] => failed)``: Refresh group failed to complete with a permanent error.
-  * ``[action:abort-force] => failed``: XXX will this abort the refresh session or just orphan it?
+  * ``[processed-success] => aborted``: Refresh group finished. Aborting was successful, money was reclaimed.
+  * ``[processed-failed] => failed``: Refresh group failed to complete with a permanent error.
+  * ``[action:abort-force] => failed``: The user explicitly asked us to give up and accepted the possible loss of funds.
 
 * ``pending(refundable)``
 
-  * ``[auto-refund-timeout] => done``
+  FIXME(CG): I do not understand this state. Left out. Remove?
 
-* ``aborting(refund)``
+  * ``[auto-refund-timeout] => done``: FIXME(CG): I do not think we should have auto-refunds with P2P payments. Remove?
 
-  * ``[processed-success] => aborted(refunded)``
-  * ``[processed-failure] => aborting(refresh)``
+* ``done``
+
+  The transfer was successful.
 
+  * ``[action:delete] => deleted``
+
+* ``aborted``
+
+  The transfer was aborted. Except for fees, the money was recovered.
+
+  * ``[action:delete] => deleted``
+
+* ``failed``
+
+  The transfer failed. Money was lost. Unless on a forced abort, we should probably complain to the auditor.
+
+  * ``[action:delete] => deleted``
+
+* ``deleted``
+
+  All memory of the push debit operation is lost.
+
+.. image:: ../transaction-push-debit-states.png
+  :width: 400
 
 
 Transaction Type: Peer Push Credit
@@ -735,7 +774,7 @@ States and transitions:
 
 * ``initial``
 
-Wallet read the taler:// URI and the transaction was initialized
+  Wallet read the taler:// URI and the transaction was initialized
 
   * ``[processed-success] => pending(withdrawing)``: Merging the reserve was successful
 
@@ -771,7 +810,7 @@ TODO: Also specify variant where account reserve needs to be created / funded fi
 
 * ``initial``
 
-Wallet created the transaction
+  Wallet created the transaction
 
   * ``[action:success] => pending(purse-created)``
 
@@ -812,7 +851,7 @@ Transaction Type: Peer Pull Debit
 
 * ``initial``
 
-Wallet read the taler:// URI
+  Wallet read the taler:// URI
 
   * ``[action:success] => pending(invoice-downloaded)``