spec tip

1 files changed, 65 insertions, 11 deletions

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index bacfff09..f9db090f 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -509,38 +509,92 @@ the same as if the double-spending transaction had been deleted by the user.
 
   The refresh operation completed.
 
+  * ``[action:delete] => deleted``
+
 * ``deleted``
 
   All memory of the refresh operation is lost, but of course the resulting
   fresh coins are preserved.
 
 .. image:: ../transaction-refresh-states.png
-  :width: 800
+  :width: 400
 
 
 
 Transaction Type: Tip
 ---------------------
 
-* ``initial``
+* ``pending(query)``
 
-  The wallet has downloaded metadata for the tip from the merchant and
-  stored it in the database.  The user needs to accept/refuse it.
+  The wallet is downloading the metadata for the tip from the merchant to store it in the database.
 
-  * ``[tip-expired] => failed(expired)``
-  * ``[action:accept-tip] => pending(pickup)``
-  * ``[action:abort] => aborted``
+  * ``[failure] => deleted``: We only show a transient warning that the tip was invalid.
+  * ``[action:suspend] => suspended(pickup)``
+  * ``[success] => pending(user)``
+
+* ``suspended(query)``
+
+  The user suspended the operation to download the tip data.
+
+  * ``[action:delete] => deleted``
+  * ``[action:resume] => pending(query)``
+
+* ``pending(user)``
+
+  We have downloaded the metadata for the tip. The user needs to accept/refuse
+  the tip.
+
+  * ``[tip-expired] => failed``
+  * ``[action:accept] => pending(pickup)``
+  * ``[action:abort] => deleted``
 
 * ``pending(pickup)``
 
-  * ``[tip-expired] => failed(expired)``
+  We are picking up the tip.
+
+  * ``[failure] => failed``: any type of failure, including expiration.
   * ``[processed-kyc-required] => pending(kyc-required)``
-  * ``[processed-success] => done``
-  * ``[action:abort] => aborted``
+  * ``[success] => done``
+  * ``[action:suspend] => suspended(pickup)``
 
-* ``pending(kyc-required)``
+* ``suspended(pickup)``
+
+  The user suspended the operation while the tip was being picked up.
+
+  * ``[action:delete] => deleted``
+  * ``[tip-expired] => failed``
+  * ``[action:resume] => pending(pickup)``
+
+* ``pending(kyc)``
+
+  The user needs to perform a KYC check to continue. This usually should only
+  happen if the wallet balance exceeds some threshold.
 
   * ``[poll-success] => pending(pickup)``
+  * ``[action:suspend] => suspended(kyc)``
+
+* ``suspended(kyc)``
+
+  The user suspended the KYC operation.  Note that we do not time out here if
+  the tip expires, as the wallet balance threshold KYC likely applies even
+  without the tip.
+
+  * ``[action:delete] => deleted``
+  * ``[action:resume] => pending(kyc)``
+
+* ``done``
+
+  The tip operation completed.
+
+  * ``[action:delete] => deleted``
+
+* ``deleted``
+
+  All memory of the tip operation is lost, but of course the resulting fresh
+  coins are preserved.
+
+.. image:: ../transaction-tip-states.png
+  :width: 400
 
 
 Transaction Type: Deposit