taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-coins-COIN_PUB-history.rst (18667B)


      1 .. http:get:: /coins/$COIN_PUB/history
      2 
      3   Obtain the transaction history of a coin.  Used only in special cases, like
      4   when the exchange claims a double-spending error and the wallet does not
      5   believe it. Usually, the wallet knows the transaction history of each coin
      6   and thus has no need to inquire.
      7 
      8   **Request:**
      9 
     10   *Taler-Coin-History-Signature*:
     11     The client MUST provide a Base-32 encoded EdDSA signature over a
     12     :ref:`TALER_CoinHistoryRequestPS <TALER_CoinHistoryRequestPS>` of purpose
     13     ``TALER_SIGNATURE_WALLET_COIN_HISTORY`` made with the respective
     14     ``$COIN_PRIV``, affirming desire to download the coin's
     15     transaction history.  The signature covers the ``start``
     16     offset of the request (0 if ``start`` is not given).
     17 
     18   *If-None-Match*:
     19     The client MAY provide an ``If-None-Match`` header with an
     20     Etag.  In that case, the server MUST additionally respond with an ``304``
     21     status code in case the coin history matches the provided Etag.
     22 
     23   :query start=OFFSET: *Optional.* Only return coin history entries with
     24                        offsets above the given OFFSET. Allows clients to not
     25                        retrieve history entries they already have.
     26 
     27   **Response:**
     28 
     29   :http:statuscode:`200 OK`:
     30     The coin is known to the exchange and the response is
     31     the coin's transaction history.
     32     The response will be a `CoinHistoryResponse` object.
     33   :http:statuscode:`204 No content`:
     34     The coin history is known, but at this point from the given
     35     starting point it is empty. Can only happen if OFFSET was
     36     positive (and the ETag changed or ``If-None-Match`` was not given).
     37   :http:statuscode:`304 Not modified`:
     38     The coin history has not changed since the previous query
     39     (detected via Etag in "If-none-match" header).
     40   :http:statuscode:`403 Forbidden`:
     41     The *Taler-Coin-History-Signature* is invalid.
     42     This response comes with a standard `ErrorDetail` response with
     43     a code of ``TALER_EC_EXCHANGE_COIN_HISTORY_BAD_SIGNATURE``.
     44   :http:statuscode:`404 Not found`:
     45     The coin is unknown to the exchange.
     46     This response comes with a standard `ErrorDetail` response with
     47     a code of ``TALER_EC_EXCHANGE_GENERIC_COIN_UNKNOWN``.
     48   :http:statuscode:`500 Internal Server Error`:
     49     The server experienced an internal error.
     50     This response comes with a standard `ErrorDetail` response.
     51     Possible error codes include
     52     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     53     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``, or
     54     ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``
     55 
     56   **Details:**
     57 
     58   .. ts:def:: CoinHistoryResponse
     59 
     60     interface CoinHistoryResponse {
     61       // Current balance of the coin.
     62       balance: Amount;
     63 
     64       // Hash of the coin's denomination.
     65       h_denom_pub: HashCode;
     66 
     67       // Transaction history for the coin.
     68       history: CoinSpendHistoryItem[];
     69     }
     70 
     71   .. ts:def:: CoinSpendHistoryItem
     72 
     73     // Union discriminated by the "type" field.
     74     type CoinSpendHistoryItem =
     75       | CoinDepositTransaction
     76       | CoinMeltTransaction
     77       | CoinRefundTransaction
     78       | CoinRecoupWithdrawTransaction
     79       | CoinRecoupRefreshTransaction
     80       | CoinRecoupRefreshReceiverTransaction
     81       | CoinPurseDepositTransaction
     82       | CoinPurseRefundTransaction
     83       | CoinReserveOpenDepositTransaction;
     84 
     85   .. ts:def:: CoinDepositTransaction
     86 
     87     interface CoinDepositTransaction {
     88       type: "DEPOSIT";
     89 
     90       // Offset of this entry in the coin history.
     91       // Useful to request incremental histories via
     92       // the "start" query parameter.
     93       history_offset: Integer;
     94 
     95       // The total amount of the coin's value absorbed (or restored in the
     96       // case of a refund) by this transaction.
     97       // The amount given includes
     98       // the deposit fee. The current coin value can thus be computed by
     99       // subtracting this amount.
    100       amount: Amount;
    101 
    102       // Deposit fee.
    103       deposit_fee: Amount;
    104 
    105       // Public key of the merchant.
    106       merchant_pub: EddsaPublicKey;
    107 
    108       // Date when the operation was made.
    109       timestamp: Timestamp;
    110 
    111       // Date until which the merchant can issue a refund to the customer via the
    112       // exchange, possibly zero if refunds are not allowed.
    113       refund_deadline?: Timestamp;
    114 
    115       // Hash over the proposal data of the contract that
    116       // is being paid.
    117       h_contract_terms: HashCode;
    118 
    119       // Hash of the bank account from where we received the funds.
    120       h_wire: HashCode;
    121 
    122       // Hash of the public denomination key used to sign the coin.
    123       // Needed because 'coin_sig' signs over this, and
    124       // that is important to fix the coin's denomination.
    125       h_denom_pub: HashCode;
    126 
    127       // Hash over the deposit policy extension. Optional.
    128       h_policy?: HashCode;
    129 
    130       // Hash over auxiliary wallet data provided by the wallet
    131       // to complete the contract. Optional.
    132       wallet_data_hash?: HashCode;
    133 
    134       // Hash over the age commitment of the coin. Optional.
    135       h_age_commitment?: HashCode;
    136 
    137       // Signature over `TALER_DepositRequestPS`, made by the customer with the
    138       // `coin's private key <coin-priv>`.
    139       coin_sig: EddsaSignature;
    140 
    141     }
    142 
    143   .. ts:def:: CoinMeltTransaction
    144 
    145     // The entry does not change when the melt is revealed.  To obtain
    146     // the blinded signatures over the fresh coins, the owner of the old
    147     // coin repeats the /reveal-melt request, which is idempotent.
    148     interface CoinMeltTransaction {
    149       type: "MELT";
    150 
    151       // Offset of this entry in the coin history.
    152       // Useful to request incremental histories via
    153       // the "start" query parameter.
    154       history_offset: Integer;
    155 
    156       // The total amount of the coin's value absorbed by this transaction.
    157       // Note that for melt this means the amount given includes
    158       // the melt fee. The current coin value can thus be computed by
    159       // subtracting the amounts.
    160       amount: Amount;
    161 
    162       // Melt fee.
    163       melt_fee: Amount;
    164 
    165       // Commitment from the melt operation, see `TALER_RefreshCommitmentP`.
    166       rc: HashCode;
    167 
    168       // Hash of the public denomination key used to sign the old coin.
    169       // Needed because ``coin_sig`` signs over this, and
    170       // that is important to fix the coin's denomination.
    171       h_denom_pub: HashCode;
    172 
    173       // Hash over the age commitment of the coin. Optional.
    174       h_age_commitment?: AgeCommitmentHash;
    175 
    176       // @since **v32**
    177       // This value is opaque to the exchange.  It was provided by the client
    178       // as part of the original melt request, and was therefore verified
    179       // with the ``coin_sig`` below.
    180       // If the reveal step was not performed yet by the old coin owner,
    181       // they can use this value and the old coin's private key to derive
    182       // all individual seeds for the n*κ coin candidates for the original
    183       // melt request and replay it.
    184       refresh_seed: HashCode;
    185 
    186       // @since **v32**
    187       // The n denomination public keys for the fresh coins
    188       // that the coin owner had requested, in the order of the request.
    189       denoms_h: HashCode[];
    190 
    191       // @since **v46**
    192       // The ``noreveal_index`` value that was returned by the exchange as
    193       // response to the melt request.
    194       noreveal_index: Integer;
    195 
    196       // @since **v46**
    197       // The n transfer public keys of the batch at ``noreveal_index``,
    198       // as provided by the old coin owner in the melt request.
    199       // Together with the old coin's private key they determine the
    200       // secrets of the fresh coins.
    201       // Absent if the melt request did not include transfer public keys.
    202       transfer_pubs?: EddsaPublicKey[];
    203 
    204       // Master seed for the Clause-Schnorr R-value
    205       // Present if one of the fresh coin's
    206       // denominations is of type Clause-Schnorr.
    207       blinding_seed?: BlindingMasterSeed;
    208 
    209       // Signature by the coin over a
    210       // `TALER_RefreshMeltCoinAffirmationPS` of
    211       // purpose ``TALER_SIGNATURE_WALLET_COIN_MELT``.
    212       coin_sig: EddsaSignature;
    213 
    214     }
    215 
    216   .. ts:def:: CoinRefundTransaction
    217 
    218     interface CoinRefundTransaction {
    219       type: "REFUND";
    220 
    221       // Offset of this entry in the coin history.
    222       // Useful to request incremental histories via
    223       // the "start" query parameter.
    224       history_offset: Integer;
    225 
    226       // The total amount of the coin's value restored
    227       // by this transaction.
    228       // The amount given excludes the transaction fee.
    229       // The current coin value can thus be computed by
    230       // adding the amounts to the coin's denomination value.
    231       amount: Amount;
    232 
    233       // Refund fee.
    234       refund_fee: Amount;
    235 
    236       // Hash over the proposal data of the contract that
    237       // is being refunded.
    238       h_contract_terms: HashCode;
    239 
    240       // Public key of the merchant.
    241       merchant_pub: EddsaPublicKey;
    242 
    243       // Refund transaction ID.
    244       rtransaction_id: Integer;
    245 
    246       // `EdDSA Signature <eddsa-sig>` authorizing the REFUND over a
    247       // `TALER_MerchantRefundConfirmationPS` with
    248       // purpose ``TALER_SIGNATURE_MERCHANT_REFUND_OK``. Made with
    249       // the `public key of the merchant <merchant-pub>`.
    250       merchant_sig: EddsaSignature;
    251 
    252     }
    253 
    254 
    255   .. ts:def:: CoinRecoupWithdrawTransaction
    256 
    257     // This represents a transaction of a call to /recoup-withdraw
    258     // where the coin's residual value has been credited to the
    259     // original reserve, from which this coin was withdrawn.
    260     // @since **v42**
    261     interface CoinRecoupWithdrawTransaction {
    262       type: "RECOUP-WITHDRAW";
    263 
    264       // Offset of this entry in the coin history.
    265       // Useful to request incremental histories via
    266       // the "start" query parameter.
    267       history_offset: Integer;
    268 
    269       // The total amount of the coin's value absorbed
    270       // by this transaction.
    271       // The current coin value can thus be computed by
    272       // subtracting the amount from
    273       // the coin's denomination value.
    274       amount: Amount;
    275 
    276       // Signature by the exchange over a
    277       // `TALER_RecoupConfirmationPS`, must be
    278       // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP``.
    279       exchange_sig: EddsaSignature;
    280 
    281       // Public key of the private key used to create 'exchange_sig'.
    282       exchange_pub: EddsaPublicKey;
    283 
    284       // Signature by the coin over a
    285       // `TALER_RecoupRequestPS` with purpose
    286       // ``TALER_SIGNATURE_WALLET_COIN_RECOUP``.
    287       coin_sig: EddsaSignature;
    288 
    289       // Hash of the public denomination key used to sign the coin.
    290       // Needed because 'coin_sig' signs over this, and
    291       // that is important to fix the coin's denomination.
    292       h_denom_pub: HashCode;
    293 
    294       // Coin blinding secret that was used in the original withdraw
    295       // request and disclosed in the recoup request.
    296       coin_blinding_secret: DenominationBlindingKeySecret;
    297 
    298       // The commitment ``planchets_h`` of the original withdraw
    299       // request that this coin was part of, see `RecoupWithdrawRequest`.
    300       planchets_h: HashCode;
    301 
    302       // Index of this coin in the batch of coins the exchange signed
    303       // in the original withdraw request, starting at 0.
    304       coin_index: Integer;
    305 
    306       // Reserve receiving the recoup.
    307       reserve_pub: EddsaPublicKey;
    308 
    309       // Date when the operation was made.
    310       timestamp: Timestamp;
    311 
    312     }
    313 
    314   .. ts:def:: CoinRecoupRefreshTransaction
    315 
    316     // This represents a transaction of a call to /recoup-refresh
    317     // where this coin was _part_ of the batch of coins whose
    318     // residual values were credited to the original coin, from
    319     // which also this coin was refreshed from.
    320     // @since **v42**
    321     interface CoinRecoupRefreshTransaction {
    322       type: "RECOUP-REFRESH";
    323 
    324       // Offset of this entry in the coin history.
    325       // Useful to request incremental histories via
    326       // the "start" query parameter.
    327       history_offset: Integer;
    328 
    329       // The total amount of the coin's value absorbed
    330       // by this transaction.
    331       // The current coin value can thus be computed by
    332       // subtracting the amount from
    333       // the coin's denomination value.
    334       amount: Amount;
    335 
    336       // Signature by the exchange over a
    337       // `TALER_RecoupRefreshConfirmationPS`
    338       // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
    339       exchange_sig: EddsaSignature;
    340 
    341       // Public key used to sign 'exchange_sig'.
    342       exchange_pub: EddsaPublicKey;
    343 
    344       // The original coin, from which this coin was derived from
    345       // in a call to /melt, and which was then credited with
    346       // the residual value of this coin in a call to /recoup-refresh.
    347       old_coin_pub: EddsaPublicKey;
    348 
    349       // Signature by the coin over a `TALER_RecoupRequestPS`
    350       // with purpose ``TALER_SIGNATURE_WALLET_COIN_RECOUP_REFRESH``.
    351       coin_sig: EddsaSignature;
    352 
    353       // Hash of the public denomination key used to sign the coin.
    354       // Needed because 'coin_sig' signs over this, and
    355       // that is important to fix the coin's denomination.
    356       h_denom_pub: HashCode;
    357 
    358       // Coin blinding secret that was used in the original melt
    359       // request and disclosed in the recoup request.
    360       coin_blinding_secret: DenominationBlindingKeySecret;
    361 
    362       // The refresh commitment ``rc`` of the original melt request
    363       // that this coin was derived from, see `RecoupRefreshRequest`.
    364       rc: HashCode;
    365 
    366       // Index of this coin in the batch of coins the exchange signed
    367       // in the original refresh operation, starting at 0.
    368       coin_index: Integer;
    369 
    370       // Date when the operation was made.
    371       timestamp: Timestamp;
    372 
    373     }
    374 
    375   .. ts:def:: CoinRecoupRefreshReceiverTransaction
    376 
    377     // This represents a transaction of a call to /recoup-refresh
    378     // where this coin was the _receiver_ of the residual value
    379     // of a coin that originated from a call to /melt of this coin.
    380     // There is one such entry per recouped coin.
    381     // @since **v42**
    382     interface CoinRecoupRefreshReceiverTransaction {
    383       type: "RECOUP-REFRESH-RECEIVER";
    384 
    385       // Offset of this entry in the coin history.
    386       // Useful to request incremental histories via
    387       // the "start" query parameter.
    388       history_offset: Integer;
    389 
    390       // The total amount of the coin's value restored
    391       // by this transaction.
    392       // The current coin value can thus be computed by
    393       // adding the amount to the coin's denomination value.
    394       amount: Amount;
    395 
    396       // Date when the operation was made.
    397       timestamp: Timestamp;
    398 
    399       // Signature by the exchange over a
    400       // `TALER_RecoupRefreshConfirmationPS`
    401       // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP_REFRESH``.
    402       exchange_sig: EddsaSignature;
    403 
    404       // Public key of the private key used to create 'exchange_sig'.
    405       exchange_pub: EddsaPublicKey;
    406 
    407       // Public key of the coin that was recouped, that is the coin
    408       // derived from this coin whose residual value was credited.
    409       coin_pub: CoinPublicKey;
    410 
    411       // The refresh commitment ``rc`` of the melt request of this
    412       // coin from which the recouped coin was derived.
    413       rc: HashCode;
    414 
    415     }
    416 
    417   .. ts:def:: CoinPurseDepositTransaction
    418 
    419     interface CoinPurseDepositTransaction {
    420       type: "PURSE-DEPOSIT";
    421 
    422       // Offset of this entry in the coin history.
    423       // Useful to request incremental histories via
    424       // the "start" query parameter.
    425       history_offset: Integer;
    426 
    427       // The total amount of the coin's value absorbed
    428       // by this transaction.
    429       // Note that this means the amount given includes
    430       // the deposit fee. The current coin value can thus be computed by
    431       // subtracting the amount from
    432       // the coin's denomination value.
    433       amount: Amount;
    434 
    435       // Base URL of the exchange the purse lives at.
    436       exchange_base_url: WebURL;
    437 
    438       // The hash of the age-commitment for the coin. Only present
    439       // if the denomination has support for age restriction.
    440       h_age_commitment?: AgeCommitmentHash;
    441 
    442       // Deposit fee.
    443       deposit_fee: Amount;
    444 
    445       // Public key of the purse.
    446       purse_pub: EddsaPublicKey;
    447 
    448       // True if the deposit was refunded for any reason.
    449       refunded: boolean;
    450 
    451       // Signature by the coin over a
    452       // `TALER_PurseDepositSignaturePS` of
    453       // purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``.
    454       coin_sig: EddsaSignature;
    455 
    456       // Hash of the public denomination key used to sign the coin.
    457       // Needed because 'coin_sig' signs over this, and
    458       // that is important to fix the coin's denomination.
    459       h_denom_pub: HashCode;
    460 
    461     }
    462 
    463   .. ts:def:: CoinPurseRefundTransaction
    464 
    465     interface CoinPurseRefundTransaction {
    466       type: "PURSE-REFUND";
    467 
    468       // Offset of this entry in the coin history.
    469       // Useful to request incremental histories via
    470       // the "start" query parameter.
    471       history_offset: Integer;
    472 
    473       // Full amount of the original PURSE-DEPOSIT, including its deposit fee.
    474       // Expiry or DELETEing a purse restores this amount to the coin.
    475       amount: Amount;
    476 
    477       // Always zero in the coin's currency. The denomination's refund fee
    478       // never applies to PURSE-REFUND. This field is required and signed.
    479       refund_fee: Amount;
    480 
    481       // Signature by the exchange over a
    482       // ``TALER_CoinPurseRefundConfirmationPS``
    483       // of purpose ``TALER_SIGNATURE_EXCHANGE_CONFIRM_PURSE_REFUND``.
    484       exchange_sig: EddsaSignature;
    485 
    486       // Public key used to sign 'exchange_sig'.
    487       exchange_pub: EddsaPublicKey;
    488 
    489       // Public key of the refunded purse.
    490       purse_pub: EddsaPublicKey;
    491 
    492     }
    493 
    494   Older exchanges signed a net ``amount`` and the denomination's
    495   ``refund_fee`` even though they restored the full deposit. Clients reading
    496   these histories verify the signature over the reported fields and check
    497   that their sum equals the original ``PURSE-DEPOSIT`` amount for this purse
    498   and coin.
    499 
    500   .. ts:def:: CoinReserveOpenDepositTransaction
    501 
    502     interface CoinReserveOpenDepositTransaction {
    503       type: "RESERVE-OPEN-DEPOSIT";
    504 
    505       // Offset of this entry in the coin history.
    506       // Useful to request incremental histories via
    507       // the "start" query parameter.
    508       history_offset: Integer;
    509 
    510       // The total amount of the coin's value absorbed
    511       // by this transaction.
    512       // Note that this means the amount given includes
    513       // the deposit fee.
    514       coin_contribution: Amount;
    515 
    516       // Hash over the age commitment of the coin. Optional.
    517       // Since **v35**.
    518       h_age_commitment?: HashCode;
    519 
    520       // Signature of the reserve open operation being paid for.
    521       reserve_sig: EddsaSignature;
    522 
    523       // Signature by the coin over a
    524       // `TALER_ReserveOpenDepositSignaturePS` of
    525       // purpose ``TALER_SIGNATURE_RESERVE_OPEN_DEPOSIT``.
    526       coin_sig: EddsaSignature;
    527 
    528     }