The Exchange RESTful API

The request was successful, and max_age was not set. The response is a WithdrawResponse. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coins signature to disk, the coins are not lost.

201 Created:

The request was successful, and max_age was set. The response is a AgeWithdrawResponse. The client is expected to call /reveal-withdraw next. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coins signature to disk, the coins are not lost.

A signature is invalid. This response comes with a standard ErrorDetail response.

A denomination key or the reserve are not known to the exchange. If the denomination key is unknown, this suggests a bug in the wallet as the wallet should have used current denomination keys from /keys. In this case, the response will be a DenominationUnknownMessage. If the reserve is unknown, the wallet should not report a hard error yet, but instead simply wait for up to a day, as the wire transaction might simply not yet have completed and might be known to the exchange in the near future. In this case, the wallet should repeat the exact same request later again using exactly the same blinded coins.

451 Unavailable for Legal Reasons:

One of the following reasons occured:

1. The balance of the reserve is not sufficient to withdraw the coins of the indicated denominations. The response is WithdrawError object.

2. The reserve has a birthday set and requires the request to provide a max_age value. The response comes with a standard ErrorDetail response with error-code TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED and an additional field maximum_allowed_age for the maximum age (in years) that the client can commit to in a call to /withdraw, this time with max_age set accordingly and coin_evs being an array of n*kappa elements of type CoinEnvelope.

3. the provided value for max_age is higher than the allowed value according to the reserve’s birthday. The response comes with a standard ErrorDetail response with error-code TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE and an additional field maximum_allowed_age for the maximum age (in years) that the client can commit to in a call to /withdraw

410 Gone:

A requested denomination key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a DenominationGoneMessage. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.

This reserve has received funds from a purse or the amount withdrawn exceeds another legal threshold and thus the reserve must be upgraded to an account (with KYC) before the withdraw can complete. Note that this response does NOT affirm that the withdraw will ultimately complete with the requested amount. The user should be redirected to the provided location to perform the required KYC checks to open the account before withdrawing. Afterwards, the request should be repeated. The response will be an LegitimizationNeededResponse object.

Implementation note: internally, we need to distinguish between upgrading the reserve to an account (due to P2P payment) and identifying the owner of the origin bank account (due to exceeding the withdraw amount threshold), as we need to create a different payto://-URI for the KYC check depending on the case.

501 Not implemented:

The client has provided a cipher that is not supported.

Details:

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?: number;

  // 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_sig: EddsaSignature;
}

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[];

}

type BlindedDenominationSignature = DenomCipher & (
  | RsaBlindedDenominationSignature
  | CSBlindedDenominationSignature
)

interface RsaBlindedDenominationSignature extends DenomCipher {
  cipher: "RSA";

  // (blinded) RSA signature
  blinded_rsa_signature: BlindedRsaSignature;
}

interface CSBlindedDenominationSignature extends DenomCipher {
  cipher: "CS";

  // Signer chosen bit value, 0 or 1, used
  // in Clause Blind Schnorr to make the
  // ROS problem harder.
  b: Integer;

  // Blinded scalar calculated from c_b.
  s: Cs25519Scalar;

}

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 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;

}

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: number;

  // 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;

}

interface SingleWithdrawError {
  // Text describing the error.
  hint: string;

  // Detailed error code.
  code: Integer;

  // Amount left in the reserve.
  balance: Amount;

}

POST /csr-withdraw#

Note

This endpoint is deprecated starting with API version v26. Use /blinding-prepare instead.

Obtain exchange-side input values in preparation for a withdraw step for certain denomination cipher types, specifically at this point for Clause-Schnorr blind signatures.

Request: The request body must be a WithdrawPrepareRequest object.

Response:

200 OK:: The request was successful, and the response is a WithdrawPrepareResponse. Note that repeating exactly the same request will again yield the same response (assuming none of the denomination is expired).
404 Not found:: The denomination key is not known to the exchange.
410 Gone:: The requested denomination key is not yet or no longer valid. It either before the validity start, past the expiration or was revoked. The response is a DenominationGoneMessage. Clients must evaluate the error code provided to understand which of the cases this is and handle it accordingly.

Details:

interface WithdrawPrepareRequest {

  // Nonce to be used by the exchange to derive
  // its private inputs from. Must not have ever
  // been used before.
  nonce: CSNonce;

  // Hash of the public key of the denomination the
  // request relates to.
  denom_pub_hash: HashCode;

}

type WithdrawPrepareResponse =
  | ExchangeWithdrawValue;

