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

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

}

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