taler-docs

get-reserves-RESERVE_PUB-history.rst (11731B)

---

 .. http: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 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:**
 
   :http:statuscode:`200 OK`:
     The exchange responds with a `ReserveHistory` object; the reserve was known to the exchange.
   :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 reserve history matches the one identified by the "If-none-match" HTTP header of the request.
   :http:statuscode:`403 Forbidden`:
     The *TALER_SIGNATURE_RESERVE_HISTORY_REQUEST* is invalid.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_RESERVE_HISTORY_BAD_SIGNATURE``.
   :http:statuscode:`404 Not found`:
     The reserve key does not belong to a reserve known to the exchange.
     This response comes with a standard `ErrorDetail` response with
     a code of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal error.
     This response comes with a standard `ErrorDetail` response.
     Possible error codes include
     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``, or
     ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``.
 
   **Details:**
 
   .. ts:def:: ReserveHistory
 
     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:
 
   .. ts:def:: TransactionHistoryItem
 
     // Union discriminated by the "type" field.
     type TransactionHistoryItem =
       | AccountSetupTransaction
       | ReserveWithdrawTransaction
       | ReserveCreditTransaction
       | ReserveClosingTransaction
       | ReserveRecoupTransaction
       | ReserveHistoryRequestTransaction
       | ReserveOpenRequestTransaction
       | ReserveCloseRequestTransaction
       | PurseMergeTransaction;
 
   .. ts:def:: AccountSetupTransaction
 
     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;
 
     }
 
   .. ts:def:: ReserveWithdrawTransaction
 
     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;
 
      }
 
 
   .. ts:def:: ReserveCreditTransaction
 
     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;
     }
 
 
   .. ts:def:: ReserveClosingTransaction
 
     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;
     }
 
 
   .. ts:def:: ReserveRecoupTransaction
 
     interface ReserveRecoupTransaction {
       type: "RECOUP";
 
       // Offset of this entry in the reserve history.
       // Useful to request incremental histories via
       // the "start" query parameter.
       history_offset: Integer;
 
       // Public key of the coin that was paid back.
       coin_pub: CoinPublicKey;
 
       // This is a signature over a
       // struct `TALER_RecoupConfirmationPS` with purpose
       // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``.
       exchange_sig: EddsaSignature;
 
       // Public key used to create 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
       // Time when the recoup was accepted.
       timestamp: Timestamp;
 
       // Amount recouped to the reserve.
       amount: Amount;
 
       // The commitment ``planchets_h`` of the withdraw request
       // from this reserve that the coin was part of, see
       // `RecoupWithdrawRequest`.
       // @since **vRECOUP**
       planchets_h: HashCode;
     }
 
   .. ts:def:: ReserveHistoryRequestTransaction
 
     interface ReserveHistoryRequestTransaction {
       type: "HISTORY";
 
       // Offset of this entry in the reserve history.
       // Useful to request incremental histories via
       // the "start" query parameter.
       history_offset: Integer;
 
       // Signature created with the reserve's private key.
       // Must be of purpose ``TALER_SIGNATURE_RESERVE_HISTORY_REQUEST`` over
       // a ``TALER_ReserveHistoryRequestSignaturePS``.
       reserve_sig: EddsaSignature;
 
       // Timestamp of the history request.
       request_timestamp: Timestamp;
 
       // Fee charged for the history request.
       amount: Amount;
     }
 
   .. ts:def:: ReserveOpenRequestTransaction
 
     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;
 
     }
 
   .. ts:def:: ReserveCloseRequestTransaction
 
     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;
     }
 
   .. ts:def:: PurseMergeTransaction
 
     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;
     }