more work on DD37

1 files changed, 148 insertions, 16 deletions

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index 4d49e4db..c35b9d64 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -92,8 +92,8 @@ Transaction Type: Withdrawal
   Initial state for bank-integrated withdrawals.  The wallet submits the reserve public key
   and selected exchange to the bank (via the bank integration API).
 
-  * ``[processing-success] => pending(bank-confirming)``
-  * ``[processing-error(bank-aborted)] => aborted(bank)``
+  * ``[processed-success] => pending(bank-confirming)``
+  * ``[processed-error(bank-aborted)] => aborted(bank)``
 
 * ``pending(bank-confirming)``
 
@@ -112,8 +112,8 @@ Transaction Type: Withdrawal
 
 * ``pending(withdrawing-coins)``
 
-  * ``[processing-success] => done``
-  * ``[processing-kyc-required] => kyc-required``
+  * ``[processed-success] => done``
+  * ``[processed-kyc-required] => kyc-required``
 
 * ``kyc-required``
 
@@ -121,8 +121,8 @@ Transaction Type: Withdrawal
 
 * ``aborting(wallet-to-bank)``
 
-  * ``[processing-success] => aborted(wallet-to-bank)``
-  * ``[processing-error(already-confirmed)] => aborted(after-wired)``
+  * ``[processed-success] => aborted(wallet-to-bank)``
+  * ``[processed-error(already-confirmed)] => aborted(after-wired)``
 
 * ``aborted(bank-to-wallet)``: The bank notified the wallet that the withdrawal
   was aborted on the side of the bank and won't proceed.
@@ -140,6 +140,9 @@ Transaction Type: Withdrawal
 Transaction Type: Payment to Merchant
 -------------------------------------
 
+XXX: Also consider re-selection when the wallet accidentally double-spends coins
+or the selected coins have expired.  Do we ask the user in this case?
+
 * ``pending(download-proposal)``
 
   Initial state. Download (claim) the proposal from the merchant.
@@ -155,8 +158,8 @@ Transaction Type: Payment to Merchant
 * ``pending(submit-payment)``
 
   * ``[action:abort] => aborting(refund)``
-  * ``[processing-success(auto-refund-enabled)] => pending(paid-auto-refund-check)``
-  * ``[processing-error(expired)] => aborting(refresh)`` XXX: If the order is expired but the payment
+  * ``[processed-success(auto-refund-enabled)] => pending(paid-auto-refund-check)``
+  * ``[processed-error(expired)] => aborting(refresh)`` XXX: If the order is expired but the payment
     succeeded partially before, do we still try an abort-refund?
 
 * ``pending(submit-payment-replay)``
@@ -174,8 +177,8 @@ Transaction Type: Payment to Merchant
 
 * ``aborting(refund)``
 
-  * ``[processing-success] => aborted(refunded)``
-  * ``[processing-failure] => aborting(refresh)``
+  * ``[processed-success] => aborted(refunded)``
+  * ``[processed-failure] => aborting(refresh)``
 
 * ``aborting(refresh)``
 
@@ -186,27 +189,99 @@ Transaction Type: Payment to Merchant
 * ``aborted(refunded)``
 
   * ``[action:delete] => deleted``
+
+* ``deleted``
+
+  When a payment is deleted, associated refunds are always deleted with it
   
 
 Transaction Type: Refund
 ------------------------
 
-TBD.
+* ``pending``
+
+  A refund is pending when the merchant is getting a non-permanent error from
+  the exchange (and relaying that error response to the wallet).
+
+  * ``[processed-success] => done``
+  * ``[processed-error] => failed``
+
+* ``done``
+
+* ``failed``
+
+  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``.
+
+  * ``[payment-refund-processed-success] => done``
+
+* ``*``
+
+  Transitions from any state:
+
+  * ``[action:delete] => deleted`` Deleting a refund has no effect on the wallet's balance
 
 Transaction Type: Refresh
 -------------------------
 
-TBD.
+XXX: If we have to adjust the refund amount (because a coin has fewer funds on
+it than we expect), what is the resulting state of the whole refresh?
+
+* ``pending``
+
+  * ``[processed-success] => done``
+  * ``[action:abort] => aborted``: Money that has not been refreshed yet is lost.
+
+* ``done``
 
 Transaction Type: Tip
 ---------------------
 
-TBD.
+* ``pending(initial)``
+
+  The wallet has downloaded metadata for the tip from the merchant and
+  stored it in the databse.  The user needs to accept/refuse it.
+
+  * ``[tip-expired] => failed(expired)``
+  * ``[action:accept-tip] => pending(pickup)``
+  * ``[action:abort] => aborted``
+
+* ``pending(pickup)``
+
+  * ``[tip-expired] => failed(expired)``
+  * ``[processed-success] => done``
+  * ``[action:abort] => aborted``
+
 
 Transaction Type: Deposit
 -------------------------
 
-TBD.
+XXX: Handle expired/invalid coins in the coin selection
+
+* ``pending(initial)``
+
+  The wallet deposits coins with the exchange.
+
+  * ``[processed-success] => pending(track)``
+  * ``[action:abort] => aborting(refund)``
+
+* ``pending(track)``
+
+  * ``[poll-success] => done``
+
+* ``aborting(refund)``
+
+  ``[processed-success] => aborting(refresh)``
+  ``[processed-error] => aborting(refresh)`` XXX Shouldn't this be some error state?
+
+* ``aborting(refresh)``
+
+  ``[processed-success] => aborted``
+  ``[processed-error] => failed``
+
+* ``done``
+
 
 Transaction Type: Peer Push Debit
 ---------------------------------
@@ -297,12 +372,69 @@ States and transitions:
 Transaction Type: Peer Pull Credit
 ----------------------------------
 
-TBD.
+TODO: Also specify variant where account reserve needs to be created / funded first.
+
+* ``pending(initial)``
+
+  In this state, the purse is created (already in a merged state, with the initiator
+  providing the reserve).
+
+  * ``[action:abort] => aborted``: At this stage, it's safe to just abort.
+
+* ``pending(wait-deposit)``
+
+  We're waiting for the other party to pay into the pre-merged purse.
+
+  * ``[action:abort] => aborting(delete-purse)``: At this stage, it's safe to just abort.
+  * ``[process-failed(expired)] => failed(expired)``
+
+* ``pending(withdrawing)``
+
+  * ``[processed-success] => done``
+
+* ``aborting(delete-purse)``
+
+  * ``[processed-success] => aborted``
+  * ``[processed-failed(merge)] => done``
+  * ``[processed-failed(expired)] => failed(expired)``
+
+* ``aborted``
+
+* ``done``
+
+* ``failed(expired)``
+
+  
 
 Transaction Type: Peer Pull Debit
 ---------------------------------
 
-TBD.
+* ``pending(initial)``
+
+  We've downloaded information about the pull payment and are waiting
+  for the user to confirm.
+
+  * ``[action:abort] => aborted``: Safe to abort!
+  * ``[action:confirm-pay] => pending(deposit)``: Safe to abort!
+
+* ``pending(deposit)``
+
+  The user has confirmed the payment and the wallet tries to deposit
+  into the provided purse.
+
+  * ``[processed-success] => done``
+  * ``[action:abort] => aborting(refresh)``: Wallet tries to refresh coins
+    that were not already deposited. XXX Do we really always refresh even if no deposit
+    attempt has been made yet?
+
+* ``aborting(refresh)``
+
+  XXX Before refreshing, should we not wait until the purse has expired?
+
+  * ``[processed-success] => aborted``
+  * ``[processed-failed] => failed``
+
+* ``done``
 
 Alternatives
 ============