type ExchangeWithdrawValue = DenomCipher & (
  | ExchangeRsaWithdrawValue
  | ExchangeCsWithdrawValue
);

interface DenomCipher {
  cipher: "RSA" | "CS";
}

interface ExchangeRsaWithdrawValue extends DenomCipher {
  cipher: "RSA";
}

interface ExchangeCsWithdrawValue extends DenomCipher {
  cipher: "CS";

  // CSR R0 value
  r_pub_0: CSRPublic;

  // CSR R1 value
  r_pub_1: CSRPublic;
}

POST /reserves/$RESERVE_PUB/batch-withdraw#

Note

This endpoint becomes deprecated starting with API version v26. Use the /withdraw endpoint instead, see withdraw.

Request: The request body must be a BatchWithdrawRequest object.

Response:

The request was successful, and the response is a WithdrawResponse. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coin signature to disk, the coin is not lost.

A signature is invalid. This response comes with a standard ErrorDetail response.

451 Unavailable for Legal Reasons:

One of the following reasons occured:

1. The balance of the reserve is not sufficient to withdraw the coins of the indicated denominations. The response is WithdrawError object.

2. The reserve has a birthday set and requires a request to /age-withdraw instead. The response comes with a standard ErrorDetail response with error-code TALER_EC_EXCHANGE_RESERVES_AGE_RESTRICTION_REQUIRED and an additional field maximum_allowed_age for the maximum age (in years) that the client can commit to in the call to /age-withdraw

410 Gone:

Details:

interface BatchWithdrawRequest {
  // Array of requests for the individual coins to withdraw.
  planchets: SingleWithdrawRequest[];

}

interface SingleWithdrawRequest {
  // Hash of a denomination public key, specifying the type of coin the client
  // would like the exchange to create.
  denom_pub_hash: HashCode;

  // Coin's blinded public key, should be (blindly) signed by the exchange's
  // denomination private key.
  coin_ev: CoinEnvelope;

  // Signature of TALER_SingleWithdrawRequestPS created with
  // the reserves's private key
  // using purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW.
  reserve_sig: EddsaSignature;

}

1.3.7. Reveal#

Note

These endpoints are available starting with API version v27.

These endpoints are 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).
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.

POST /reveal-melt#

Reveal previously committed values to the exchange, except for the values corresponding to the noreveal_index returned by the /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.

The coin’s’ secret material matched the commitment and the original request was well-formed. The response body is a RevealResponse.

One of the signatures is invalid. This response comes with a standard ErrorDetail response.

The provided commitment is unknown.

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.

The response body is a RevealConflictResponse.

Details:

Request body for a reveal-melt request contains a JSON object with the following fields:

interface RevealMeltRequest {
  // The commitment from the /melt/ step,
  // i.e. the SHA512 value  of
  //   1. refresh_seed
  //   2. blinding_seed, if applicable, skip otherwise
  //   4. amount with fee (NBO)
  //   5. kappa*n blinded planchet hashes (which include denomination information),
  //      depths first: [0..n)[0..n)[0..n)
  rc: string;

  // The disclosed kappa-1 signatures by the old coin's private key,
  // over Hash1a("Refresh", Cp, r, i), where Cp is the melted coin's public key,
  // r is the public refresh nonce from the metling step and i runs over the
  // _disclosed_ kappa-1 indices.
  signatures: CoinSignature[kappa-1];

  // IFF the denomination of the old coin had support for age restriction,
  // the client MUST provide the original age commitment, i. e. the
  // vector of public keys, or omitted otherwise.
  // The size of the vector MUST be the number of age groups as defined by the
  // Exchange in the field .age_groups of the extension age_restriction.
  age_commitment?: Edx25519PublicKey[];

}

type RevealResponse = WithdrawResponse;

interface RevealConflictResponse {
  // Text describing the error.
  hint: string;

  // Detailed error code.
  code: Integer;

  // Commitment as calculated by the exchange from the revealed data.
  rc_expected: HashCode;

}

POST /reveal-withdraw#

Reveal previously committed values to the exchange, except for the values corresponding to the noreveal_index returned by the /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.

The coin’s’ secret material matched the commitment and the original request was well-formed. The response body is a RevealResponse.

The provided commitment $RCH is unknown.

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 /withdraw request, but of course expected to be primarily used for diagnostics.

The response body is a RevealConflictResponse.

The following specific error codes can be returned:

