[taler-docs] branch master updated: -propose reserve open/close API

[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 be69b01  -propose reserve open/close API
be69b01 is described below

commit be69b01fcc7b5cfc3e2575b50211b2d74e47f83d
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat Sep 17 23:27:42 2022 +0200

    -propose reserve open/close API
---
 core/api-exchange.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 3e71ba4..357aa56 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -4372,3 +4372,175 @@ KYC status updates
     The webhook succeeded.
   :http:statuscode:`404 Not found`:
     The specified logic is unknown.
+
+
+---------------
+Reserve control
+---------------
+
+This section is about a proposed API. It is not implemented.
+
+.. http:post:: /reserves/$RESERVE_PUB/open
+
+  Request keeping a reserve open for tipping or invoicing.
+
+  **Request:**
+
+  The request body must be a `ReserveOpenRequest` object.
+
+  **Response:**
+
+  :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.
+  :http:statuscode:`403 Forbidden`:
+    The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* 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:`451 Unavailable For Legal Reasons`:
+    This account has not yet passed the KYC checks.
+    The client must pass KYC checks before the reserve can be opened.
+    The response will be an `KycNeededRedirect` object.
+
+  **Details:**
+
+  .. ts:def:: ReserveOpenRequest
+
+    interface ReserveOpenRequest {
+      // Signature of purpose
+      // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over
+      // a `TALER_ReserveOpenRequestSignaturePS`.
+      reserve_sig: EddsaSignature;
+
+      // Time when the client made the request.
+      // Timestamp must be reasonably close to the time of
+      // the exchange, otherwise the exchange may reject
+      // the request (with a status code of 400).
+      request_timestamp: Timestamp;
+
+      // Desired new expiration time for the reserve.
+      // If the reserve would expire before this time,
+      // the exchange will charge account fees (and
+      // possibly KYC fees) until the expiration time
+      // exceeds this timestamp. Note that the exchange
+      // will refuse requests (with a status code of 400)
+      // if the time is so far in the future that the
+      // fees are not yet known (see /keys).
+      reserve_expiration: Timestamp;
+
+      // Desired open purse limit. Can be used to pay the
+      // annual account fee more than once to get a larger
+      // purse limit.
+      purse_limit: Integer;
+
+    }
+
+  .. 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.
+      reserve_expiration: Timestamp;
+    }
+
+  .. ts:def:: RequiredBalanceResponse
+
+    interface RequiredBalanceResponse {
+      // Balance left in the reserve after the account_fee
+      // was charged.
+      balance: Amount;
+
+      // Transaction cost for extending to the
+      // requested expiration time.
+      // Includes applicable KYC fees.
+      required: Amount;
+
+    }
+
+
+
+.. http:post:: /reserves/$RESERVE_PUB/close
+
+  Force immediate closure of a reserve. Does not actually
+  delete the reserve or the KYC data, but merely forces
+  the reserve's current balance to be wired back to the
+  account where it originated from, or another account of
+  the user's choosing if they performed the required KYC
+  check and designated another target account.
+
+  **Request:**
+
+  The request body must be a `ReserveCloseRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The exchange responds with a `ReserveCloseResponse` object.
+  :http:statuscode:`403 Forbidden`:
+    The *TALER_SIGNATURE_WALLET_RESERVE_CLOSE* 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`:
+    No target account was given, and the exchange does not know an
+    origin account for this reserve.
+  :http:statuscode:`451 Unavailable For Legal Reasons`:
+    This account has not yet passed the KYC checks, hence wiring
+    funds to a non-origin account is not allowed.
+    The client must pass KYC checks before the reserve can be opened.
+    The response will be an `KycNeededRedirect` object.
+
+  **Details:**
+
+  .. ts:def:: ReserveCloseRequest
+
+    interface ReserveCloseRequest {
+      // Signature of purpose
+      // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE`` over
+      // a `TALER_ReserveCloseRequestSignaturePS`.
+      reserve_sig: EddsaSignature;
+
+      // Time when the client made the request.
+      // Timestamp must be reasonably close to the time of
+      // the exchange, otherwise the exchange may reject
+      // 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
+      // method is not supported, this is a bad request (400)).
+      // If not given, the reserve's origin account
+      // will be used. If no origin account is known for the
+      // reserve and not given, this is a conflict (409).
+      payto_uri?: string;
+
+    }
+
+  .. 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;
+
+    }

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