kyc and aml is a substate of pending

1 files changed, 28 insertions, 20 deletions

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index 56ddda90..e8251949 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -57,21 +57,6 @@ resumed and may then still succeed.
 
 ``failed``: Similar to ``done``, but the transaction could not even be aborted successfully.
 
-``kyc-required``: The transaction can't proceed because the user needs to actively
-finish a KYC process. 
-
-``aml-required``: The transaction can't proceed because the user needs to wait for
-the exchange operator to conclude an AML investigation.
-
-There are two key distinctions for AML-required transactions:
-
-* pending: the staff at the exchange is running its investigation. The user is not
-  expected to take any action and should just wait for the investigation to conclude.
-
-* frozen: the staff at the exchange decided that the account needed to be frozen.
-  The user should contact the exchange provider's customer service department and
-  seek resolution (possibly through the courts) to avoid loosing the funds for good.
-
 ``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.
@@ -88,10 +73,10 @@ 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.
 
-``[action:retry]``: Retrying a transaction *(1.)* stops ongoing longpolling
+``[action:retry]``: Retrying a transaction *(1.)* stops ongoing long-polling
 requests for the transaction *(2.)* resets the retry timeout *(3.)* re-runs the
 handler to process the transaction. Retries are always possible the following
-states: ``pending(*)``, ``kyc-required(*)``, ``updating(*)``, ``aborting(*)``.
+states: ``pending(*)`` and ``aborting(*)``.
 
 .. attention::
 
@@ -100,8 +85,10 @@ states: ``pending(*)``, ``kyc-required(*)``, ``updating(*)``, ``aborting(*)``.
    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 ``aborting`` state.
+``[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
@@ -117,11 +104,32 @@ of the two choices should be offered.
 
 
 .. image:: ../transaction-common-states.svg
-  :width: 800
+  :width: 400
 
 Red label means end state, where it is safe to delete the transaction record since no work is due.
 Blue label means that the transaction will not change the state unless is resumed. Safe to cache.
 
+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 
+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. 
+
+``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 
+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.
+The user should contact the exchange provider's customer service department and
+seek resolution (possibly through the courts) to avoid loosing the funds for good.
+Part of a withdrawal process or peer-to-peer push credit.
+
+
 Transaction Type: Withdrawal
 ----------------------------