[taler-docs] branch master updated: remove non-batched withdraw from 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 449d4123 remove non-batched withdraw from API
449d4123 is described below

commit 449d41231fdda77a38ca6cb2d5ac714013543edb
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Sun Oct 15 22:40:22 2023 +0200

    remove non-batched withdraw from API
---
 core/api-exchange.rst | 177 ++++++++++++++++----------------------------------
 1 file changed, 55 insertions(+), 122 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 5bdebef0..3992b7e2 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -1720,28 +1720,31 @@ Withdraw
     }
 
 
-.. http:post:: /reserves/$RESERVE_PUB/withdraw
+Batch Withdraw
+~~~~~~~~~~~~~~
+
+.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw
 
-  Withdraw a coin of the specified denomination.  Note that the client should
-  commit all of the request details, including the private key of the coin and
-  the blinding factor, to disk *before* issuing this request, so that it can
+  Withdraw multiple coins from the same reserve.  Note that the client should
+  commit all of the request details, including the private key of the coins and
+  the blinding factors, to disk *before* issuing this request, so that it can
   recover the information if necessary in case of transient failures, like
   power outage, network outage, etc.
 
-  **Request:** The request body must be a `WithdrawRequest` object.
+  **Request:** The request body must be a `BatchWithdrawRequest` object.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `WithdrawResponse`.  
Note that repeating exactly the same request
-    will again yield the same response, so if the network goes down during the
-    transaction or before the client can commit the coin signature to disk, the
-    coin is not lost.
+    The request was successful, and the response is a `BatchWithdrawResponse`.
+    Note that repeating exactly the same request will again yield the same
+    response, so if the network goes down during the transaction or before the
+    client can commit the coin signature to disk, the coin is not lost.
   :http:statuscode:`403 Forbidden`:
-    The signature is invalid.
+    A signature is invalid.
     This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
-    The denomination key or the reserve are not known to the exchange.  If the
+    A denomination key or the reserve are not known to the exchange.  If the
     denomination key is unknown, this suggests a bug in the wallet as the
     wallet should have used current denomination keys from ``/keys``.
     In this case, the response will be a `DenominationUnknownMessage`.
@@ -1759,11 +1762,11 @@ Withdraw
     2. The reserve has a birthday set and requires a request to 
``/age-withdraw`` instead.
     The response comes with a standard `ErrorDetail` response with error-code 
``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED`` and an additional field 
``maximum_allowed_age`` for the maximum age (in years) that the client can 
commit to in the call to ``/age-withdraw``
   :http:statuscode:`410 Gone`:
-    The requested denomination key is not yet or no longer valid.
-    It either before the validity start, past the expiration or was revoked. 
The response is a
-    `DenominationExpiredMessage`. Clients must evaluate
-    the error code provided to understand which of the
-    cases this is and handle it accordingly.
+    A requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was revoked.
+    The response is a `DenominationExpiredMessage`. Clients must evaluate the
+    error code provided to understand which of the cases this is and handle it
+    accordingly.
   :http:statuscode:`451 Unavailable for Legal Reasons`:
     This reserve has received funds from a purse or the amount withdrawn
     exceeds another legal threshold and thus the reserve must
@@ -1786,37 +1789,14 @@ Withdraw
 
   **Details:**
 
