[taler-docs] branch master updated: [age-withdraw] update response types in error cases

[gnunet]

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

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 2dee5793 [age-withdraw] update response types in error cases
2dee5793 is described below

commit 2dee57931d27858aa5f2ab0a0fd88ed6481a2272
Author: Özgür Kesim <oec@codeblau.de>
AuthorDate: Thu Jul 13 12:06:42 2023 +0200

    [age-withdraw] update response types in error cases
---
 core/api-exchange.rst | 44 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 987e9648..71dec510 100644
--- 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:

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