spec AML API

1 files changed, 261 insertions, 2 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 25738a45..c1d82e62 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -906,7 +906,7 @@ Management operations authorized by master key
 
 .. http:post:: /management/wire-fee
 
-  This request will be used to configure wire fees.
+  This request is used to configure wire fees.
 
   **Request:**
 
@@ -1108,7 +1108,53 @@ Management operations authorized by master key
     }
 
 
-.. http:post:: /management/partners
+.. http:post:: /management/aml-officers/$OFFICER_PUB
+
+  Update settings for an AML Officer status.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+  **Request:**
+
+  The request must be an `AmlOfficerSetup` message.
+
+  **Response**
+
+  :http:statuscode:`204 No content`:
+    The officer settings have been updated successfully.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+  :http:statuscode:`409 Conflict`:
+    The exchange has previously received a conflicting configuration message.
+
+  **Details:**
+
+  .. ts:def:: AmlOfficerSetup
+    interface AmlOfficerSetup {
+
+      // Legal full name of the AML officer
+      officer_name: string;
+
+      // Is the account active?
+      is_active: bool;
+
+      // Is the account read-only?
+      read_only: bool;
+
+      // Signature by the exchange master key over a
+      // `TALER_MasterAmlOfficerStatusPS`.
+      // Must have purpose ``TALER_SIGNATURE_MASTER_AML_KEY``.
+      master_sig: EddsaSignature;
+
+      // When will the change take effect?
+      change_date: Timestamp;
+
+    }
+
+
+    .. http:post:: /management/partners/$PARTNER_PUB
 
   Enables a partner exchange for wad transfers.
 
@@ -1129,7 +1175,220 @@ Management operations authorized by master key
   :http:statuscode:`409 Conflict`:
     The exchange has previously received a conflicting configuration message.
 
+  **Details:**
+
+  .. ts:def:: ExchangePartner
+    interface ExchangePartner {
+
+      // Base URL of the partner exchange
+      partner_base_url: string;
+
+      // How frequently will wad transfers be made
+      wad_frequency: RelativeTime;
+
+      // Signature by the exchange master key over a
+      // `TALER_PartnerConfigurationPS`.
+      // Must have purpose ``TALER_SIGNATURE_MASTER_PARTNER_DETAILS``.
+      master_sig: EddsaSignature;
+
+      // When will the partner relationship start (inclusive).
+      start_date: Timestamp;
+
+      // When will the partner relationship end (exclusive).
+      end_date: Timestamp;
+
+      // Wad fee to be charged (to customers).
+      wad_fee: Amount;
+
+    }
+
+--------------
+AML operations
+--------------
+
+This API is only for designated AML officers. It is used
+to allow exchange staff to monitor suspicious transactions
+and freeze or unfreeze accounts suspected of money laundering.
+
+
+.. http:get:: /aml/$OFFICER_PUB/decisions
+
+  Obtain list of AML decisions (typically filtered).
 
+  *AML-Officer-Signature*: The client must provide Base-32 encoded EdDSA signature with ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature.
+
+  :query frozen: *Optional*. If set to yes, only return frozen AML records.
+  :query pending: *Optional*. If set to yes, only return AML records where the decision is pending.
+  :query normal: *Optional*. If set to yes, only return AML records where transactions are allowed.
+  :query delta: *Optional*. takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries (before ``start``).
+  :query start: *Optional*. Row number threshold, see ``delta`` for its interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id possible in the database.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+  **Response**
+
+  :http:statuscode:`200 Success`:
+    The responds will be an `AmlRecords` message.
+  :http:statuscode:`204 No content`:
+    There are no matching AML records.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The designated AML account is not known.
+  :http:statuscode:`409 Conflict`:
+    The designated AML account is not enabled.
+
+  **Details:**
+
+  .. ts:def:: AmlRecords
+    interface AmlRecords {
+
+      // Array of AML records matching the query.
+      records: AmlRecord[];
+    }
+
+  .. ts:def:: AmlRecord
+    interface AmlRecord {
+
+      // Which payto-address is this record about.
+      // Identifies a GNU Taler wallet or an affected bank account.
+      h_payto: Hash;
+
+      // What is the current AML state.
+      current_state: integer;
+
+      // When was the last decision made?
+      last_decision_time: Timestamp;
+
+    }
+
+
+.. http:get:: /aml/$OFFICER_PUB/decisions/$H_PAYTO
+
+  Obtain deails about an AML decision.
+
+  *AML-Officer-Signature*: The client must provide Base-32 encoded EdDSA signature with ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this is merely a simple authentication mechanism, the details of the request are not protected by the signature.
+
+  :query history: *Optional*. If set to yes, we return all historic decisions and not only the last one.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+  **Response**
+
+  :http:statuscode:`200 Success`:
+    The responds will be an `AmlDecisionDetails` message.
+  :http:statuscode:`204 No content`:
+    There are no matching AML records for the given payto://-URI.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The designated AML account is not known.
+  :http:statuscode:`409 Conflict`:
+    The designated AML account is not enabled.
+
+  **Details:**
+
+  .. ts:def:: AmlDecisionDetails
+    interface AmlDecisionDetails {
+
+      // Array of AML decisions made for this account. Possibly
+      // contains only the most recent decision if "history" was
+      // not set to 'true'.
+      aml_records: AmlDecisionDetail[];
+
+      // Array of KYC records obtained for this account.
+      kyc_records: KycDetail[];
+    }
+
+  .. ts:def:: AmlDecisionDetails
+    interface AmlDecisionDetails {
+
+      // What was the justification given?
+      justification: String;
+
+      // What is the new AML state.
+      new_state: integer;
+
+      // When was this decision made?
+      decision_time: Timestamp;
+
+    }
+
+  .. ts:def:: KycDetail
+    interface KycDetail {
+
+      // Name of the configuration section that specifies the provider
+      // which was used to collect the KYC details
+      provider_section: String;
+
+      // The collected KYC data.
+      attributes: Object;
+
+      // Time when the KYC data was collected
+      collection_time: Timestamp;
+
+    }
+
+
+    .. http:post:: /aml/$OFFICER_PUB/decision
+
+  Make an AML decision. Triggers the respective action and
+  records the justification.
+
+  .. note::
+
+     This is a draft API that is not yet implemented.
+
+  **Request:**
+
+  The request must be an `AmlDecision` message.
+
+  **Response**
+
+  :http:statuscode:`204 No content`:
+    The AML decision has been executed and recorded successfully.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The address the decision was made upon is unknown to the exchange or
+    the designated AML account is not known.
+  :http:statuscode:`409 Conflict`:
+    The designated AML account is not enabled or a more recent
+    decision was already submitted.
+
+  **Details:**
+
+  .. ts:def:: AmlDecision
+    interface AmlDecision {
+
+      // Human-readable justification for the decision.
+      justification: string;
+
+      // At what monthly transaction volume should the
+      // decision be automatically reviewed?
+      new_threshold: Amount;
+
+      // Which payto-address is the decision about?
+      // Identifies a GNU Taler wallet or an affected bank account.
+      h_payto: Hash;
+
+      // What is the new AML state (e.g. frozen, unfrozen, etc.)
+      // Numerical values are defined in `enum TALER_AmlDecisionState`.
+      new_state: integer;
+
+      // Signature by the AML officer over a
+      // `TALER_MasterAmlOfficerStatusPS`.
+      // Must have purpose ``TALER_SIGNATURE_MASTER_AML_KEY``.
+      officer_sig: EddsaSignature;
+
+      // When was the decision made?
+      decision_time: Timestamp;
+
+    }
 
 
 ---------------