exchange

Base system with REST service to issue digital coins, run by the payment service provider
Log | Files | Refs | Submodules | README | LICENSE

common.h (4431B)

      1 /*
      2    This file is part of TALER
      3    Copyright (C) 2014-2025 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/common.h
     18  * @brief C interface of libtalerexchange, a C library to use exchange's HTTP API
     19  *        This library is not thread-safe, all APIs must only be used from a single thread.
     20  *        This library calls abort() if it runs out of memory. Be aware of these limitations.
     21  * @author Sree Harsha Totakura <sreeharsha@totakura.in>
     22  * @author Christian Grothoff
     23  * @author Özgür Kesim
     24  */
     25 #ifndef _TALER_EXCHANGE__COMMON_H
     26 #define _TALER_EXCHANGE__COMMON_H
     27 
     28 #include <jansson.h>
     29 #include <taler/taler_util.h>
     30 #include <taler/taler_error_codes.h>
     31 #include <gnunet/gnunet_curl_lib.h>
     32 
     33 
     34 /**
     35  * Maximum number of options that can be set in one set_options
     36  * call. Used as a dummy for "infinite" in the varargs case.
     37  */
     38 #define TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE UINT_MAX
     39 
     40 
     41 /**
     42  * General information about the HTTP response we obtained
     43  * from the exchange for a request.
     44  */
     45 struct TALER_EXCHANGE_HttpResponse
     46 {
     47 
     48   /**
     49    * The complete JSON reply. NULL if we failed to parse the
     50    * reply (too big, invalid JSON).
     51    */
     52   const json_t *reply;
     53 
     54   /**
     55    * Set to the human-readable 'hint' that is optionally
     56    * provided by the exchange together with errors. NULL
     57    * if no hint was provided or if there was no error.
     58    */
     59   const char *hint;
     60 
     61   /**
     62    * HTTP status code for the response.  0 if the
     63    * HTTP request failed and we did not get any answer, or
     64    * if the answer was invalid and we set @a ec to a
     65    * client-side error code.
     66    */
     67   unsigned int http_status;
     68 
     69   /**
     70    * Taler error code.  #TALER_EC_NONE if everything was
     71    * OK.  Usually set to the "code" field of an error
     72    * response, but may be set to values created at the
     73    * client side, for example when the response was
     74    * not in JSON format or was otherwise ill-formed.
     75    */
     76   enum TALER_ErrorCode ec;
     77 
     78 };
     79 
     80 
     81 /**
     82  * Information returned when a client needs to pass
     83  * a KYC check before the transaction may succeed.
     84  */
     85 struct TALER_EXCHANGE_KycNeededRedirect
     86 {
     87 
     88   /**
     89    * Hash of the payto-URI of the account to KYC;
     90    */
     91   struct TALER_NormalizedPaytoHashP h_payto;
     92 
     93   /**
     94    * Public key needed to access the KYC state of
     95    * this account. All zeros if a wire transfer
     96    * is required first to establish the key.
     97    */
     98   union TALER_AccountPublicKeyP account_pub;
     99 
    100   /**
    101    * Legitimization requirement that the merchant should use
    102    * to check for its KYC status, 0 if not known.
    103    */
    104   uint64_t requirement_row;
    105 
    106   /**
    107    * Set to true if the KYC AUTH public key known to the exchange does not
    108    * match the merchant public key associated with the deposit operation.
    109    */
    110   bool bad_kyc_auth;
    111 };
    112 
    113 
    114 /**
    115  * We received an #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS response code.
    116  * Parse the JSON response and initialize the @a uflr object.
    117  *
    118  * @param[out] uflr data structure to initialize
    119  * @param j JSON response to parse
    120  * @return #GNUNET_OK on success
    121  */
    122 enum GNUNET_GenericReturnValue
    123 TALER_EXCHANGE_parse_451 (struct TALER_EXCHANGE_KycNeededRedirect *uflr,
    124                           const json_t *j);
    125 
    126 
    127 /**
    128  * Information about a coin to be deposited into a purse or reserve.
    129  */
    130 struct TALER_EXCHANGE_PurseDeposit
    131 {
    132   /**
    133    * Age commitment data, might be NULL.
    134    */
    135   const struct TALER_AgeCommitmentProof *age_commitment_proof;
    136 
    137   /**
    138    * Private key of the coin.
    139    */
    140   struct TALER_CoinSpendPrivateKeyP coin_priv;
    141 
    142   /**
    143    * Signature proving the validity of the coin.
    144    */
    145   struct TALER_DenominationSignature denom_sig;
    146 
    147   /**
    148    * Hash of the denomination's public key.
    149    */
    150   struct TALER_DenominationHashP h_denom_pub;
    151 
    152   /**
    153    * Amount of the coin to transfer into the purse.
    154    */
    155   struct TALER_Amount amount;
    156 
    157 };
    158 
    159 
    160 #endif