free_reserve_history.h (14088B)
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_reserve_history.h 18 * @brief implementation of the free_reserve_history function for Postgres 19 * @author Christian Grothoff 20 */ 21 #ifndef EXCHANGE_DATABASE_FREE_RESERVE_HISTORY_H 22 #define EXCHANGE_DATABASE_FREE_RESERVE_HISTORY_H 23 24 #include "taler/taler_util.h" 25 #include "taler/taler_json_lib.h" 26 #include "exchangedb_lib.h" 27 28 29 /** 30 * @brief Information we keep on bank transfer(s) that established a reserve. 31 */ 32 struct TALER_EXCHANGEDB_BankTransfer 33 { 34 35 /** 36 * Public key of the reserve that was filled. 37 */ 38 struct TALER_ReservePublicKeyP reserve_pub; 39 40 /** 41 * Amount that was transferred to the exchange. 42 */ 43 struct TALER_Amount amount; 44 45 /** 46 * When did the exchange receive the incoming transaction? 47 * (This is the execution date of the exchange's database, 48 * the execution date of the bank should be in @e wire). 49 */ 50 struct GNUNET_TIME_Timestamp execution_date; 51 52 /** 53 * Detailed wire information about the sending account 54 * in "payto://" format. 55 */ 56 struct TALER_FullPayto sender_account_details; 57 58 /** 59 * Data uniquely identifying the wire transfer (wire transfer-type specific) 60 */ 61 uint64_t wire_reference; 62 63 }; 64 65 66 /** 67 * @brief Information we keep for a withdraw request 68 * to reproduce the /withdraw operation if needed, and to have proof 69 * that a reserve was drained by this amount. 70 */ 71 struct TALER_EXCHANGEDB_Withdraw 72 { 73 /** 74 * Total amount (with fee) committed to withdraw 75 */ 76 struct TALER_Amount amount_with_fee; 77 78 /** 79 * true, if a proof of age was required following this withdraw, 80 * in a subsequent call to /reveal-withdraw. 81 * In this case, @e max_age, @e h_commitment and 82 * @e noreveal_index are to be taken into account 83 */ 84 bool age_proof_required; 85 86 /** 87 * Maximum age (in years) that the coins are restricted to, 88 * if ``age_proof_required`` is true. 89 */ 90 uint16_t max_age; 91 92 /** 93 * If ``age_proof_required`` is true, index (smaller #TALER_CNC_KAPPA) 94 * which the exchange has chosen to keep unrevealed 95 * during the next cut and choose (aka /reveal-age) step. 96 * This value applies to all n coins in the commitment. 97 */ 98 uint16_t noreveal_index; 99 100 /** 101 * If @e age_proof_required is true, the running hash over all blinded coin 102 * envelope's TALER_BlindedCoinHashP values. 103 * It runs over ``kappa*num_coins``, starting with the hashes for the coins 104 * for kappa index=0, then index=1 etc., 105 * i.e. h[0][0]...h[0][n-1]h[1][0]...h[1][n-1]...h[κ-1][0]...h[κ-1][n-1] 106 */ 107 struct TALER_HashBlindedPlanchetsP planchets_h; 108 109 /** 110 * Public key of the reserve that was drained. 111 */ 112 struct TALER_ReservePublicKeyP reserve_pub; 113 114 /** 115 * Signature confirming the withdrawal commitment 116 */ 117 struct TALER_ReserveSignatureP reserve_sig; 118 119 /** 120 * Number of coins to be withdrawn. 121 */ 122 size_t num_coins; 123 124 /** 125 * The hash of the blinded coin envelopes which are signed by the exchange. 126 * In case of @e age_proof_required = true, this is the hash over the chosen coins' 127 * envelopes (according to @e noreveal_index) from the request, which contained 128 * kappa*num_coins blinded coins envelopes. 129 */ 130 struct TALER_HashBlindedPlanchetsP selected_h; 131 132 /** 133 * Array of @a num_coins denomination signatures of the blinded coins @a 134 * h_coin_evs. 135 */ 136 struct TALER_BlindedDenominationSignature *denom_sigs; 137 138 /** 139 * Array of @a num_coins serial id's of the denominations, corresponding to 140 * the coins in @a h_coin_evs. 141 * If @e age_proof_required is true, the denominations MUST support age restriction. 142 */ 143 uint64_t *denom_serials; 144 145 /** 146 * If true, no @e blinding_seed is set and @e num_cs_r_values is 0. 147 */ 148 bool no_blinding_seed; 149 150 /** 151 * If @e no_blinding_seed is false, the blinding seed for the nonces needed for 152 * blind CS signatures. 153 */ 154 struct TALER_BlindingMasterSeedP blinding_seed; 155 156 /** 157 * Number of elements in @e cs_r_values. 158 * Only non-zero IF @e age_proof_required is true AND any of the denomination 159 * has a cipher of type CS. 160 */ 161 size_t num_cs_r_values; 162 163 /** 164 * Array @e num_r_pubs of public R-value pairs for CS that were generated from the 165 * @e blinding_seed, a coin's index and the denomination's private key during the 166 * the /withdraw request, to ensure idempotency in case of expiration of a denomination. 167 * NULL if @e num_r_pub is 0 (or @e age_proof_required is false). 168 */ 169 struct GNUNET_CRYPTO_CSPublicRPairP *cs_r_values; 170 171 /** 172 * The bitvector encoding the choices per coin, made by the exchange, 173 * for the R-values in @e cs_r_values. The value is encoded in NBO 174 * and the lowest bit corresponds to the pair at index 0 in @e cs_r_values. 175 */ 176 uint64_t cs_r_choices; 177 178 /** 179 * [out]-Array of @a num_coins hashes of the public keys of the denominations 180 * identified by @e denom_serials. This field is only set when calling 181 * get_reserve_history(). 182 */ 183 struct TALER_DenominationHashP *denom_pub_hashes; 184 185 /** 186 * [out]-Row of this operation in the `withdraw` table. 187 * Set by get_withdraw(), zero otherwise. 188 */ 189 uint64_t withdraw_id; 190 }; 191 192 193 /** 194 * Information the exchange records about a recoup request 195 * in a reserve history. 196 */ 197 struct TALER_EXCHANGEDB_Recoup 198 { 199 200 /** 201 * Information about the coin that was paid back. 202 */ 203 struct TALER_CoinPublicInfo coin; 204 205 /** 206 * Blinding factor supplied to prove to the exchange that 207 * the coin came from this reserve. 208 */ 209 union GNUNET_CRYPTO_BlindingSecretP coin_blind; 210 211 /** 212 * Signature of the coin of type 213 * #TALER_SIGNATURE_WALLET_COIN_RECOUP. 214 */ 215 struct TALER_CoinSpendSignatureP coin_sig; 216 217 /** 218 * Public key of the reserve the coin was paid back into. 219 */ 220 struct TALER_ReservePublicKeyP reserve_pub; 221 222 /** 223 * How much was the coin still worth at this time? 224 */ 225 struct TALER_Amount value; 226 227 /** 228 * When did the recoup operation happen? 229 */ 230 struct GNUNET_TIME_Timestamp timestamp; 231 232 /** 233 * Commitment of the withdraw operation the coin originated from. 234 */ 235 struct TALER_HashBlindedPlanchetsP planchets_h; 236 237 }; 238 239 240 /** 241 * @brief Information we keep on bank transfer(s) that 242 * closed a reserve. 243 */ 244 struct TALER_EXCHANGEDB_ClosingTransfer 245 { 246 247 /** 248 * Public key of the reserve that was depleted. 249 */ 250 struct TALER_ReservePublicKeyP reserve_pub; 251 252 /** 253 * Amount that was transferred from the exchange. 254 */ 255 struct TALER_Amount amount; 256 257 /** 258 * Amount that was charged by the exchange. 259 */ 260 struct TALER_Amount closing_fee; 261 262 /** 263 * When did the exchange execute the transaction? 264 */ 265 struct GNUNET_TIME_Timestamp execution_date; 266 267 /** 268 * Detailed wire information about the receiving account 269 * in payto://-format. 270 */ 271 struct TALER_FullPayto receiver_account_details; 272 273 /** 274 * Detailed wire transfer information that uniquely identifies the 275 * wire transfer. 276 */ 277 struct TALER_WireTransferIdentifierRawP wtid; 278 279 }; 280 281 282 /** 283 * Details about a purse merge operation. 284 */ 285 struct TALER_EXCHANGEDB_PurseMerge 286 { 287 288 /** 289 * Public key of the reserve the coin was merged into. 290 */ 291 struct TALER_ReservePublicKeyP reserve_pub; 292 293 /** 294 * Amount in the purse, with fees. 295 */ 296 struct TALER_Amount amount_with_fee; 297 298 /** 299 * Fee paid for the purse. 300 */ 301 struct TALER_Amount purse_fee; 302 303 /** 304 * Hash over the contract. 305 */ 306 struct TALER_PrivateContractHashP h_contract_terms; 307 308 /** 309 * Merge capability key. 310 */ 311 struct TALER_PurseMergePublicKeyP merge_pub; 312 313 /** 314 * Purse public key. 315 */ 316 struct TALER_PurseContractPublicKeyP purse_pub; 317 318 /** 319 * Signature by the reserve approving the merge. 320 */ 321 struct TALER_ReserveSignatureP reserve_sig; 322 323 /** 324 * When was the merge made. 325 */ 326 struct GNUNET_TIME_Timestamp merge_timestamp; 327 328 /** 329 * When was the purse set to expire. 330 */ 331 struct GNUNET_TIME_Timestamp purse_expiration; 332 333 /** 334 * Minimum age required for depositing into the purse. 335 */ 336 uint32_t min_age; 337 338 /** 339 * Flags of the purse. 340 */ 341 enum TALER_WalletAccountMergeFlags flags; 342 343 /** 344 * true if the purse was actually successfully merged, 345 * false if the @e purse_fee was charged but the 346 * @e amount was not credited to the reserve. 347 */ 348 bool merged; 349 }; 350 351 352 /** 353 * Details about a (paid for) reserve history request. 354 */ 355 struct TALER_EXCHANGEDB_HistoryRequest 356 { 357 /** 358 * Public key of the reserve the history request was for. 359 */ 360 struct TALER_ReservePublicKeyP reserve_pub; 361 362 /** 363 * Fee paid for the request. 364 */ 365 struct TALER_Amount history_fee; 366 367 /** 368 * When was the request made. 369 */ 370 struct GNUNET_TIME_Timestamp request_timestamp; 371 372 /** 373 * Signature by the reserve approving the history request. 374 */ 375 struct TALER_ReserveSignatureP reserve_sig; 376 }; 377 378 379 /** 380 * Details about a (paid for) reserve open request. 381 */ 382 struct TALER_EXCHANGEDB_OpenRequest 383 { 384 /** 385 * Public key of the reserve the open request was for. 386 */ 387 struct TALER_ReservePublicKeyP reserve_pub; 388 389 /** 390 * Fee paid for the request from the reserve. 391 */ 392 struct TALER_Amount open_fee; 393 394 /** 395 * When was the request made. 396 */ 397 struct GNUNET_TIME_Timestamp request_timestamp; 398 399 /** 400 * How long was the reserve supposed to be open. 401 */ 402 struct GNUNET_TIME_Timestamp reserve_expiration; 403 404 /** 405 * Signature by the reserve approving the open request, 406 * with purpose #TALER_SIGNATURE_WALLET_RESERVE_OPEN. 407 */ 408 struct TALER_ReserveSignatureP reserve_sig; 409 410 /** 411 * How many open purses should be included with the 412 * open reserve? 413 */ 414 uint32_t purse_limit; 415 416 }; 417 418 419 /** 420 * Details about an (explicit) reserve close request. 421 */ 422 struct TALER_EXCHANGEDB_CloseRequest 423 { 424 /** 425 * Public key of the reserve the history request was for. 426 */ 427 struct TALER_ReservePublicKeyP reserve_pub; 428 429 /** 430 * When was the request made. 431 */ 432 struct GNUNET_TIME_Timestamp request_timestamp; 433 434 /** 435 * Hash of the payto://-URI of the target account 436 * for the closure, or all zeros for the reserve 437 * origin account. 438 */ 439 struct TALER_FullPaytoHashP target_account_h_payto; 440 441 /** 442 * Signature by the reserve approving the history request. 443 */ 444 struct TALER_ReserveSignatureP reserve_sig; 445 446 }; 447 448 449 /** 450 * @brief Types of operations on a reserve. 451 */ 452 enum TALER_EXCHANGEDB_ReserveOperation 453 { 454 /** 455 * Money was deposited into the reserve via a bank transfer. 456 * This is how customers establish a reserve at the exchange. 457 */ 458 TALER_EXCHANGEDB_RO_BANK_TO_EXCHANGE = 0, 459 460 /** 461 * A batch of coins was withdrawn from the reserve using /withdraw. 462 */ 463 TALER_EXCHANGEDB_RO_WITHDRAW_COINS = 1, 464 465 /** 466 * A coin was returned to the reserve using /recoup. 467 */ 468 TALER_EXCHANGEDB_RO_RECOUP_COIN = 2, 469 470 /** 471 * The exchange send inactive funds back from the reserve to the 472 * customer's bank account. This happens when the exchange 473 * closes a reserve with a non-zero amount left in it. 474 */ 475 TALER_EXCHANGEDB_RO_EXCHANGE_TO_BANK = 3, 476 477 /** 478 * Event where a purse was merged into a reserve. 479 */ 480 TALER_EXCHANGEDB_RO_PURSE_MERGE = 4, 481 482 /** 483 * Event where a wallet paid for a full reserve history. 484 */ 485 TALER_EXCHANGEDB_RO_HISTORY_REQUEST = 5, 486 487 /** 488 * Event where a wallet paid to open a reserve for longer. 489 */ 490 TALER_EXCHANGEDB_RO_OPEN_REQUEST = 6, 491 492 /** 493 * Event where a wallet requested a reserve to be closed. 494 */ 495 TALER_EXCHANGEDB_RO_CLOSE_REQUEST = 7, 496 497 }; 498 499 500 /** 501 * @brief Reserve history as a linked list. Lists all of the transactions 502 * associated with this reserve (such as the bank transfers that 503 * established the reserve and all /withdraw operations we have done 504 * since). 505 */ 506 struct TALER_EXCHANGEDB_ReserveHistory 507 { 508 509 /** 510 * Next entry in the reserve history. 511 */ 512 struct TALER_EXCHANGEDB_ReserveHistory *next; 513 514 /** 515 * Offset of this entry in the reserve history. 516 * Corresponds to the reserve_history_serial_id in the database. 517 */ 518 uint64_t history_offset; 519 520 /** 521 * Type of the event, determines @e details. 522 */ 523 enum TALER_EXCHANGEDB_ReserveOperation type; 524 525 /** 526 * Details of the operation, depending on @e type. 527 */ 528 union 529 { 530 531 /** 532 * Details about a bank transfer to the exchange (reserve 533 * was established). 534 */ 535 struct TALER_EXCHANGEDB_BankTransfer *bank; 536 537 /** 538 * Details about a /withdraw operation. 539 */ 540 struct TALER_EXCHANGEDB_Withdraw *withdraw; 541 542 /** 543 * Details about a /recoup operation. 544 */ 545 struct TALER_EXCHANGEDB_Recoup *recoup; 546 547 /** 548 * Details about a bank transfer from the exchange (reserve 549 * was closed). 550 */ 551 struct TALER_EXCHANGEDB_ClosingTransfer *closing; 552 553 /** 554 * Details about a purse merge operation. 555 */ 556 struct TALER_EXCHANGEDB_PurseMerge *merge; 557 558 /** 559 * Details about a (paid for) reserve history request. 560 */ 561 struct TALER_EXCHANGEDB_HistoryRequest *history; 562 563 /** 564 * Details about a (paid for) open reserve request. 565 */ 566 struct TALER_EXCHANGEDB_OpenRequest *open_request; 567 568 /** 569 * Details about an (explicit) reserve close request. 570 */ 571 struct TALER_EXCHANGEDB_CloseRequest *close_request; 572 573 } details; 574 575 }; 576 577 578 /** 579 * Free memory associated with the given reserve history. 580 * 581 * No primary test table; exercised by test_misc.c. 582 * 583 * @param[in] rh history to free. 584 */ 585 void 586 TALER_EXCHANGEDB_free_reserve_history ( 587 struct TALER_EXCHANGEDB_ReserveHistory *rh); 588 589 590 #endif