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 }