commit 2dee57931d27858aa5f2ab0a0fd88ed6481a2272
parent 568f76a371bdb8a954a729e652a8e88fe947201a
Author: Özgür Kesim <oec@codeblau.de>
Date: Thu, 13 Jul 2023 12:06:42 +0200
[age-withdraw] update response types in error cases
Diffstat:
1 file changed, 33 insertions(+), 11 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -2166,8 +2166,13 @@ Withdraw
In this case, the wallet should repeat the exact same request later again
using exactly the same blinded coin.
:http:statuscode:`409 Conflict`:
- The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination.
- The response is `WithdrawError` object.
+ 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`:
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
@@ -2362,8 +2367,13 @@ Batch Withdraw
In this case, the wallet should repeat the exact same request later again
using exactly the same blinded coin.
:http:statuscode:`409 Conflict`:
- The balance of the reserve is not sufficient to withdraw the coins of the
+ 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.
@@ -2443,8 +2453,13 @@ If so, the exchange will blindly sign ``n`` undisclosed coins from the request.
A signature is invalid.
This response comes with a standard `ErrorDetail` response.
:http:statuscode:`409 Conflict`:
- The balance of the reserve is not sufficient to withdraw the coins of the
+ One of two reasons occured:
+
+ 1. The balance of the reserve is not sufficient to withdraw the coins of the
given amount. The response is a `WithdrawError` object.
+
+ 2. The provided value for ``max_age`` is higher than the allowed value according to the reserve's birthday.
+ The response comes with a standard `ErrorDetail` response with error-code ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE`` and an additional field ``maximum_allowed_age`` for the maximum age (in years) that the client can commit to in a 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.
@@ -2527,7 +2542,7 @@ If so, the exchange will blindly sign ``n`` undisclosed coins from the request.
**Response:**
:http:statuscode:`200 OK`:
- The request was successful, and the response is a `RevealResponse`.
+ The request was successful, and the response is a `AgeWithdrawRevealResponse`.
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.
@@ -2537,13 +2552,14 @@ If so, the exchange will blindly sign ``n`` undisclosed coins from the request.
The reveal operation failed and the response is an `WithdrawError` object.
The error codes indicate one of two cases:
- 1. An age commitment for one of the coins did not fulfill the required
- maximum age requirement of the corresponding reserve. Error code:
+ 1. An age commitment for at least one of the coins did not fulfill the
+ required maximum age requirement of the corresponding reserve.
+ Error code:
``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``.
- 2. The sum of all denominations in the request is not equal to the amount
- that was given in the previous commitment via the call to
- /reserves/$RESERVE_PUB/age-withdraw. Error code:
- ``TALER_EC_EXCHANGE_GENERIC_MISMATCH_OF_AMOUNT_AND_DENOMINATIONS``.
+ 2. The computation of the hash of the commitment with provided input does
+ result in the value $ACH.
+ Error code:
+ ``TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH``
.. ts:def:: AgeWithdrawRevealRequest
@@ -2594,6 +2610,12 @@ If so, the exchange will blindly sign ``n`` undisclosed coins from the request.
const PublishedAgeRestrictionBaseKey =
new Edx25519PublicKey("DZJRF6HXN520505XDAWM8NMH36QV9J3VH77265WQ09EBQ76QSKCG");
+ .. ts:def:: AgeWithdrawRevealResponse
+
+ interface AgeWithdrawRevealResponse {
+ // List of the exchange's blinded RSA signatures on the new coins.
+ ev_sigs : BlindedDenominationSignature[];
+ }
.. _deposit-par:
