taler-docs

commit d4592ab7e7efe4dd6d031ff8f9c7b5361afd6f11
parent 4ac0247e531abfbe941f9a42be350e720e3e323c
Author: Özgür Kesim <oec-taler@kesim.org>
Date:   Sat, 25 Jan 2025 12:26:42 +0100

[exchange] TALER_WithdrawRequestPS refinement

The struct TALER_WithdrawRequestPS encapsulates
the hash of the withdraw commitment, not the withdraw data.
The hash of the commitment is needed for /reveal-withdraw (in case of
age-retriction) and /recoup, so we require the wallet to sign its value
for the withdraw request.

Diffstat:
M
core/api-common.rst
 | 
48
+++++++++++++++++++++++++++++++++++++++---------
M
core/api-exchange.rst
 | 
3
+--

2 files changed, 40 insertions(+), 11 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -1191,18 +1191,14 @@ Taler. Their definition is typically found in ``src/include/taler_signatures.h``
 within the
 `exchange's codebase <https://docs.taler.net/global-licensing.html#exchange-repo>`_.
 
-.. _TALER_WithdrawRequestPS:
-
-.. note::
-   struct ``TALER_WithdrawRequestPS`` is first introduced with protocol version v24.
 
+.. _TALER_WithdrawCommitmentP:
 .. sourcecode:: c
 
-  struct TALER_WithdrawRequestPS {
+  struct TALER_WithdrawCommitmentP {
     /**
-     * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
+     * The reserve's public key
      */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
     struct TALER_ReservePublicKeyP reserve_pub;
     /**
      * Amount to withdraw, excluding fees, i.e.
@@ -1246,6 +1242,40 @@ within the
     struct TALER_AgeMask mask;
   };
 
+.. _TALER_WithdrawCommitmentHashP:
+.. sourcecode:: c
+
+  /*
+   * Hash of the `TALER_WithdrawCommitmentP`,
+   * representing a withdraw request.
+   */
+  struct TALER_WithdrawCommitmentHashP
+  {
+    struct GNUNET_HashCode hash;
+  };
+
+
+.. _TALER_WithdrawRequestPS:
+.. sourcecode:: c
+
+  /**
+   * Format used for to generate the signature on a request to withdraw
+   * coins from a reserve.
+   */
+  struct TALER_WithdrawRequestPS
+  {
+  /**
+   * Purpose is #TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
+   */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+
+    /**
+     * The hash of the `TALER_WithdrawCommitmentP` for the withdraw
+     */
+    struct TALER_WithdrawCommitmentHashP h_commitment;
+  };
+
+
 
 .. _TALER_WithdrawConfirmationPS:
 
@@ -1254,8 +1284,8 @@ within the
   struct TALER_WithdrawConfirmationPS
   {
     /**
-     * Purpose is #TALER_SIGNATURE_EXCHANGE_CONFIRM_WITHDRAW.   Signed by a
-     * `struct TALER_ExchangePublicKeyP` using EdDSA.
+     * Purpose is #TALER_SIGNATURE_EXCHANGE_CONFIRM_WITHDRAW.
+     * Signed by a `struct TALER_ExchangePrivateKeyP` using EdDSA.
      */
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1840,8 +1840,7 @@ Withdraw
       coin_evs:  CoinEnvelope[];
 
       // Signature of `TALER_WithdrawRequestPS` created with
-      // the `reserves's private key <reserve-priv>`
-      // using purpose ``TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW``.
+      // the `reserves's private key <reserve-priv>`.
       reserve_sig: EddsaSignature;
     }