taler-docs

commit 5b44b7e1ab43bef85d0a47ed9aed7e8d9286c9d5
parent 7cb9e3002ee7c24e34be4eb21714e69e609f49e2
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Thu, 11 Dec 2025 19:06:30 +0100

[exchange] improve wording in the description of MeltRequest

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

1 file changed, 14 insertions(+), 11 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -2198,27 +2198,30 @@ Melt
        refresh_seed: HashCode;
 
        // @since vDOLDPLUS
-       // This value is opaque to the exchange.  It was provided by the client
-       // as part of the original refresh request, and was therefore
-       // verified with the coin_sig below.
        //
-       // Note:  The honest owner of the old coin SHOULD use this value
+       // 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 honest owner of the old coin SHOULD use this value
        // and the old coin's private key to derive kappa many
-       // transfer secret batch seeds like this:
+       // 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 kappa seeds is then expanded via HKDF:
+       // Each of the batch seeds is then 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]``
-       // 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.
+       // coin index i in the batch is then ``ts[k][i]``.
        master_refresh_seed: HashCode;
 
        // Master seed for the Clause-Schnorr R-value