taler-docs

commit ac19cf5dc38d9d6b0866177edb5b757166a201c6
parent 5460fdaf2d1e7481ccbf7458dc03f0aa078a4aea
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Fri, 28 Nov 2025 19:46:43 +0100

[exchange] WIP: old but updated Dold'19 refresh

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

2 files changed, 35 insertions(+), 13 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -836,7 +836,7 @@ When no sign is present, the amount is assumed to be positive.
     uint8_t currency_code[12];
   };
 
-  
+
 Images
 ^^^^^^
 
@@ -1327,7 +1327,7 @@ within the
      * to κ index=1 etc:
      * h[0][0]…h[0][n-1]h[1][0]…h[1][n-1] … h[κ-1][0]…h[κ-1][n-1]
      *
-     * Note also that this value is required for /recoup and 
+     * Note also that this value is required for /recoup and
      * -- in case of a withdraw request with required age proof --
      * in the subsequent call to /reveal-withdraw
      */
@@ -1339,7 +1339,7 @@ within the
      struct TALER_BlindingMasterSecretP blinding_seed;
     /**
      * If age restriction proof is required, the maximum age _group_
-     * to commit to, 0 otherwise. Note that in this case, all 
+     * to commit to, 0 otherwise. Note that in this case, all
      * denominations for all coins MUST support age restriction.
      * Also note that this is not an age (in years), but the age group
      * (an index) according to list of age groups in the configuration
@@ -1374,7 +1374,7 @@ within the
     struct TALER_HashBlindedPlanchetsP h_planchets;
 
     /**
-     * If proof of age restriction is not required for to this 
+     * If proof of age restriction is not required for to this
      * withdrawal, (i.e. max_age was not set during the request)
      * MUST be 0xFFFFFFFF.
      * Otherwise (i.e. proof of age restriction required):
@@ -1442,15 +1442,20 @@ within the
   };
 
 
-.. _TALER_RefreshMeltCoinAffirmationPS:
+.. _TALER_RefreshCommitmentP:
 .. sourcecode:: c
 
-  struct TALER_RefreshMeltCoinAffirmationPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_MELT
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+  struct TALER_RefreshCommitmentP {
     /**
+     * Starting with vDOLDPLUS this is defined as:
+     * Hash over:
+     *   1. kappa hashes of tranfer public keys: H(T_1),...,H(T_κ)
+     *   2. hash over all pairs of R-values (for CS) if present, skipped otherwise
+     *   3. list of denomination hashes, in order
+     *   4. amount with fee
+     *   5. kappa list of n planchets, depths first: [0..n),[0..n),[0..n)
+     *
+     * Before vDOLDPLUS this was defined as:
      * Hash over:
      *   1. refresh_seed (v27)
      *   2. the hash over all pairs of R-values if present, skipped otherwise
@@ -1458,6 +1463,17 @@ within the
      *   4. amount with fee
      *   5. kappa list of n planchets, depths first: [0..n),[0..n),[0..n)
      */
+     struct GNUNET_HashCode session_hash;
+ };
+
+.. _TALER_RefreshMeltCoinAffirmationPS:
+.. sourcecode:: c
+
+  struct TALER_RefreshMeltCoinAffirmationPS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_MELT
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
     struct TALER_RefreshCommitmentP session_hash;
     struct TALER_DenominationHash h_denom_pub;
     struct TALER_AgeCommitmentHash h_age_commitment;
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -2059,7 +2059,7 @@ These endpoints are called by the client
       //   4. amount with fee (NBO)
       //   5. kappa*n blinded planchet hashes (which include denomination information),
       //      depths first: [0..n)[0..n)[0..n)
-      rc: string;
+      rc: HashCode;
 
       // The disclosed kappa-1 signatures by the old coin's private key,
       // over Hash1a("Refresh", Cp, r, i), where Cp is the melted coin's public key,
@@ -3365,7 +3365,7 @@ by anyone except the wallet itself.
   exchange. The exchange MUST return a 307 or 308 redirection to the correct
   base URL if this is the case.
 
-  This endpoint was introduced in this form in protocol **v27**.
+  This endpoint was introduced in this form in protocol **vDOLDPLUS**.
 
   :http:statuscode:`200 OK`:
     The request was successful.  The response body is `MeltResponse` in this case.
@@ -3416,9 +3416,10 @@ by anyone except the wallet itself.
        //      + sum over all withdraw fees for the fresh coins
        value_with_fee: Amount;
 
+       // NOTE: This value was only used since v27 and before vDOLDPLUS!
        // Seed from which the nonces for the n*κ coin candidates are derived
        // from.
-       refresh_seed: HashCode;
+       refresh_seed?: HashCode;
 
        // Master seed for the Clause-Schnorr R-value
        // creation. Must match the /blinding-prepare request.
@@ -3435,6 +3436,11 @@ by anyone except the wallet itself.
        // each matching the respective entries in ``denoms_h``.
        coin_evs: CoinEnvelope[kappa][];
 
+       // NOTE: This value is required starting from vDOLDPLUS.
+       // ``kappa`` arrays of ``n`` entries of transwer public keys each.
+       // These are ephemeral ECDHE keys.
+       transfer_pubs: EddsaPublicKey[kappa][];
+
        // Signature by the `coin <coin-priv>` over `TALER_RefreshMeltCoinAffirmationPS`.
        confirm_sig: EddsaSignature;