taler-docs

commit 2c37eb1c43c7d6e07db2643ad977b6d732098114
parent 7ca305587f4d887b6e08eb7d5b81037997152416
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Mon, 14 Jul 2025 12:58:00 +0200

[exchange] complete recoup request object for withdraw-case

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

1 file changed, 35 insertions(+), 6 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1497,10 +1497,6 @@ Bachelor thesis of Gian Demarmels and Lucien Heuzeveldt,
 `Adding Schnorr’s Blind Signature in Taler <https://www.taler.net/papers/cs-thesis.pdf>`_,
 for details.
 
-
-   for ``/csr-withdraw`` and ``/csr-melt``.
-
-
 .. http:post:: /blinding-prepare
 
   Obtain exchange-side input values in preparation for a
@@ -3517,12 +3513,31 @@ became minted, and proof ownership of the coin itself.
 
   .. ts:def:: RecoupCoinData
 
+    // This is either
+    // a) the hash code of a blinded coin envelope (not to be recouped)
+    // b) the disclosed coin details, in order to recoup it.
     type RecoupCoinData =
-      | HashCode
-      | RecoupDisclosedCoinDetails
+       | BlindedEnvelopeHash
+       | RecoupDisclosedCoinDetails
+
+  .. ts:def:: BlindedEnvelopeHash
+
+    // 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.
+    type BlindedEnvelopeHash = HashCode;
+
 
   .. ts:def:: RecoupDisclosedCoinDetails
 
+    // This object provides all necessary coin data
+    // in order to call TALER_denom_blind and retrieve
+    // a blinded coin planchet, from which we can
+    // calculate the blinded coin envelope hash.
+    // It also contains the denomination's signature
+    // for the (unblinded) coin's public key,
+    // and the coin's signature to authorize the recoup request.
     interface RecoupDisclosedCoinDetails {
       // The coin's public key
       coin_pub: CoinPublicKey;
@@ -3531,6 +3546,20 @@ became minted, and proof ownership of the coin itself.
       // that was used during withdraw
       coin_blinding_key_secret: DenominationBlindingKeySecret;
 
+      // The coin's commitment for age restriction,
+      // if the denomination had age restriction support.
+      age_commitment_h?: AgeCommitmentHash;
+
+      // The blinding nonce that went into this coin's
+      // blinded envelope
+      cs_session_nonce?: HashCode;
+
+      // In case of Clause-Schnorr denomination,
+      // the blinding values that were provided
+      // for this coin, by the exchange, as response
+      // to a call to /blinding-prepare.
+      cs_r_pubs?: CSRPublicPair;
+
       // Unblinded signature of the coins' public key,
       // signed by the denomination key.
       denom_pub_sig: DenominationSignature;