taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-aml-OFFICER_PUB-measures.rst (4439B)

      1 .. http:get:: /aml/$OFFICER_PUB/measures
      2 
      3   To enable the AML staff SPA to give AML staff a choice of possible measures, a
      4   new endpoint ``/aml/$OFFICER_PUB/measures`` is added that allows the AML SPA
      5   to dynamically GET the list of available measures.  It returns a list of known
      6   KYC checks (by name) with their descriptions and a list of AML programs with
      7   information about the required context.
      8 
      9   This endpoint was introduced in protocol **v20**.
     10 
     11   **Request:**
     12 
     13   *Taler-AML-Officer-Signature*:
     14     The client must provide Base-32 encoded EdDSA signature with
     15     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
     16     this is merely a simple authentication mechanism, the details of the
     17     request are not protected by the signature.
     18 
     19   **Response:**
     20 
     21   :http:statuscode:`200 Ok`:
     22     Information about possible measures is returned in a
     23     `AvailableMeasureSummary` object.
     24 
     25   **Details:**
     26 
     27   .. ts:def:: AvailableMeasureSummary
     28 
     29     interface AvailableMeasureSummary {
     30 
     31       // Available original measures that can be
     32       // triggered directly by default rules.
     33       roots: { "$measure_name" : MeasureInformation; };
     34 
     35       // Available AML programs.
     36       programs: { "$prog_name" : AmlProgramRequirement; };
     37 
     38       // Available KYC checks.
     39       checks: { "$check_name" : KycCheckInformation; };
     40 
     41       // Default KYC rules. This is the set of KYC rules that
     42       // applies by default to new "accounts".  Note that some
     43       // rules only apply to wallets, while others only apply to
     44       // bank accounts. The returned array is the union of all
     45       // possible rules, applications should consider the
     46       // ``operation_type`` to filter for rules that actually
     47       // apply to a specific situation.
     48       // @since protocol **v28**.
     49       default_rules: KycRule[];
     50 
     51     }
     52 
     53   .. ts:def:: MeasureInformation
     54 
     55     interface MeasureInformation {
     56 
     57       // Name of a KYC check.
     58       check_name: string;
     59 
     60       // Name of an AML program.
     61       // Optional @since protocol **v30**.
     62       prog_name?: string;
     63 
     64       // Context for the check. Optional.
     65       context?: Object;
     66 
     67       // Operation that this measure relates to.
     68       // NULL if unknown. Useful as a hint to the
     69       // user if there are many (voluntary) measures
     70       // and some related to unlocking certain operations.
     71       // (and due to zero-amount thresholds, no measure
     72       // was actually specifically triggered).
     73       //
     74       // Must be one of "WITHDRAW", "DEPOSIT",
     75       // (p2p) "MERGE", (wallet) "BALANCE",
     76       // (reserve) "CLOSE", "AGGREGATE",
     77       // "TRANSACTION" or "REFUND".
     78       // @since protocol **v21**.
     79       operation_type?: string;
     80 
     81       // Can this measure be undertaken voluntarily?
     82       // Optional, default is false.
     83       // @since protocol **vATTEST**.
     84       voluntary?: boolean;
     85 
     86     }
     87 
     88   .. ts:def:: AmlProgramRequirement
     89 
     90     interface AmlProgramRequirement {
     91 
     92       // Description of what the AML program does.
     93       description: string;
     94 
     95       // List of required field names in the context to run this
     96       // AML program. SPA must check that the AML staff is providing
     97       // adequate CONTEXT when defining a measure using this program.
     98       context: string[];
     99 
    100       // List of required attribute names in the
    101       // input of this AML program.  These attributes
    102       // are the minimum that the check must produce
    103       // (it may produce more).
    104       inputs: string[];
    105 
    106     }
    107 
    108   .. ts:def:: KycCheckInformation
    109 
    110     interface KycCheckInformation {
    111 
    112       // Description of the KYC check.  Should be shown
    113       // to the AML staff but will also be shown to the
    114       // client when they initiate the check in the KYC SPA.
    115       description: string;
    116 
    117       // Map from IETF BCP 47 language tags to localized
    118       // description texts.
    119       description_i18n ?: { [lang_tag: string]: string};
    120 
    121       // Names of the fields that the CONTEXT must provide
    122       // as inputs to this check.
    123       // SPA must check that the AML staff is providing
    124       // adequate CONTEXT when defining a measure using
    125       // this check.
    126       requires: string[];
    127 
    128       // Names of the attributes the check will output.
    129       // SPA must check that the outputs match the
    130       // required inputs when combining a KYC check
    131       // with an AML program into a measure.
    132       outputs: string[];
    133 
    134       // Name of a root measure taken when this check fails.
    135       fallback: string;
    136     }