commit 449d41231fdda77a38ca6cb2d5ac714013543edb
parent f50f671753e331703c2920af1b54f604ccea8333
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Sun, 15 Oct 2023 22:40:22 +0200
remove non-batched withdraw from API
Diffstat:
| M | core/api-exchange.rst | | | 177 | +++++++++++++++++++++++++------------------------------------------------------ |
1 file changed, 55 insertions(+), 122 deletions(-)
diff --git 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
