taler-docs

commit f67600b7f2f35e30655ba998ee4b466bdabda18b
parent 4ff749e8809be1fb46240cbb750df0331955383b
Author: Christian Grothoff <christian@grothoff.org>
Date:   Mon,  3 Feb 2025 10:55:48 +0100

API revision suggestion

Diffstat:
M
core/api-common.rst
 | 
62
+++++++++++++++++++++++++++++++++++++++++++++++++++++++-------

1 file changed, 55 insertions(+), 7 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -1197,21 +1197,25 @@ within the
 .. sourcecode:: c
 
   struct TALER_WithdrawCommitmentP {
+
     /**
      * The reserve's public key
      */
     struct TALER_ReservePublicKeyP reserve_pub;
+
     /**
      * Amount to withdraw, excluding fees, i.e.
      * the total sum of the denominations of the coins.
      * Note that the reserve must have a value of at least amount+fee.
      */
     struct TALER_Amount amount;
+
     /**
      * Total fee for the withdrawal.
      * Note that the reserve must have a value of at least amount+fee.
      */
     struct TALER_Amount fee;
+
     /**
      * This is the running SHA512-hash over all
      * `TALER_BlindedCoinHashP` values of the coins.
@@ -1225,6 +1229,7 @@ within the
      * h[0][0]…h[0][n-1]h[1][0]…h[1][n-1] … h[κ-1][0]…h[κ-1][n-1]
      */
     struct GNUNET_HashCode h_planchets;
+
     /**
      * If age restriction applies, maximum age _group_ to commit to,
      * 0 otherwise.
@@ -1236,6 +1241,7 @@ within the
      * the age group to a given age (in years).
      */
     uint32_t max_age_group;
+
     /**
      * The age groups as configured for the exchange, represented as a mask.
      * If max_age_group is > 0, the mask MUST be non-zero, too.
@@ -1246,9 +1252,10 @@ within the
 .. _TALER_WithdrawCommitmentHashP:
 .. sourcecode:: c
 
-  /*
+  /**
    * Hash of the `TALER_WithdrawCommitmentP`,
-   * representing a withdraw request.
+   * representing a withdraw request. Will become the $RCH in the
+   * reveal URL.
    */
   struct TALER_WithdrawCommitmentHashP
   {
@@ -1265,15 +1272,55 @@ within the
    */
   struct TALER_WithdrawRequestPS
   {
-  /**
-   * Purpose is #TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
-   */
+    /**
+     * Purpose is #TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
+     */
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 
     /**
-     * The hash of the `TALER_WithdrawCommitmentP` for the withdraw
+     * Amount to withdraw, excluding fees, i.e.
+     * the total sum of the denominations of the coins.
+     * Note that the reserve must have a value of at least amount+fee.
      */
-    struct TALER_WithdrawCommitmentHashP h_commitment;
+    struct TALER_Amount amount;
+
+    /**
+     * Total fee for the withdrawal.
+     * Note that the reserve must have a value of at least amount+fee.
+     */
+    struct TALER_Amount fee;
+
+    /**
+     * This is the running SHA512-hash over all
+     * `TALER_BlindedCoinHashP` values of the coins.
+     * Note that each `TALER_BlindedCoinHashP` itself
+     * captures the hash of the corresponding denomination's
+     * public key.
+     * If max_age was set in the withdraw request, there will be
+     * n*κ many such values. The iteration MUST be first over
+     * all coins belonging to κ index=0, then all coins
+     * 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]
+     */
+    struct GNUNET_HashCode h_planchets;
+
+    /**
+     * If age restriction applies, maximum age _group_ to commit to,
+     * 0 otherwise.
+     * Note that if age restriction applies, 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
+     * of the exchange.  See TALER_get_max_group() how to calculate
+     * the age group to a given age (in years).
+     */
+    uint32_t max_age_group;
+
+    /**
+     * The age groups as configured for the exchange, represented as a mask.
+     * If max_age_group is > 0, the mask MUST be non-zero, too.
+     */
+    struct TALER_AgeMask mask;
   };
 
 
@@ -1292,6 +1339,7 @@ within the
 
     /**
      * Commitment made in the /reserves/$RESERVE_PUB/withdraw.
+     * Also the $RCH value for the reveal endpoint.
      */
     struct TALER_WithdrawCommitmentHashP h_commitment;