work on reserve control API design

1 files changed, 136 insertions, 26 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 357aa565..6680cd88 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -4378,7 +4378,17 @@ KYC status updates
 Reserve control
 ---------------
 
-This section is about a proposed API. It is not implemented.
+This section describes the reserve control API which can be used to (1)
+prevent a reserve from expiring (which is useful if the reserve is used for
+tipping), to (2) pay an annual fee to allow a number of purses to be created
+for the respective reserve without paying a purse fee each time, to (3) obtain
+KYC information associated with a reserve to prove the identity of the person
+sending an invoice to the payer, and to (4) close a reserve before it would
+naturally expire and possibly (5) wire the funds to a designated account.
+
+  .. note::
+
+     This section is about a proposed API. It is not implemented. See also DD 31.
 
 .. http:post:: /reserves/$RESERVE_PUB/open
 
@@ -4393,8 +4403,7 @@ This section is about a proposed API. It is not implemented.
   :http:statuscode:`200 OK`:
     The exchange responds with a `ReserveOpenResponse` object.
   :http:statuscode:`402 Payment Required`:
-    The reserve balance is insufficient to pay for the open operation.
-    The exchange responds with a `RequiredBalanceResponse` object.
+    The exchange responds with a `ReserveOpenFailure` object.
   :http:statuscode:`403 Forbidden`:
     The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid.
     This response comes with a standard `ErrorDetail` response.
@@ -4415,6 +4424,10 @@ This section is about a proposed API. It is not implemented.
       // a `TALER_ReserveOpenRequestSignaturePS`.
       reserve_sig: EddsaSignature;
 
+      // Array of payments made towards the cost of the
+      // operation.
+      payments: OpenPaymentDetail[];
+
       // Time when the client made the request.
       // Timestamp must be reasonably close to the time of
       // the exchange, otherwise the exchange may reject
@@ -4441,33 +4454,139 @@ This section is about a proposed API. It is not implemented.
   .. ts:def:: ReserveOpenResponse
 
     interface ReserveOpenResponse {
-      // Balance left in the reserve after the account_fee
-      // was charged.
-      balance: Amount;
-
       // Transaction cost for extending the expiration time.
       // Excludes KYC fees.
       open_cost: Amount;
 
-      // New expiration time for the reserve.
+      // Current expiration time for the reserve.
       reserve_expiration: Timestamp;
     }
 
-  .. ts:def:: RequiredBalanceResponse
+  .. ts:def:: ReserveOpenFailure
 
-    interface RequiredBalanceResponse {
-      // Balance left in the reserve after the account_fee
-      // was charged.
-      balance: Amount;
+    interface ReserveOpenFailure {
+      // Transaction cost that should have been paid
+      // to extending the reserve as requested.
+      // Excludes KYC fees.
+      open_cost: Amount;
+
+      // Remaining expiration time for the reserve.
+      reserve_expiration: Timestamp;
+    }
+
+  .. ts:def:: OpenPaymentDetail
+
+    interface OpenPaymentDetail {
+
+      // Contribution of this coin to the overall amount.
+      // Can be a fraciton of the coin's total value.
+      contribution: Amount;
+
+      // Hash of denomination RSA key with which the coin is signed.
+      denom_pub_hash: HashCode;
+
+      // Exchange's unblinded RSA signature of the coin.
+      ub_sig: DenominationSignature;
+
+      // Age commitment for the coin, if the denomination is age-restricted.
+      age_commitment?: AgeCommitment;
+
+      // Signature over `TALER_ReserveOpenDepositSignaturePS`
+      // of purpose ``TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT``
+      // made by the customer with the
+      // `coin's private key <coin-priv>`.
+      coin_sig: EddsaSignature;
+
+      // Public key of the coin being used to pay for
+      // opening the reserve.
+      coin_pub: EddsaPublicKey;
+
+    }
+
+
+.. http:get:: /reserves/$RESERVE_PUB/attest
+
+  Request list of available KYC attributes about the owner of a reserve.
+  Used as a preliminary step to find out which subsets of attributes the
+  exchange could provide signatures over.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The exchange responds with a `ReserveKycAttributes` object.
+  :http:statuscode:`404 Not found`:
+    The reserve key does not belong to a reserve known to the exchange.
+  :http:statuscode:`409 Conflict`:
+    The exchange does not have the requested KYC information.
+
+  **Details:**
 
-      // Transaction cost for extending to the
-      // requested expiration time.
-      // Includes applicable KYC fees.
-      required: Amount;
+  .. ts:def:: ReserveKycAttributes
 
+    interface ReserveKycAttributes {
+      // Array of KYC attributes available.  The attribute names
+      // listed are expected to be from the respective GANA
+      // registry.
+      details: String[];
     }
 
 
+.. http:post:: /reserves/$RESERVE_PUB/attest
+
+  Request signed KYC information about the owner of a reserve.
+  This can be used by a reserve owner to include a proof
+  of their identity in invoices.
+
+  **Request:**
+
+  The request body must be a `ReserveAttestRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The exchange responds with a `ReserveAttestResponse` object.
+  :http:statuscode:`403 Forbidden`:
+    The *TALER_SIGNATURE_WALLET_KYC_DETAILS* signature is invalid.
+    This response comes with a standard `ErrorDetail` response.
+  :http:statuscode:`404 Not found`:
+    The reserve key does not belong to a reserve known to the exchange.
+  :http:statuscode:`409 Conflict`:
+    The exchange does not have the requested KYC information.
+
+  **Details:**
+
+  .. ts:def:: ReserveAttestRequest
+
+    interface ReserveAttestRequest {
+      // Signature of purpose
+      // ``TALER_SIGNATURE_WALLET_ATTEST_DETAILS`` over
+      // a `TALER_WalletReserveAttestRequestSignaturePS`.
+      reserve_sig: EddsaSignature;
+
+      // Array of KYC attributes requested.
+      details: String[];
+    }
+
+  .. ts:def:: ReserveAttestResponse
+
+    interface ReserveAttestResponse {
+      // Signature of purpose
+      // ``TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS`` over
+      // a `TALER_ExchangeReserveAttestDetailsSignaturePS`.
+      reserve_sig: EddsaSignature;
+
+      // Time when the exchange created the signature.
+      exchange_timestamp: Timestamp;
+
+      // Expiration time for the provided information.
+      expiration_time: Timestamp;
+
+      // KYC details (key-value pairs) as requested.
+      // The keys will match the elements of the
+      // ``details`` array from the request.
+      attributes: Object;
+    }
+
 
 .. http:post:: /reserves/$RESERVE_PUB/close
 
@@ -4516,13 +4635,6 @@ This section is about a proposed API. It is not implemented.
       // the request (with a status code of 400).
       request_timestamp: Timestamp;
 
-      // Maximum amount to transfer to the indicated
-      // account (after fees). If not given, the
-      // reserve will be completely drained.  The amount
-      // given may exceed the reserve balance, in which case
-      // the reserve will also be completely drained.
-      maximum_transfer?: Amount;
-
       // payto://-URI of the account the reserve balance is to be
       // wired to.  Must be of the form: 'payto://$METHOD' for a
       // wire method supported by this exchange (if the
@@ -4537,8 +4649,6 @@ This section is about a proposed API. It is not implemented.
   .. ts:def:: ReserveCloseResponse
 
     interface ReserveCloseResponse {
-      // Balance left in the reserve after the close.
-      balance: Amount;
 
       // Actual amount that will be wired (excludes closing fee).
       wire_amount: Amount;