[taler-docs] branch master updated: work on reserve control API design

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 3f7927f  work on reserve control API design
3f7927f is described below

commit 3f7927f435da3ff89b126f6837b5fb0016025a23
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Sep 18 00:03:13 2022 +0200

    work on reserve control API design
---
 core/api-exchange.rst              | 162 +++++++++++++++++++++++++++++++------
 design-documents/031-invoicing.rst |  25 +++++-
 2 files changed, 160 insertions(+), 27 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 357aa56..6680cd8 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;
diff --git a/design-documents/031-invoicing.rst 
b/design-documents/031-invoicing.rst
index 4e2ebc5..24c64d7 100644
--- a/design-documents/031-invoicing.rst
+++ b/design-documents/031-invoicing.rst
@@ -36,6 +36,25 @@ Requirements
 
   * Reasonable UX and overall design impact.
 
+Unclear in the current proposal are:
+
+  * How to pay for the opening. Do we support the use of
+    coins, or should we require the user to have a
+    sufficient balance in the reserve, or do we allow
+    both? Probably best to only support one. As
+    reserves are typically instant-drained by the
+    wallet, might be best to require coins?
+
+  * Here (and in other places!), the payment of the KYC
+    fee remains, eh, obscure. This should probably be
+    part of the KYC endpoints, and not for each
+    KYC-trigger.
+
+  * Proposed table structure does not properly capture
+    if user paid extra for more purses (I could open
+    for 3 years, then pay for 5x purses in year 1, but
+    should not automatically get 5x purses in years 2/3).
+
 
 Proposed Solution
 =================
@@ -55,18 +74,22 @@ reserve after tips are no longer issued.
 The solution needs three new tables for:
 
   * account creation data:
+
     - serial
     - timestamp
     - signature affirming desire to create account
     - KYC requirement row
 
   * account creation payment data:
+
     - serial (for replication)
     - coin signature (affirming payment)
     - amount contributed
     - account creation link (serial row ID)
 
   * reserve closure request data:
+
+    - serial (for replication)
     - timestamp
     - reserve signature
     - target account payto:// URI
@@ -100,7 +123,7 @@ Reserve Attestation
 
   * This new endpoint ``/reserve/$RID/attest`` allows the user to
     obtain exchange-signed KYC information about themselves.
-    This will basically be a list of (standardized) attributes
+    This will basically be a list of (GANA standardized) attributes
     and exchange signatures. The user can then choose which of
     these attributes to include when invoicing.  The available
     set of attributes may differ depending on the KYC providers

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.