An age commitment for at least one of the coins did not fulfill the required maximum age requirement of the corresponding reserve. Error code: TALER_EC_EXCHANGE_GENERIC_COIN_AGE_REQUIREMENT_FAILURE.
The computation of the hash of the commitment with provided input does result in the value of field h_commitment. Error code: TALER_EC_EXCHANGE_AGE_WITHDRAW_REVEAL_INVALID_HASH

Details:

Request body for a reveal-withdraw request contains a JSON object with the following fields:

interface RevealWithdrawRequest {
  // The reserve's public key from the previous call to /withdraw.
  reserve_pub: string;

  // This is the h_planchets running hash of all blinded planchets
  // from the previous call to /withdraw.
  h_planchets: string;

  // Array of (kappa - 1) disclosed batch secrets,
  // from which for each of the n coins in a batch
  // their coin master secret is derived,
  // from which in turn their private key,
  // blinding, nonce (for Clause-Schnorr) and
  // age-restriction is calculated.
  disclosed_batch_seeds: AgeRestrictedPlanchetSeed[];

}

// The master seed material from which for n coins in a batch,
// each the coins' private key coin_priv,  blinding beta
// and nonce nonce (for Clause-Schnorr) itself are
// derived as usually in wallet-core.  Given a coin's master key material,
// the age commitment for the coin MUST be derived from this private key as
// follows:
//
// Let m ∈  {1,...,M} be the maximum age group as defined in the reserve
// that the wallet can commit to.
//
// For age group $AG ∈  {1,...m}, set
//     seed = HDKF(coin_secret, "age-commitment", $AG)
//   p[$AG] = Edx25519_generate_private(seed)
// and calculate the corresponding Edx25519PublicKey as
//   q[$AG] = Edx25519_public_from_private(p[$AG])
//
// For age groups $AG ∈  {m+1,...,M}, set
//   f[$AG] = HDKF(coin_secret, "age-factor", $AG)
// and calculate the corresponding Edx25519PublicKey as
//   q[$AG] = Edx25519_derive_public(PublishedAgeRestrictionBaseKey, f[$AG])
//
type AgeRestrictedPlanchetSeed = string;

// The value for PublishedAgeRestrictionBaseKey is a randomly chosen
// Edx25519PublicKey for which the private key is not known to the clients.  It is
// used during the age-withdraw protocol so that clients can prove that they
// derived all public keys to age groups higher than their allowed maximum
// from this particular value.
const PublishedAgeRestrictionBaseKey =
    new Edx25519PublicKey("CH0VKFDZ2GWRWHQBBGEK9MWV5YDQVJ0RXEE0KYT3NMB69F0R96TG");

1.3.8. Reserve History#

GET /reserves/$RESERVE_PUB/history#

Request information about the full history of a reserve or an account.

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 reserve history matches the provided Etag.
Taler-Reserve-History-Signature:: The client MUST provide Base-32 encoded EdDSA signature over a TALER_SIGNATURE_RESERVE_HISTORY_REQUEST made with the respective $RESERVE_PRIV, affirming desire to download the current reserve transaction history.

Query Parameters:

start=OFFSET – Optional. Only return reserve history entries with offsets above the given OFFSET. Allows clients to not retrieve history entries they already have.

Response:

200 OK:: The exchange responds with a ReserveHistory object; the reserve was known to the exchange.
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.
304 Not modified:: The reserve history matches the one identified by the “If-none-match” HTTP header of the request.
403 Forbidden:: The TALER_SIGNATURE_RESERVE_HISTORY_REQUEST is invalid. This response comes with a standard ErrorDetail response.
404 Not found:: The reserve key does not belong to a reserve known to the exchange.

Details:

interface ReserveHistory {
  // Balance left in the reserve.
  balance: Amount;

  // If set, gives the maximum age group that the client is required to set
  // during withdrawal.
  maximum_age_group: number;

  // Transaction history for this reserve.
  // May be partial (!).
  history: TransactionHistoryItem[];
}

Objects in the transaction history have the following format:

// Union discriminated by the "type" field.
type TransactionHistoryItem =
  | AccountSetupTransaction
  | ReserveBatchWithdrawTransaction
  | ReserveWithdrawTransaction
  | ReserveCreditTransaction
  | ReserveClosingTransaction
  | ReserveOpenRequestTransaction
  | ReserveCloseRequestTransaction
  | PurseMergeTransaction;

interface AccountSetupTransaction {
  type: "SETUP";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // KYC fee agreed to by the reserve owner.
  kyc_fee: Amount;

  // Time when the KYC was triggered.
  kyc_timestamp: Timestamp;

