taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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:
Mcore/api-common.rst | 29++++++++++++++++++++---------
Mcore/api-exchange.rst | 19+++++++++++++------
Mcore/exchange/get-coins-COIN_PUB-history.rst | 78+++++++++++++++++++++++++++++++++++++++++-------------------------------------
Mcore/exchange/get-reserves-RESERVE_PUB-history.rst | 2+-
Mcore/exchange/get-reserves-RESERVE_PUB.rst | 2+-
Mcore/exchange/post-batch-deposit.rst | 2+-
Mcore/exchange/post-melt.rst | 29+++++++++++++++--------------
Mcore/exchange/post-recoup-refresh.rst | 6+-----
Mcore/exchange/post-recoup-withdraw.rst | 2+-
Mcore/exchange/post-reveal-melt.rst | 19++++---------------
Mcore/exchange/post-reveal-withdraw.rst | 6------
Mdesign-documents/037-wallet-transactions-lifecycle.rst | 4++--
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