From 201686c4372b1c163bdf860b9e0ea460727fa2b0 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 18 Mar 2024 12:09:10 +0100 Subject: more work on DD23 --- design-documents/023-taler-kyc.rst | 82 ++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 31 deletions(-) (limited to 'design-documents') 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. -- cgit v1.2.3