  // Hash of the wire details of the account.
  // Note that this hash is unsalted and potentially
  // private (as it could be inverted), hence access
  // to this endpoint must be authorized using the
  // private key of the reserve.
  h_wire: HashCode;

  // Signature created with the reserve's private key.
  // Must be of purpose TALER_SIGNATURE_ACCOUNT_SETUP_REQUEST over
  // a TALER_AccountSetupRequestSignaturePS.
  reserve_sig: EddsaSignature;

}

// NOTE: This interface is will be phased out after v26
// of the protocol
interface ReserveBatchWithdrawTransaction {
  type: "BATCH_WITHDRAW";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // Amount withdrawn.
  amount: Amount;

  // Hash of the denomination public key of the coin.
  h_denom_pub: HashCode;

  // Hash of the blinded coin to be signed.
  h_coin_envelope: HashCode;

  // Signature over a TALER_SingleWithdrawRequestPS
  // with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
  // created with the reserve's private key.
  reserve_sig: EddsaSignature;

  // The maximum age committed to, if applicable
  max_age?: Integer;

  // Fee that is charged for withdraw.
  withdraw_fee: Amount;
 }

interface ReserveWithdrawTransaction {
  type: "WITHDRAW";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // Amount withdrawn.
  amount: Amount;

  // Total fee that is charged for withdraw.
  withdraw_fee: Amount;

  // Total number of coins in the withdraw request
  num_coins: Integer;

  // Signature over a TALER_WithdrawRequestPS
  // with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
  // created with the reserve's private key.
  reserve_sig: EddsaSignature;

  // The hash of the all the planchets that were provided during the
  // call to /withdraw.
  h_planchets: HashCode;

  // The blinding seed that was provided. It will be NULL if
  // no denominations of cipher type Clause-Schnorr were invovled
  blinding_seed?: BlindingMasterSeed;

  // The array of hashes of public key of denominations for the coins.
  denom_pub_hashes: HashCode[];

  // The maximum age committed to, if the withdraw request
  // required age-restriction
  max_age?: Integer;

  // The noreveal index that was returned as part
  // of a age-restricted withdraw, if applicable
  noreveal_index?: Integer;

 }

interface ReserveCreditTransaction {
  type: "CREDIT";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // Amount deposited.
  amount: Amount;

  // Sender account full payto:// URI.
  sender_account_url: string;

  // Opaque identifier internal to the exchange that
  // uniquely identifies the wire transfer that credited the reserve.
  wire_reference: Integer;

  // Timestamp of the incoming wire transfer.
  timestamp: Timestamp;
}

interface ReserveClosingTransaction {
  type: "CLOSING";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // Closing balance.
  amount: Amount;

  // Closing fee charged by the exchange.
  closing_fee: Amount;

  // Wire transfer subject.
  wtid: Base32;

  // Full payto URI of the wire account into which the funds were returned to.
  receiver_account_details: string;

  // This is a signature over a
  // struct TALER_ReserveCloseConfirmationPS with purpose
  // TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
  exchange_sig: EddsaSignature;

  // Public key used to create 'exchange_sig'.
  exchange_pub: EddsaPublicKey;

  // Time when the reserve was closed.
  timestamp: Timestamp;
}

interface ReserveOpenRequestTransaction {
  type: "OPEN";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // Open fee paid from the reserve.
  open_fee: Amount;

  // This is a signature over
  // a struct TALER_ReserveOpenPS with purpose
  // TALER_SIGNATURE_WALLET_RESERVE_OPEN.
  reserve_sig: EddsaSignature;

  // Timestamp of the open request.
  request_timestamp: Timestamp;

  // Requested expiration.
  requested_expiration: Timestamp;

  // Requested number of free open purses.
  requested_min_purses: Integer;

}

interface ReserveCloseRequestTransaction {
  type: "CLOSE";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // This is a signature over
  // a struct TALER_ReserveClosePS with purpose
  // TALER_SIGNATURE_WALLET_RESERVE_CLOSE.
  reserve_sig: EddsaSignature;

  // Hash over the full payto URI of the target account.
  h_payto?: FullPaytoHash;

  // Timestamp of the close request.
  request_timestamp: Timestamp;
}

interface PurseMergeTransaction {
  type: "MERGE";

  // Offset of this entry in the reserve history.
  // Useful to request incremental histories via
  // the "start" query parameter.
  history_offset: Integer;

  // SHA-512 hash of the contact of the purse.
  h_contract_terms: HashCode;

  // EdDSA public key used to approve merges of this purse.
  merge_pub: EddsaPublicKey;

  // Minimum age required for all coins deposited into the purse.
  min_age: Integer;

