taler-docs

commit 71a20478b626a13385fe920726e2f86d977a1708
parent ab7fe96d33500c562933916d895e3a51dd74434d
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Mon, 14 Jul 2025 18:48:08 +0200

[exchange] refine /recoup-withdraw req and resp

Diffstat:
M
core/api-exchange.rst
 | 
36
+++++++++++++++++++++---------------

1 file changed, 21 insertions(+), 15 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1648,6 +1648,12 @@ exchange.
       // @since protocol **v23**.
       last_origin?: string;
 
+      // The expiration date of the reserve.
+      // Any residual value of in the reserve after this date
+      // will be returned to the ``last_origin``, if present.
+      // @since protocol **vRECOUP**.
+      reserve_expiration: Timestamp;
+
       // If set, proof of age restriction is required and age restriction needs
       // to be set for each coin to this value during the withdrawal from this reserve.
       // The client then MUST use a denomination with support for age restriction enabled
@@ -3464,11 +3470,7 @@ became minted, and proof ownership of the coin itself.
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `RecoupWithdrawalConfirmation`.
-    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 `ReserveSummary`.
   :http:statuscode:`403 Forbidden`:
     A coin's signature is invalid.
     This response comes with a standard `ErrorDetail` response.
@@ -3498,6 +3500,10 @@ became minted, and proof ownership of the coin itself.
   .. ts:def:: RecoupWithdrawRequest
 
     interface RecoupWithdrawRequest {
+      // Public key of the reserve that will receive the recoup.
+      // MUST be the same as the one from the original withdraw.
+      reserve_pub: EddsaPublicKey;
+
       // The details about the coins:
       // An array of either
       // a) the hash code of a blinded coin envelope (not to be recouped)
@@ -3519,15 +3525,22 @@ became minted, and proof ownership of the coin itself.
   .. ts:def:: NonRecoupedCoin
 
     interface  NonRecoupedCoin {
-      type: "ev_hash";
+      type: "non_recouped_coin";
 
       // This is the SHA512 hash code of a blinded coin envelope,
       // including the corresponding denomination's hash.
       // It is the output of the TALER_coin_ev_hash function
       // from libtalerutil.
-      h: HashCode;
+      coin_ev: BlindedCoinEnvelopeHash;
     };
 
+  .. ts:def:: BlindedCoinEnvelopeHash
+
+    // The hash value of a blinded coin envelope,
+    // as it its generated by the function TALER_coin_ev_hash
+    // in libtalerutil.
+    type BlindedCoinEnvelopeHash = HashCode;
+
   .. ts:def:: RecoupDisclosedCoinDetails
 
     // This object provides all necessary coin data
@@ -3538,7 +3551,7 @@ became minted, and proof ownership of the coin itself.
     // for the (unblinded) coin's public key,
     // and the coin's signature to authorize the recoup request.
     interface RecoupDisclosedCoinDetails {
-      type: "details";
+      type: "recoup_coin_details";
 
       // The coin's public key
       coin_pub: CoinPublicKey;
@@ -3575,13 +3588,6 @@ became minted, and proof ownership of the coin itself.
       coin_sig: EddsaSignature;
     }
 
-  .. ts:def:: RecoupWithdrawalConfirmation
-
-    interface RecoupWithdrawalConfirmation {
-      // Public key of the reserve that will receive the recoup.
-      reserve_pub: EddsaPublicKey;
-    }
-
 
 .. http:post:: /coins/$COIN_PUB/recoup-refresh