post-batch-deposit.h (12811B)
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/post-batch-deposit.h 18 * @brief C interface for POST /batch-deposit 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__POST_BATCH_DEPOSIT_H 22 #define _TALER_EXCHANGE__POST_BATCH_DEPOSIT_H 23 24 #include <taler/taler-exchange/common.h> 25 26 /** 27 * Information needed for a coin to be deposited. 28 */ 29 struct TALER_EXCHANGE_CoinDepositDetail 30 { 31 /** 32 * The amount to be deposited. 33 */ 34 struct TALER_Amount amount; 35 36 /** 37 * Hash over the age commitment of the coin. 38 */ 39 struct TALER_AgeCommitmentHashP h_age_commitment; 40 41 /** 42 * The coin's public key. 43 */ 44 struct TALER_CoinSpendPublicKeyP coin_pub; 45 46 /** 47 * The signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT made 48 * by the customer with the coin's private key. 49 */ 50 struct TALER_CoinSpendSignatureP coin_sig; 51 52 /** 53 * Exchange's unblinded signature of the coin. 54 */ 55 struct TALER_DenominationSignature denom_sig; 56 57 /** 58 * Hash of the public key of the coin. 59 */ 60 struct TALER_DenominationHashP h_denom_pub; 61 }; 62 63 64 /** 65 * Meta information about the contract relevant for a coin's deposit 66 * operation. 67 */ 68 struct TALER_EXCHANGE_DepositContractDetail 69 { 70 /** 71 * Hash of the contact of the merchant with the customer (further details 72 * are never disclosed to the exchange) 73 */ 74 struct TALER_PrivateContractHashP h_contract_terms; 75 76 /** 77 * The public key of the merchant (used to identify the merchant for refund 78 * requests). 79 */ 80 struct TALER_MerchantPublicKeyP merchant_pub; 81 82 /** 83 * The signature of the merchant (used to show that the merchant indeed 84 * agree to the deposit). 85 */ 86 struct TALER_MerchantSignatureP merchant_sig; 87 88 /** 89 * Salt used to hash the @e merchant_payto_uri. 90 */ 91 struct TALER_WireSaltP wire_salt; 92 93 /** 94 * Hash over data provided by the wallet to customize the contract. 95 * All zero if not used. 96 */ 97 struct GNUNET_HashCode wallet_data_hash; 98 99 /** 100 * Date until which the merchant can issue a refund to the customer via the 101 * exchange (can be zero if refunds are not allowed); must not be after the 102 * @e wire_deadline. 103 * Note: this should become an option in the future API! 104 */ 105 struct GNUNET_TIME_Timestamp refund_deadline; 106 107 /** 108 * Execution date, until which the merchant would like the exchange to 109 * settle the balance (advisory, the exchange cannot be forced to settle in 110 * the past or upon very short notice, but of course a well-behaved exchange 111 * will limit aggregation based on the advice received). 112 */ 113 struct GNUNET_TIME_Timestamp wire_deadline; 114 115 /** 116 * Timestamp when the contract was finalized, must match approximately the 117 * current time of the exchange. 118 */ 119 struct GNUNET_TIME_Timestamp wallet_timestamp; 120 121 /** 122 * The merchant's account details, in the payto://-format supported by the 123 * exchange. 124 */ 125 struct TALER_FullPayto merchant_payto_uri; 126 127 /** 128 * Policy extension specific details about the deposit relevant to the exchange. 129 * Note: this should become an option in the future API! 130 */ 131 const json_t *policy_details; 132 133 /** 134 * Metadata to additionally include in the wire transfer subject. 135 * Note: this should become an option in the future API! 136 */ 137 const char *extra_wire_subject_metadata; 138 }; 139 140 141 /** 142 * Handle for an operation to POST /batch-deposit. 143 */ 144 struct TALER_EXCHANGE_PostBatchDepositHandle; 145 146 147 /** 148 * Possible options we can set for the POST /batch-deposit request. 149 */ 150 enum TALER_EXCHANGE_PostBatchDepositOption 151 { 152 /** 153 * End of list of options. 154 */ 155 TALER_EXCHANGE_POST_BATCH_DEPOSIT_OPTION_END = 0, 156 157 /** 158 * Change the chance that our deposit confirmation will be given to the 159 * auditor to 100%. 160 */ 161 TALER_EXCHANGE_POST_BATCH_DEPOSIT_OPTION_FORCE_DC, 162 163 /** 164 * Verify the merchant signature on the contract terms. 165 * Not enabled by default as the caller typically just created the signature. 166 */ 167 TALER_EXCHANGE_POST_BATCH_DEPOSIT_OPTION_VERIFY_MERCHANT_SIG 168 169 }; 170 171 172 /** 173 * Value for an option we can set for the POST /batch-deposit request. 174 */ 175 struct TALER_EXCHANGE_PostBatchDepositOptionValue 176 { 177 /** 178 * Type of the option being set. 179 */ 180 enum TALER_EXCHANGE_PostBatchDepositOption option; 181 182 }; 183 184 185 /** 186 * Set up POST /batch-deposit operation. 187 * Note that you must explicitly start the operation after setup. 188 * 189 * This API is typically used by a merchant. 190 * 191 * @param ctx curl context 192 * @param url exchange base URL 193 * @param keys exchange keys 194 * @param dcd details about the contract the deposit is for 195 * @param num_cdds length of the @a cdds array 196 * @param cdds array with details about the coins to be deposited 197 * @param[out] ec if NULL is returned, set to the error code explaining why 198 * the operation failed 199 * @return handle to operation, NULL if inputs are invalid (in this case 200 * @a ec is set to the error code) 201 */ 202 struct TALER_EXCHANGE_PostBatchDepositHandle * 203 TALER_EXCHANGE_post_batch_deposit_create ( 204 struct GNUNET_CURL_Context *ctx, 205 const char *url, 206 struct TALER_EXCHANGE_Keys *keys, 207 const struct TALER_EXCHANGE_DepositContractDetail *dcd, 208 unsigned int num_cdds, 209 const struct TALER_EXCHANGE_CoinDepositDetail cdds[static num_cdds], 210 enum TALER_ErrorCode *ec); 211 212 213 /** 214 * Terminate the list of options. 215 * 216 * @return the terminating object 217 */ 218 #define TALER_EXCHANGE_post_batch_deposit_option_end_() \ 219 (const struct TALER_EXCHANGE_PostBatchDepositOptionValue) \ 220 { \ 221 .option = TALER_EXCHANGE_POST_BATCH_DEPOSIT_OPTION_END \ 222 } 223 224 /** 225 * Force the deposit confirmation to be sent to the auditor with 100% 226 * probability. 227 * 228 * @return representation of the option 229 */ 230 #define TALER_EXCHANGE_post_batch_deposit_option_force_dc() \ 231 (const struct TALER_EXCHANGE_PostBatchDepositOptionValue) \ 232 { \ 233 .option = TALER_EXCHANGE_POST_BATCH_DEPOSIT_OPTION_FORCE_DC \ 234 } 235 236 /** 237 * Enable verification of the merchant signature on the contract terms. 238 * 239 * @return representation of the option 240 */ 241 #define TALER_EXCHANGE_post_batch_deposit_option_verify_merchant_sig() \ 242 (const struct TALER_EXCHANGE_PostBatchDepositOptionValue) \ 243 { \ 244 .option = \ 245 TALER_EXCHANGE_POST_BATCH_DEPOSIT_OPTION_VERIFY_MERCHANT_SIG \ 246 } 247 248 249 /** 250 * Set the requested options for the operation. 251 * 252 * If any option fails, other options may or may not be applied. 253 * 254 * @param pbdh the request to set the options for 255 * @param num_options length of the @a options array 256 * @param options an array of options 257 * @return #GNUNET_OK on success, 258 * #GNUNET_NO on failure, 259 * #GNUNET_SYSERR on internal error 260 */ 261 enum GNUNET_GenericReturnValue 262 TALER_EXCHANGE_post_batch_deposit_set_options_ ( 263 struct TALER_EXCHANGE_PostBatchDepositHandle *pbdh, 264 unsigned int num_options, 265 const struct TALER_EXCHANGE_PostBatchDepositOptionValue options[]); 266 267 268 /** 269 * Set the requested options for the operation. 270 * 271 * If any option fails, other options may or may not be applied. 272 * 273 * @param pbdh the request to set the options for 274 * @param ... the list of the options, each created by a 275 * TALER_EXCHANGE_post_batch_deposit_option_NAME(VALUE) macro 276 * @return #GNUNET_OK on success, 277 * #GNUNET_NO on failure, 278 * #GNUNET_SYSERR on internal error 279 */ 280 #define TALER_EXCHANGE_post_batch_deposit_set_options(pbdh,...) \ 281 TALER_EXCHANGE_post_batch_deposit_set_options_ ( \ 282 pbdh, \ 283 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 284 ((const struct TALER_EXCHANGE_PostBatchDepositOptionValue[]) \ 285 {__VA_ARGS__, \ 286 TALER_EXCHANGE_post_batch_deposit_option_end_ ()} \ 287 )) 288 289 290 /** 291 * Structure with information about a POST /batch-deposit operation's result. 292 */ 293 struct TALER_EXCHANGE_PostBatchDepositResponse 294 { 295 /** 296 * HTTP response data 297 */ 298 struct TALER_EXCHANGE_HttpResponse hr; 299 300 union 301 { 302 /** 303 * Information returned if the HTTP status is #MHD_HTTP_OK. 304 */ 305 struct 306 { 307 /** 308 * Time when the exchange generated the batch deposit confirmation 309 */ 310 struct GNUNET_TIME_Timestamp deposit_timestamp; 311 312 /** 313 * Deposit confirmation signature provided by the exchange 314 */ 315 const struct TALER_ExchangeSignatureP *exchange_sig; 316 317 /** 318 * exchange key used to sign @a exchange_sig. 319 */ 320 const struct TALER_ExchangePublicKeyP *exchange_pub; 321 322 /** 323 * Base URL for looking up wire transfers, or 324 * NULL to use the default base URL. 325 */ 326 const char *transaction_base_url; 327 328 /** 329 * Total amount deposited so far under this contract terms for 330 * this merchant. 331 */ 332 struct TALER_Amount accumulated_total_without_fee; 333 334 } ok; 335 336 /** 337 * Information returned if the HTTP status is #MHD_HTTP_CONFLICT. 338 */ 339 struct 340 { 341 /** 342 * Details depending on the @e hr.ec. 343 */ 344 union 345 { 346 struct 347 { 348 /** 349 * The coin that had a conflict. 350 */ 351 struct TALER_CoinSpendPublicKeyP coin_pub; 352 353 /** 354 * Hash of the denomination public key of the coin. 355 */ 356 struct TALER_DenominationHashP h_denom_pub; 357 } insufficient_funds; 358 359 struct 360 { 361 /** 362 * The coin that had a conflict. 363 */ 364 struct TALER_CoinSpendPublicKeyP coin_pub; 365 366 /** 367 * Hash of the denomination public key of the coin. 368 */ 369 struct TALER_DenominationHashP h_denom_pub; 370 } coin_conflicting_age_hash; 371 372 struct 373 { 374 /** 375 * The coin that had a conflict. 376 */ 377 struct TALER_CoinSpendPublicKeyP coin_pub; 378 } coin_conflicting_denomination_key; 379 380 } details; 381 382 } conflict; 383 384 /** 385 * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. 386 */ 387 struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons; 388 389 } details; 390 }; 391 392 393 #ifndef TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE 394 /** 395 * Type of the closure used by 396 * the #TALER_EXCHANGE_PostBatchDepositCallback. 397 */ 398 #define TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE void 399 #endif /* TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE */ 400 401 /** 402 * Type of the function that receives the result of a 403 * POST /batch-deposit request. 404 * 405 * @param cls closure 406 * @param result result returned by the HTTP server 407 */ 408 typedef void 409 (*TALER_EXCHANGE_PostBatchDepositCallback)( 410 TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE *cls, 411 const struct TALER_EXCHANGE_PostBatchDepositResponse *result); 412 413 414 /** 415 * Start POST /batch-deposit operation. 416 * 417 * @param[in,out] pbdh operation to start 418 * @param cb function to call with the exchange's result 419 * @param cb_cls closure for @a cb 420 * @return status code, #TALER_EC_NONE on success 421 */ 422 enum TALER_ErrorCode 423 TALER_EXCHANGE_post_batch_deposit_start ( 424 struct TALER_EXCHANGE_PostBatchDepositHandle *pbdh, 425 TALER_EXCHANGE_PostBatchDepositCallback cb, 426 TALER_EXCHANGE_POST_BATCH_DEPOSIT_RESULT_CLOSURE *cb_cls); 427 428 429 /** 430 * Cancel POST /batch-deposit operation. This function must not be called by 431 * clients after the TALER_EXCHANGE_PostBatchDepositCallback has been invoked 432 * (as in those cases it'll be called internally by the implementation 433 * already). 434 * 435 * @param[in] pbdh operation to cancel 436 */ 437 void 438 TALER_EXCHANGE_post_batch_deposit_cancel ( 439 struct TALER_EXCHANGE_PostBatchDepositHandle *pbdh); 440 441 442 #endif /* _TALER_EXCHANGE__POST_BATCH_DEPOSIT_H */