commit 2f0225baa19f8b8fad884823e9f0dd89161584fd
parent 6994fe263616520eb88951898b3aad317d439ca3
Author: Özgür Kesim <oec@kesim.org>
Date: Wed, 2 Apr 2025 23:07:53 +0200
[withdraw] simplify structures and update /reveal-withdraw for v26
Diffstat:
2 files changed, 61 insertions(+), 100 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -1235,57 +1235,6 @@ within the
`exchange's codebase <https://docs.taler.net/global-licensing.html#exchange-repo>`_.
-.. _TALER_WithdrawRequestDetailsP:
-.. sourcecode:: c
-
- struct TALER_WithdrawRequestDetailsP {
-
- /**
- * 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.
- * 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 TALER_HashPlanchetsP 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;
-
- };
-
.. _TALER_HashPlanchetsP:
.. sourcecode:: c
@@ -1324,34 +1273,6 @@ within the
};
-.. _TALER_WithdrawCommitmentP:
-.. sourcecode:: c
-
- struct TALER_WithdrawCommitmentP {
- /**
- * The hash of the reserve's public key
- */
- struct TALER_HashReservePublicKeyP h_reserve_pub;
- /**
- * The details of the withdraw request
- */
- struct TALER_WithdrawRequestDetailsP details;
- };
-
-
-.. _TALER_WithdrawCommitmentHashP:
-.. sourcecode:: c
-
- /**
- * Hash of the `TALER_WithdrawCommitmentP`,
- * representing a withdraw request. Will become the $RCH in the
- * reveal URL.
- */
- struct TALER_WithdrawCommitmentHashP
- {
- struct GNUNET_HashCode hash;
- };
-
.. _TALER_WithdrawRequestPS:
.. sourcecode:: c
@@ -1367,10 +1288,55 @@ within the
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+
+ /**
+ * 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;
+
/**
- * The details of the withdraw request
+ * Total fee for the withdrawal.
+ * Note that the reserve must have a value of at least amount+fee.
*/
- struct TALER_WithdrawRequestDetailsP details;
+ 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]
+ *
+ * Note also that this value is required for /recoup and
+ * -- in case of a withdraw request with required age proof --
+ * in the subsequent call to /reveal-withdraw
+ */
+ struct TALER_HashPlanchetsP h_planchets;
+
+ /**
+ * If age restriction proof is required, the maximum age _group_
+ * to commit to, 0 otherwise. Note that in this case, 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;
+
};
@@ -1394,10 +1360,10 @@ within the
struct TALER_WithdrawCommitmentHashP h_commitment;
/**
- * If age restriction does not apply to this withdrawal,
+ * If proof of age restriction is not required for to this withdrawal,
* (i.e. max_age was not set during the request)
* MUST be 0xFFFFFFFF.
- * Otherwise (i.e. age restriction applies):
+ * Otherwise (i.e. proof of age restriction required):
* index that the client will not have to reveal, in NBO,
* MUST be smaller than #TALER_CNC_KAPPA.
*/
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -1524,10 +1524,10 @@ exchange.
// @since protocol **v23**.
last_origin?: string;
- // If set, age restriction is required to be set for each coin to this
- // value during the withdrawal from this reserve. The client then MUST
- // use a denomination with support for age restriction enabled for the
- // withdrawal.
+ // If set, proof of age restriction is required and age restriction needs
+ // to be set for each coin to this value during the withdrawal from this reserve.
+ // The client then MUST use a denomination with support for age restriction enabled
+ // for the withdrawal and MUST set an appropriate value for ``max_age``
// The value represents a valid age group from the list of permissible
// age groups as defined by the exchange's output to /keys.
maximum_age_group?: number;
@@ -2073,13 +2073,13 @@ These endpoints are called by the client
Now the client has to disclose --for each coin--
all but one of the κ secrets that went into creating the blinded coin's planchets,
the transfer public keys (linking the ownership of the old and new coin),
- and the commitent to age restriction,
+ and the commitment to age restriction,
as proof that the age restriction was set correctly (if applicable).
#. after a call to `Withdraw`_, *if* the original request had ``max_age`` set
and the response was of type `AgeWithdrawResponse`.
Now the client has to disclose for each coin all but one of the κ secrets
that went into creating the blinded coin's planchets,
- including the commitent to age restriction,
+ including the commitment to age restriction,
and prove that the age restriction was set correctly.
@@ -2216,7 +2216,7 @@ These endpoints are called by the client
Error code:
``TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE``.
- The computation of the hash of the commitment with provided input does
- result in the value of field ``withdraw_commitment_h``.
+ result in the value of field ``h_planchets``.
Error code:
``TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH``
@@ -2228,9 +2228,9 @@ These endpoints are called by the client
.. ts:def:: RevealWithdrawRequest
interface RevealWithdrawRequest {
- // The hash of the withdraw commitment (`TALER_WithdrawCommitmentHashP`)
+ // The running hash of all blinded planchets
// from the previous call to /withdraw.
- withdraw_commitment_h: string;
+ h_planchets: string;
// Array of ``(kappa - 1)`` disclosed batch secrets,
// from which for each of the n coins in a batch
@@ -2440,12 +2440,8 @@ Reserve History
// created with the reserve's private key.
reserve_sig: EddsaSignature;
- // The hash of the withdraw commitment (TALER_WithdrawCommitmentHashP)
- // from the previous call to /withdraw.
- h_commitment: HashCode;
-
// The hash of the all the planchets that were provided during the
- // call to /withdraw. Needed to re-calculate withdraw_commitment_h
+ // call to /withdraw.
h_planchets: HashCode;
// The array of blinded coins to be signed.
@@ -3968,9 +3964,8 @@ in using this API.
// Signature over the `coin public key <eddsa-coin-pub>` by the denomination.
denom_sig: DenominationSignature;
- // The hash of the original withdraw commitment (TALER_WithdrawCommitmentHashP)
- // that this coin was part of.
- withdraw_commitment_hash: HashCode;
+ // The hash of the original withdraw commitment that this coin was part of.
+ h_planchets: HashCode;
// The hash of the age-commitment for the coin. Only present
// if the denomination has support for age restriction.
