[taler-docs] branch master updated: spec updates for #9039 and #9124

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new f32c3721 spec updates for #9039 and #9124
f32c3721 is described below

commit f32c3721fd0b597041e470e195858494ac5e6e30
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Sep 5 11:52:19 2024 +0200

    spec updates for #9039 and #9124
---
 core/api-exchange.rst              | 36 ++++++++++++++++++++++++++++--------
 design-documents/023-taler-kyc.rst | 35 ++++++++++++++++++-----------------
 manpages/taler.conf.5.rst          | 18 ++++++++++--------
 3 files changed, 56 insertions(+), 33 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 7da33a90..38d2014d 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -4934,9 +4934,9 @@ regulatory compliance.
       // Default (if missing) is false.
       is_and_combinator?: boolean
 
-      // List of available voluntary checks the client could pay for.
+      // List of available voluntary checks the client could undertake.
       // Since **vATTEST**.
-      voluntary_checks?: { name : KycCheckPublicInformation};
+      voluntary_measures?: KycRequirementInformation[];
     }
 
   .. ts:def:: KycRequirementInformation
@@ -5203,6 +5203,25 @@ and freeze or unfreeze accounts suspected of money 
laundering.
       // Context for the check. Optional.
       context?: Object;
 
+      // Operation that this measure relates to.
+      // NULL if unknown. Useful as a hint to the
+      // user if there are many (voluntary) measures
+      // and some related to unlocking certain operations.
+      // (and due to zero-amount thresholds, no measure
+      // was actually specifically triggered).
+      //
+      // Must be one of "WITHDRAW", "DEPOSIT",
+      // (p2p) "MERGE", (wallet) "BALANCE",
+      // (reserve) "CLOSE", "AGGREGATE",
+      // "TRANSACTION" or "REFUND".
+      // New in protocol **v21**.
+      operation_type?: string;
+
+      // Can this measure be undertaken voluntarily?
+      // Optional, default is false.
+      // Since protocol **vATTEST**.
+      voluntary?: boolean;
+
     }
 
   .. ts:def:: AmlProgramRequirement
@@ -5457,6 +5476,7 @@ and freeze or unfreeze accounts suspected of money 
laundering.
     interface KycRule {
 
       // Type of operation to which the rule applies.
+      //
       // Must be one of "WITHDRAW", "DEPOSIT",
       // (p2p) "MERGE", (wallet) "BALANCE",
       // (reserve) "CLOSE", "AGGREGATE",
@@ -5617,14 +5637,14 @@ and freeze or unfreeze accounts suspected of money 
laundering.
       // New since protocol **v20**.
       properties: AccountProperties;
 
-      // New checks to enable immediately on the account.
+      // Space-separated list of measures to trigger
+      // immediately on the account.
+      // Prefixed with a "+" to indicate that the
+      // measures should be ANDed.
       // Should typically be used to give the user some
       // information or request additional information.
-      // Use "verboten" to communicate to the customer
-      // that there is no KYC check that could be passed
-      // to modify the ``new_rules``.
-      // New since protocol **v20**.
-      new_checks: string[];
+      // New since protocol **v21**.
+      new_measures?: string;
 
       // True if the account should remain under investigation by AML staff.
       // New since protocol **v20**.
diff --git a/design-documents/023-taler-kyc.rst 
b/design-documents/023-taler-kyc.rst
index 3c25a608..e5dc8b35 100644
--- a/design-documents/023-taler-kyc.rst
+++ b/design-documents/023-taler-kyc.rst
@@ -432,7 +432,7 @@ body.
 New endpoints
 ^^^^^^^^^^^^^
 
-.. http:get:: /kyc-check/$REQUIREMENT_ROW
+.. http:get:: /kyc-check/$H_PAYTO
 
   Checks the KYC status of a particular payment target and possibly begins a
   KYC process by allowing the customer to choose the next KYC measure to
@@ -443,11 +443,12 @@ New endpoints
   statisfied and the operation can now proceed).  Long-polling may be used
   to instantly observe a change in the KYC requirement status.
 
-  The requirement row of the ``/kyc-check/`` endpoint encodes the
-  legitimization measure's serial number.  It is returned in
-  `LegitimizationNeededResponse` responses via the ``requirement_row`` field.
+  The payto hash of the ``/kyc-check/`` endpoint encodes the
+  account (or wallet) for which legitimization measures are determined.
+  It is returned in `LegitimizationNeededResponse` responses as in
+  the case of withdraw, the wallet may not know the debited bank account.
 
-  Given a valid pair of requirement row and account owner signature, the
+  Given a valid pair of payto hash and account owner signature, the
   ``/kyc-check/`` endpoint returns either just the KYC status or redirects the
   client (202) to the next required stage of the KYC process.  The redirection
   must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET.  It
@@ -495,7 +496,7 @@ New endpoints
     The exchange is not configured to perform KYC and thus
     the legal requirements are already satisfied.
   :http:statuscode:`403 Forbidden`:
-    The provided signature is not acceptable for the requirement row.
+    The provided signature is not acceptable for the payto hash.
   :http:statuscode:`404 Not found`:
     The requirement row is unknown.
 
@@ -902,9 +903,7 @@ to the new ``/kyc-check/`` handler.
 When depositing, the exchange aggregator (!) checks the KYC status and if
 negative, returns an additional information field via the
 ``aggregation_transient`` table which is returned via GET ``/deposts/`` to the
-merchant.  This way, the merchant learns the ``requirement_row`` needed to
-begin the KYC process (this is independent of the amount) at the new
-``/kyc-check/`` handler.
+merchant.
 
 When merging into a reserve, the KYC status is checked and again the
 merge fails with ``451 Unavailable for Legal Reasons`` to trigger the
@@ -980,14 +979,6 @@ providers, one per configuration section:
   #
   TYPE = INFO|LINK|FORM
 
-  # Optional. Set to YES to allow this check be
-  # done voluntarily by a client (they may then
-  # still have to pay for it). Used to offer the
-  # SPA to display checks even if they are
-  # not required. Default is NO.
-  # Since **vATTEST**.
-  VOLUNTARY = YES/NO
-
   # Provider id, present only if type is LINK.
   # Refers to a ``kyc-provider-$PROVIDER_ID`` section.
   PROVIDER_ID = id
@@ -1179,6 +1170,13 @@ Finally, the configuration specifies a set of
   # Refers to a ``[aml-program-$PROG_NAME]`` section name.
   PROGRAM = taler-aml-program
 
+  # Optional. Set to YES to allow this measure to be
+  # done voluntarily by a client. Used to offer the
+  # KYC SPA to display measure even if they are
+  # not required. Default is NO.
+  VOLUNTARY = YES/NO
+
+
 If ``CHECK_NAME`` is set to "SKIP" (or is not provided at all), the AML
 ``PROGRAM`` is to be run immediately.  This is useful if no client-interaction
 is required to arrive at a decision.
@@ -1290,6 +1288,7 @@ on GET ``/deposits/`` with the respective legitimization 
requirement row.
     ,decision_time INT8 NOT NULL DEFAULT(0)
     ,expiration_time INT8 NOT NULL DEFAULT(0)
     ,jproperties TEXT,
+    ,new_measure_name TEXT,
     ,to_investigate BOOL NOT NULL
     ,is_active BOOL NOT NULL DEFAULT(TRUE)
     ,jnew_rules TEXT NOT NULL
@@ -1310,6 +1309,8 @@ on GET ``/deposits/`` with the respective legitimization 
requirement row.
     IS 'AML staff should investigate the activity of this account';
   COMMENT ON COLUMN legitimization_outcomes.is_active
     IS 'TRUE if this is the current authoritative legitimization outcome';
+  COMMENT ON COLUMN legitimization_outcomes.new_measure_name
+    IS 'space-separated list of measures to trigger immediately, NULL for 
none, prefixed with a "+" to indicate AND combination for the measures';
   COMMENT ON COLUMN legitimization_outcomes.jnew_rules
     IS 'JSON object of type LegitimizationRuleSet with rules to apply to the 
various operation types for this account; all KYC checks should first check if 
active new rules for a given account exist in this table (and apply specified 
measures); if not, it should check the default rules to decide if a measure is 
required';
 
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 128e19dd..aca19d95 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -381,13 +381,6 @@ TYPE
   * FORM: SPA should show an inline (HTML) form
   * LINK: SPA may start external KYC process or upload
 
-VOLUNTARY
-  Optional. Set to YES to allow this check be
-  done voluntarily by a client (they may then
-  still have to pay for it). Used to offer the
-  SPA to display checks even if they are
-  not required. Default is NO.
-
 PROVIDER_ID
   Provider id, present only if type is LINK.
   Refers to a ``kyc-provider-$PROVIDER_ID`` section.
@@ -451,7 +444,9 @@ NEXT_MEASURES
   which order they are to be performed.)
   A special measure name "verboten" is used if the
   specified threshold may never be crossed
-  (under this set of rules).
+  (under this set of rules). This option is equivalent
+  to the "new_measure" string in an AmlDecisionRequest
+  (with IS_AND_COMBINATOR replacing the "+"-prefix).
 
 IS_AND_COMBINATOR
   "YES" if all NEXT_MEASURES will eventually need
@@ -527,6 +522,13 @@ PROGRAM
   determine the outcome and next measure.
   Refers to a ``[aml-program-$PROG_NAME]`` section name.
 
+VOLUNTARY
+  Optional. Set to YES to allow this measure to be
+  done voluntarily by a client. Used to offer the
+  SPA to display measures even if they are
+  not required. Default is NO.
+
+
 
 EXCHANGE EXTENSIONS OPTIONS
 ---------------------------

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