more work on DD23

1 files changed, 51 insertions, 31 deletions

diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst
index 44275a94..21df9d43 100644
--- a/design-documents/023-taler-kyc.rst
+++ b/design-documents/023-taler-kyc.rst
@@ -19,7 +19,7 @@ Requirements
 
 The solution should support fees to be paid by the user for the KYC process (#7365).
 
-Taler needs to run KYC checks in the following circumstances:
+Taler needs to take *measures* based on the following primary *triggers*:
 
 * Customer withdraws money over a monthly threshold
 
@@ -44,17 +44,22 @@ Taler needs to run KYC checks in the following circumstances:
 
   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
 
-There are many different possible KYC/AML flows:
+* Import of new sanctions lists and triggering of measures against matches of existing
+  customer records against the list
+
+
+For the different *measures*, there are various different possible KYC/AML *checks*
+that could happen:
 
 * In-person validation by AML staff
+* Various forms to be filled by AML staff
 * Validation involving local authorities and post-office
-* Online validation
-  
-  * Forms to be supplied by user
+* Online validation, sometimes with multiple options (like KYC for multiple people):
+
+  * Forms to be supplied by user (different types of ID)
   * Interactive video
-  * Documents to be supplied
-    
-* Forms to be filled by AML staff
+  * Documents to be supplied (business register)
+  * Address validation (e-mail or phone or postal)
 
 Additionally, the process is dynamic and conditional upon various decisions:
 
@@ -65,21 +70,26 @@ Additionally, the process is dynamic and conditional upon various decisions:
 * Need for plausibilization (via documents by user or staff research)
 * Periodic updates (of customer data, of sanction lists) and re-assessment
 
-There are also various outcomes:
+There are also various *outcomes*:
 
-* normal operation
-* normal operation but with AML staff investigating
-* held, requesting customer documentation
-* held, AML staff reviewing evidence
+* normal operation (with expiration date)
+* normal operation but with AML staff investigating (new measure)
+* held, requesting customer documentation (new measure)
+* held, AML staff reviewing evidence for plausibilization (new measure)
 * automatically frozen until certain day (due to sanctions)
 * institutionally frozen until certain day (due to order by state authority)
 
+The outcome of a *check* can trigger further *measures* (including
+expiration of the outcome state).
+
+
 Finally, we need to produce statistics:
 
 * number of incidents reported (voluntarily, required)
 * number of business relationships at any point in time
 * number of risky business relationships (PEP, etc.)
-* begin/end-date of relationships (data retained for X years after end of relationship)
+* number of frozen transactions (authority vs. sanction) with start-date and end-date
+* start-data and end-date of relationships (data retained for X years after end of relationship)
 
 For this high-level monitoring, we need certain designated critical events to
 be tracked in the system statistics:
@@ -101,26 +111,30 @@ disclosed).
 Proposed Solution
 =================
 
-We allow certain **conditions** to trigger a single specific **measures**.
-For the different measures, we define:
+We allow certain *conditions* to *trigger* a single specific *measures*.
+For the different *measures*, we define:
 
 * Who has to do something (AML staff, user, nobody)
-* The specific operational state (normal, held on staff, held on user, frozen)
-  the account is to transition to
-* Specification of required context inputs (w. templating, e.g. amount set dynamically)
-* What state to show to the user (normal, information required, pending, etc.)
-* For user-interactive states:
+* Contextual input data to be provided (with templating, e.g. amount set dynamically based on the *trigger*)
+* A *check* to be performed
+* A *program* that uses data from the *check* as well as *context* data
+  to determine an *outcome* which is the specific operational state
+  (normal, held on staff, held on user, frozen, etc.) the account is to transition to
+* What information about the state to show to the user (normal, information required, pending, etc.)
 
-  * Web page template with instructions to render
-  * The check to set up (if any) and measure on failure
-  * An external helper to run on success to determine the next measure
-    based on context and data provided in the measure
+* For user-interactive checks:
 
