taler-docs

api-exchange.rst (35040B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2014-2025 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
   @author Özgür Kesim
 
 ====================
 Exchange RESTful API
 ====================
 
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
 defines all specific terms used in this section.
 
 
 ---------------
 Version History
 ---------------
 
 The current protocol version is **v34**.
 
 * The merchant is currently targeting **v34**.
 * The AML SPA is currently targeting **v31**.
 * The KYC SPA is currently targeting **v30**.
 
 **Version history:**
 
 * ``v29``: AML reporting on KYC auth transfers
 * ``v30``: various minor feature additions
 * ``v31``: improvements for AML reporting
 * ``v32``: support for extra_wire_subject_metadata
 * ``v33``: addition of accumulated_total_without_fee in ``/batch-deposit``
 * ``v34``: new offline signature; support for open_banking_gateway and
            wire_transfer_gateway per wire account in ``/keys``
 
 **Upcoming versions:**
 
 * ``vRECOUP``: improved recoup protocol
 * ``vATTEST``: KYC attestation support
 
 **Ideas for future version:**
 
 * ``vXXX``: marker for features not yet targeted for release
 
 
 
 .. include:: tos.rst
 
 .. _keys:
 
 ---------------------------
 Exchange status information
 ---------------------------
 
 This API is used by wallets and merchants to obtain global information about
 the exchange, such as online signing keys, available denominations and the fee
 structure.  This is typically the first call any exchange client makes, as it
 returns information required to process all of the other interactions with the
 exchange.  The returned information is secured by (1) signature(s) from the exchange,
 especially the long-term offline signing key of the exchange, which clients should
 cache; (2) signature(s) from auditors, and the auditor keys should be
 hard-coded into the wallet as they are the trust anchors for Taler; (3)
 possibly by using HTTPS.
 
 
 .. include:: exchange/get-seed.rst
 
 .. include:: exchange/get-config.rst
 
 .. include:: exchange/get-keys.rst
 
 
 ----------------------------------------------
 Management operations authorized by master key
 ----------------------------------------------
 
 .. include:: exchange/get-management-keys.rst
 
 .. include:: exchange/post-management-keys.rst
 
 .. include:: exchange/post-management-denominations-H_DENOM_PUB-revoke.rst
 
 .. include:: exchange/post-management-signkeys-EXCHANGE_PUB-revoke.rst
 
 .. include:: exchange/post-management-auditors.rst
 
 .. include:: exchange/post-management-auditors-AUDITOR_PUB-disable.rst
 
 .. include:: exchange/post-management-wire-fee.rst
 
 .. include:: exchange/post-management-global-fees.rst
 
 .. include:: exchange/post-management-wire.rst
 
 .. include:: exchange/post-management-wire-disable.rst
 
 .. include:: exchange/post-management-drain.rst
 
 .. include:: exchange/post-management-aml-officers.rst
 
 .. include:: exchange/post-management-partners.rst
 
 ---------------
 Auditor actions
 ---------------
 
 .. _auditor_action:
 
 This part of the API is for the use by auditors interacting with the exchange.
 
 
 .. include:: exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.rst
 
 
 ----------------
 Blinding Prepare
 ----------------
 
 Certain denomination cipher types, such as Clause-Schnorr, require input values
 from the exchange-side as preparation for the blinding of the coins.  See the
 Bachelor thesis of Gian Demarmels and Lucien Heuzeveldt,
 `Adding Schnorr’s Blind Signature in Taler <https://www.taler.net/papers/cs-thesis.pdf>`_,
 for details.
 
 .. include:: exchange/post-blinding-prepare.rst
 
 
 
 .. _exchange-withdrawal:
 
 ----------
 Withdrawal
 ----------
 
 This API is used by the wallet to obtain digital coins.
 
 When transferring money to the exchange such as via SEPA transfers, the exchange creates
 a *reserve*, which keeps the money from the customer.  The customer must
 specify an EdDSA reserve public key as part of the transfer, and can then
 withdraw digital coins using the corresponding private key.  All incoming and
 outgoing transactions are recorded under the corresponding public key by the
 exchange.
 
 .. note::
 
    Eventually the exchange will need to advertise a policy for how long it will
    keep transaction histories for inactive or even fully drained reserves.  We
    will therefore need some additional handler similar to ``/keys`` to
    advertise those terms of service.
 
 
 .. include:: exchange/get-reserves-RESERVE_PUB.rst
 
 .. _withdraw:
 .. include:: exchange/post-withdraw.rst
 
 
 .. ts:def:: WithdrawRequest
 
   interface WithdrawRequest {
     // Cipher that is used for the rerserve's signatures.
     // For now, only ed25519 signatures are applicable,
     // but this might change in future versions.
     cipher: "ED25519";
 
     // The reserve's public key, for the the cipher ED25519,
     // to verify the signature ``reserve_sig``.
     reserve_pub: EddsaPublicKey;
 
     // Array of ``n`` hash codes of denomination public keys to order.
     // The sum of all denomination's values and fees MUST be
     // at most the balance of the reserve. The balance of
     // the reserve will be immediatley reduced by that amount.
     // If ``max_age`` is set, these denominations MUST support
     // age restriction as defined in the output to /keys.
     denoms_h: HashCode[];
 
     // If set, the maximum age to commit to. This implies:
     // 1.) it MUST be the same value as the maximum age
     //     of the reserve.
     // 2.) ``coin_evs`` MUST be an array of ``n*kappa``
     // 3.) the denominations in ``denoms_h`` MUST support
     //      age restriction.
     max_age?: Integer;
 
     // Master seed for the Clause-Schnorr R-value creation.
     // MUST match the /blinding-prepare request.
     // MUST NOT have been used in any prior withdraw request.
     // MUST be present if one of the fresh coin's
     // denomination is of type Clause-Schnorr.
     blinding_seed?: BlindingMasterSeed;
 
     // Array of blinded coin envelopes of type `CoinEnvelope`.
     // If ``max_age`` is not set, MUST be n entries.
     // If ``max_age`` is set, MUST be ``n*kappa`` entries,
     // arranged in [0..n)..[0..n), with the first n entries
     // belonging to kappa=0 etc.
     // In case of age restriction, the exchange will
     // respond with an index ``gamma``, which is the index
     // that shall remain undisclosed during the subsequent
     // reveal phase.
     // This hash value along with the reserve's public key
     // will also be used for recoup operations, if needed.
     coin_evs:  CoinEnvelope[];
 
     // Signature of `TALER_WithdrawRequestPS` created with
     // the `reserves's private key <reserve-priv>`.
     reserve_sig: EddsaSignature;
   }
 
 .. ts:def:: WithdrawResponse
 
   interface WithdrawResponse {
     // Array of blinded signatures over each ``coin_evs``,
     // in the same order as was given in the request.
     // The blinded signatures affirm the coin's validity
     // after unblinding.
     ev_sigs: BlindedDenominationSignature[];
 
   }
 
 
 .. ts:def:: AgeWithdrawResponse
 
   interface AgeWithdrawResponse {
     // index of the commitments that the client doesn't
     // have to disclose in the subsequent call to
     // ``/reveal-withdraw``.
     noreveal_index: Integer;
 
     // Signature of `TALER_WithdrawConfirmationPS` whereby
     // the exchange confirms the ``noreveal_index``.
     exchange_sig: EddsaSignature;
 
     // `Public EdDSA key <sign-key-pub>` of the exchange that was used to
     // generate the signature.  Should match one of the exchange's signing
     // keys from ``/keys``.  Again given explicitly as the client might
     // otherwise be confused by clock skew as to which signing key was used.
     exchange_pub: EddsaPublicKey;
 
   }
 
 .. ts:def:: DenominationGoneMessage
 
   interface DenominationGoneMessage {
 
     // Taler error code.  Note that beyond
     // expiration this message format is also
     // used if the key is not yet valid, or
     // has been revoked. May be one of
     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``
     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``
     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``
     code: Integer;
 
     // Signature by the exchange over a
     // `TALER_DenominationExpiredAffirmationPS`.
     // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``.
     exchange_sig: EddsaSignature;
 
     // Public key of the exchange used to create
     // the 'exchange_sig.
     exchange_pub: EddsaPublicKey;
 
     // Hash of the denomination public key that is unknown.
     h_denom_pub: HashCode;
 
     // When was the signature created.
     timestamp: Timestamp;
 
     // What kind of operation was requested that now
     // failed?
     oper: string;
 
   }
 
 
 .. ts:def:: WithdrawError
 
   interface SingleWithdrawError {
     // Text describing the error.
     hint: string;
 
     // Detailed error code.
     code: Integer;
 
     // Amount left in the reserve.
     balance: Amount;
 
   }
 
 
 
 ------------------
 
 
 .. _reveal-withdraw:
 
 **Reveal-Withdraw**
 
 This endpoint is called by the client 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 commitment to age restriction,
 and prove that the age restriction was set correctly.
 
 .. include:: exchange/post-reveal-withdraw.rst
 
 
 
 ----------
 Refreshing
 ----------
 
 Refreshing creates ``n`` new coins from ``m`` old coins, where the sum of
 denominations of the new coins must be smaller than the sum of the old coins'
 denominations plus melting (refresh) and withdrawal fees charged by the exchange.
 The refreshing API can be used by wallets to melt partially spent coins, making
 transactions with the freshly exchangeed coins unlinkabe to previous transactions
 by anyone except the wallet itself.
 
 Refreshing is a two step process, consisting of
 
 1. the **melting** of the old coin, together with ``kappa`` batches
    of blinded planchets candidates,
 2. the **reveal** of ``kappa-1`` secrets to prove the proper construction
    of the (revealed) batches of blinded planchets candidates.
 
 
 ^^^^
 Melt
 ^^^^
 
 .. _melt:
 .. include:: exchange/post-melt.rst
 
 ^^^^^^^^^^^
 Reveal-Melt
 ^^^^^^^^^^^
 
 This endpoint is called by the client after a call to `melt`_.
 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 commitment to age restriction,
 as proof that the age restriction was set correctly (if applicable).
 
 .. include:: exchange/post-reveal-melt.rst
 
 
 .. _deposit-par:
 
 -------
 Deposit
 -------
 
 Deposit operations are requested f.e. by a merchant during a transaction or a
 bidder during an auction.
 
 For the deposit operation during purchase, the merchant has to obtain the
 deposit permission for a coin from their customer who owns the coin.  When
 depositing a coin, the merchant is credited an amount specified in the deposit
 permission, possibly a fraction of the total coin's value, minus the deposit
 fee as specified by the coin's denomination.
 
 For auctions, a bidder performs an deposit operation and provides all relevant
 information for the auction policy (such as timeout and public key as bidder)
 and can use the ``exchange_sig`` field from the `DepositSuccess` message as a
 proof to the seller for the escrow of sufficient fund.
 
 
 .. _deposit:
 
 .. include:: exchange/post-batch-deposit.rst
 
 
 
 ------
 Recoup
 ------
 
 The purpose of this API is to allow coins to be cashed back in,
 in certain exceptional situations.
 This API is only used if the exchange is either about to go out of
 business or has had its private signing keys compromised (so in
 either case, the protocol is only used in **abnormal**
 situations).  In the above cases, the exchange signals to the
 wallets that the emergency cash back protocol has been activated
 by putting the affected denomination keys into the cash-back
 part of the ``/keys`` response.  If and only if this has happened,
 coins that were signed with those denomination keys can be cashed
 in using this API.
 
 For a recoup, a coin has to provide the necessary information to
 identify the original transaction (either a withdraw or a refresh) it
 became minted, and proof ownership of the coin itself.
 
 
 .. include:: exchange/post-recoup-withdraw.rst
 
 
 .. include:: exchange/post-recoup-refresh.rst
 
 
 
 .. _exchange_refund:
 
 -------
 Refunds
 -------
 
 .. include:: exchange/post-coins-COIN_PUB-refund.rst
 
 
 .. _reserve-history:
 
 ---------------
 Reserve History
 ---------------
 
 .. include:: exchange/get-reserves-RESERVE_PUB-history.rst
 
 
 
 .. _coin-history:
 
 ------------
 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
 -----------------------
 
 This API is used by merchants that need to find out which wire
 transfers (from the exchange to the merchant) correspond to which deposit
 operations.  Typically, a merchant will receive a wire transfer with a
 **wire transfer identifier** and want to know the set of deposit
 operations that correspond to this wire transfer.  This is the
 preferred query that merchants should make for each wire transfer they
 receive.  If a merchant needs to investigate a specific deposit
 operation (i.e. because it seems that it was not paid), then the
 merchant can also request the wire transfer identifier for a deposit
 operation.
 
 Sufficient information is returned to verify that the coin signatures
 are correct. This also allows governments to use this API when doing
 a tax audit on merchants.
 
 Naturally, the returned information may be sensitive for the merchant.
 We do not require the merchant to sign the request, as the same requests
 may also be performed by the government auditing a merchant.
 However, wire transfer identifiers should have sufficient entropy to
 ensure that obtaining a successful reply by brute-force is not practical.
 Nevertheless, the merchant should protect the wire transfer identifiers
 from his bank statements against unauthorized access, lest his income
 situation is revealed to an adversary. (This is not a major issue, as
 an adversary that has access to the line-items of bank statements can
 typically also view the balance.)
 
 
 .. include:: exchange/get-transfers-WTID.rst
 
 .. include:: exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.rst
 
 
 .. _exchange_w2w:
 
 --------------------------
 Wallet-to-wallet transfers
 --------------------------
 
 .. include:: exchange/get-purses-PURSE_PUB-merge.rst
 
 .. include:: exchange/post-purses-PURSE_PUB-create.rst
 
 .. include:: exchange/delete-purses-PURSE_PUB.rst
 
 .. include:: exchange/post-purses-PURSE_PUB-merge.rst
 
 .. include:: exchange/post-reserves-RESERVE_PUB-purse.rst
 
 .. include:: exchange/get-contracts-CONTRACT_PUB.rst
 
 .. include:: exchange/post-purses-PURSE_PUB-deposit.rst
 
 
 .. _exchange_wads:
 
 ----
 Wads
 ----
 
   .. note::
 
      This is a draft API that is not yet implemented.
 
 
 These endpoints are used to manage exchange-to-exchange payments in support of
 wallet-to-wallet payments.  Only another exchange should access this endpoint.
 
 
 .. include:: exchange/get-wads-WAD_ID.rst
 
 
 ------------------
 KYC status updates
 ------------------
 
 This section describes endpoints used to set up, complete and
 inquire about KYC operations performed by an exchange for
 regulatory compliance.
 
 .. include:: exchange/post-kyc-wallet.rst
 
 .. include:: exchange/get-kyc-check-H_NORMALIZED_PAYTO.rst
 
 .. include:: exchange/get-kyc-spa-ACCESS_TOKEN.rst
 
 .. include:: exchange/get-kyc-info-ACCESS_TOKEN.rst
 
 .. include:: exchange/post-kyc-upload-ID.rst
 
 .. include:: exchange/post-kyc-start-ID.rst
 
 .. include:: exchange/get-kyc-proof-PROVIDER_NAME.rst
 
 .. include:: exchange/get-kyc-webhook-PROVIDER_NAME-star.rst
 
 
 --------------
 AML operations
 --------------
 
 This API is only for designated AML officers. It is used
 to allow exchange staff to monitor suspicious transactions
 and freeze or unfreeze accounts suspected of money laundering.
 
 .. include:: exchange/get-aml-OFFICER_PUB-measures.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-decisions.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-legitimizations.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-accounts.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst
 
 .. include:: exchange/post-aml-OFFICER_PUB-decision.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-transfers-credit.rst
 
 ---------------
 Reserve control
 ---------------
 
 This section describes the reserve control API which can be used to (1)
 prevent a reserve from expiring, to (2) pay an annual fee to allow a number of
 purses to be created for the respective reserve without paying a purse fee
 each time, to (3) obtain KYC information associated with a reserve to prove
 the identity of the person sending an invoice to the payer, and to (4) close a
 reserve before it would naturally expire and possibly (5) wire the funds to a
 designated account.
 
   .. note::
 
      This section is about a proposed API. It is not implemented. See also DD 31.
 
 .. include:: exchange/post-reserves-RESERVE_PUB-open.rst
 
 .. include:: exchange/get-reserves-RESERVE_PUB-attest.rst
 
 .. include:: exchange/post-reserves-RESERVE_PUB-attest.rst
 
 .. include:: exchange/post-reserves-RESERVE_PUB-close.rst
 
 .. _delete-reserve:
 
 .. include:: exchange/delete-reserves-RESERVE_PUB.rst