-  .. ts:def:: DenominationExpiredMessage
-
-    interface DenominationExpiredMessage {
-
-      // Taler error code.  Note that beyond
-      // expiration this message format is also
-      // used if the key is not yet valid, or
-      // has been revoked.
-      code: number;
-
-      // Signature by the exchange over a
-      // `TALER_DenominationExpiredAffirmationPS`.
-      // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``.
-      exchange_sig: EddsaSignature;
-
-      // Public key of the exchange used to create
-      // the 'exchange_sig.
-      exchange_pub: EddsaPublicKey;
-
-      // Hash of the denomination public key that is unknown.
-      h_denom_pub: HashCode;
+  .. ts:def:: BatchWithdrawRequest
 
-      // When was the signature created.
-      timestamp: Timestamp;
+    interface BatchWithdrawRequest {
+      // Array of requests for the individual coins to withdraw.
+      planchets: WithdrawRequest[];
 
-      // What kind of operation was requested that now
-      // failed?
-      oper: string;
     }
 
-
   .. ts:def:: WithdrawRequest
 
     interface WithdrawRequest {
@@ -1835,7 +1815,17 @@ Withdraw
 
     }
 
-  .. ts:def:: WithdrawResponse
+
+  .. ts:def:: BatchWithdrawResponse
+
+    interface BatchWithdrawResponse {
+      // Array of blinded signatures, in the same order as was
+      // given in the request.
+      ev_sigs: WithdrawResponse[];
+
+    }
+
+    .. ts:def:: WithdrawResponse
 
     interface WithdrawResponse {
       // The blinded signature over the 'coin_ev', affirms the coin's
@@ -1914,96 +1904,39 @@ Withdraw
       history: TransactionHistoryItem[]
     }
 
+  .. ts:def:: DenominationExpiredMessage
 
+    interface DenominationExpiredMessage {
 
+      // Taler error code.  Note that beyond
+      // expiration this message format is also
+      // used if the key is not yet valid, or
+      // has been revoked.
+      code: number;
 
-Batch Withdraw
-~~~~~~~~~~~~~~
-
-
-.. http:post:: /reserves/$RESERVE_PUB/batch-withdraw
-
-  Withdraw multiple coins from the same reserve.  Note that the client should
-  commit all of the request details, including the private key of the coins and
-  the blinding factors, to disk *before* issuing this request, so that it can
-  recover the information if necessary in case of transient failures, like
-  power outage, network outage, etc.
-
-  **Request:** The request body must be a `BatchWithdrawRequest` object.
-
-  **Response:**
-
-  :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `BatchWithdrawResponse`.
-    Note that repeating exactly the same request will again yield the same
-    response, so if the network goes down during the transaction or before the
-    client can commit the coin signature to disk, the coin is not lost.
-  :http:statuscode:`403 Forbidden`:
-    A signature is invalid.
-    This response comes with a standard `ErrorDetail` response.
-  :http:statuscode:`404 Not found`:
-    A denomination key or the reserve are not known to the exchange.  If the
-    denomination key is unknown, this suggests a bug in the wallet as the
-    wallet should have used current denomination keys from ``/keys``.
-    In this case, the response will be a `DenominationUnknownMessage`.
-    If the reserve is unknown, the wallet should not report a hard error yet, 
but
-    instead simply wait for up to a day, as the wire transaction might simply
-    not yet have completed and might be known to the exchange in the near 
future.
-    In this case, the wallet should repeat the exact same request later again
-    using exactly the same blinded coin.
-  :http:statuscode:`409 Conflict`:
-    One of the following reasons occured:
-
-    1. The balance of the reserve is not sufficient to withdraw the coins of 
the
-    indicated denominations.  The response is `WithdrawError` object.
-
-    2. The reserve has a birthday set and requires a request to 
``/age-withdraw`` instead.
-    The response comes with a standard `ErrorDetail` response with error-code 
``TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED`` and an additional field 
``maximum_allowed_age`` for the maximum age (in years) that the client can 
commit to in the call to ``/age-withdraw``
-  :http:statuscode:`410 Gone`:
-    A requested denomination key is not yet or no longer valid.
-    It either before the validity start, past the expiration or was revoked.
-    The response is a `DenominationExpiredMessage`. Clients must evaluate the
-    error code provided to understand which of the cases this is and handle it
-    accordingly.
-  :http:statuscode:`451 Unavailable for Legal Reasons`:
-    This reserve has received funds from a purse or the amount withdrawn
-    exceeds another legal threshold and thus the reserve must
-    be upgraded to an account (with KYC) before the withdraw can
-    complete.  Note that this response does NOT affirm that the
-    withdraw will ultimately complete with the requested amount.
-    The user should be redirected to the provided location to perform
-    the required KYC checks to open the account before withdrawing.
-    Afterwards, the request should be repeated.
-    The response will be an `KycNeededRedirect` object.
-
-    Implementation note: internally, we need to
-    distinguish between upgrading the reserve to an
-    account (due to P2P payment) and identifying the
-    owner of the origin bank account (due to exceeding
-    the withdraw amount threshold), as we need to create
-    a different payto://-URI for the KYC check depending
-    on the case.
-
+      // Signature by the exchange over a
+      // `TALER_DenominationExpiredAffirmationPS`.
+      // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``.
+      exchange_sig: EddsaSignature;
 
-  **Details:**
+      // Public key of the exchange used to create
+      // the 'exchange_sig.
+      exchange_pub: EddsaPublicKey;
 
-  .. ts:def:: BatchWithdrawRequest
+      // Hash of the denomination public key that is unknown.
+      h_denom_pub: HashCode;
 
-    interface BatchWithdrawRequest {
-      // Array of requests for the individual coins to withdraw.
-      planchets: WithdrawRequest[];
+      // When was the signature created.
+      timestamp: Timestamp;
 
+      // What kind of operation was requested that now
+      // failed?
+      oper: string;
     }
 
 
-  .. ts:def:: BatchWithdrawResponse
 
-    interface BatchWithdrawResponse {
-      // Array of blinded signatures, in the same order as was
-      // given in the request.
-      ev_sigs: WithdrawResponse[];
 
-    }
 
 Withdraw with Age Restriction
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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