-* For (AML) staff-interactive states the UI provides the ability to:
+  * Web page template with instructions to render (with either a form to fill or links to external checks);
+    here the context could provide an array of choices!
+  * Possibly an external check to set up (if any); for cost-reasons, we should only do one at a time,
+    and probably should then always redirect the browser to that check.
+  * A *measure* to take on failure of the external check
 
-  * file forms and upload documentation (without state transition)
-  * decide on next measure (providing context); here, the exchange needs
-    to expose the list of available measures and required context for each
+* For (AML) staff-interactive checks:
+
+  * UI to file forms and upload documentation (without state transition)
+  * UI to decide on next measure (providing context); here, the exchange needs
+    to expose the list of available *measures* and required *context* for each
 
 * Non-interactive measures (normal operation, account frozen) need:
 
@@ -133,12 +147,14 @@ For the different measures, we define:
 Terminology
 ^^^^^^^^^^^
 
-* **Check**: A check establishes a particular attribute of a user, such as their name based on an ID document and lifeness, mailing address, phone number, taxpayer identity, etc.
+* **Check**: A check establishes a particular attribute of a user, such as their name based on an ID document and lifeness, mailing address, phone number, taxpayer identity, etc.  Checks may be given *context* (such as whether a customer is an individual or a business) to run correctly. Checks can also be AML staff inserting information for plausibilization.  Checks result in an *outcome* being decided by an external AML *program*.
 
 * **Condition**: A condition specifies when KYC is required. Conditions include the *type of operation*, a threshold amount (e.g. above EUR:1000) and possibly a time period (e.g. over the last month).
 
 * **Configuration**: The configuration determines the *legitimization rules*, and specifies which providers offer which *checks* at what *cost*.
 
+* **Context**: Context is information provided as input into a *check* and *program* to customize their execution. The context is initially set by the *trigger*, but may evolve as the *account* undergoes *measures*. For each *check* and *program*, the required *context* data must be specified.
+
 * **Cost**: Metric for the business expense for a KYC check at a certain *provider*. Not in any currency, costs are simply relative and non-negative values. Costs are considered when multiple choices are allowed by the *configuration*.
 
 * **Expiration**: KYC legitimizations may be outdated. Expiration rules determine when *checks* have to be performed again.
@@ -147,10 +163,14 @@ Terminology
 
 * **Logic**: Logic refers to a specific bit of code (realized as an exchange plugin) that enables the interaction with a specific *provider*.  Logic typically requires *configuration* for access control (such as an authorization token) and possibly the endpoint of the specific *provider* implementing the respective API.
 
-* **Measure**: Describes the possible outgoing edges from one state in the state machine (including how to show the current state).
+* **Measure**: Describes the possible outgoing edges from one state in the state machine (including how to show the current state). Each edge is given some *context* and a *check* to be performed as well as a *program* to decide the *outcome* and the next *measure*.
+
+* **Outcome**: Describes the account state that an account ends up in due to the result of a *check*. Outcomes can be that an account is frozen (no transactions possible until freeze expires), held (no transactions possible until another *measure* has been taken), or operating normally.
 
 * **Provider**: A provider performs a specific set of *checks* at a certain *cost*. Interaction with a provider is performed by provider-specific *logic*.
 
+* **Program**: An AML helper *program* is given *context* about the current state of an account and the data from a *check* to compute the *outcome*.  For example, a *program* may look at the "PEP" field of a KYC check and decide if the outcome is to put the account into ``normal`` or ``held-for-manual-review`` state.  A *program* operating on an AML form filed by AML staff will likely be trivial and directly apply the explicit decision taken by the staff member.
+
 * **Type of operation**: The operation type determines which Taler-specific operation has triggered the KYC requirement. We support four types of operation: withdraw (by customer), deposit (by merchant), P2P receive (by wallet) and (high) wallet balance.