taler-docs

commit 23575f9d30be7c161b8514681eef67fb970aa2c7
parent 5b44b7e1ab43bef85d0a47ed9aed7e8d9286c9d5
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Thu, 11 Dec 2025 21:07:13 +0100

[exchange] more clearity in the description of master_refresh_seed

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

1 file changed, 16 insertions(+), 11 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -2175,7 +2175,8 @@ Melt
        // The old coin's public key
        old_coin_pub: CoinPublicKey;
 
-       // Hash of the denomination public key of the old coin, to determine total coin value.
+       // Hash of the denomination public key of the old coin,
+       // to determine total coin value.
        old_denom_pub_h: HashCode;
 
        // The hash of the age-commitment for the old coin. Only present
@@ -2198,28 +2199,32 @@ Melt
        refresh_seed: HashCode;
 
        // @since vDOLDPLUS
-       //
-       // Note: This value is opaque to the exchange.
-       // It is provided by the client as part of this refresh request,
-       // and is therefore verified with the coin_sig below.
-       // This ensures that the honest owner of the old coin can replay
-       // a MeltRequest from the coin history provided by the exchange
-       // (which includes this value), in case a wallet was restored
-       // from a backup into a state prior to the refresh operation.
+       // The ``master_refresh_seed`` is an opaque value to the exchange.
+       // It is provided by the client and is verified with the ``coin_sig`` below.
+       // Its purpose is to ensure that the honest owner of the old coin
+       // can replay a /melt request from data in the coin history,
+       // provided by the exchange and including this value, in case a wallet
+       // was restored into a state prior to the refresh operation.
        //
        // The honest owner of the old coin SHOULD use this value
        // and the old coin's private key to derive kappa many
        // batch seeds (one for each cut-and-choose candidate)
        // like this:
+       //
        //   ``bs[] = HKDF(kappa*sizeof(HashCode),``
        //               ``"refresh-batch-seeds",``
        //               ``old_coin_priv,``
        //               ``master_refresh_seed)``
-       // Each of the batch seeds is then expanded to a batch of
-       // n transfer secrets via HKDF:
+       //
+       // These batch seeds (however constructed) are relevant in the
+       // subsequent reveal step of the cut-and-chose.  There, each of the
+       // revealed batch seeds is expanded to a batch of ``n`` transfer secrets
+       // via HKDF:
+       //
        //   ``ts[k][] = HKDF(n*sizeof(HashCode),``
        //                  ``"refresh-batch-transfer-secrets",``
        //                  ``bs[k])``
+       //
        // An individual coin's transfer secret at kappa-index k and
        // coin index i in the batch is then ``ts[k][i]``.
        master_refresh_seed: HashCode;