taler-docs

commit 4978e3a9b0b95ac9e484ac09753f9d6e58d16c11
parent 449765705ba009bdd967132e346c9c4af2b34558
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Mon, 30 Dec 2024 16:59:47 +0100

[reveal] each batch only takes one master seed (instead of n)

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

1 file changed, 27 insertions(+), 16 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -2163,34 +2163,45 @@ This endpoint is called by the client
   .. ts:def:: RevealRequest
 
     interface RevealRequest {
-      // Array of ``n`` of ``(kappa - 1)`` disclosed coin master secrets, from
-      // which the coins' private key, blinding, nonce (for Clause-Schnorr),
+      // Array of ``(kappa - 1)`` disclosed batch secrets,
+      // from which for each of the n coins in a batch
+      // their coin master secret is derived,
+      // from which in turn their private key,
+      // blinding, nonce (for Clause-Schnorr),
       // transfer private keys (in case of prior ``/melt``) and
-      // age-restriction  is calculated (in case of prior ``/withdraw``).
-      disclosed_coin_secrets: DisclosedCoinSecret[][];
+      // age-restriction is calculated (in case of prior ``/withdraw``).
+      //
+      // TODO: add details about the derivation.
+      disclosed_batch_seeds: DisclosedBatchSeed[];
 
     }
 
-  .. ts:def:: DisclosedCoinSecret
+  .. ts:def:: DisclosedBatchSeed
 
-    type DisclosedCoinSecret = MasterCoinSecret
-                             | AgeRestrictedCoinSecret
+    // For the reveal of n coins, contains the secret information
+    // from which n coin specific secrets are derived from.
+    // Details of the derivation depend of the specific sum type.
+    type DisclosedBatchSeed = BatchSeed
+                            | AgeRestrictedBatchSeed;
 
 
-  .. ts:def:: MasterCoinSecret
+  .. ts:def:: BatchSeed
 
-    // The master key material from which the coins' private key ``coin_priv``,
-    // blinding ``beta``, nonce ``nonce`` (for Clause-Schnorr) and
+    // The master seed material from which for n coins in a batch,
+    // each coins' private key ``coin_priv``, blinding ``beta``,
+    // nonce ``nonce`` (for Clause-Schnorr) and
     // the transfer private key (to link the new coin to the previous)
     // are derived.
-    // TODO: specification of how exactly this derivation works.
-    type MasterCoinSecret = string
+    //
+    // TODO: add specification of how exactly this derivation works.
+    type BatchSeed = string;
 
 
-  .. ts:def:: AgeRestrictedCoinSecret
+  .. ts:def:: AgeRestrictedBatchSeed
 
-    // The master key material from which the coins' private key ``coin_priv``,
-    // blinding ``beta`` and nonce ``nonce`` (for Clause-Schnorr) itself are
+    // The master seed material from which for n coins in a batch,
+    // each the coins' private key ``coin_priv``,  blinding ``beta``
+    // and nonce ``nonce`` (for Clause-Schnorr) itself are
     // derived as usually in wallet-core.  Given a coin's master key material,
     // the age commitment for the coin MUST be derived from this private key as
     // follows:
@@ -2209,7 +2220,7 @@ This endpoint is called by the client
     // and calculate the corresponding Edx25519PublicKey as
     //   q[$AG] = Edx25519_derive_public(`PublishedAgeRestrictionBaseKey`, f[$AG])
     //
-    type AgeRestrictedCoinSecret = string;
+    type AgeRestrictedBatchSeed = string;
 
   .. ts:def:: PublishedAgeRestrictionBaseKey