get-reserves-RESERVE_PUB-history.h (15747B)
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 json_t *out_authorization_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 } recoup_details; 209 210 /** 211 * Information about a close operation of the reserve. 212 * @e type is #TALER_EXCHANGE_RTT_CLOSING. 213 */ 214 struct 215 { 216 /** 217 * Receiver account for the outgoing wire transfer. 218 */ 219 struct TALER_FullPayto receiver_account_details; 220 221 /** 222 * Wire transfer details for the outgoing wire transfer. 223 */ 224 struct TALER_WireTransferIdentifierRawP wtid; 225 226 /** 227 * Signature of type TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED. 228 */ 229 struct TALER_ExchangeSignatureP exchange_sig; 230 231 /** 232 * Public key used for @e exchange_sig. 233 */ 234 struct TALER_ExchangePublicKeyP exchange_pub; 235 236 /** 237 * When did the wire transfer happen? 238 */ 239 struct GNUNET_TIME_Timestamp timestamp; 240 241 /** 242 * Fee charged for the closing. 243 */ 244 struct TALER_Amount fee; 245 246 } close_details; 247 248 /** 249 * Information about a merge operation on the reserve. 250 * @e type is #TALER_EXCHANGE_RTT_MERGE. 251 */ 252 struct 253 { 254 /** 255 * Fee paid for the purse. 256 */ 257 struct TALER_Amount purse_fee; 258 259 /** 260 * Hash over the contract. 261 */ 262 struct TALER_PrivateContractHashP h_contract_terms; 263 264 /** 265 * Merge capability key. 266 */ 267 struct TALER_PurseMergePublicKeyP merge_pub; 268 269 /** 270 * Purse public key. 271 */ 272 struct TALER_PurseContractPublicKeyP purse_pub; 273 274 /** 275 * Signature by the reserve approving the merge. 276 */ 277 struct TALER_ReserveSignatureP reserve_sig; 278 279 /** 280 * When was the merge made? 281 */ 282 struct GNUNET_TIME_Timestamp merge_timestamp; 283 284 /** 285 * When was the purse set to expire? 286 */ 287 struct GNUNET_TIME_Timestamp purse_expiration; 288 289 /** 290 * Minimum age required for depositing into the purse. 291 */ 292 uint32_t min_age; 293 294 /** 295 * Flags of the purse. 296 */ 297 enum TALER_WalletAccountMergeFlags flags; 298 299 /** 300 * True if the purse was actually merged, false if only the 301 * @e purse_fee was charged. 302 */ 303 bool merged; 304 305 } merge_details; 306 307 /** 308 * Information about an open request operation on the reserve. 309 * @e type is #TALER_EXCHANGE_RTT_OPEN. 310 */ 311 struct 312 { 313 /** 314 * Signature by the reserve approving the open. 315 */ 316 struct TALER_ReserveSignatureP reserve_sig; 317 318 /** 319 * Amount to be paid from the reserve balance to open the reserve. 320 */ 321 struct TALER_Amount reserve_payment; 322 323 /** 324 * When was the request created? 325 */ 326 struct GNUNET_TIME_Timestamp request_timestamp; 327 328 /** 329 * For how long should the reserve be kept open? 330 */ 331 struct GNUNET_TIME_Timestamp reserve_expiration; 332 333 /** 334 * How many open purses should be included with the open reserve? 335 */ 336 uint32_t purse_limit; 337 338 } open_request; 339 340 /** 341 * Information about a close request operation on the reserve. 342 * @e type is #TALER_EXCHANGE_RTT_CLOSE. 343 */ 344 struct 345 { 346 /** 347 * Signature by the reserve approving the close. 348 */ 349 struct TALER_ReserveSignatureP reserve_sig; 350 351 /** 352 * When was the request created? 353 */ 354 struct GNUNET_TIME_Timestamp request_timestamp; 355 356 /** 357 * Hash of the payto://-URI of the target account for the closure, 358 * or all zeros for the reserve origin account. 359 */ 360 struct TALER_FullPaytoHashP target_account_h_payto; 361 362 } close_request; 363 364 } details; 365 366 }; 367 368 369 /** 370 * Possible options we can set for the GET reserves history request. 371 */ 372 enum TALER_EXCHANGE_GetReservesHistoryOption 373 { 374 /** 375 * End of list of options. 376 */ 377 TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END = 0, 378 379 /** 380 * Only return entries with offset strictly greater than this value. 381 * Defaults to 0 (return all entries). 382 * The offset corresponds to the etag / last entry offset from a 383 * previous response. 384 */ 385 TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF 386 387 }; 388 389 390 /** 391 * Value for an option for the GET reserves history request. 392 */ 393 struct TALER_EXCHANGE_GetReservesHistoryOptionValue 394 { 395 /** 396 * Type of the option being set. 397 */ 398 enum TALER_EXCHANGE_GetReservesHistoryOption option; 399 400 /** 401 * Specific option value. 402 */ 403 union 404 { 405 /** 406 * Value if @e option is TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF. 407 */ 408 uint64_t start_off; 409 410 } details; 411 412 }; 413 414 415 /** 416 * Handle for an operation to GET /reserves/$RESERVE_PUB/history. 417 */ 418 struct TALER_EXCHANGE_GetReservesHistoryHandle; 419 420 421 /** 422 * Set up GET /reserves/$RESERVE_PUB/history operation. 423 * Note that you must explicitly start the operation after 424 * possibly setting options. 425 * 426 * @param ctx the context 427 * @param url base URL of the exchange 428 * @param keys exchange keys for signature verification 429 * @param reserve_priv private key of the reserve to inspect 430 * @return handle to operation 431 */ 432 struct TALER_EXCHANGE_GetReservesHistoryHandle * 433 TALER_EXCHANGE_get_reserves_history_create ( 434 struct GNUNET_CURL_Context *ctx, 435 const char *url, 436 struct TALER_EXCHANGE_Keys *keys, 437 const struct TALER_ReservePrivateKeyP *reserve_priv); 438 439 440 /** 441 * Terminate the list of options. 442 * 443 * @return the terminating object of struct TALER_EXCHANGE_GetReservesHistoryOptionValue 444 */ 445 #define TALER_EXCHANGE_get_reserves_history_option_end_() \ 446 (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \ 447 { \ 448 .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_END \ 449 } 450 451 /** 452 * Set starting offset for partial history fetch. 453 * 454 * @param o offset: only return entries with offset > this value. 455 * Use the etag value from a previous response. 456 * @return representation of the option as a struct TALER_EXCHANGE_GetReservesHistoryOptionValue 457 */ 458 #define TALER_EXCHANGE_get_reserves_history_option_start_off(o) \ 459 (const struct TALER_EXCHANGE_GetReservesHistoryOptionValue) \ 460 { \ 461 .option = TALER_EXCHANGE_GET_RESERVES_HISTORY_OPTION_START_OFF, \ 462 .details.start_off = (o) \ 463 } 464 465 466 /** 467 * Set the requested options for the operation. 468 * 469 * If any option fails, other options may or may not be applied. 470 * 471 * @param grhh the request to set the options for 472 * @param num_options length of the @a options array 473 * @param options an array of options 474 * @return #GNUNET_OK on success, 475 * #GNUNET_NO on failure, 476 * #GNUNET_SYSERR on internal error 477 */ 478 enum GNUNET_GenericReturnValue 479 TALER_EXCHANGE_get_reserves_history_set_options_ ( 480 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh, 481 unsigned int num_options, 482 const struct TALER_EXCHANGE_GetReservesHistoryOptionValue *options); 483 484 485 /** 486 * Set the requested options for the operation. 487 * 488 * If any option fails, other options may or may not be applied. 489 * 490 * It should be used with helpers that create required options, for example: 491 * 492 * TALER_EXCHANGE_get_reserves_history_set_options ( 493 * grhh, 494 * TALER_EXCHANGE_get_reserves_history_option_start_off (last_etag)); 495 * 496 * @param grhh the request to set the options for 497 * @param ... the list of options, each created by a 498 * TALER_EXCHANGE_get_reserves_history_option_NAME(VALUE) helper 499 * @return #GNUNET_OK on success, 500 * #GNUNET_NO on failure, 501 * #GNUNET_SYSERR on internal error 502 */ 503 #define TALER_EXCHANGE_get_reserves_history_set_options(grhh,...) \ 504 TALER_EXCHANGE_get_reserves_history_set_options_ ( \ 505 grhh, \ 506 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 507 ((const struct TALER_EXCHANGE_GetReservesHistoryOptionValue[]) \ 508 {__VA_ARGS__, \ 509 TALER_EXCHANGE_get_reserves_history_option_end_ () } \ 510 )) 511 512 513 /** 514 * @brief Reserve history response. 515 */ 516 struct TALER_EXCHANGE_GetReservesHistoryResponse 517 { 518 /** 519 * HTTP response data. 520 */ 521 struct TALER_EXCHANGE_HttpResponse hr; 522 523 /** 524 * Details depending on @e hr.http_status. 525 */ 526 union 527 { 528 /** 529 * Information returned on #MHD_HTTP_OK. 530 */ 531 struct 532 { 533 /** 534 * Current reserve balance. May differ from total_in - total_out 535 * if the history is truncated. 536 */ 537 struct TALER_Amount balance; 538 539 /** 540 * Total of all inbound transactions in @e history. 541 */ 542 struct TALER_Amount total_in; 543 544 /** 545 * Total of all outbound transactions in @e history. 546 */ 547 struct TALER_Amount total_out; 548 549 /** 550 * Current etag / last entry offset in the history. 551 * Use this as the start_off option for incremental fetches. 552 * Offsets are not necessarily contiguous. 553 */ 554 uint64_t etag; 555 556 /** 557 * Reserve transaction history. 558 */ 559 const struct TALER_EXCHANGE_ReserveHistoryEntry *history; 560 561 /** 562 * Length of the @e history array. 563 */ 564 size_t history_len; 565 566 } ok; 567 568 } details; 569 570 }; 571 572 573 #ifndef TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE 574 /** 575 * Type of the closure used by 576 * the #TALER_EXCHANGE_GetReservesHistoryCallback. 577 */ 578 #define TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE void 579 #endif /* TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE */ 580 581 /** 582 * Type of the function that receives the result of a 583 * GET /reserves/$RESERVE_PUB/history request. 584 * 585 * @param cls closure 586 * @param result result returned by the HTTP server 587 */ 588 typedef void 589 (*TALER_EXCHANGE_GetReservesHistoryCallback)( 590 TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cls, 591 const struct TALER_EXCHANGE_GetReservesHistoryResponse *result); 592 593 594 /** 595 * Start GET /reserves/$RESERVE_PUB/history operation. 596 * 597 * @param[in,out] grhh operation to start 598 * @param cb function to call with the exchange's result 599 * @param cb_cls closure for @a cb 600 * @return status code, #TALER_EC_NONE on success 601 */ 602 enum TALER_ErrorCode 603 TALER_EXCHANGE_get_reserves_history_start ( 604 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh, 605 TALER_EXCHANGE_GetReservesHistoryCallback cb, 606 TALER_EXCHANGE_GET_RESERVES_HISTORY_RESULT_CLOSURE *cb_cls); 607 608 609 /** 610 * Cancel GET /reserves/$RESERVE_PUB/history operation. This function must 611 * not be called by clients after the TALER_EXCHANGE_GetReservesHistoryCallback 612 * has been invoked (as in those cases it'll be called internally by the 613 * implementation already). 614 * 615 * @param[in] grhh operation to cancel 616 */ 617 void 618 TALER_EXCHANGE_get_reserves_history_cancel ( 619 struct TALER_EXCHANGE_GetReservesHistoryHandle *grhh); 620 621 622 #endif /* _TALER_EXCHANGE__GET_RESERVES_RESERVE_PUB_HISTORY_H */