commit 3d0eaaca9052d94d0112cf80391d4ea9d709d024
parent 9804a9cc02c76a074a40ff5c2b43544ac2330646
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 3 May 2026 22:23:42 +0200
fix reserve history spec, fix #11318
Diffstat:
2 files changed, 504 insertions(+), 524 deletions(-)
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 current protocol version is **v34**.
+The current protocol version is **v35**.
* The merchant is currently targeting **v34**.
* The AML SPA is currently targeting **v31**.
@@ -437,521 +437,6 @@ Coin History
.. include:: exchange/get-coins-COIN_PUB-history.rst
-Obtain the transaction history of a coin. Used only in special cases, like
-when the exchange claims a double-spending error and the wallet does not
-believe it. Usually, the wallet knows the transaction history of each coin
-and thus has no need to inquire.
-
-**Request:**
-
-The GET request should come with the following HTTP headers:
-
-*If-None-Match*:
- 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.
-
-*Taler-Coin-History-Signature*:
- The client MUST provide Base-32 encoded EdDSA signature over a
- ``TALER_SIGNATURE_COIN_HISTORY_REQUEST`` made with the respective
- ``$COIN_PRIV``, affirming desire to download the current coin
- transaction history.
-
-:query start=OFFSET: *Optional.* Only return coin history entries with
- offsets above the given OFFSET. Allows clients to not
- retrieve history entries they already have.
-
-**Response:**
-
-:http:statuscode:`200 OK`:
- The operation succeeded, the exchange confirms that no double-spending took
- place. The response will include a `CoinHistoryResponse` object.
-:http:statuscode:`204 No content`:
- The reserve history is known, but at this point from the given starting point it is empty. Can only happen if OFFSET was positive.
-: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* is invalid.
- This response comes with a standard `ErrorDetail` response.
-:http:statuscode:`404 Not found`:
- The coin public key is not (yet) known to the exchange.
-
-**Details:**
-
-.. ts:def:: CoinHistoryResponse
-
- interface CoinHistoryResponse {
- // Current balance of the coin.
- balance: Amount;
-
- // Hash of the coin's denomination.
- h_denom_pub: HashCode;
-
- // Transaction history for the coin.
- history: CoinSpendHistoryItem[];
- }
-
-.. ts:def:: CoinSpendHistoryItem
-
- // Union discriminated by the "type" field.
- type CoinSpendHistoryItem =
- | CoinDepositTransaction
- | CoinMeltTransaction
- | CoinRefundTransaction
- | CoinRecoupWithdrawTransaction
- | CoinRecoupRefreshTransaction
- | CoinRecoupRefreshReceiverTransaction
- | CoinPurseDepositTransaction
- | CoinPurseRefundTransaction
- | CoinReserveOpenDepositTransaction;
-
-.. ts:def:: CoinDepositTransaction
-
- interface CoinDepositTransaction {
- type: "DEPOSIT";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value absorbed (or restored in the
- // case of a refund) by this transaction.
- // The amount given includes
- // the deposit fee. The current coin value can thus be computed by
- // subtracting this amount.
- amount: Amount;
-
- // Deposit fee.
- deposit_fee: Amount;
-
- // Public key of the merchant.
- merchant_pub: EddsaPublicKey;
-
- // Date when the operation was made.
- timestamp: Timestamp;
-
- // Date until which the merchant can issue a refund to the customer via the
- // exchange, possibly zero if refunds are not allowed.
- refund_deadline?: Timestamp;
-
- // Hash over the proposal data of the contract that
- // is being paid.
- h_contract_terms: HashCode;
-
- // Hash of the bank account from where we received the funds.
- h_wire: HashCode;
-
- // Hash of the public denomination key used to sign the coin.
- // Needed because 'coin_sig' signs over this, and
- // that is important to fix the coin's denomination.
- h_denom_pub: HashCode;
-
- // Hash over the deposit policy extension. Optional.
- h_policy?: HashCode;
-
- // Hash over auxiliary wallet data provided by the wallet
- // to complete the contract. Optional.
- wallet_data_hash?: HashCode;
-
- // Hash over the age commitment of the coin. Optional.
- h_age_commitment?: HashCode;
-
- // Signature over `TALER_DepositRequestPS`, made by the customer with the
- // `coin's private key <coin-priv>`.
- coin_sig: EddsaSignature;
-
- }
-
-.. ts:def:: CoinMeltTransaction
-
- interface CoinMeltTransaction {
- type: "MELT";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value absorbed by this transaction.
- // Note that for melt this means the amount given includes
- // the melt fee. The current coin value can thus be computed by
- // subtracting the amounts.
- amount: Amount;
-
- // Melt fee.
- melt_fee: Amount;
-
- // 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
- // that is important to fix the coin's denomination.
- old_denom_pub_h: HashCode;
-
- // Hash over the age commitment of the coin. Optional.
- old_age_commitment_h?: 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.
- // 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
- 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.
- denoms_h: HashCode[];
-
- // @since **v32**
- // 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.
- ev_sigs?: BlindedDenominationSignature[];
-
- // Master seed for the Clause-Schnorr R-value
- // Present if one of the fresh coin's
- // denominations is of type Clause-Schnorr.
- blinding_seed?: BlindingMasterSeed;
-
- // Signature by the coin over a
- // `TALER_RefreshMeltCoinAffirmationPS` of
- // purpose ``TALER_SIGNATURE_WALLET_COIN_MELT``.
- confirm_sig: EddsaSignature;
-
- }
-
-.. ts:def:: CoinRefundTransaction
-
- interface CoinRefundTransaction {
- type: "REFUND";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value restored
- // by this transaction.
- // The amount given excludes the transaction fee.
- // The current coin value can thus be computed by
- // adding the amounts to the coin's denomination value.
- amount: Amount;
-
- // Refund fee.
- refund_fee: Amount;
-
- // Hash over the proposal data of the contract that
- // is being refunded.
- h_contract_terms: HashCode;
-
- // Public key of the merchant.
- merchant_pub: EddsaPublicKey;
-
- // Refund transaction ID.
- rtransaction_id: Integer;
-
- // `EdDSA Signature <eddsa-sig>` authorizing the REFUND over a
- // `TALER_MerchantRefundConfirmationPS` with
- // purpose ``TALER_SIGNATURE_MERCHANT_REFUND_OK``. Made with
- // the `public key of the merchant <merchant-pub>`.
- merchant_sig: EddsaSignature;
-
- }
-
-
-.. note::
-
- The `CoinRecoupWithdrawTransaction` interface defintion is WIP.
- It will be fully specified and implemented with **vRECOUP**.
-
-.. ts:def:: CoinRecoupWithdrawTransaction
-
- // 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.
- interface CoinRecoupWithdrawTransaction {
- type: "RECOUP-WITHDRAW";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value absorbed
- // by this transaction.
- // The current coin value can thus be computed by
- // subtracting the amount from
- // the coin's denomination value.
- amount: Amount;
-
- // Signature by the exchange over a
- // `TALER_RecoupConfirmationPS`, must be
- // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``.
- exchange_sig: EddsaSignature;
-
- // Public key of the private key used to create 'exchange_sig'.
- exchange_pub: EddsaPublicKey;
-
- // Signature by the coin over a
- // `TALER_RecoupRequestPS` with purpose
- // ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
- coin_sig: EddsaSignature;
-
- // Hash of the public denomination key used to sign the coin.
- // Needed because 'coin_sig' signs over this, and
- // that is important to fix the coin's denomination.
- h_denom_pub: HashCode;
-
- // Coin blinding key that was used in the original withdraw request.
- coin_blind: DenominationBlindingKeyP;
-
- // The hash of the withdraw commitment of the original withdraw
- // request that this coin was part of
- h_commitment: HashCode;
-
- // Coin's index in the original withdraw request, starting at 0
- coin_index: Integer;
-
- // Reserve receiving the recoup.
- reserve_pub: EddsaPublicKey;
-
- // Date when the operation was made.
- timestamp: Timestamp;
-
- }
-
-
-.. note::
-
- The `CoinRecoupRefreshTransaction` interface defintion is WIP.
- It will be fully specified and implemented with **vRECOUP**.
-
-.. ts:def:: CoinRecoupRefreshTransaction
-
- // This represents a transaction of a call to /recoup-refresh
- // 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 refresh from.
- interface CoinRecoupRefreshTransaction {
- type: "RECOUP-REFRESH";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value absorbed
- // by this transaction.
- // The current coin value can thus be computed by
- // subtracting this amounts from
- // the coin's denomination value.
- amount: Amount;
-
- // Signature by the exchange over a
- // `TALER_RecoupRefreshConfirmationPS`
- // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
- exchange_sig: EddsaSignature;
-
- // Public key used to sign 'exchange_sig'.
- exchange_pub: EddsaPublicKey;
-
- // The original coin, from which this coin was derived from
- // in a call to /refresh, and which was then credited with
- // the residual value of this coin in a call to /recoup-refresh.
- old_coin_pub: EddsaPublicKey;
-
- // Signature by the coin over a `TALER_RecoupRequestPS`
- // with purpose ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
- coin_sig: EddsaSignature;
-
- // Hash of the public denomination key used to sign the coin.
- // Needed because 'coin_sig' signs over this, and
- // that is important to fix the coin's denomination.
- h_denom_pub: HashCode;
-
- // Coin blinding key that was used in the original refresh request.
- coin_blind: DenominationBlindingKeyP;
-
- // The hash of the refresh commitment of the original refresh
- // request that this coin was derived from.
- h_commitment: HashCode;
-
- // Coin's index in the original refresh request, starting at 0
- coin_index: Integer;
-
- // Blinding factor of the revoked new coin.
- new_coin_blinding_secret: DenominationBlindingKeySecret;
-
- // Blinded public key of the revoked new coin.
- new_coin_ev: DenominationBlindingKeySecret;
-
- // Date when the operation was made.
- timestamp: Timestamp;
-
- }
-
-
-.. note::
-
- The `CoinRecoupRefreshReceiverTransaction` interface defintion is WIP.
- It will be fully specified and implemented with **vRECOUP**.
-
-.. ts:def:: CoinRecoupRefreshReceiverTransaction
-
- // This represents a transaction of a call to /recoup-refresh
- // where this coin was the _receiver_ of the residual values
- // from coins, that originated from a call to /refresh of this coin.
- interface CoinRecoupRefreshReceiverTransaction {
- type: "RECOUP-REFRESH-RECEIVER";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value restored
- // by this transaction.
- // The current coin value can thus be computed by
- // adding the amount to the coin's denomination value.
- amount: Amount;
-
- // Date when the operation was made.
- timestamp: Timestamp;
-
- // Signature by the exchange over a
- // `TALER_RecoupRefreshConfirmationPS`
- // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
- exchange_sig: EddsaSignature;
-
- // Public key of the private key used to create 'exchange_sig'.
- exchange_pub: EddsaPublicKey;
-
- }
-
-.. ts:def:: CoinPurseDepositTransaction
-
- interface CoinPurseDepositTransaction {
- type: "PURSE-DEPOSIT";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value absorbed
- // by this transaction.
- // Note that this means the amount given includes
- // the deposit fee. The current coin value can thus be computed by
- // subtracting the amount from
- // the coin's denomination value.
- amount: Amount;
-
- // Base URL of the exchange the purse lives at.
- exchange_base_url: string;
-
- // The hash of the age-commitment for the coin. Only present
- // if the denomination has support for age restriction.
- h_age_commitment?: AgeCommitmentHash;
-
- // Deposit fee.
- deposit_fee: Amount;
-
- // Public key of the purse.
- purse_pub: EddsaPublicKey;
-
- // True if the deposit was refunded for any reason.
- refunded: boolean;
-
- // Signature by the coin over a
- // `TALER_PurseDepositSignaturePS` of
- // purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``.
- coin_sig: EddsaSignature;
-
- // Hash of the public denomination key used to sign the coin.
- // Needed because 'coin_sig' signs over this, and
- // that is important to fix the coin's denomination.
- h_denom_pub: HashCode;
-
- }
-
-.. ts:def:: CoinPurseRefundTransaction
-
- interface CoinPurseRefundTransaction {
- type: "PURSE-REFUND";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value restored
- // by this transaction.
- // The amount given excludes the refund fee.
- // The current coin value can thus be computed by
- // adding the amount to the coin's denomination value.
- amount: Amount;
-
- // Refund fee (of the coin's denomination). The deposit
- // fee will be waived.
- refund_fee: Amount;
-
- // Signature by the exchange over a
- // ``TALER_CoinPurseRefundConfirmationPS``
- // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PURSE_REFUND``.
- exchange_sig: EddsaSignature;
-
- // Public key used to sign 'exchange_sig'.
- exchange_pub: EddsaPublicKey;
-
- // Public key of the purse that expired.
- purse_pub: EddsaPublicKey;
-
- }
-
-.. ts:def:: CoinReserveOpenDepositTransaction
-
- interface CoinReserveOpenDepositTransaction {
- type: "RESERVE-OPEN-DEPOSIT";
-
- // Offset of this entry in the reserve history.
- // Useful to request incremental histories via
- // the "start" query parameter.
- history_offset: Integer;
-
- // The total amount of the coin's value absorbed
- // by this transaction.
- // Note that this means the amount given includes
- // the deposit fee.
- coin_contribution: Amount;
-
- // Signature of the reserve open operation being paid for.
- reserve_sig: EddsaSignature;
-
- // Signature by the coin over a
- // `TALER_ReserveOpenDepositSignaturePS` of
- // purpose ``TALER_SIGNATURE_RESERVE_OPEN_DEPOSIT``.
- coin_sig: EddsaSignature;
-
- }
-
-
-----------------------
Tracking wire transfers
-----------------------
diff --git a/core/exchange/get-coins-COIN_PUB-history.rst b/core/exchange/get-coins-COIN_PUB-history.rst
@@ -1,26 +1,43 @@
.. http:get:: /coins/$COIN_PUB/history
- Obtain the transaction history of a coin.
+ Obtain the transaction history of a coin. Used only in special cases, like
+ when the exchange claims a double-spending error and the wallet does not
+ believe it. Usually, the wallet knows the transaction history of each coin
+ and thus has no need to inquire.
**Request:**
- *Coin-History-Signature*:
- The client must provide a Base-32 encoded EdDSA signature with
- the coin's private key, affirming the desire to obtain the coin's
- history.
+ *Taler-Coin-History-Signature*:
+ The client MUST provide Base-32 encoded EdDSA signature over a
+ ``TALER_SIGNATURE_COIN_HISTORY_REQUEST`` made with the respective
+ ``$COIN_PRIV``, affirming desire to download the coin's
+ transaction history.
*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.
+
+ :query start=OFFSET: *Optional.* Only return coin history entries with
+ offsets above the given OFFSET. Allows clients to not
+ retrieve history entries they already have.
**Response:**
:http:statuscode:`200 OK`:
The coin is known to the exchange and the response is
the coin's transaction history.
+ The response will be a `CoinHistoryResponse` object.
:http:statuscode:`204 No content`:
- The coin's transaction history is empty (but the ETag changed).
+ The reserve 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 coin history signature is invalid.
+ The *TALER_SIGNATURE_COIN_HISTORY_REQUEST* 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`:
@@ -33,4 +50,482 @@
Possible error codes include
``TALER_EC_GENERIC_DB_FETCH_FAILED``,
``TALER_EC_GENERIC_DB_SOFT_FAILURE``, or
- ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``.
+ ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``
+
+ **Details:**
+
+ .. ts:def:: CoinHistoryResponse
+
+ interface CoinHistoryResponse {
+ // Current balance of the coin.
+ balance: Amount;
+
+ // Hash of the coin's denomination.
+ h_denom_pub: HashCode;
+
+ // Transaction history for the coin.
+ history: CoinSpendHistoryItem[];
+ }
+
+ .. ts:def:: CoinSpendHistoryItem
+
+ // Union discriminated by the "type" field.
+ type CoinSpendHistoryItem =
+ | CoinDepositTransaction
+ | CoinMeltTransaction
+ | CoinRefundTransaction
+ | CoinRecoupWithdrawTransaction
+ | CoinRecoupRefreshTransaction
+ | CoinRecoupRefreshReceiverTransaction
+ | CoinPurseDepositTransaction
+ | CoinPurseRefundTransaction
+ | CoinReserveOpenDepositTransaction;
+
+ .. ts:def:: CoinDepositTransaction
+
+ interface CoinDepositTransaction {
+ type: "DEPOSIT";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value absorbed (or restored in the
+ // case of a refund) by this transaction.
+ // The amount given includes
+ // the deposit fee. The current coin value can thus be computed by
+ // subtracting this amount.
+ amount: Amount;
+
+ // Deposit fee.
+ deposit_fee: Amount;
+
+ // Public key of the merchant.
+ merchant_pub: EddsaPublicKey;
+
+ // Date when the operation was made.
+ timestamp: Timestamp;
+
+ // Date until which the merchant can issue a refund to the customer via the
+ // exchange, possibly zero if refunds are not allowed.
+ refund_deadline?: Timestamp;
+
+ // Hash over the proposal data of the contract that
+ // is being paid.
+ h_contract_terms: HashCode;
+
+ // Hash of the bank account from where we received the funds.
+ h_wire: HashCode;
+
+ // Hash of the public denomination key used to sign the coin.
+ // Needed because 'coin_sig' signs over this, and
+ // that is important to fix the coin's denomination.
+ h_denom_pub: HashCode;
+
+ // Hash over the deposit policy extension. Optional.
+ h_policy?: HashCode;
+
+ // Hash over auxiliary wallet data provided by the wallet
+ // to complete the contract. Optional.
+ wallet_data_hash?: HashCode;
+
+ // Hash over the age commitment of the coin. Optional.
+ h_age_commitment?: HashCode;
+
+ // Signature over `TALER_DepositRequestPS`, made by the customer with the
+ // `coin's private key <coin-priv>`.
+ coin_sig: EddsaSignature;
+
+ }
+
+ .. ts:def:: CoinMeltTransaction
+
+ interface CoinMeltTransaction {
+ type: "MELT";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value absorbed by this transaction.
+ // Note that for melt this means the amount given includes
+ // the melt fee. The current coin value can thus be computed by
+ // subtracting the amounts.
+ amount: Amount;
+
+ // Melt fee.
+ melt_fee: Amount;
+
+ // 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
+ // that is important to fix the coin's denomination.
+ old_denom_pub_h: HashCode;
+
+ // Hash over the age commitment of the coin. Optional.
+ old_age_commitment_h?: 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.
+ // 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
+ 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.
+ denoms_h: HashCode[];
+
+ // @since **v32**
+ // 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.
+ ev_sigs?: BlindedDenominationSignature[];
+
+ // Master seed for the Clause-Schnorr R-value
+ // Present if one of the fresh coin's
+ // denominations is of type Clause-Schnorr.
+ blinding_seed?: BlindingMasterSeed;
+
+ // Signature by the coin over a
+ // `TALER_RefreshMeltCoinAffirmationPS` of
+ // purpose ``TALER_SIGNATURE_WALLET_COIN_MELT``.
+ confirm_sig: EddsaSignature;
+
+ }
+
+ .. ts:def:: CoinRefundTransaction
+
+ interface CoinRefundTransaction {
+ type: "REFUND";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value restored
+ // by this transaction.
+ // The amount given excludes the transaction fee.
+ // The current coin value can thus be computed by
+ // adding the amounts to the coin's denomination value.
+ amount: Amount;
+
+ // Refund fee.
+ refund_fee: Amount;
+
+ // Hash over the proposal data of the contract that
+ // is being refunded.
+ h_contract_terms: HashCode;
+
+ // Public key of the merchant.
+ merchant_pub: EddsaPublicKey;
+
+ // Refund transaction ID.
+ rtransaction_id: Integer;
+
+ // `EdDSA Signature <eddsa-sig>` authorizing the REFUND over a
+ // `TALER_MerchantRefundConfirmationPS` with
+ // purpose ``TALER_SIGNATURE_MERCHANT_REFUND_OK``. Made with
+ // the `public key of the merchant <merchant-pub>`.
+ merchant_sig: EddsaSignature;
+
+ }
+
+
+ .. note::
+
+ The `CoinRecoupWithdrawTransaction` interface defintion is WIP.
+ It will be fully specified and implemented with **vRECOUP**.
+
+ .. ts:def:: CoinRecoupWithdrawTransaction
+
+ // 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.
+ interface CoinRecoupWithdrawTransaction {
+ type: "RECOUP-WITHDRAW";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value absorbed
+ // by this transaction.
+ // The current coin value can thus be computed by
+ // subtracting the amount from
+ // the coin's denomination value.
+ amount: Amount;
+
+ // Signature by the exchange over a
+ // `TALER_RecoupConfirmationPS`, must be
+ // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``.
+ exchange_sig: EddsaSignature;
+
+ // Public key of the private key used to create 'exchange_sig'.
+ exchange_pub: EddsaPublicKey;
+
+ // Signature by the coin over a
+ // `TALER_RecoupRequestPS` with purpose
+ // ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
+ coin_sig: EddsaSignature;
+
+ // Hash of the public denomination key used to sign the coin.
+ // Needed because 'coin_sig' signs over this, and
+ // that is important to fix the coin's denomination.
+ h_denom_pub: HashCode;
+
+ // Coin blinding key that was used in the original withdraw request.
+ coin_blind: DenominationBlindingKeyP;
+
+ // The hash of the withdraw commitment of the original withdraw
+ // request that this coin was part of
+ h_commitment: HashCode;
+
+ // Coin's index in the original withdraw request, starting at 0
+ coin_index: Integer;
+
+ // Reserve receiving the recoup.
+ reserve_pub: EddsaPublicKey;
+
+ // Date when the operation was made.
+ timestamp: Timestamp;
+
+ }
+
+
+ .. note::
+
+ The `CoinRecoupRefreshTransaction` interface defintion is WIP.
+ It will be fully specified and implemented with **vRECOUP**.
+
+ .. ts:def:: CoinRecoupRefreshTransaction
+
+ // This represents a transaction of a call to /recoup-refresh
+ // 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 refresh from.
+ interface CoinRecoupRefreshTransaction {
+ type: "RECOUP-REFRESH";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value absorbed
+ // by this transaction.
+ // The current coin value can thus be computed by
+ // subtracting this amounts from
+ // the coin's denomination value.
+ amount: Amount;
+
+ // Signature by the exchange over a
+ // `TALER_RecoupRefreshConfirmationPS`
+ // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
+ exchange_sig: EddsaSignature;
+
+ // Public key used to sign 'exchange_sig'.
+ exchange_pub: EddsaPublicKey;
+
+ // The original coin, from which this coin was derived from
+ // in a call to /refresh, and which was then credited with
+ // the residual value of this coin in a call to /recoup-refresh.
+ old_coin_pub: EddsaPublicKey;
+
+ // Signature by the coin over a `TALER_RecoupRequestPS`
+ // with purpose ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
+ coin_sig: EddsaSignature;
+
+ // Hash of the public denomination key used to sign the coin.
+ // Needed because 'coin_sig' signs over this, and
+ // that is important to fix the coin's denomination.
+ h_denom_pub: HashCode;
+
+ // Coin blinding key that was used in the original refresh request.
+ coin_blind: DenominationBlindingKeyP;
+
+ // The hash of the refresh commitment of the original refresh
+ // request that this coin was derived from.
+ h_commitment: HashCode;
+
+ // Coin's index in the original refresh request, starting at 0
+ coin_index: Integer;
+
+ // Blinding factor of the revoked new coin.
+ new_coin_blinding_secret: DenominationBlindingKeySecret;
+
+ // Blinded public key of the revoked new coin.
+ new_coin_ev: DenominationBlindingKeySecret;
+
+ // Date when the operation was made.
+ timestamp: Timestamp;
+
+ }
+
+
+ .. note::
+
+ The `CoinRecoupRefreshReceiverTransaction` interface defintion is WIP.
+ It will be fully specified and implemented with **vRECOUP**.
+
+ .. ts:def:: CoinRecoupRefreshReceiverTransaction
+
+ // This represents a transaction of a call to /recoup-refresh
+ // where this coin was the _receiver_ of the residual values
+ // from coins, that originated from a call to /refresh of this coin.
+ interface CoinRecoupRefreshReceiverTransaction {
+ type: "RECOUP-REFRESH-RECEIVER";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value restored
+ // by this transaction.
+ // The current coin value can thus be computed by
+ // adding the amount to the coin's denomination value.
+ amount: Amount;
+
+ // Date when the operation was made.
+ timestamp: Timestamp;
+
+ // Signature by the exchange over a
+ // `TALER_RecoupRefreshConfirmationPS`
+ // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
+ exchange_sig: EddsaSignature;
+
+ // Public key of the private key used to create 'exchange_sig'.
+ exchange_pub: EddsaPublicKey;
+
+ }
+
+ .. ts:def:: CoinPurseDepositTransaction
+
+ interface CoinPurseDepositTransaction {
+ type: "PURSE-DEPOSIT";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value absorbed
+ // by this transaction.
+ // Note that this means the amount given includes
+ // the deposit fee. The current coin value can thus be computed by
+ // subtracting the amount from
+ // the coin's denomination value.
+ amount: Amount;
+
+ // Base URL of the exchange the purse lives at.
+ exchange_base_url: string;
+
+ // The hash of the age-commitment for the coin. Only present
+ // if the denomination has support for age restriction.
+ h_age_commitment?: AgeCommitmentHash;
+
+ // Deposit fee.
+ deposit_fee: Amount;
+
+ // Public key of the purse.
+ purse_pub: EddsaPublicKey;
+
+ // True if the deposit was refunded for any reason.
+ refunded: boolean;
+
+ // Signature by the coin over a
+ // `TALER_PurseDepositSignaturePS` of
+ // purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``.
+ coin_sig: EddsaSignature;
+
+ // Hash of the public denomination key used to sign the coin.
+ // Needed because 'coin_sig' signs over this, and
+ // that is important to fix the coin's denomination.
+ h_denom_pub: HashCode;
+
+ }
+
+ .. ts:def:: CoinPurseRefundTransaction
+
+ interface CoinPurseRefundTransaction {
+ type: "PURSE-REFUND";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value restored
+ // by this transaction.
+ // The amount given excludes the refund fee.
+ // The current coin value can thus be computed by
+ // adding the amount to the coin's denomination value.
+ amount: Amount;
+
+ // Refund fee (of the coin's denomination). The deposit
+ // fee will be waived.
+ refund_fee: Amount;
+
+ // Signature by the exchange over a
+ // ``TALER_CoinPurseRefundConfirmationPS``
+ // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PURSE_REFUND``.
+ exchange_sig: EddsaSignature;
+
+ // Public key used to sign 'exchange_sig'.
+ exchange_pub: EddsaPublicKey;
+
+ // Public key of the purse that expired.
+ purse_pub: EddsaPublicKey;
+
+ }
+
+ .. ts:def:: CoinReserveOpenDepositTransaction
+
+ interface CoinReserveOpenDepositTransaction {
+ type: "RESERVE-OPEN-DEPOSIT";
+
+ // Offset of this entry in the reserve history.
+ // Useful to request incremental histories via
+ // the "start" query parameter.
+ history_offset: Integer;
+
+ // The total amount of the coin's value absorbed
+ // by this transaction.
+ // Note that this means the amount given includes
+ // the deposit fee.
+ coin_contribution: Amount;
+
+ // Hash over the age commitment of the coin. Optional.
+ // Since **v35**.
+ h_age_commitment?: HashCode;
+
+ // Signature of the reserve open operation being paid for.
+ reserve_sig: EddsaSignature;
+
+ // Signature by the coin over a
+ // `TALER_ReserveOpenDepositSignaturePS` of
+ // purpose ``TALER_SIGNATURE_RESERVE_OPEN_DEPOSIT``.
+ coin_sig: EddsaSignature;
+
+ }
