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