[taler-docs] branch master updated: review DD64

[Admin]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository taler-docs.

The following commit(s) were added to refs/heads/master by this push:
     new d86185fd review DD64
d86185fd is described below

commit d86185fdc440ffd58260eb3371907ec6c45a7960
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Jun 7 13:41:29 2025 +0200

    review DD64
---
 design-documents/064-kyc-operation-algo.rst | 119 +++++++++++++++++++++-------
 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
index fcdfa611..27792cd8 100644
--- 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
 ==================

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.