free_coin_transaction_list.h (16466B)
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 * Commitment of the withdraw operation the coin originated from. 373 */ 374 struct TALER_HashBlindedPlanchetsP planchets_h; 375 376 /** 377 * Index of the coin in the batch of coins signed in that 378 * withdraw operation, starting at 0. 379 */ 380 uint32_t coin_index; 381 382 }; 383 384 385 /** 386 * Information the exchange records about a recoup-refresh request in 387 * a coin transaction history. 388 */ 389 struct TALER_EXCHANGEDB_RecoupRefreshListEntry 390 { 391 392 /** 393 * Information about the coin that was paid back 394 * (NOT the coin we are considering the history of!) 395 */ 396 struct TALER_CoinPublicInfo coin; 397 398 /** 399 * Blinding factor supplied to prove to the exchange that 400 * the coin came from this @e old_coin_pub. 401 */ 402 union GNUNET_CRYPTO_BlindingSecretP coin_blind; 403 404 /** 405 * Signature of the coin of type 406 * #TALER_SIGNATURE_WALLET_COIN_RECOUP. 407 */ 408 struct TALER_CoinSpendSignatureP coin_sig; 409 410 /** 411 * Public key of the old coin that the refreshed coin was paid back to. 412 */ 413 struct TALER_CoinSpendPublicKeyP old_coin_pub; 414 415 /** 416 * How much was the coin still worth at this time? 417 */ 418 struct TALER_Amount value; 419 420 /** 421 * When did the recoup operation happen? 422 */ 423 struct GNUNET_TIME_Timestamp timestamp; 424 425 /** 426 * Commitment of the refresh operation the recouped coin 427 * originated from. 428 */ 429 struct TALER_RefreshCommitmentP rc; 430 431 /** 432 * Index of the recouped coin in the batch of coins signed in that 433 * refresh operation, starting at 0. 434 */ 435 uint32_t coin_index; 436 437 }; 438 439 440 /** 441 * Information about a /purses/$PID/deposit operation in a coin transaction history. 442 */ 443 struct TALER_EXCHANGEDB_PurseDepositListEntry 444 { 445 446 /** 447 * Exchange hosting the purse, NULL for this exchange. 448 */ 449 char *exchange_base_url; 450 451 /** 452 * Public key of the purse. 453 */ 454 struct TALER_PurseContractPublicKeyP purse_pub; 455 456 /** 457 * Contribution of the coin to the purse, including 458 * deposit fee. 459 */ 460 struct TALER_Amount amount; 461 462 /** 463 * Depositing fee. 464 */ 465 struct TALER_Amount deposit_fee; 466 467 /** 468 * Signature by the coin affirming the deposit. 469 */ 470 struct TALER_CoinSpendSignatureP coin_sig; 471 472 /** 473 * Hash of the age commitment used to sign the coin, if age restriction was 474 * applicable to the denomination. 475 */ 476 struct TALER_AgeCommitmentHashP h_age_commitment; 477 478 /** 479 * Hash of the public denomination key used to sign the coin. 480 */ 481 struct TALER_DenominationHashP h_denom_pub; 482 483 /** 484 * Set to true if the coin was refunded. 485 */ 486 bool refunded; 487 488 /** 489 * Set to true if there was no age commitment. 490 */ 491 bool no_age_commitment; 492 493 }; 494 495 496 /** 497 * @brief Specification for a purse refund operation in a coin's transaction list. 498 */ 499 struct TALER_EXCHANGEDB_PurseRefundListEntry 500 { 501 502 /** 503 * Public key of the purse. 504 */ 505 struct TALER_PurseContractPublicKeyP purse_pub; 506 507 /** 508 * Fraction of the original deposit's value to be refunded, including 509 * refund fee (if any). The coin is identified by @e coin_pub. 510 */ 511 struct TALER_Amount refund_amount; 512 513 /** 514 * Refund fee to be covered by the customer. 515 */ 516 struct TALER_Amount refund_fee; 517 518 }; 519 520 521 /** 522 * Information about a /reserves/$RID/open operation in a coin transaction history. 523 */ 524 struct TALER_EXCHANGEDB_ReserveOpenListEntry 525 { 526 527 /** 528 * Signature of the reserve. 529 */ 530 struct TALER_ReserveSignatureP reserve_sig; 531 532 /** 533 * Contribution of the coin to the open fee, including 534 * deposit fee. 535 */ 536 struct TALER_Amount coin_contribution; 537 538 /** 539 * Signature by the coin affirming the open deposit. 540 */ 541 struct TALER_CoinSpendSignatureP coin_sig; 542 543 /** 544 * Hash of the age commitment used to sign the coin, if age restriction was 545 * applicable to the denomination. 546 */ 547 struct TALER_AgeCommitmentHashP h_age_commitment; 548 549 /** 550 * Set to true if there was no age commitment. 551 */ 552 bool no_age_commitment; 553 554 }; 555 556 557 /** 558 * @brief List of transactions we performed for a particular coin. 559 */ 560 struct TALER_EXCHANGEDB_TransactionList 561 { 562 563 /** 564 * Next pointer in the NULL-terminated linked list. 565 */ 566 struct TALER_EXCHANGEDB_TransactionList *next; 567 568 /** 569 * Type of the transaction, determines what is stored in @e details. 570 */ 571 enum TALER_EXCHANGEDB_TransactionType type; 572 573 /** 574 * Serial ID of this entry in the @e type-specific table. 575 */ 576 uint64_t serial_id; 577 578 /** 579 * Serial ID of this entry in the coin history table. 580 */ 581 uint64_t coin_history_id; 582 583 /** 584 * Details about the transaction, depending on @e type. 585 */ 586 union 587 { 588 589 /** 590 * Details if transaction was a deposit operation. 591 * (#TALER_EXCHANGEDB_TT_DEPOSIT) 592 */ 593 struct TALER_EXCHANGEDB_DepositListEntry *deposit; 594 595 /** 596 * Details if transaction was a melt operation. 597 * (#TALER_EXCHANGEDB_TT_MELT) 598 */ 599 struct TALER_EXCHANGEDB_MeltListEntry *melt; 600 601 /** 602 * Details if transaction was a refund operation. 603 * (#TALER_EXCHANGEDB_TT_REFUND) 604 */ 605 struct TALER_EXCHANGEDB_RefundListEntry *refund; 606 607 /** 608 * Details if transaction was a recoup-refund operation where 609 * this coin was the OLD coin. 610 * (#TALER_EXCHANGEDB_TT_RECOUP_REFRESH_RECEIVER). 611 */ 612 struct TALER_EXCHANGEDB_RecoupRefreshListEntry *old_coin_recoup; 613 614 /** 615 * Details if transaction was a recoup operation. 616 * (#TALER_EXCHANGEDB_TT_RECOUP_WITHDRAW) 617 */ 618 struct TALER_EXCHANGEDB_RecoupListEntry *recoup; 619 620 /** 621 * Details if transaction was a recoup-refund operation where 622 * this coin was the REFRESHED coin. 623 * (#TALER_EXCHANGEDB_TT_RECOUP_REFRESH) 624 */ 625 struct TALER_EXCHANGEDB_RecoupRefreshListEntry *recoup_refresh; 626 627 /** 628 * Coin was deposited into a purse. 629 * (#TALER_EXCHANGEDB_TT_PURSE_DEPOSIT) 630 */ 631 struct TALER_EXCHANGEDB_PurseDepositListEntry *purse_deposit; 632 633 /** 634 * Coin was refunded upon purse expiration 635 * (#TALER_EXCHANGEDB_TT_PURSE_REFUND) 636 */ 637 struct TALER_EXCHANGEDB_PurseRefundListEntry *purse_refund; 638 639 /** 640 * Coin was used to pay to open a reserve. 641 * (#TALER_EXCHANGEDB_TT_RESERVE_OPEN) 642 */ 643 struct TALER_EXCHANGEDB_ReserveOpenListEntry *reserve_open; 644 645 } details; 646 647 }; 648 649 /** 650 * Calculate the total value of all transactions performed. 651 * Stores @a off plus the cost of all transactions in @a tl 652 * in @a ret. 653 * 654 * No primary test table; exercised by test_misc.c. 655 * 656 * @param tl transaction list to process 657 * @param off offset to use as the starting value 658 * @param[out] ret where the resulting total is to be stored 659 * @return #GNUNET_OK on success, #GNUNET_SYSERR on errors 660 */ 661 enum GNUNET_GenericReturnValue 662 TALER_EXCHANGEDB_calculate_transaction_list_totals ( 663 struct TALER_EXCHANGEDB_TransactionList *tl, 664 const struct TALER_Amount *off, 665 struct TALER_Amount *ret); 666 667 668 /** 669 * Free linked list of transactions. 670 * 671 * No primary test table; exercised by test_misc.c. 672 * 673 * @param[in] tl list to free 674 */ 675 void 676 TALER_EXCHANGEDB_free_coin_transaction_list ( 677 struct TALER_EXCHANGEDB_TransactionList *tl); 678 679 680 #endif