free_coin_transaction_list.h (15923B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2022 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file free_coin_transaction_list.h 18 * @brief implementation of the free_coin_transaction_list function for Postgres 19 * @author Christian Grothoff 20 */ 21 #ifndef EXCHANGE_DATABASE_FREE_COIN_TRANSACTION_LIST_H 22 #define EXCHANGE_DATABASE_FREE_COIN_TRANSACTION_LIST_H 23 24 #include "exchangedb_lib.h" 25 26 27 /** 28 * @brief Enumeration to classify the different types of transactions 29 * that can be done with a coin. 30 */ 31 enum TALER_EXCHANGEDB_TransactionType 32 { 33 34 /** 35 * Deposit operation. 36 */ 37 TALER_EXCHANGEDB_TT_DEPOSIT = 0, 38 39 /** 40 * Melt operation. 41 */ 42 TALER_EXCHANGEDB_TT_MELT = 1, 43 44 /** 45 * Refund operation. 46 */ 47 TALER_EXCHANGEDB_TT_REFUND = 2, 48 49 /** 50 * Recoup-refresh operation (on the old coin, adding to the old coin's value) 51 */ 52 TALER_EXCHANGEDB_TT_RECOUP_REFRESH_RECEIVER = 3, 53 54 /** 55 * Recoup operation. 56 */ 57 TALER_EXCHANGEDB_TT_RECOUP_WITHDRAW = 4, 58 59 /** 60 * Recoup-refresh operation (on the new coin, eliminating its value) 61 */ 62 TALER_EXCHANGEDB_TT_RECOUP_REFRESH = 5, 63 64 /** 65 * Purse deposit operation. 66 */ 67 TALER_EXCHANGEDB_TT_PURSE_DEPOSIT = 6, 68 69 /** 70 * Purse deposit operation. 71 */ 72 TALER_EXCHANGEDB_TT_PURSE_REFUND = 7, 73 74 /** 75 * Reserve open deposit operation. 76 */ 77 TALER_EXCHANGEDB_TT_RESERVE_OPEN = 8 78 79 }; 80 81 82 /** 83 * @brief Specification for a deposit operation in the 84 * `struct TALER_EXCHANGEDB_TransactionList`. 85 */ 86 struct TALER_EXCHANGEDB_DepositListEntry 87 { 88 89 /** 90 * ECDSA signature affirming that the customer intends 91 * this coin to be deposited at the merchant identified 92 * by @e h_wire in relation to the proposal data identified 93 * by @e h_contract_terms. 94 */ 95 struct TALER_CoinSpendSignatureP csig; 96 97 /** 98 * Public key of the merchant. Enables later identification 99 * of the merchant in case of a need to rollback transactions. 100 */ 101 struct TALER_MerchantPublicKeyP merchant_pub; 102 103 /** 104 * Hash over the proposa data between merchant and customer 105 * (remains unknown to the Exchange). 106 */ 107 struct TALER_PrivateContractHashP h_contract_terms; 108 109 /** 110 * Hash over inputs from the wallet to customize the contract. 111 */ 112 struct GNUNET_HashCode wallet_data_hash; 113 114 /** 115 * Hash of the public denomination key used to sign the coin. 116 */ 117 struct TALER_DenominationHashP h_denom_pub; 118 119 /** 120 * Age commitment hash, if applicable to the denomination. Should be all 121 * zeroes if age commitment is not applicable to the denonimation. 122 */ 123 struct TALER_AgeCommitmentHashP h_age_commitment; 124 125 /** 126 * Salt used to compute h_wire from the @e receiver_wire_account. 127 */ 128 struct TALER_WireSaltP wire_salt; 129 130 /** 131 * Hash over the policy data for this deposit (remains unknown to the 132 * Exchange). Needed for the verification of the deposit's signature 133 */ 134 struct TALER_ExtensionPolicyHashP h_policy; 135 136 /** 137 * Fraction of the coin's remaining value to be deposited, including 138 * depositing fee (if any). The coin is identified by @e coin_pub. 139 */ 140 struct TALER_Amount amount_with_fee; 141 142 /** 143 * Depositing fee. 144 */ 145 struct TALER_Amount deposit_fee; 146 147 /** 148 * Time when this request was generated. Used, for example, to 149 * assess when (roughly) the income was achieved for tax purposes. 150 * Note that the Exchange will only check that the timestamp is not "too 151 * far" into the future (i.e. several days). The fact that the 152 * timestamp falls within the validity period of the coin's 153 * denomination key is irrelevant for the validity of the deposit 154 * request, as obviously the customer and merchant could conspire to 155 * set any timestamp. Also, the Exchange must accept very old deposit 156 * requests, as the merchant might have been unable to transmit the 157 * deposit request in a timely fashion (so back-dating is not 158 * prevented). 159 */ 160 struct GNUNET_TIME_Timestamp timestamp; 161 162 /** 163 * How much time does the merchant have to issue a refund request? 164 * Zero if refunds are not allowed. After this time, the coin 165 * cannot be refunded. 166 */ 167 struct GNUNET_TIME_Timestamp refund_deadline; 168 169 /** 170 * How much time does the merchant have to execute the wire transfer? 171 * This time is advisory for aggregating transactions, not a hard 172 * constraint (as the merchant can theoretically pick any time, 173 * including one in the past). 174 */ 175 struct GNUNET_TIME_Timestamp wire_deadline; 176 177 /** 178 * Detailed information about the receiver for executing the transaction. 179 * URL in payto://-format. 180 */ 181 struct TALER_FullPayto receiver_wire_account; 182 183 /** 184 * true, if age commitment is not applicable 185 */ 186 bool no_age_commitment; 187 188 /** 189 * true, if wallet data hash is not present 190 */ 191 bool no_wallet_data_hash; 192 193 /** 194 * True if a policy was provided with the deposit request 195 */ 196 bool has_policy; 197 198 /** 199 * Has the deposit been wired? 200 */ 201 bool done; 202 203 }; 204 205 206 /** 207 * @brief Specification for a refund operation in a coin's transaction list. 208 */ 209 struct TALER_EXCHANGEDB_RefundListEntry 210 { 211 212 /** 213 * Public key of the merchant. 214 */ 215 struct TALER_MerchantPublicKeyP merchant_pub; 216 217 /** 218 * Signature from the merchant affirming the refund. 219 */ 220 struct TALER_MerchantSignatureP merchant_sig; 221 222 /** 223 * Hash over the proposal data between merchant and customer 224 * (remains unknown to the Exchange). 225 */ 226 struct TALER_PrivateContractHashP h_contract_terms; 227 228 /** 229 * Merchant-generated REFUND transaction ID to detect duplicate 230 * refunds. 231 */ 232 uint64_t rtransaction_id; 233 234 /** 235 * Fraction of the original deposit's value to be refunded, including 236 * refund fee (if any). The coin is identified by @e coin_pub. 237 */ 238 struct TALER_Amount refund_amount; 239 240 /** 241 * Refund fee to be covered by the customer. 242 */ 243 struct TALER_Amount refund_fee; 244 245 }; 246 247 248 /** 249 * Information about a /coins/$COIN_PUB/melt operation in a coin transaction history. 250 */ 251 struct TALER_EXCHANGEDB_MeltListEntry 252 { 253 254 /** 255 * Signature over the melting operation. 256 */ 257 struct TALER_CoinSpendSignatureP coin_sig; 258 259 /** 260 * Refresh commitment this coin is melted into. 261 */ 262 struct TALER_RefreshCommitmentP rc; 263 264 /** 265 * Hash of the public denomination key used to sign the coin. 266 */ 267 struct TALER_DenominationHashP h_denom_pub; 268 269 /** 270 * Hash of the age commitment used to sign the coin, if age restriction was 271 * applicable to the denomination. May be all zeroes if no age restriction 272 * applies. 273 */ 274 struct TALER_AgeCommitmentHashP h_age_commitment; 275 276 /** 277 * true, if no @e h_age_commitment is applicable 278 */ 279 bool no_age_commitment; 280 281 /** 282 * How much value is being melted? This amount includes the fees, 283 * so the final amount contributed to the melt is this value minus 284 * the fee for melting the coin. We include the fee in what is 285 * being signed so that we can verify a reserve's remaining total 286 * balance without needing to access the respective denomination key 287 * information each time. 288 */ 289 struct TALER_Amount amount_with_fee; 290 291 /** 292 * Melt fee the exchange charged. 293 */ 294 struct TALER_Amount melt_fee; 295 296 /** 297 * Index (smaller #TALER_CNC_KAPPA) which the exchange has chosen to not 298 * have revealed during cut and choose. 299 */ 300 uint32_t noreveal_index; 301 302 /** 303 * The refresh seed that was used for the melt operation 304 */ 305 struct TALER_PublicRefreshMasterSeedP refresh_seed; 306 307 /** 308 * Number of fresh coins requested by this melt. 309 */ 310 size_t num_coins; 311 312 /** 313 * Denomination hashes for the fresh coins, in the original request order. 314 * Contains @e num_coins entries, including repeated denominations. 315 */ 316 struct TALER_DenominationHashP *denom_pub_hashes; 317 318 /** 319 * If false, @e blinding_seed is present 320 */ 321 bool no_blinding_seed; 322 323 /** 324 * If @e no_blinding_seed it false, the blinding seed that was used 325 * for the melt operation, in case of CS denominations. 326 */ 327 struct TALER_BlindingMasterSeedP blinding_seed; 328 329 }; 330 331 332 /** 333 * Information the exchange records about a recoup request 334 * in a coin history. 335 */ 336 struct TALER_EXCHANGEDB_RecoupListEntry 337 { 338 339 /** 340 * Blinding factor supplied to prove to the exchange that 341 * the coin came from this reserve. 342 */ 343 union GNUNET_CRYPTO_BlindingSecretP coin_blind; 344 345 /** 346 * Signature of the coin of type 347 * #TALER_SIGNATURE_WALLET_COIN_RECOUP. 348 */ 349 struct TALER_CoinSpendSignatureP coin_sig; 350 351 /** 352 * Hash of the public denomination key used to sign the coin. 353 */ 354 struct TALER_DenominationHashP h_denom_pub; 355 356 /** 357 * Public key of the reserve the coin was paid back into. 358 */ 359 struct TALER_ReservePublicKeyP reserve_pub; 360 361 /** 362 * How much was the coin still worth at this time? 363 */ 364 struct TALER_Amount value; 365 366 /** 367 * When did the /recoup operation happen? 368 */ 369 struct GNUNET_TIME_Timestamp timestamp; 370 371 }; 372 373 374 /** 375 * Information the exchange records about a recoup-refresh request in 376 * a coin transaction history. 377 */ 378 struct TALER_EXCHANGEDB_RecoupRefreshListEntry 379 { 380 381 /** 382 * Information about the coin that was paid back 383 * (NOT the coin we are considering the history of!) 384 */ 385 struct TALER_CoinPublicInfo coin; 386 387 /** 388 * Blinding factor supplied to prove to the exchange that 389 * the coin came from this @e old_coin_pub. 390 */ 391 union GNUNET_CRYPTO_BlindingSecretP coin_blind; 392 393 /** 394 * Signature of the coin of type 395 * #TALER_SIGNATURE_WALLET_COIN_RECOUP. 396 */ 397 struct TALER_CoinSpendSignatureP coin_sig; 398 399 /** 400 * Public key of the old coin that the refreshed coin was paid back to. 401 */ 402 struct TALER_CoinSpendPublicKeyP old_coin_pub; 403 404 /** 405 * How much was the coin still worth at this time? 406 */ 407 struct TALER_Amount value; 408 409 /** 410 * When did the recoup operation happen? 411 */ 412 struct GNUNET_TIME_Timestamp timestamp; 413 414 }; 415 416 417 /** 418 * Information about a /purses/$PID/deposit operation in a coin transaction history. 419 */ 420 struct TALER_EXCHANGEDB_PurseDepositListEntry 421 { 422 423 /** 424 * Exchange hosting the purse, NULL for this exchange. 425 */ 426 char *exchange_base_url; 427 428 /** 429 * Public key of the purse. 430 */ 431 struct TALER_PurseContractPublicKeyP purse_pub; 432 433 /** 434 * Contribution of the coin to the purse, including 435 * deposit fee. 436 */ 437 struct TALER_Amount amount; 438 439 /** 440 * Depositing fee. 441 */ 442 struct TALER_Amount deposit_fee; 443 444 /** 445 * Signature by the coin affirming the deposit. 446 */ 447 struct TALER_CoinSpendSignatureP coin_sig; 448 449 /** 450 * Hash of the age commitment used to sign the coin, if age restriction was 451 * applicable to the denomination. 452 */ 453 struct TALER_AgeCommitmentHashP h_age_commitment; 454 455 /** 456 * Hash of the public denomination key used to sign the coin. 457 */ 458 struct TALER_DenominationHashP h_denom_pub; 459 460 /** 461 * Set to true if the coin was refunded. 462 */ 463 bool refunded; 464 465 /** 466 * Set to true if there was no age commitment. 467 */ 468 bool no_age_commitment; 469 470 }; 471 472 473 /** 474 * @brief Specification for a purse refund operation in a coin's transaction list. 475 */ 476 struct TALER_EXCHANGEDB_PurseRefundListEntry 477 { 478 479 /** 480 * Public key of the purse. 481 */ 482 struct TALER_PurseContractPublicKeyP purse_pub; 483 484 /** 485 * Fraction of the original deposit's value to be refunded, including 486 * refund fee (if any). The coin is identified by @e coin_pub. 487 */ 488 struct TALER_Amount refund_amount; 489 490 /** 491 * Refund fee to be covered by the customer. 492 */ 493 struct TALER_Amount refund_fee; 494 495 }; 496 497 498 /** 499 * Information about a /reserves/$RID/open operation in a coin transaction history. 500 */ 501 struct TALER_EXCHANGEDB_ReserveOpenListEntry 502 { 503 504 /** 505 * Signature of the reserve. 506 */ 507 struct TALER_ReserveSignatureP reserve_sig; 508 509 /** 510 * Contribution of the coin to the open fee, including 511 * deposit fee. 512 */ 513 struct TALER_Amount coin_contribution; 514 515 /** 516 * Signature by the coin affirming the open deposit. 517 */ 518 struct TALER_CoinSpendSignatureP coin_sig; 519 520 /** 521 * Hash of the age commitment used to sign the coin, if age restriction was 522 * applicable to the denomination. 523 */ 524 struct TALER_AgeCommitmentHashP h_age_commitment; 525 526 /** 527 * Set to true if there was no age commitment. 528 */ 529 bool no_age_commitment; 530 531 }; 532 533 534 /** 535 * @brief List of transactions we performed for a particular coin. 536 */ 537 struct TALER_EXCHANGEDB_TransactionList 538 { 539 540 /** 541 * Next pointer in the NULL-terminated linked list. 542 */ 543 struct TALER_EXCHANGEDB_TransactionList *next; 544 545 /** 546 * Type of the transaction, determines what is stored in @e details. 547 */ 548 enum TALER_EXCHANGEDB_TransactionType type; 549 550 /** 551 * Serial ID of this entry in the @e type-specific table. 552 */ 553 uint64_t serial_id; 554 555 /** 556 * Serial ID of this entry in the coin history table. 557 */ 558 uint64_t coin_history_id; 559 560 /** 561 * Details about the transaction, depending on @e type. 562 */ 563 union 564 { 565 566 /** 567 * Details if transaction was a deposit operation. 568 * (#TALER_EXCHANGEDB_TT_DEPOSIT) 569 */ 570 struct TALER_EXCHANGEDB_DepositListEntry *deposit; 571 572 /** 573 * Details if transaction was a melt operation. 574 * (#TALER_EXCHANGEDB_TT_MELT) 575 */ 576 struct TALER_EXCHANGEDB_MeltListEntry *melt; 577 578 /** 579 * Details if transaction was a refund operation. 580 * (#TALER_EXCHANGEDB_TT_REFUND) 581 */ 582 struct TALER_EXCHANGEDB_RefundListEntry *refund; 583 584 /** 585 * Details if transaction was a recoup-refund operation where 586 * this coin was the OLD coin. 587 * (#TALER_EXCHANGEDB_TT_RECOUP_REFRESH_RECEIVER). 588 */ 589 struct TALER_EXCHANGEDB_RecoupRefreshListEntry *old_coin_recoup; 590 591 /** 592 * Details if transaction was a recoup operation. 593 * (#TALER_EXCHANGEDB_TT_RECOUP_WITHDRAW) 594 */ 595 struct TALER_EXCHANGEDB_RecoupListEntry *recoup; 596 597 /** 598 * Details if transaction was a recoup-refund operation where 599 * this coin was the REFRESHED coin. 600 * (#TALER_EXCHANGEDB_TT_RECOUP_REFRESH) 601 */ 602 struct TALER_EXCHANGEDB_RecoupRefreshListEntry *recoup_refresh; 603 604 /** 605 * Coin was deposited into a purse. 606 * (#TALER_EXCHANGEDB_TT_PURSE_DEPOSIT) 607 */ 608 struct TALER_EXCHANGEDB_PurseDepositListEntry *purse_deposit; 609 610 /** 611 * Coin was refunded upon purse expiration 612 * (#TALER_EXCHANGEDB_TT_PURSE_REFUND) 613 */ 614 struct TALER_EXCHANGEDB_PurseRefundListEntry *purse_refund; 615 616 /** 617 * Coin was used to pay to open a reserve. 618 * (#TALER_EXCHANGEDB_TT_RESERVE_OPEN) 619 */ 620 struct TALER_EXCHANGEDB_ReserveOpenListEntry *reserve_open; 621 622 } details; 623 624 }; 625 626 /** 627 * Calculate the total value of all transactions performed. 628 * Stores @a off plus the cost of all transactions in @a tl 629 * in @a ret. 630 * 631 * No primary test table; exercised by test_misc.c. 632 * 633 * @param tl transaction list to process 634 * @param off offset to use as the starting value 635 * @param[out] ret where the resulting total is to be stored 636 * @return #GNUNET_OK on success, #GNUNET_SYSERR on errors 637 */ 638 enum GNUNET_GenericReturnValue 639 TALER_EXCHANGEDB_calculate_transaction_list_totals ( 640 struct TALER_EXCHANGEDB_TransactionList *tl, 641 const struct TALER_Amount *off, 642 struct TALER_Amount *ret); 643 644 645 /** 646 * Free linked list of transactions. 647 * 648 * No primary test table; exercised by test_misc.c. 649 * 650 * @param[in] tl list to free 651 */ 652 void 653 TALER_EXCHANGEDB_free_coin_transaction_list ( 654 struct TALER_EXCHANGEDB_TransactionList *tl); 655 656 657 #endif