commit d86185fdc440ffd58260eb3371907ec6c45a7960
parent 8f8839e0cdcb2e281d9f8a2de5155fc9ddca6414
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 7 Jun 2025 13:41:29 +0200
review DD64
Diffstat:
1 file changed, 91 insertions(+), 28 deletions(-)
diff --git a/design-documents/064-kyc-operation-algo.rst b/design-documents/064-kyc-operation-algo.rst
@@ -27,55 +27,118 @@ Proposed Solution
Steps for processing operation of type ``op`` and amount ``amt``:
0. Initialize ``last_op_attempt := null``, ``last_rule_gen := null``
-
+ and ``last_aml_review := false`` and all back-off values to 0.
+
1. Check if a zero limit for ``op`` is applicable.
* If the zero limit denies ``op``, proceed with step 3.
* Proceed with step 2.
-2. Attempt to make a request for ``op`` at the exchange. Set ``last_op_attempt`` to
- the current time.
+2. Attempt to make a request for ``op`` at the exchange. If the
+ ``/kyc-check/`` result did not change since the last attempt,
+ make sure to use exponential backoff on ``op`` requests with
+ the frequency increasing up to once per day. The exponential
+ backoff should be reset to 0 if the ``/kyc-check/`` result
+ changed in any way.
+ Set ``last_op_attempt`` to the current time.
* If the request succeeds, *halt*.
- * If ``last_rule_gen`` is not ``null`` (Note 2), proceed with step 4.
-
+ * If ``last_aml_review`` was true, proceed with step 6.
+ * If ``last_rule_gen`` is not ``null`` (Note 1), proceed with step 5.
* Proceed with step 3.
-3. Request the ``/kyc-check/...`` endpoint applicable for ``op`` (no long-polling!)
-
- * If the request returns ``204 No Content``, proceed with step 2.
- * If the request returns ``200 Ok`` or a ``202 Accepted``:
-
- * Set ``last_rule_gen := response.rule_gen``
- * If the exposed limits do not deny ``op``, proceed with step 2.
+3. Request the ``/kyc-check/...`` endpoint applicable for ``op``
+ (without long-polling!).
- * Proceed with the next step 4.
+ * Handle response as detailed in step 7.
4. Request the ``/kyc-check/...`` endpoint applicable for ``op``
+ with long-polling for ``lpt=1``.
+
+ * While waiting for the response, prompt the user to
+ perform KYC auth wire transfer.
+ * Handle response as detailed in step 7.
+
+5. Request the ``/kyc-check/...`` endpoint applicable for ``op``
with long-polling for ``min_rule`` set to ``last_rule_gen``.
- * If the request returns ``204 No Content``, proceed with step 2.
- * If the request returns ``200 Ok`` or a ``202 Accepted``:
+ * While waiting for the response, prompt the user to
+ provide KYC information.
+ * Handle response as detailed in step 7.
+
+6. Request the ``/kyc-check/...`` endpoint applicable for ``op``
+ with long-polling for ``lpt=2`` and, additionally
+ ``min_rule`` set to the last ``last_rule_gen`` (if the
+ latter is not ``null``).
+
+ * While waiting, indicate to the user that we are waiting on the
+ provider's staff to review our account.
+ * Handle response as detailed in step 7.
+
+7. General handling of ``/kyc-check`` responses:
+
+ * If the request returns ``409 Conflict``, proceed with step 4.
+ * If the request returns ``404 Not found``, proceed with
+ step 8 applying the exposed default rules of the exchange.
+ * If the request returns ``403 Forbidden``, check if the
+ private key for the indicated public key is available, if
+ so try again with that private key, otherwise
+ proceed with step 4.
+ * If the request returns ``204 No Content``:
+ * Set ``last_aml_review := false``.
+ * Proceed with step 2.
+ * If the request returns ``202 Accepted``:
+
+ * Set ``last_aml_review := response.aml_review``.
+ * Set ``last_rule_gen := response.rule_gen``.
+ * If the exposed limits do not explicitly deny ``op``,
+ proceed with step 2.
+ * Otherwise, proceed with step 5.
+
+ * If the request returns ``200 Ok``:
+
+ * Set ``last_aml_review := response.aml_review``.
+ * Set ``last_rule_gen := response.rule_gen``.
+ * Handle exposed limits returned in step 8.
+
+ * If the response indicates no change in the status (including
+ when there was no response because the connection was closed):
+
+ * Repeat the request, using exponential back-off to reduce
+ check frequency (without even long-polling) to eventually
+ only check once per day.
+ * Ensure the long-polling interval specified in the request
+ works with the middleware. If we detect that a request timed
+ out before the specified long-polling interval, use a shorter
+ timeout argument in the HTTP request the next time
+ (but do still keep exponentially
+ backing off the actual request frequency).
+ * Lower the back-off to zero if:
+
+ * the user manually reviews the KYC auth wire transfer instructions, or
+ * the user manually reviews KYC information page instructions, or
+ * if ``op`` is a deposit and ``lpt=1`` and a withdraw succeeded
+ from the same account
+
+8. Handle exposed limits applicable to the account:
+
+ * If the exposed limits do not deny ``op``, proceed with step 2.
+ * Otherwise (the exposed limits do deny ``op``), show an error message
+ indicating that the operation is forbidden due to legal
+ restrictions on the payment service provider.
+ * If merely a threshold over some timeframe is currently
+ violated, compute the time when the operation may be allowed again,
+ indicate that to the user, allowing them to "retry immediately"
+ anyway, and also go to step 2 automatically at that time.
- * Set ``last_rule_gen := response.rule_gen``
- * If the exposed limits do not deny ``op``, proceed with step 2.
-
- * If if the ``last_op_attempt`` is ``null`` or is more than 10 minutes in the past,
- proceed with step 2. (See Note 1)
- * Proceed with step 4.
Notes:
+------
-* Note 1: In practice, this might not be necessary, but
- there could be a non-exposed rule that the client needs
- to trigger to proceed.
-* Note 2: We must long-poll for the next rule generation here,
+* Note 1: We must long-poll for the next rule generation here,
since we can assume that the current set of rules contains non-exposed
rule that prevents the current operation.
-Open questions:
-
-* What should the `lpt` parameter be in step 4?
Definition of Done
==================
