get-reserves-RESERVE_PUB-history.h (15586B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero 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 Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/taler/taler-exchange/get-reserves-RESERVE_PUB-history.h 18 * @brief C interface for GET /reserves/$RESERVE_PUB/history 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H 22 #define _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H 23 24 #include <taler/taler-exchange/common.h> 25 26 27 /** 28 * Ways how a reserve's balance may change. 29 */ 30 enum TALER_EXCHANGE_ReserveTransactionType 31 { 32 33 /** 34 * Deposit into the reserve. 35 */ 36 TALER_EXCHANGE_RTT_CREDIT, 37 38 /** 39 * Withdrawal from the reserve. 40 */ 41 TALER_EXCHANGE_RTT_WITHDRAWAL, 42 43 /** 44 * /recoup operation. 45 */ 46 TALER_EXCHANGE_RTT_RECOUP, 47 48 /** 49 * Reserve closed operation. 50 */ 51 TALER_EXCHANGE_RTT_CLOSING, 52 53 /** 54 * Reserve purse merge operation. 55 */ 56 TALER_EXCHANGE_RTT_MERGE, 57 58 /** 59 * Reserve open request operation. 60 */ 61 TALER_EXCHANGE_RTT_OPEN, 62 63 /** 64 * Reserve close request operation. 65 */ 66 TALER_EXCHANGE_RTT_CLOSE 67 68 }; 69 70 71 /** 72 * @brief Entry in the reserve's transaction history. 73 */ 74 struct TALER_EXCHANGE_ReserveHistoryEntry 75 { 76 77 /** 78 * Type of the transaction. 79 */ 80 enum TALER_EXCHANGE_ReserveTransactionType type; 81 82 /** 83 * Amount transferred (in or out). 84 */ 85 struct TALER_Amount amount; 86 87 /** 88 * Details depending on @e type. 89 */ 90 union 91 { 92 93 /** 94 * Information about a deposit that filled this reserve. 95 * @e type is #TALER_EXCHANGE_RTT_CREDIT. 96 */ 97 struct 98 { 99 /** 100 * Sender account payto://-URL of the incoming transfer. 101 */ 102 struct TALER_FullPayto sender_url; 103 104 /** 105 * Information that uniquely identifies the wire transfer. 106 */ 107 uint64_t wire_reference; 108 109 /** 110 * When did the wire transfer happen? 111 */ 112 struct GNUNET_TIME_Timestamp timestamp; 113 114 } in_details; 115 116 /** 117 * Information about a withdrawal operation. 118 * @e type is #TALER_EXCHANGE_RTT_WITHDRAWAL. 119 */ 120 struct 121 { 122 /** 123 * Signature authorizing the withdrawal. 124 */ 125 json_t *out_authorization_sig; 126 127 /** 128 * Running hash over all hashes of blinded planchets of the withdrawal. 129 */ 130 struct TALER_HashBlindedPlanchetsP planchets_h; 131 132 /** 133 * True if age restriction was required during the protocol. 134 */ 135 bool age_restricted; 136 137 /** 138 * Maximum age committed, if @e age_restricted is true. 139 */ 140 uint8_t max_age; 141 142 /** 143 * If @e age_restricted is true, the index not to be revealed 144 * after the initial commitment in /withdraw. 145 */ 146 uint8_t noreveal_index; 147 148 /** 149 * If @e age_restricted is true, hash of the selected blinded planchets. 150 */ 151 struct TALER_HashBlindedPlanchetsP selected_h; 152 153 /** 154 * True if no blinding_seed was provided. 155 */ 156 bool no_blinding_seed; 157 158 /** 159 * For CS denominations, the seed for the prior /blinding-prepare call. 160 */ 161 struct TALER_BlindingMasterSeedP blinding_seed; 162 163 /** 164 * Fee charged for the withdrawal. 165 */ 166 struct TALER_Amount fee; 167 168 /** 169 * Number of coins withdrawn. 170 */ 171 uint16_t num_coins; 172 173 } withdraw; 174 175 /** 176 * Information provided if the reserve was filled via /recoup. 177 * @e type is #TALER_EXCHANGE_RTT_RECOUP. 178 */ 179 struct 180 { 181 /** 182 * Public key of the coin that was paid back. 183 */ 184 struct TALER_CoinSpendPublicKeyP coin_pub; 185 186 /** 187 * Signature of type TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP. 188 */ 189 struct TALER_ExchangeSignatureP exchange_sig; 190 191 /** 192 * Public key used for @e exchange_sig. 193 */ 194 struct TALER_ExchangePublicKeyP exchange_pub; 195 196 /** 197 * When did the /recoup operation happen? 198 */ 199 struct GNUNET_TIME_Timestamp timestamp; 200 201 } recoup_details; 202 203 /** 204 * Information about a close operation of the reserve. 205 * @e type is #TALER_EXCHANGE_RTT_CLOSING. 206 */ 207 struct 208 { 209 /** 210 * Receiver account for the outgoing wire transfer. 211 */ 212 struct TALER_FullPayto receiver_account_details; 213 214 /** 215 * Wire transfer details for the outgoing wire transfer. 216 */ 217 struct TALER_WireTransferIdentifierRawP wtid; 218 219 /** 220 * Signature of type TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED. 221 */ 222 struct TALER_ExchangeSignatureP exchange_sig; 223 224 /** 225 * Public key used for @e exchange_sig. 226 */ 227 struct TALER_ExchangePublicKeyP exchange_pub; 228 229 /** 230 * When did the wire transfer happen? 231 */ 232 struct GNUNET_TIME_Timestamp timestamp; 233 234 /** 235 * Fee charged for the closing. 236 */ 237 struct TALER_Amount fee; 238 239 } close_details; 240 241 /** 242 * Information about a merge operation on the reserve. 243 * @e type is #TALER_EXCHANGE_RTT_MERGE. 244 */ 245 struct 246 { 247 /** 248 * Fee paid for the purse. 249 */ 250 struct TALER_Amount purse_fee; 251 252 /** 253 * Hash over the contract. 254 */ 255 struct TALER_PrivateContractHashP h_contract_terms; 256 257 /** 258 * Merge capability key. 259 */ 260 struct TALER_PurseMergePublicKeyP merge_pub; 261 262 /** 263 * Purse public key. 264 */ 265 struct TALER_PurseContractPublicKeyP purse_pub; 266 267 /** 268 * Signature by the reserve approving the merge. 269 */ 270 struct TALER_ReserveSignatureP reserve_sig; 271 272 /** 273 * When was the merge made? 274 */ 275 struct GNUNET_TIME_Timestamp merge_timestamp; 276 277 /** 278 * When was the purse set to expire? 279 */ 280 struct GNUNET_TIME_Timestamp purse_expiration; 281 282 /** 283 * Minimum age required for depositing into the purse. 284 */ 285 uint32_t min_age; 286 287 /** 288 * Flags of the purse. 289 */ 290 enum TALER_WalletAccountMergeFlags flags; 291 292 /** 293 * True if the purse was actually merged, false if only the 294 * @e purse_fee was charged. 295 */ 296 bool merged; 297 298 } merge_details; 299 300 /** 301 * Information about an open request operation on the reserve. 302 * @e type is #TALER_EXCHANGE_RTT_OPEN. 303 */ 304 struct 305 { 306 /** 307 * Signature by the reserve approving the open. 308 */ 309 struct TALER_ReserveSignatureP reserve_sig; 310 311 /** 312 * Amount to be paid from the reserve balance to open the reserve. 313 */ 314 struct TALER_Amount reserve_payment; 315 316 /** 317 * When was the request created? 318 */ 319 struct GNUNET_TIME_Timestamp request_timestamp; 320 321 /** 322 * For how long should the reserve be kept open? 323 */ 324 struct GNUNET_TIME_Timestamp reserve_expiration; 325 326 /** 327 * How many open purses should be included with the open reserve? 328 */ 329 uint32_t purse_limit; 330 331 } open_request; 332 333 /** 334 * Information about a close request operation on the reserve. 335 * @e type is #TALER_EXCHANGE_RTT_CLOSE. 336 */ 337 struct 338 { 339 /** 340 * Signature by the reserve approving the close. 341 */ 342 struct TALER_ReserveSignatureP reserve_sig; 343 344 /** 345 * When was the request created? 346 */ 347 struct GNUNET_TIME_Timestamp request_timestamp; 348 349 /** 350 * Hash of the payto://-URI of the target account for the closure, 351 * or all zeros for the reserve origin account. 352 */ 353 struct TALER_FullPaytoHashP target_account_h_payto; 354 355 } close_request; 356 357 } details; 358 359 }; 360 361 362 /** 363 * Possible options we can set for the GET reserves history request. 364 */ 365 enum TALER_EXCHANGE_GetReservesHistoryOption 366 { 367 /** 368 * End of list of options. 369 */ 370 TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END = 0, 371 372 /** 373 * Only return entries with offset strictly greater than this value. 374 * Defaults to 0 (return all entries). 375 * The offset corresponds to the etag / last entry offset from a 376 * previous response. 377 */ 378 TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF 379 380 }; 381 382 383 /** 384 * Value for an option for the GET reserves history request. 385 */ 386 struct TALER_EXCHANGE_GetReservesHistoryOptionValue 387 { 388 /** 389 * Type of the option being set. 390 */ 391 enum TALER_EXCHANGE_GetReservesHistoryOption option; 392 393 /** 394 * Specific option value. 395 */ 396 union 397 { 398 /** 399 * Value if @e option is TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF. 400 */ 401 uint64_t start_off; 402 403 } details; 404 405 }; 406 407 408 /** 409 * Handle for an operation to GET /reserves/$RESERVE_PUB/history. 410 */ 411 struct TALER_EXCHANGE_GetReservesHistoryHandle; 412 413 414 /** 415 * Set up GET /reserves/$RESERVE_PUB/history operation. 416 * Note that you must explicitly start the operation after 417 * possibly setting options. 418 * 419 * @param ctx the context 420 * @param url base URL of the exchange 421 * @param keys exchange keys for signature verification 422 * @param reserve_priv private key of the reserve to inspect 423 * @return handle to operation 424 */ 425 struct TALER_EXCHANGE_GetReservesHistoryHandle * 426 TALER_EXCHANGE_get_reserves_history_create ( 427 struct GNUNET_CURL_Context *ctx, 428 const char *url, 429 struct TALER_EXCHANGE_Keys *keys, 430 const struct TALER_ReservePrivateKeyP *reserve_priv); 431 432 433 /** 434 * Terminate the list of options. 435 * 436 * @return the terminating object of struct TALER_EXCHANGE_GetReservesHistoryOptionValue 437 */ 438 #define TALER_EXCHANGE_get_reserves_history_option_end_() \ 439 (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \ 440 { \ 441 .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END \ 442 } 443 444 /** 445 * Set starting offset for partial history fetch. 446 * 447 * @param o offset: only return entries with offset > this value. 448 * Use the etag value from a previous response. 449 * @return representation of the option as a struct TALER_EXCHANGE_GetReservesHistoryOptionValue 450 */ 451 #define TALER_EXCHANGE_get_reserves_history_option_start_off(o) \ 452 (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \ 453 { \ 454 .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF, \ 455 .details.start_off = (o) \ 456 } 457 458 459 /** 460 * Set the requested options for the operation. 461 * 462 * If any option fails, other options may or may not be applied. 463 * 464 * @param grhh the request to set the options for 465 * @param num_options length of the @a options array 466 * @param options an array of options 467 * @return #GNUNET_OK on success, 468 * #GNUNET_NO on failure, 469 * #GNUNET_SYSERR on internal error 470 */ 471 enum GNUNET_GenericReturnValue 472 TALER_EXCHANGE_get_reserves_history_set_options_ ( 473 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh, 474 unsigned int num_options, 475 const struct TALER_EXCHANGE_GetReservesHistoryOptionValue *options); 476 477 478 /** 479 * Set the requested options for the operation. 480 * 481 * If any option fails, other options may or may not be applied. 482 * 483 * It should be used with helpers that create required options, for example: 484 * 485 * TALER_EXCHANGE_get_reserves_history_set_options ( 486 * grhh, 487 * TALER_EXCHANGE_get_reserves_history_option_start_off (last_etag)); 488 * 489 * @param grhh the request to set the options for 490 * @param ... the list of options, each created by a 491 * TALER_EXCHANGE_get_reserves_history_option_NAME(VALUE) helper 492 * @return #GNUNET_OK on success, 493 * #GNUNET_NO on failure, 494 * #GNUNET_SYSERR on internal error 495 */ 496 #define TALER_EXCHANGE_get_reserves_history_set_options(grhh,...) \ 497 TALER_EXCHANGE_get_reserves_history_set_options_ ( \ 498 grhh, \ 499 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 500 ((const struct TALER_EXCHANGE_GetReservesHistoryOptionValue[]) \ 501 {__VA_ARGS__, \ 502 TALER_EXCHANGE_get_reserves_history_option_end_ () } \ 503 )) 504 505 506 /** 507 * @brief Reserve history response. 508 */ 509 struct TALER_EXCHANGE_GetReservesHistoryResponse 510 { 511 /** 512 * HTTP response data. 513 */ 514 struct TALER_EXCHANGE_HttpResponse hr; 515 516 /** 517 * Details depending on @e hr.http_status. 518 */ 519 union 520 { 521 /** 522 * Information returned on #MHD_HTTP_OK. 523 */ 524 struct 525 { 526 /** 527 * Current reserve balance. May differ from total_in - total_out 528 * if the history is truncated. 529 */ 530 struct TALER_Amount balance; 531 532 /** 533 * Total of all inbound transactions in @e history. 534 */ 535 struct TALER_Amount total_in; 536 537 /** 538 * Total of all outbound transactions in @e history. 539 */ 540 struct TALER_Amount total_out; 541 542 /** 543 * Current etag / last entry offset in the history. 544 * Use this as the start_off option for incremental fetches. 545 * Offsets are not necessarily contiguous. 546 */ 547 uint64_t etag; 548 549 /** 550 * Reserve transaction history. 551 */ 552 const struct TALER_EXCHANGE_ReserveHistoryEntry *history; 553 554 /** 555 * Length of the @e history array. 556 */ 557 size_t history_len; 558 559 } ok; 560 561 } details; 562 563 }; 564 565 566 #ifndef TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE 567 /** 568 * Type of the closure used by 569 * the #TALER_EXCHANGE_GetReservesHistoryCallback. 570 */ 571 #define TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE void 572 #endif /* TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE */ 573 574 /** 575 * Type of the function that receives the result of a 576 * GET /reserves/$RESERVE_PUB/history request. 577 * 578 * @param cls closure 579 * @param result result returned by the HTTP server 580 */ 581 typedef void 582 (*TALER_EXCHANGE_GetReservesHistoryCallback)( 583 TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cls, 584 const struct TALER_EXCHANGE_GetReservesHistoryResponse *result); 585 586 587 /** 588 * Start GET /reserves/$RESERVE_PUB/history operation. 589 * 590 * @param[in,out] grhh operation to start 591 * @param cb function to call with the exchange's result 592 * @param cb_cls closure for @a cb 593 * @return status code, #TALER_EC_NONE on success 594 */ 595 enum TALER_ErrorCode 596 TALER_EXCHANGE_get_reserves_history_start ( 597 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh, 598 TALER_EXCHANGE_GetReservesHistoryCallback cb, 599 TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cb_cls); 600 601 602 /** 603 * Cancel GET /reserves/$RESERVE_PUB/history operation. This function must 604 * not be called by clients after the TALER_EXCHANGE_GetReservesHistoryCallback 605 * has been invoked (as in those cases it'll be called internally by the 606 * implementation already). 607 * 608 * @param[in] grhh operation to cancel 609 */ 610 void 611 TALER_EXCHANGE_get_reserves_history_cancel ( 612 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh); 613 614 615 #endif /* _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H */