free_reserve_history.h (13763B)
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 187 /** 188 * Information the exchange records about a recoup request 189 * in a reserve history. 190 */ 191 struct TALER_EXCHANGEDB_Recoup 192 { 193 194 /** 195 * Information about the coin that was paid back. 196 */ 197 struct TALER_CoinPublicInfo coin; 198 199 /** 200 * Blinding factor supplied to prove to the exchange that 201 * the coin came from this reserve. 202 */ 203 union GNUNET_CRYPTO_BlindingSecretP coin_blind; 204 205 /** 206 * Signature of the coin of type 207 * #TALER_SIGNATURE_WALLET_COIN_RECOUP. 208 */ 209 struct TALER_CoinSpendSignatureP coin_sig; 210 211 /** 212 * Public key of the reserve the coin was paid back into. 213 */ 214 struct TALER_ReservePublicKeyP reserve_pub; 215 216 /** 217 * How much was the coin still worth at this time? 218 */ 219 struct TALER_Amount value; 220 221 /** 222 * When did the recoup operation happen? 223 */ 224 struct GNUNET_TIME_Timestamp timestamp; 225 226 }; 227 228 229 /** 230 * @brief Information we keep on bank transfer(s) that 231 * closed a reserve. 232 */ 233 struct TALER_EXCHANGEDB_ClosingTransfer 234 { 235 236 /** 237 * Public key of the reserve that was depleted. 238 */ 239 struct TALER_ReservePublicKeyP reserve_pub; 240 241 /** 242 * Amount that was transferred from the exchange. 243 */ 244 struct TALER_Amount amount; 245 246 /** 247 * Amount that was charged by the exchange. 248 */ 249 struct TALER_Amount closing_fee; 250 251 /** 252 * When did the exchange execute the transaction? 253 */ 254 struct GNUNET_TIME_Timestamp execution_date; 255 256 /** 257 * Detailed wire information about the receiving account 258 * in payto://-format. 259 */ 260 struct TALER_FullPayto receiver_account_details; 261 262 /** 263 * Detailed wire transfer information that uniquely identifies the 264 * wire transfer. 265 */ 266 struct TALER_WireTransferIdentifierRawP wtid; 267 268 }; 269 270 271 /** 272 * Details about a purse merge operation. 273 */ 274 struct TALER_EXCHANGEDB_PurseMerge 275 { 276 277 /** 278 * Public key of the reserve the coin was merged into. 279 */ 280 struct TALER_ReservePublicKeyP reserve_pub; 281 282 /** 283 * Amount in the purse, with fees. 284 */ 285 struct TALER_Amount amount_with_fee; 286 287 /** 288 * Fee paid for the purse. 289 */ 290 struct TALER_Amount purse_fee; 291 292 /** 293 * Hash over the contract. 294 */ 295 struct TALER_PrivateContractHashP h_contract_terms; 296 297 /** 298 * Merge capability key. 299 */ 300 struct TALER_PurseMergePublicKeyP merge_pub; 301 302 /** 303 * Purse public key. 304 */ 305 struct TALER_PurseContractPublicKeyP purse_pub; 306 307 /** 308 * Signature by the reserve approving the merge. 309 */ 310 struct TALER_ReserveSignatureP reserve_sig; 311 312 /** 313 * When was the merge made. 314 */ 315 struct GNUNET_TIME_Timestamp merge_timestamp; 316 317 /** 318 * When was the purse set to expire. 319 */ 320 struct GNUNET_TIME_Timestamp purse_expiration; 321 322 /** 323 * Minimum age required for depositing into the purse. 324 */ 325 uint32_t min_age; 326 327 /** 328 * Flags of the purse. 329 */ 330 enum TALER_WalletAccountMergeFlags flags; 331 332 /** 333 * true if the purse was actually successfully merged, 334 * false if the @e purse_fee was charged but the 335 * @e amount was not credited to the reserve. 336 */ 337 bool merged; 338 }; 339 340 341 /** 342 * Details about a (paid for) reserve history request. 343 */ 344 struct TALER_EXCHANGEDB_HistoryRequest 345 { 346 /** 347 * Public key of the reserve the history request was for. 348 */ 349 struct TALER_ReservePublicKeyP reserve_pub; 350 351 /** 352 * Fee paid for the request. 353 */ 354 struct TALER_Amount history_fee; 355 356 /** 357 * When was the request made. 358 */ 359 struct GNUNET_TIME_Timestamp request_timestamp; 360 361 /** 362 * Signature by the reserve approving the history request. 363 */ 364 struct TALER_ReserveSignatureP reserve_sig; 365 }; 366 367 368 /** 369 * Details about a (paid for) reserve open request. 370 */ 371 struct TALER_EXCHANGEDB_OpenRequest 372 { 373 /** 374 * Public key of the reserve the open request was for. 375 */ 376 struct TALER_ReservePublicKeyP reserve_pub; 377 378 /** 379 * Fee paid for the request from the reserve. 380 */ 381 struct TALER_Amount open_fee; 382 383 /** 384 * When was the request made. 385 */ 386 struct GNUNET_TIME_Timestamp request_timestamp; 387 388 /** 389 * How long was the reserve supposed to be open. 390 */ 391 struct GNUNET_TIME_Timestamp reserve_expiration; 392 393 /** 394 * Signature by the reserve approving the open request, 395 * with purpose #TALER_SIGNATURE_WALLET_RESERVE_OPEN. 396 */ 397 struct TALER_ReserveSignatureP reserve_sig; 398 399 /** 400 * How many open purses should be included with the 401 * open reserve? 402 */ 403 uint32_t purse_limit; 404 405 }; 406 407 408 /** 409 * Details about an (explicit) reserve close request. 410 */ 411 struct TALER_EXCHANGEDB_CloseRequest 412 { 413 /** 414 * Public key of the reserve the history request was for. 415 */ 416 struct TALER_ReservePublicKeyP reserve_pub; 417 418 /** 419 * When was the request made. 420 */ 421 struct GNUNET_TIME_Timestamp request_timestamp; 422 423 /** 424 * Hash of the payto://-URI of the target account 425 * for the closure, or all zeros for the reserve 426 * origin account. 427 */ 428 struct TALER_FullPaytoHashP target_account_h_payto; 429 430 /** 431 * Signature by the reserve approving the history request. 432 */ 433 struct TALER_ReserveSignatureP reserve_sig; 434 435 }; 436 437 438 /** 439 * @brief Types of operations on a reserve. 440 */ 441 enum TALER_EXCHANGEDB_ReserveOperation 442 { 443 /** 444 * Money was deposited into the reserve via a bank transfer. 445 * This is how customers establish a reserve at the exchange. 446 */ 447 TALER_EXCHANGEDB_RO_BANK_TO_EXCHANGE = 0, 448 449 /** 450 * A batch of coins was withdrawn from the reserve using /withdraw. 451 */ 452 TALER_EXCHANGEDB_RO_WITHDRAW_COINS = 1, 453 454 /** 455 * A coin was returned to the reserve using /recoup. 456 */ 457 TALER_EXCHANGEDB_RO_RECOUP_COIN = 2, 458 459 /** 460 * The exchange send inactive funds back from the reserve to the 461 * customer's bank account. This happens when the exchange 462 * closes a reserve with a non-zero amount left in it. 463 */ 464 TALER_EXCHANGEDB_RO_EXCHANGE_TO_BANK = 3, 465 466 /** 467 * Event where a purse was merged into a reserve. 468 */ 469 TALER_EXCHANGEDB_RO_PURSE_MERGE = 4, 470 471 /** 472 * Event where a wallet paid for a full reserve history. 473 */ 474 TALER_EXCHANGEDB_RO_HISTORY_REQUEST = 5, 475 476 /** 477 * Event where a wallet paid to open a reserve for longer. 478 */ 479 TALER_EXCHANGEDB_RO_OPEN_REQUEST = 6, 480 481 /** 482 * Event where a wallet requested a reserve to be closed. 483 */ 484 TALER_EXCHANGEDB_RO_CLOSE_REQUEST = 7, 485 486 }; 487 488 489 /** 490 * @brief Reserve history as a linked list. Lists all of the transactions 491 * associated with this reserve (such as the bank transfers that 492 * established the reserve and all /withdraw operations we have done 493 * since). 494 */ 495 struct TALER_EXCHANGEDB_ReserveHistory 496 { 497 498 /** 499 * Next entry in the reserve history. 500 */ 501 struct TALER_EXCHANGEDB_ReserveHistory *next; 502 503 /** 504 * Offset of this entry in the reserve history. 505 * Corresponds to the reserve_history_serial_id in the database. 506 */ 507 uint64_t history_offset; 508 509 /** 510 * Type of the event, determines @e details. 511 */ 512 enum TALER_EXCHANGEDB_ReserveOperation type; 513 514 /** 515 * Details of the operation, depending on @e type. 516 */ 517 union 518 { 519 520 /** 521 * Details about a bank transfer to the exchange (reserve 522 * was established). 523 */ 524 struct TALER_EXCHANGEDB_BankTransfer *bank; 525 526 /** 527 * Details about a /withdraw operation. 528 */ 529 struct TALER_EXCHANGEDB_Withdraw *withdraw; 530 531 /** 532 * Details about a /recoup operation. 533 */ 534 struct TALER_EXCHANGEDB_Recoup *recoup; 535 536 /** 537 * Details about a bank transfer from the exchange (reserve 538 * was closed). 539 */ 540 struct TALER_EXCHANGEDB_ClosingTransfer *closing; 541 542 /** 543 * Details about a purse merge operation. 544 */ 545 struct TALER_EXCHANGEDB_PurseMerge *merge; 546 547 /** 548 * Details about a (paid for) reserve history request. 549 */ 550 struct TALER_EXCHANGEDB_HistoryRequest *history; 551 552 /** 553 * Details about a (paid for) open reserve request. 554 */ 555 struct TALER_EXCHANGEDB_OpenRequest *open_request; 556 557 /** 558 * Details about an (explicit) reserve close request. 559 */ 560 struct TALER_EXCHANGEDB_CloseRequest *close_request; 561 562 } details; 563 564 }; 565 566 567 /** 568 * Free memory associated with the given reserve history. 569 * 570 * @param[in] rh history to free. 571 */ 572 void 573 TALER_EXCHANGEDB_free_reserve_history ( 574 struct TALER_EXCHANGEDB_ReserveHistory *rh); 575 576 577 #endif