auditordb_lib.h (17058B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2016 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 include/auditordb_lib.h 18 * @brief high-level interface for the auditor's database 19 * @author Florian Dold 20 * @author Benedikt Mueller 21 * @author Christian Grothoff 22 */ 23 #ifndef TALER_AUDITORDB_LIB_H 24 #define TALER_AUDITORDB_LIB_H 25 26 #include <jansson.h> 27 #include <gnunet/gnunet_util_lib.h> 28 #include <gnunet/gnunet_db_lib.h> 29 #include <taler/taler_util.h> 30 #include <auditordb_lib.h> 31 32 /** 33 * Connection to the postgres database of the auditor. 34 */ 35 struct TALER_AUDITORDB_PostgresContext; 36 37 38 /** 39 * Information about a deposit confirmation we received from 40 * a merchant. 41 */ 42 struct TALER_AUDITORDB_DepositConfirmation 43 { 44 45 /** 46 * Hash over the contract for which this deposit is made. 47 */ 48 struct TALER_PrivateContractHashP h_contract_terms; 49 50 /** 51 * Hash over the policy extension for the deposit. 52 */ 53 struct TALER_ExtensionPolicyHashP h_policy; 54 55 /** 56 * Hash over the wiring information of the merchant. 57 */ 58 struct TALER_MerchantWireHashP h_wire; 59 60 /** 61 * Time when this deposit confirmation was generated by the exchange. 62 */ 63 struct GNUNET_TIME_Timestamp exchange_timestamp; 64 65 /** 66 * How much time does the @e merchant have to issue a refund 67 * request? Zero if refunds are not allowed. After this time, the 68 * coin cannot be refunded. Note that the wire transfer will not be 69 * performed by the exchange until the refund deadline. This value 70 * is taken from the original deposit request. 71 */ 72 struct GNUNET_TIME_Timestamp refund_deadline; 73 74 /** 75 * How much time does the @e exchange have to wire the funds? 76 */ 77 struct GNUNET_TIME_Timestamp wire_deadline; 78 79 /** 80 * Amount to be deposited, excluding fee. Calculated from the 81 * amount with fee and the fee from the deposit request. 82 */ 83 struct TALER_Amount total_without_fee; 84 85 /** 86 * Array of the coin public keys involved in the 87 * batch deposit operation. 88 */ 89 const struct TALER_CoinSpendPublicKeyP *coin_pubs; 90 91 /** 92 * Array of coin deposit signatures from the deposit operation. 93 */ 94 const struct TALER_CoinSpendSignatureP *coin_sigs; 95 96 /** 97 * The Merchant's public key. Allows the merchant to later refund 98 * the transaction or to inquire about the wire transfer identifier. 99 */ 100 struct TALER_MerchantPublicKeyP merchant; 101 102 /** 103 * Signature from the exchange of type 104 * #TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT. 105 */ 106 struct TALER_ExchangeSignatureP exchange_sig; 107 108 /** 109 * Public signing key from the exchange matching @e exchange_sig. 110 */ 111 struct TALER_ExchangePublicKeyP exchange_pub; 112 113 /** 114 * Exchange master signature over @e exchange_sig. 115 */ 116 struct TALER_MasterSignatureP master_sig; 117 118 /** 119 * Row of this entry in the auditor database. 120 */ 121 uint64_t row_id; 122 123 /** 124 * Length of the @e coin_pubs and @e coin_sigs arrays. 125 */ 126 unsigned int num_coins; 127 128 bool suppressed; 129 130 }; 131 132 133 /** 134 * Information about a row inconsistency 135 */ 136 struct TALER_AUDITORDB_Generic_Update 137 { 138 uint64_t row_id; 139 bool suppressed; 140 bool ancient; 141 }; 142 143 144 /** 145 * Information about a coin inconsistency 146 */ 147 struct TALER_AUDITORDB_CoinInconsistency 148 { 149 uint64_t row_id; 150 char *operation; 151 struct TALER_Amount exchange_amount; 152 struct TALER_Amount auditor_amount; 153 struct GNUNET_CRYPTO_EddsaPublicKey coin_pub; 154 /** 155 * 1 if the inconsistency is profitable for the exchange, -1 if it 156 * is a loss for the exchange, 0 if that is unclear. 157 */ 158 int16_t profitable; 159 bool suppressed; 160 }; 161 162 /** 163 * Information about a row inconsistency 164 */ 165 struct TALER_AUDITORDB_RowInconsistency 166 { 167 uint64_t row_id; 168 uint64_t problem_row_id; 169 char *row_table; 170 char *diagnostic; 171 bool suppressed; 172 }; 173 174 /** 175 * Information about a bad sig loss 176 */ 177 struct TALER_AUDITORDB_BadSigLosses 178 { 179 uint64_t row_id; 180 uint64_t problem_row_id; 181 char *operation; 182 struct TALER_Amount loss; 183 struct GNUNET_CRYPTO_EddsaPublicKey operation_specific_pub; 184 bool suppressed; 185 }; 186 187 /** 188 * Information about a closure lags 189 */ 190 struct TALER_AUDITORDB_ClosureLags 191 { 192 uint64_t row_id; 193 uint64_t problem_row_id; 194 struct TALER_Amount amount; 195 struct GNUNET_TIME_Absolute deadline; 196 struct TALER_WireTransferIdentifierRawP wtid; 197 struct TALER_FullPayto account; 198 bool suppressed; 199 }; 200 201 /** 202 * Information about a emergency 203 */ 204 struct TALER_AUDITORDB_Emergency 205 { 206 uint64_t row_id; 207 struct TALER_DenominationHashP denompub_h; 208 struct TALER_Amount denom_risk; 209 struct TALER_Amount denom_loss; 210 struct GNUNET_TIME_Absolute deposit_start; 211 struct GNUNET_TIME_Absolute deposit_end; 212 struct TALER_Amount value; 213 bool suppressed; 214 }; 215 216 /** 217 * Information about an emergency by count 218 */ 219 struct TALER_AUDITORDB_EmergenciesByCount 220 { 221 uint64_t row_id; 222 struct TALER_DenominationHashP denompub_h; 223 uint64_t num_issued; 224 uint64_t num_known; 225 struct TALER_Amount risk; 226 struct GNUNET_TIME_Absolute start; 227 struct GNUNET_TIME_Absolute deposit_end; 228 struct TALER_Amount value; 229 bool suppressed; 230 }; 231 232 /** 233 * Information about a fee time inconsistency 234 */ 235 struct TALER_AUDITORDB_FeeTimeInconsistency 236 { 237 uint64_t row_id; 238 uint64_t problem_row_id; 239 char *type; 240 struct GNUNET_TIME_Absolute time; 241 char *diagnostic; 242 bool suppressed; 243 }; 244 245 /** 246 * Information about a denom key validity withdraw inconsistency 247 */ 248 struct TALER_AUDITORDB_DenominationKeyValidityWithdrawInconsistency 249 { 250 uint64_t row_id; 251 uint64_t problem_row_id; 252 struct GNUNET_TIME_Absolute execution_date; 253 struct TALER_ReservePublicKeyP reserve_pub; 254 struct TALER_DenominationHashP denompub_h; 255 bool suppressed; 256 }; 257 258 /** 259 * Information about a purse not closed inconsistencies 260 */ 261 struct TALER_AUDITORDB_PurseNotClosedInconsistencies 262 { 263 uint64_t row_id; 264 struct GNUNET_CRYPTO_EddsaPublicKey purse_pub; 265 struct TALER_Amount amount; 266 struct GNUNET_TIME_Absolute expiration_date; 267 bool suppressed; 268 }; 269 270 /** 271 * Information about a reserve balance insufficient inconsistency 272 */ 273 struct TALER_AUDITORDB_ReserveBalanceInsufficientInconsistency 274 { 275 uint64_t row_id; 276 struct GNUNET_CRYPTO_EddsaPublicKey reserve_pub; 277 bool inconsistency_gain; 278 struct TALER_Amount inconsistency_amount; 279 bool suppressed; 280 }; 281 282 /** 283 * Information about a reserve in inconsistency 284 */ 285 struct TALER_AUDITORDB_ReserveInInconsistency 286 { 287 uint64_t serial_id; 288 uint64_t bank_row_id; 289 struct TALER_Amount amount_exchange_expected; 290 struct TALER_Amount amount_wired; 291 struct TALER_ReservePublicKeyP reserve_pub; 292 struct GNUNET_TIME_Absolute timestamp; 293 struct TALER_FullPayto account; 294 char *diagnostic; 295 bool suppressed; 296 297 }; 298 299 /** 300 * Information about a disagreement between the bank and the exchange 301 * about an incoming wire transfer that established an account key for 302 * KYC authentication. 303 */ 304 struct TALER_AUDITORDB_KycauthInInconsistency 305 { 306 /** 307 * Row of the finding in our own table. 308 */ 309 uint64_t serial_id; 310 311 /** 312 * Row of the wire transfer in the bank's credit history. This is what 313 * the two sides are matched on: the exchange stores it in 314 * `kycauths_in.wire_reference`. 315 */ 316 uint64_t bank_row_id; 317 318 /** 319 * Amount the exchange claims to have received, zero if the exchange 320 * does not know the transfer at all. 321 */ 322 struct TALER_Amount amount_exchange_expected; 323 324 /** 325 * Amount the bank says it transferred, zero if the bank does not 326 * report the transfer at all. 327 */ 328 struct TALER_Amount amount_wired; 329 330 /** 331 * Account public key the transfer established, as known to whichever 332 * side did report the transfer. 333 */ 334 union TALER_AccountPublicKeyP account_pub; 335 336 /** 337 * When the transfer was executed. 338 */ 339 struct GNUNET_TIME_Absolute timestamp; 340 341 /** 342 * Bank account that was debited, as known to whichever side did report 343 * the transfer. 344 */ 345 struct TALER_FullPayto account; 346 347 /** 348 * Human-readable description of what does not match. 349 */ 350 char *diagnostic; 351 352 bool suppressed; 353 354 }; 355 356 /** 357 * Balance values for a reserve (or all reserves). 358 */ 359 struct TALER_AUDITORDB_ReserveFeeBalance 360 { 361 /** 362 * Remaining funds. 363 */ 364 struct TALER_Amount reserve_balance; 365 366 /** 367 * Losses from operations that should not have 368 * happened (e.g. negative balance). 369 */ 370 struct TALER_Amount reserve_loss; 371 372 /** 373 * Fees charged for withdraw. 374 */ 375 struct TALER_Amount withdraw_fee_balance; 376 377 /** 378 * Fees charged for closing. 379 */ 380 struct TALER_Amount close_fee_balance; 381 382 /** 383 * Fees charged for purse creation. 384 */ 385 struct TALER_Amount purse_fee_balance; 386 387 /** 388 * Opening fees charged. 389 */ 390 struct TALER_Amount open_fee_balance; 391 392 /** 393 * History fees charged. 394 */ 395 struct TALER_Amount history_fee_balance; 396 }; 397 398 399 /** 400 * Balance data for denominations in circulation. 401 */ 402 struct TALER_AUDITORDB_DenominationCirculationData 403 { 404 /** 405 * Amount of outstanding coins in circulation. 406 */ 407 struct TALER_Amount denom_balance; 408 409 /** 410 * Amount lost due coins illicitly accepted (effectively, a 411 * negative @a denom_balance). 412 */ 413 struct TALER_Amount denom_loss; 414 415 /** 416 * Total amount that could still be theoretically lost in the future due to 417 * recoup operations. (Total put into circulation minus @e recoup_loss). 418 */ 419 struct TALER_Amount denom_risk; 420 421 /** 422 * Amount lost due to recoups. 423 */ 424 struct TALER_Amount recoup_loss; 425 426 /** 427 * Number of coins of this denomination that the exchange signed into 428 * existence. 429 */ 430 uint64_t num_issued; 431 }; 432 433 struct TALER_AUDITORDB_DenominationsWithoutSigs 434 { 435 uint64_t row_id; 436 struct TALER_DenominationHashP denompub_h; 437 struct TALER_Amount value; 438 struct GNUNET_TIME_Absolute start_time; 439 struct GNUNET_TIME_Absolute end_time; 440 bool suppressed; 441 }; 442 443 struct TALER_AUDITORDB_MisattributionInInconsistency 444 { 445 uint64_t row_id; 446 struct TALER_Amount amount; 447 uint64_t bank_row; 448 struct TALER_ReservePublicKeyP reserve_pub; 449 bool suppressed; 450 451 }; 452 453 struct TALER_AUDITORDB_DenominationPending 454 { 455 uint64_t row_id; 456 struct TALER_DenominationHashP denom_pub_hash; 457 struct TALER_Amount denom_balance; 458 struct TALER_Amount denom_loss; 459 uint64_t num_issued; 460 struct TALER_Amount denom_risk; 461 struct TALER_Amount recoup_loss; 462 bool suppressed; 463 464 }; 465 466 struct TALER_AUDITORDB_HistoricReserveSummary 467 { 468 uint64_t row_id; 469 struct GNUNET_TIME_Absolute start_date; 470 struct GNUNET_TIME_Absolute end_date; 471 struct TALER_Amount reserve_profits; 472 bool suppressed; 473 474 }; 475 476 struct TALER_AUDITORDB_WireFormatInconsistency 477 { 478 uint64_t row_id; 479 struct TALER_Amount amount; 480 uint64_t wire_offset; 481 char *diagnostic; 482 bool suppressed; 483 484 }; 485 486 struct TALER_AUDITORDB_WireOutInconsistency 487 { 488 uint64_t row_id; 489 struct TALER_FullPayto destination_account; 490 char *diagnostic; 491 uint64_t wire_out_row_id; 492 struct TALER_Amount expected; 493 struct TALER_Amount claimed; 494 bool suppressed; 495 496 }; 497 498 struct TALER_AUDITORDB_RowMinorInconsistencies 499 { 500 uint64_t row_id; 501 char *row_table; 502 uint64_t problem_row; 503 char *diagnostic; 504 bool suppressed; 505 }; 506 507 508 struct TALER_AUDITORDB_ReserveBalanceSummaryWrongInconsistency 509 { 510 uint64_t row_id; 511 struct TALER_ReservePublicKeyP reserve_pub; 512 struct TALER_Amount exchange_amount; 513 struct TALER_Amount auditor_amount; 514 bool suppressed; 515 516 }; 517 518 struct TALER_AUDITORDB_ReserveNotClosedInconsistency 519 { 520 uint64_t row_id; 521 struct TALER_ReservePublicKeyP reserve_pub; 522 struct TALER_Amount balance; 523 struct GNUNET_TIME_Absolute expiration_time; 524 char *diagnostic; 525 bool suppressed; 526 527 }; 528 529 530 enum TALER_AUDITORDB_DeletableSuppressableTables 531 { 532 /** 533 * For auditor_amount_arithmetic_inconsistency table. 534 */ 535 TALER_AUDITORDB_AMOUNT_ARITHMETIC_INCONSISTENCY, 536 537 /** 538 * For auditor_closure_lags table. 539 */ 540 TALER_AUDITORDB_CLOSURE_LAGS, 541 542 /** 543 * For auditor_bad_sig_losses table. 544 */ 545 TALER_AUDITORDB_BAD_SIG_LOSSES, 546 547 /** 548 * For auditor_coin_inconsistency table. 549 */ 550 TALER_AUDITORDB_COIN_INCONSISTENCY, 551 552 /** 553 * For auditor_denomination_key_validity_withdraw_inconsistency table. 554 */ 555 TALER_AUDITORDB_DENOMINATION_KEY_VALIDITY_WITHDRAW_INCONSISTENCY, 556 557 /** 558 * For auditor_denomination_pending table. 559 */ 560 TALER_AUDITORDB_DENOMINATION_PENDING, 561 562 /** 563 * For auditor_denominations_without_sig table. 564 */ 565 TALER_AUDITORDB_DENOMINATIONS_WITHOUT_SIG, 566 567 /** 568 * For auditor_deposit_confirmation table. 569 */ 570 TALER_AUDITORDB_DEPOSIT_CONFIRMATION, 571 572 /** 573 * For auditor_emergency table. 574 */ 575 TALER_AUDITORDB_EMERGENCY, 576 577 /** 578 * For auditor_emergency_by_count table. 579 */ 580 TALER_AUDITORDB_EMERGENCY_BY_COUNT, 581 582 /** 583 * For auditor_fee_time_inconsistency table. 584 */ 585 TALER_AUDITORDB_FEE_TIME_INCONSISTENCY, 586 587 /** 588 * For auditor_misattribution_in_inconsistency table. 589 */ 590 TALER_AUDITORDB_MISATTRIBUTION_IN_INCONSISTENCY, 591 592 /** 593 * For auditor_purse_not_closed_inconsistency table. 594 */ 595 TALER_AUDITORDB_PURSE_NOT_CLOSED_INCONSISTENCY, 596 597 /** 598 * For auditor_refreshes_hanging table. 599 */ 600 TALER_AUDITORDB_REFRESHES_HANGING, 601 602 /** 603 * For auditor_reserve_balance_insufficient_inconsistency table. 604 */ 605 TALER_AUDITORDB_RESERVE_BALANCE_INSUFFICIENT_INCONSISTENCY, 606 607 /** 608 * For auditor_reserve_balance_summary_wrong_inconsistency table. 609 */ 610 TALER_AUDITORDB_RESERVE_BALANCE_SUMMARY_WRONG_INCONSISTENCY, 611 612 /** 613 * For auditor_reserve_in_inconsistency table. 614 */ 615 TALER_AUDITORDB_RESERVE_IN_INCONSISTENCY, 616 617 /** 618 * For auditor_reserve_not_closed_inconsistency table. 619 */ 620 TALER_AUDITORDB_RESERVE_NOT_CLOSED_INCONSISTENCY, 621 622 /** 623 * For auditor_row_inconsistency table. 624 */ 625 TALER_AUDITORDB_ROW_INCONSISTENCY, 626 627 /** 628 * For auditor_row_minor_inconsistency table. 629 */ 630 TALER_AUDITORDB_ROW_MINOR_INCONSISTENCY, 631 632 /** 633 * For auditor_wire_format_inconsistency table. 634 */ 635 TALER_AUDITORDB_WIRE_FORMAT_INCONSISTENCY, 636 637 /** 638 * For auditor_wire_out_inconsistency table. 639 */ 640 TALER_AUDITORDB_WIRE_OUT_INCONSISTENCY, 641 642 /** 643 * For auditor_kycauth_in_inconsistency table. Note that new values 644 * must be appended here rather than inserted alphabetically: the 645 * numbering is what `TALER_AUDITORDB_get_deletable_suppressable_table_name()` 646 * indexes its table with. 647 */ 648 TALER_AUDITORDB_KYCAUTH_IN_INCONSISTENCY, 649 650 /** 651 * For auditor_aml_holds table. 652 */ 653 TALER_AUDITORDB_AML_HOLDS, 654 655 /** 656 * For auditor_early_aggregations table. 657 */ 658 TALER_AUDITORDB_EARLY_AGGREGATIONS, 659 660 /** 661 * For auditor_pending_deposits table. 662 */ 663 TALER_AUDITORDB_PENDING_DEPOSITS, 664 665 /** 666 * Terminal. 667 */ 668 TALER_AUDITORDB_DELETABLESUPPRESSABLE_TABLES_MAX 669 }; 670 671 672 /** 673 * Information about a wire transfer the exchange aggregated but did not 674 * execute. 675 */ 676 struct TALER_AUDITORDB_AmlHold 677 { 678 uint64_t row_id; 679 680 /** 681 * Wire transfer the deposits were aggregated into. 682 */ 683 struct TALER_WireTransferIdentifierRawP wtid; 684 685 /** 686 * Account the transfer should be made to. 687 */ 688 struct TALER_FullPaytoHashP wire_target_h_payto; 689 690 /** 691 * Payto URI of @e wire_target_h_payto. 692 */ 693 struct TALER_FullPayto account; 694 695 /** 696 * What the exchange still owes on this transfer. 697 */ 698 struct TALER_Amount amount; 699 700 /** 701 * Why the exchange says it has not made the transfer, an 702 * `enum TALER_EXCHANGEDB_DeferralReason` value taken from its 703 * `aggregation_deferrals` row. Zero if the exchange gave no reason at all, 704 * which is the case that says it is simply not paying. 705 */ 706 uint32_t deferral_reason; 707 708 /** 709 * Measure the exchange named as blocking the payout, or 0 if it named none. 710 */ 711 uint64_t legitimization_measure_serial_id; 712 713 /** 714 * When did the auditor first see this transfer being held? 715 */ 716 struct GNUNET_TIME_Absolute creation_date; 717 718 bool suppressed; 719 }; 720 721 722 /** 723 * Information about an arithmetic inconsistency 724 */ 725 struct TALER_AUDITORDB_AmountArithmeticInconsistency 726 { 727 uint64_t row_id; 728 uint64_t problem_row_id; 729 char *operation; 730 struct TALER_Amount exchange_amount; 731 struct TALER_Amount auditor_amount; 732 /** 733 * 1 if the inconsistency is profitable for the exchange, -1 if it 734 * is a loss for the exchange, 0 if that is unclear. 735 */ 736 int16_t profitable; 737 bool suppressed; 738 }; 739 740 741 /** 742 * Initialize database connection. 743 * 744 * @param cfg configuration to use 745 * @return NULL on failure 746 */ 747 struct TALER_AUDITORDB_PostgresContext * 748 TALER_AUDITORDB_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); 749 750 751 /** 752 * Shutdown the database connection. 753 * 754 * @param[in] pg connection to disconnect 755 */ 756 void 757 TALER_AUDITORDB_disconnect (struct TALER_AUDITORDB_PostgresContext *pg); 758 759 760 #endif