  // Number that identifies who created the purse
  // and how it was paid for.
  flags: Integer;

  // Purse public key.
  purse_pub: EddsaPublicKey;

  // EdDSA signature of the account/reserve affirming the merge
  // over a TALER_AccountMergeSignaturePS.
  // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE
  reserve_sig: EddsaSignature;

  // Client-side timestamp of when the merge request was made.
  merge_timestamp: Timestamp;

  // Indicative time by which the purse should expire
  // if it has not been merged into an account. At this
  // point, all of the deposits made should be
  // auto-refunded.
  purse_expiration: Timestamp;

  // Purse fee the reserve owner paid for the purse creation.
  purse_fee: Amount;

  // Total amount merged into the reserve.
  // (excludes fees).
  amount: Amount;

  // True if the purse was actually merged.
  // If false, only the purse_fee has an impact
  // on the reserve balance!
  merged: boolean;
}

1.3.9. Coin History#

GET /coins/$COIN_PUB/history#

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 $RESERVE_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:

200 OK:
The operation succeeded, the exchange confirms that no double-spending took place. The response will include a CoinHistoryResponse object.

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.

304 Not modified:
The coin history has not changed since the previous query (detected via Etag in “If-none-match” header).

403 Forbidden:
The TALER_SIGNATURE_COIN_HISTORY_REQUEST is invalid. This response comes with a standard ErrorDetail response.

404 Not found:
The coin public key is not (yet) known to the exchange.
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[];
}
// Union discriminated by the "type" field.
type CoinSpendHistoryItem =
  | CoinDepositTransaction
  | CoinMeltTransaction
  | CoinRefundTransaction
  | CoinRecoupTransaction
  | CoinOldCoinRecoupTransaction
  | CoinRecoupRefreshTransaction
  | CoinPurseDepositTransaction
  | CoinPurseRefundTransaction
  | CoinReserveOpenDepositTransaction;
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;

  // Signature over TALER_DepositRequestPS, made by the customer with the
  // coin's private key.
  coin_sig: EddsaSignature;

  // 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 proposal data of the contract that
  // is being paid.
  h_contract_terms: HashCode;

}
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;

  // Signature by the coin over a
  // TALER_RefreshMeltCoinAffirmationPS of
  // purpose TALER_SIGNATURE_WALLET_COIN_MELT.
  coin_sig: EddsaSignature;

  // Melt fee.
  melt_fee: Amount;

  // Commitment from the melt operation.
  rc: TALER_RefreshCommitmentP;

  // 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;

  // Date when the operation was made.
  timestamp: Timestamp;

}

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;

  // Refund transaction ID.
  rtransaction_id: Integer;

  // EdDSA Signature authorizing the REFUND over a
  // TALER_MerchantRefundConfirmationPS with
  // purpose TALER_SIGNATURE_MERCHANT_REFUND_OK. Made with
  // the public key of the merchant.
  merchant_sig: EddsaSignature;

}

interface CoinRecoupTransaction {
  type: "RECOUP";

  // 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;

  // Date when the operation was made.
  timestamp: Timestamp;

  // 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;

  // 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;

}

interface CoinOldCoinRecoupTransaction {
  type: "OLD-COIN-RECOUP";

  // 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;

}

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;

  // Date when the operation was made.
  timestamp: Timestamp;

  // 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;

  // 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;

  // Blinding factor of the revoked new coin.
  new_coin_blinding_secret: DenominationBlindingKeySecret;

  // Blinded public key of the revoked new coin.
  new_coin_ev: DenominationBlindingKeySecret;
}

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;

  // Deposit fee.
  deposit_fee: Amount;

  // Public key of the purse.
  purse_pub: EddsaPublicKey;

  // Date when the purse was set to expire.
  purse_expiration: Timestamp;

  // 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;

}

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;

  // Public key of the purse that expired.
  purse_pub: EddsaPublicKey;

  // 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;

}

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;

}

1.3.10. 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.

POST /batch-deposit#

Deposit multiple coins and ask the exchange to transfer the given Amounts into the merchant’s bank account. This API is used by the merchant to redeem the digital coins.

Request:

The request body must be a BatchDepositRequest object.

Response:

The operation succeeded, the exchange confirms that no double-spending took place. The response will include a DepositSuccess object.

One of the signatures is invalid. This response comes with a standard ErrorDetail response.

Either one of the denomination keys is not recognized (expired or invalid), or the wire type is not recognized. If a denomination key is unknown, the response will be a DenominationUnknownMessage.