commit ad213ec8a15157e35931f8a80a9538d27ad44116
parent acce50c33aea094ab88782e9c705cd6db3b4eefe
Author: Özgür Kesim <oec@codeblau.de>
Date: Sat, 7 Nov 2026 12:30:57 +0100
[exchange] v46: fix refresh, coin history and recoup spec (#11916)
Coin history MELT fields match the exchange; history signature, HKDF, noreveal_index width corrected; vRECOUP/vCONFLICT are v42.
Diffstat:
12 files changed, 100 insertions(+), 98 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -437,14 +437,8 @@ hashed data. See `base32`_.
.. ts:def:: RefreshCommitmentHash
- // A refresh commitment corresponding to a call to /melt
- // This is the Hash over:
- // 1. refresh_seed
- // 2. blinding_seed, if provided, skip otherwise
- // 3. denominations in order
- // 4. amount_with_fee
- // 5. κ*n blinded planchet hashes (which include denomination information),
- // depths first: [0..n)[0..n)[0..n)
+ // A refresh commitment corresponding to a call to /melt.
+ // See `TALER_RefreshCommitmentP` for the data it is computed over.
type RefreshCommitmentHash = HashCode;
.. ts:def:: BlindingMasterSeed
@@ -1629,7 +1623,8 @@ within the
*/
struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
struct TALER_RefreshCommitmentP session_hash;
- uint16_t noreveal_index;
+ // in network byte order
+ uint32_t noreveal_index;
};
.. _TALER_ExchangeSigningKeyValidityPS:
@@ -2075,6 +2070,22 @@ within the
};
+.. _TALER_CoinHistoryRequestPS:
+.. sourcecode:: c
+
+ struct TALER_CoinHistoryRequestPS {
+ /**
+ * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_HISTORY
+ */
+ struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+ /**
+ * Value of the ``start`` query parameter, 0 if not given,
+ * in network byte order.
+ */
+ uint64_t start_off;
+ };
+
+
.. _TALER_ReserveHistoryRequestSignaturePS:
.. sourcecode:: c
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -30,7 +30,7 @@ defines all specific terms used in this section.
Version History
---------------
-The currently implemented protocol version is **v45**.
+The currently implemented protocol version is **v46**.
* Wallet-core is currently targeting **vXX**.
* The merchant is currently targeting **v34**.
@@ -82,6 +82,13 @@ The currently implemented protocol version is **v45**.
request; clients must include them with exchanges of v45 or
later. The exchange still accepts the commitment without
them from older clients.
+* ``v46``: the ``MELT`` entries of the coin history
+ (:http:get:`/coins/$COIN_PUB/history </coins/$COIN_PUB/history>`)
+ include ``noreveal_index``, the ``transfer_pubs`` of the
+ batch at ``noreveal_index`` and, after the reveal, the
+ ``ev_sigs`` of the fresh coins;
+ :http:post:`/melt </melt>` of a zombie coin returns the
+ `CoinDenominationConflictError` proof like all other paths
**Upcoming versions:**
@@ -324,7 +331,7 @@ exchange.
// Response to an operation on a coin whose public key the exchange
// already knows under a *different* denomination. Since protocol
- // **vCONFLICT** the response is a proof: it carries the denomination
+ // **v42** the response is a proof: it carries the denomination
// signature the exchange holds for the coin, which clients verify
// against ``prev_denom_pub`` (see ``TALER_EXCHANGE_check_coin_denomination_conflict_``).
interface CoinDenominationConflictError {
@@ -350,7 +357,7 @@ exchange.
// Age commitment hash stored for the coin. Present exactly
// if ``prev_denom_pub`` is an age-restricted denomination.
- // @since **vCONFLICT**
+ // @since **v42**
prev_h_age_commitment?: AgeCommitmentHash;
}
@@ -359,7 +366,7 @@ exchange.
// Response to an operation on a coin whose public key the exchange
// already knows under the same denomination, but with a different
- // age commitment hash. Since protocol **vCONFLICT** the response is
+ // age commitment hash. Since protocol **v42** the response is
// a proof: it carries the denomination signature the exchange holds
// for the coin, which covers ``coin_pub`` and
// ``expected_age_commitment_hash``.
@@ -389,7 +396,7 @@ exchange.
// Signature by the denomination over ``coin_pub`` and
// ``expected_age_commitment_hash``, i.e. the denomination
// signature of the coin as issued by the exchange.
- // @since **vCONFLICT**
+ // @since **v42**
prev_denom_sig: DenominationSignature;
}
@@ -511,7 +518,7 @@ part of the :http:get:`/keys </keys>` response. If and only if this has happene
coins that were signed with those denomination keys can be cashed
in using this API.
-Since protocol **vRECOUP**, coins are recouped in batches: all coins in one
+Since protocol **v42**, coins are recouped in batches: all coins in one
request must originate from the same withdraw or refresh operation, which
the client identifies by its commitment (``planchets_h`` of the withdraw
request, or ``rc`` of the melt request). For the coins to be recouped, the
diff --git a/core/exchange/get-coins-COIN_PUB-history.rst b/core/exchange/get-coins-COIN_PUB-history.rst
@@ -8,13 +8,14 @@
**Request:**
*Taler-Coin-History-Signature*:
- The client MUST provide Base-32 encoded EdDSA signature over a
- ``TALER_SIGNATURE_COIN_HISTORY_REQUEST`` made with the respective
+ The client MUST provide a Base-32 encoded EdDSA signature over a
+ :ref:`TALER_CoinHistoryRequestPS <TALER_CoinHistoryRequestPS>` of purpose
+ ``TALER_SIGNATURE_WALLET_COIN_HISTORY`` made with the respective
``$COIN_PRIV``, affirming desire to download the coin's
- transaction history.
+ transaction history. The signature covers the ``start``
+ offset of the request (0 if ``start`` is not given).
*If-None-Match*:
- The client MAY provide an ``If-None-Match`` header with an ETag.
The client MAY provide an ``If-None-Match`` header with an
Etag. In that case, the server MUST additionally respond with an ``304``
status code in case the coin history matches the provided Etag.
@@ -30,14 +31,14 @@
the coin's transaction history.
The response will be a `CoinHistoryResponse` object.
:http:statuscode:`204 No content`:
- The reserve history is known, but at this point from the given
+ The coin history is known, but at this point from the given
starting point it is empty. Can only happen if OFFSET was
positive (and the ETag changed or ``If-None-Match`` was not given).
:http:statuscode:`304 Not modified`:
The coin history has not changed since the previous query
(detected via Etag in "If-none-match" header).
:http:statuscode:`403 Forbidden`:
- The *TALER_SIGNATURE_COIN_HISTORY_REQUEST* signature is invalid.
+ The *Taler-Coin-History-Signature* is invalid.
This response comes with a standard `ErrorDetail` response with
a code of ``TALER_EC_EXCHANGE_COIN_HISTORY_BAD_SIGNATURE``.
:http:statuscode:`404 Not found`:
@@ -86,7 +87,7 @@
interface CoinDepositTransaction {
type: "DEPOSIT";
- // Offset of this entry in the reserve history.
+ // Offset of this entry in the coin history.
// Useful to request incremental histories via
// the "start" query parameter.
history_offset: Integer;
@@ -144,7 +145,7 @@
interface CoinMeltTransaction {
type: "MELT";
- // Offset of this entry in the reserve history.
+ // Offset of this entry in the coin history.
// Useful to request incremental histories via
// the "start" query parameter.
history_offset: Integer;
@@ -158,46 +159,49 @@
// Melt fee.
melt_fee: Amount;
- // Commitment from the melt operation, see `TALER_RefreshCommitmentP`
+ // Commitment from the melt operation, see `TALER_RefreshCommitmentP`.
rc: HashCode;
// Hash of the public denomination key used to sign the old coin.
- // Needed because 'coin_sig' signs over this, and
+ // Needed because ``coin_sig`` signs over this, and
// that is important to fix the coin's denomination.
- old_denom_pub_h: HashCode;
+ h_denom_pub: HashCode;
// Hash over the age commitment of the coin. Optional.
- old_age_commitment_h?: AgeCommitmentHash;
+ h_age_commitment?: AgeCommitmentHash;
// @since **v32**
// 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 confirm_sig below.
+ // as part of the original melt request, and was therefore verified
+ // with the ``coin_sig`` below.
// If the reveal step was not performed yet by the old coin owner,
// they can use this value and the old coin's private key to derive
- // all indivual seeds for the n*κ coin candidates for the original
- // refresh request and replay it
+ // all individual seeds for the n*κ coin candidates for the original
+ // melt request and replay it.
refresh_seed: HashCode;
// @since **v32**
- // The kappa*n list of transfer public keys that were provided by the
- // old coin owner during the melt request.
- transfer_pubs: EddsaPublicKey[kappa][];
-
- // @since **v32**
// The n denomination public keys for the fresh coins
- // that the coin owner had requested.
+ // that the coin owner had requested, in the order of the request.
denoms_h: HashCode[];
- // @since **v32**
- // The ``noreveal_index`` value that was returned by the exchange as response
- // to the melt request.
+ // @since **v46**
+ // The ``noreveal_index`` value that was returned by the exchange as
+ // response to the melt request.
noreveal_index: Integer;
- // @since **v32**
- // If the reveal step was successfully peformed by the coin owner,
- // this field contains the blind coin signatures that were returned
- // by the exchange for the chosen batch of coins.
+ // @since **v46**
+ // The n transfer public keys of the batch at ``noreveal_index``,
+ // as provided by the old coin owner in the melt request.
+ // Together with the old coin's private key they determine the
+ // secrets of the fresh coins.
+ // Absent if the melt request did not include transfer public keys.
+ transfer_pubs?: EddsaPublicKey[];
+
+ // @since **v46**
+ // The n blinded denomination signatures over the fresh coins of the
+ // batch at ``noreveal_index``, in the order of ``denoms_h``.
+ // Present only if the reveal step was successfully performed.
ev_sigs?: BlindedDenominationSignature[];
// Master seed for the Clause-Schnorr R-value
@@ -208,7 +212,7 @@
// Signature by the coin over a
// `TALER_RefreshMeltCoinAffirmationPS` of
// purpose ``TALER_SIGNATURE_WALLET_COIN_MELT``.
- confirm_sig: EddsaSignature;
+ coin_sig: EddsaSignature;
}
@@ -217,7 +221,7 @@
interface CoinRefundTransaction {
type: "REFUND";
- // Offset of this entry in the reserve history.
+ // Offset of this entry in the coin history.
// Useful to request incremental histories via
// the "start" query parameter.
history_offset: Integer;
@@ -256,7 +260,7 @@
// This represents a transaction of a call to /recoup-withdraw
// where the coin's residual value has been credited to the
// original reserve, from which this coin was withdrawn.
- // @since **vRECOUP**
+ // @since **v42**
interface CoinRecoupWithdrawTransaction {
type: "RECOUP-WITHDRAW";
@@ -316,7 +320,7 @@
// where this coin was _part_ of the batch of coins whose
// residual values were credited to the original coin, from
// which also this coin was refreshed from.
- // @since **vRECOUP**
+ // @since **v42**
interface CoinRecoupRefreshTransaction {
type: "RECOUP-REFRESH";
@@ -377,7 +381,7 @@
// where this coin was the _receiver_ of the residual value
// of a coin that originated from a call to /melt of this coin.
// There is one such entry per recouped coin.
- // @since **vRECOUP**
+ // @since **v42**
interface CoinRecoupRefreshReceiverTransaction {
type: "RECOUP-REFRESH-RECEIVER";
@@ -418,7 +422,7 @@
interface CoinPurseDepositTransaction {
type: "PURSE-DEPOSIT";
- // Offset of this entry in the reserve history.
+ // Offset of this entry in the coin history.
// Useful to request incremental histories via
// the "start" query parameter.
history_offset: Integer;
@@ -464,7 +468,7 @@
interface CoinPurseRefundTransaction {
type: "PURSE-REFUND";
- // Offset of this entry in the reserve history.
+ // Offset of this entry in the coin history.
// Useful to request incremental histories via
// the "start" query parameter.
history_offset: Integer;
@@ -498,7 +502,7 @@
interface CoinReserveOpenDepositTransaction {
type: "RESERVE-OPEN-DEPOSIT";
- // Offset of this entry in the reserve history.
+ // Offset of this entry in the coin history.
// Useful to request incremental histories via
// the "start" query parameter.
history_offset: Integer;
diff --git a/core/exchange/get-reserves-RESERVE_PUB-history.rst b/core/exchange/get-reserves-RESERVE_PUB-history.rst
@@ -245,7 +245,7 @@
// The commitment ``planchets_h`` of the withdraw request
// from this reserve that the coin was part of, see
// `RecoupWithdrawRequest`.
- // @since **vRECOUP**
+ // @since **v42**
planchets_h: HashCode;
}
diff --git a/core/exchange/get-reserves-RESERVE_PUB.rst b/core/exchange/get-reserves-RESERVE_PUB.rst
@@ -39,7 +39,7 @@
// The expiration date of the reserve.
// Any residual value of in the reserve after this date
// will be returned to the ``last_origin``, if present.
- // @since protocol **vRECOUP**.
+ // @since protocol **v42**.
reserve_expiration: Timestamp;
// If set, proof of age restriction is required and age restriction needs
diff --git a/core/exchange/post-batch-deposit.rst b/core/exchange/post-batch-deposit.rst
@@ -229,7 +229,7 @@
// Must be TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS
// or TALER_EC_EXCHANGE_DEPOSIT_CONFLICTING_CONTRACT.
- // (Since **vCONFLICT**, a conflicting denomination is
+ // (Since **v42**, a conflicting denomination is
// reported with a `CoinDenominationConflictError` instead.)
code: Integer;
diff --git a/core/exchange/post-melt.rst b/core/exchange/post-melt.rst
@@ -6,10 +6,6 @@
various arguments are given ``kappa``-times in this step. At present ``kappa``
is always 3.
- The base URL for ``/melt/``-requests may differ from the main base URL of the
- exchange. The exchange MUST return a 307 or 308 redirection to the correct
- base URL if this is the case.
-
This endpoint was introduced in this form in protocol **v32**.
Since protocol **v45**, the commitment
@@ -115,7 +111,7 @@
//
// @since **v32**
// The ``refresh_seed`` is an opaque value to the exchange.
- // It is provided by the client and is verified with the ``coin_sig`` below.
+ // It is provided by the client and is verified with the ``confirm_sig`` below.
// Its purpose is to ensure that the honest owner of the old coin
// can replay a /melt request from data in the coin history,
// provided by the exchange and including this value, in case a wallet
@@ -123,20 +119,22 @@
//
// The honest owner of the old coin SHOULD use this value
// and the old coin's private key to derive kappa many
- // batch seeds (one for each cut-and-choose candidate)
- // like this:
+ // 64-byte batch seeds (one for each cut-and-choose candidate)
+ // like this, where ``HKDF(length, salt, key_material, context)``
+ // is the HKDF of GNUnet (HMAC-SHA512 for the extraction,
+ // HMAC-SHA256 for the expansion):
//
- // ``bs[] = HKDF(kappa*sizeof(HashCode),``
+ // ``bs[] = HKDF(kappa*64,``
// ``"refresh-batch-seeds",``
- // ``old_coin_priv,``
- // ``refresh_seed)``
+ // ``refresh_seed,``
+ // ``old_coin_priv)``
//
// These batch seeds (however constructed) are relevant in the
- // subsequent reveal step of the cut-and-chose. Each of the
+ // subsequent reveal step of the cut-and-choose. Each of the
// revealed seeds is expanded to a batch of ``n`` transfer private keys
- // via HKDF:
+ // (32-byte ECDHE private keys) via HKDF without context:
//
- // ``tp[k][] = HKDF(n*sizeof(HashCode),``
+ // ``tp[k][] = HKDF(n*32,``
// ``"refresh-transfer-private-keys",``
// ``bs[k])``
//
@@ -165,6 +163,9 @@
// These are ephemeral ECDHE keys that allow the owner of a coin
// to (re-)obtain the derived coins from a refresh operation, f.e. should
// the wallet state be restored from a backup, prior to the refresh operation.
+ // The exchange keeps the ``n`` keys of the batch at ``noreveal_index``
+ // and returns them in the coin history of the old coin, see
+ // `CoinMeltTransaction`.
transfer_pubs: EddsaPublicKey[kappa][];
// Signature by the `coin <coin-priv>` over `TALER_RefreshMeltCoinAffirmationPS`.
@@ -201,7 +202,7 @@
interface MeltForbiddenResponse {
// Must be TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS.
- // (Since **vCONFLICT**, a conflicting denomination is
+ // (Since **v42**, a conflicting denomination is
// reported with a `CoinDenominationConflictError` instead.)
code: Integer;
diff --git a/core/exchange/post-recoup-refresh.rst b/core/exchange/post-recoup-refresh.rst
@@ -23,11 +23,7 @@
The exchange only accepts this request for coins of denominations that
are listed in the ``recoup`` field of :http:get:`/keys </keys>`.
- The base URL for this request may differ from the main base URL of the
- exchange. The exchange MUST return a 307 or 308 redirection to the correct
- base URL if this is the case.
-
- This endpoint was introduced in protocol **vRECOUP** and replaces the
+ This endpoint was introduced in protocol **v42** and replaces the
former ``/coins/$COIN_PUB/recoup-refresh`` endpoint.
**Request:**
diff --git a/core/exchange/post-recoup-withdraw.rst b/core/exchange/post-recoup-withdraw.rst
@@ -23,7 +23,7 @@
The exchange only accepts this request for coins of denominations that
are listed in the ``recoup`` field of :http:get:`/keys </keys>`.
- This endpoint was introduced in protocol **vRECOUP** and replaces the
+ This endpoint was introduced in protocol **v42** and replaces the
former ``/coins/$COIN_PUB/recoup`` endpoint.
**Request:**
diff --git a/core/exchange/post-reveal-melt.rst b/core/exchange/post-reveal-melt.rst
@@ -3,12 +3,6 @@
Reveal previously committed values to the exchange, except for the values
corresponding to the ``noreveal_index`` returned by the :http:post:`/melt </melt>` step.
- The base URL for ``/reveal-melt``-request may differ from the main base URL of
- the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
- coin during melt operations. The exchange MUST return a
- 307 or 308 redirection to the correct base URL if the client failed to
- respect the ``reveal_base_url`` or if the allocation has changed.
-
The request body is a `RevealMeltRequest`.
This endpoint was introduced in this form in protocol **v32**.
@@ -20,9 +14,12 @@
The request body is malformed or a parameter is invalid.
This response comes with a standard `ErrorDetail` response with
codes of:
+
- ``TALER_EC_GENERIC_PARAMETER_MALFORMED``
- ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_AGE_RESTRICTION_COMMITMENT_INVALID``
- - ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_INVALID_RCH``
+ - ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_INVALID_RCH``, if the revealed
+ secrets do not match the commitment of the original melt request
+
:http:statuscode:`403 Forbidden`:
A signature is invalid. Returned with a
``TALER_EC_EXCHANGE_REFRESHES_REVEAL_LINK_SIGNATURE_INVALID``.
@@ -30,14 +27,6 @@
:http:statuscode:`404 Not found`:
The provided commitment is unknown. Returned with an error code of
``TALER_EC_EXCHANGE_REFRESHES_REVEAL_SESSION_UNKNOWN``.
- :http:statuscode:`409 Conflict`:
- There is a problem between the original commitment and the revealed secret data.
- The returned information is proof of the mismatch,
- and therefore rather verbose, as it includes most of the original /melt request,
- but of course expected to be primarily used for diagnostics.
-
- Returned with a code of
- ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_INVALID_RCH``.
:http:statuscode:`413 Request entity too large`:
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
diff --git a/core/exchange/post-reveal-withdraw.rst b/core/exchange/post-reveal-withdraw.rst
@@ -3,12 +3,6 @@
Reveal previously committed values to the exchange, except for the values
corresponding to the ``noreveal_index`` returned by the :http:post:`/withdraw </withdraw>` step.
- The base URL for ``/reveal-withdraw``-request may differ from the main base URL of
- the exchange. Clients SHOULD respect the ``reveal_base_url`` returned for the
- coin during melt operations. The exchange MUST return a
- 307 or 308 redirection to the correct base URL if the client failed to
- respect the ``reveal_base_url`` or if the allocation has changed.
-
The request body is a `RevealWithdrawRequest`.
This endpoint was introduced in this form in protocol **v32**.
diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -957,12 +957,12 @@ and action table is the same as refresh: ``pending/working`` offers
.. note::
The following paragraphs are a proposal for the wallet team, written
- together with the exchange protocol **vRECOUP** specification of
+ together with the exchange protocol **v42** specification of
:http:post:`/recoup-withdraw </recoup-withdraw>` and
:http:post:`/recoup-refresh </recoup-refresh>`. wallet-core still
implements the per-coin recoup of earlier protocol versions.
-Since exchange protocol **vRECOUP** recoup is a batch operation on the coins of
+Since exchange protocol **v42** recoup is a batch operation on the coins of
one withdraw or one refresh operation. A recoup transaction therefore
groups the affected coins by the operation they originated from: one
transaction per withdraw request, credited to the reserve, and one per