taler/exchange
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
c693ec4a3e
exchange/src/include/taler_exchange_service.h
Christian Grothoff 385b3e77df
tighten formatting rules
2019-10-31 12:59:50 +01:00

1780 lines
64 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/*
This file is part of TALER
Copyright (C) 2014-2018 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
Foundation; either version 3, or (at your option) any later version.
TALER is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
*/
/**
* @file include/taler_exchange_service.h
* @brief C interface of libtalerexchange, a C library to use exchange's HTTP API
* @author Sree Harsha Totakura <sreeharsha@totakura.in>
* @author Christian Grothoff
*/
#ifndef _TALER_EXCHANGE_SERVICE_H
#define _TALER_EXCHANGE_SERVICE_H
#include <jansson.h>
#include "taler_util.h"
#include "taler_error_codes.h"
#include <gnunet/gnunet_curl_lib.h>
/* ********************* /keys *********************** */
/**
* List of possible options to be passed to
* #TALER_EXCHANGE_connect().
*/
enum TALER_EXCHANGE_Option
{
/**
* Terminator (end of option list).
*/
TALER_EXCHANGE_OPTION_END = 0,
/**
* Followed by a "const json_t *" that was previously returned for
* this exchange URL by #TALER_EXCHANGE_serialize_data(). Used to
* resume a connection to an exchange without having to re-download
* /keys data (or at least only download the deltas).
*/
TALER_EXCHANGE_OPTION_DATA
};
/**
* @brief Exchange's signature key
*/
struct TALER_EXCHANGE_SigningPublicKey
{
/**
* The signing public key
*/
struct TALER_ExchangePublicKeyP key;
/**
* Signature over this signing key by the exchange's master signature.
*/
struct TALER_MasterSignatureP master_sig;
/**
* Validity start time
*/
struct GNUNET_TIME_Absolute valid_from;
/**
* Validity expiration time (how long the exchange may use it).
*/
struct GNUNET_TIME_Absolute valid_until;
/**
* Validity expiration time for legal disputes.
*/
struct GNUNET_TIME_Absolute valid_legal;
};
/**
* @brief Public information about a exchange's denomination key
*/
struct TALER_EXCHANGE_DenomPublicKey
{
/**
* The public key
*/
struct TALER_DenominationPublicKey key;
/**
* The hash of the public key.
*/
struct GNUNET_HashCode h_key;
/**
* Exchange's master signature over this denomination record.
*/
struct TALER_MasterSignatureP master_sig;
/**
* Timestamp indicating when the denomination key becomes valid
*/
struct GNUNET_TIME_Absolute valid_from;
/**
* Timestamp indicating when the denomination key can’t be used anymore to
* withdraw new coins.
*/
struct GNUNET_TIME_Absolute withdraw_valid_until;
/**
* Timestamp indicating when coins of this denomination become invalid.
*/
struct GNUNET_TIME_Absolute expire_deposit;
/**
* When do signatures with this denomination key become invalid?
* After this point, these signatures cannot be used in (legal)
* disputes anymore, as the Exchange is then allowed to destroy its side
* of the evidence. @e expire_legal is expected to be significantly
* larger than @e expire_deposit (by a year or more).
*/
struct GNUNET_TIME_Absolute expire_legal;
/**
* The value of this denomination
*/
struct TALER_Amount value;
/**
* The applicable fee for withdrawing a coin of this denomination
*/
struct TALER_Amount fee_withdraw;
/**
* The applicable fee to spend a coin of this denomination
*/
struct TALER_Amount fee_deposit;
/**
* The applicable fee to melt/refresh a coin of this denomination
*/
struct TALER_Amount fee_refresh;
/**
* The applicable fee to refund a coin of this denomination
*/
struct TALER_Amount fee_refund;
};
/**
* Information we track per denomination audited by the auditor.
*/
struct TALER_EXCHANGE_AuditorDenominationInfo
{
/**
* Signature by the auditor affirming that it is monitoring this
* denomination.
*/
struct TALER_AuditorSignatureP auditor_sig;
/**
* Offsets into the key's main `denom_keys` array identifying the
* denomination being audited by this auditor.
*/
unsigned int denom_key_offset;
};
/**
* @brief Information we get from the exchange about auditors.
*/
struct TALER_EXCHANGE_AuditorInformation
{
/**
* Public key of the auditing institution. Wallets and merchants
* are expected to be configured with a set of public keys of
* auditors that they deem acceptable. These public keys are
* the roots of the Taler PKI.
*/
struct TALER_AuditorPublicKeyP auditor_pub;
/**
* URL of the auditing institution. Signed by the auditor's public
* key, this URL is a place where applications can direct users for
* additional information about the auditor. In the future, there
* should also be an auditor API for automated submission about
* claims of misbehaving exchange providers.
*/
char *auditor_url;
/**
* Array of length @a num_denom_keys with the denomination
* keys audited by this auditor.
*/
struct TALER_EXCHANGE_AuditorDenominationInfo *denom_keys;
/**
* Number of denomination keys audited by this auditor.
*/
unsigned int num_denom_keys;
};
/**
* @brief Information about keys from the exchange.
*/
struct TALER_EXCHANGE_Keys
{
/**
* Long-term offline signing key of the exchange.
*/
struct TALER_MasterPublicKeyP master_pub;
/**
* Array of the exchange's online signing keys.
*/
struct TALER_EXCHANGE_SigningPublicKey *sign_keys;
/**
* Array of the exchange's denomination keys.
*/
struct TALER_EXCHANGE_DenomPublicKey *denom_keys;
/**
* Array of the keys of the auditors of the exchange.
*/
struct TALER_EXCHANGE_AuditorInformation *auditors;
/**
* Supported Taler protocol version by the exchange.
* String in the format current:revision:age using the
* semantics of GNU libtool. See
* https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
*/
char *version;
/**
* How long after a reserve went idle will the exchange close it?
* This is an approximate number, not cryptographically signed by
* the exchange (advisory-only, may change anytime).
*/
struct GNUNET_TIME_Relative reserve_closing_delay;
/**
* Timestamp indicating the /keys generation.
*/
struct GNUNET_TIME_Absolute list_issue_date;
/**
* Timestamp indicating the creation time of the last
* denomination key in /keys.
* Used to fetch /keys incrementally.
*/
struct GNUNET_TIME_Absolute last_denom_issue_date;
/**
* Length of the @e sign_keys array (number of valid entries).
*/
unsigned int num_sign_keys;
/**
* Length of the @e denom_keys array.
*/
unsigned int num_denom_keys;
/**
* Length of the @e auditors array.
*/
unsigned int num_auditors;
/**
* Actual length of the @e auditors array (size of allocation).
*/
unsigned int auditors_size;
/**
* Actual length of the @e denom_keys array (size of allocation).
*/
unsigned int denom_keys_size;
};
/**
* How compatible are the protocol version of the exchange and this
* client? The bits (1,2,4) can be used to test if the exchange's
* version is incompatible, older or newer respectively.
*/
enum TALER_EXCHANGE_VersionCompatibility
{
/**
* The exchange runs exactly the same protocol version.
*/
TALER_EXCHANGE_VC_MATCH = 0,
/**
* The exchange is too old or too new to be compatible with this
* implementation (bit)
*/
TALER_EXCHANGE_VC_INCOMPATIBLE = 1,
/**
* The exchange is older than this implementation (bit)
*/
TALER_EXCHANGE_VC_OLDER = 2,
/**
* The exchange is too old to be compatible with
* this implementation.
*/
TALER_EXCHANGE_VC_INCOMPATIBLE_OUTDATED
= TALER_EXCHANGE_VC_INCOMPATIBLE
| TALER_EXCHANGE_VC_OLDER,
/**
* The exchange is more recent than this implementation (bit).
*/
TALER_EXCHANGE_VC_NEWER = 4,
/**
* The exchange is too recent for this implementation.
*/
TALER_EXCHANGE_VC_INCOMPATIBLE_NEWER
= TALER_EXCHANGE_VC_INCOMPATIBLE
| TALER_EXCHANGE_VC_NEWER,
/**
* We could not even parse the version data.
*/
TALER_EXCHANGE_VC_PROTOCOL_ERROR = 8
};
/**
* Function called with information about who is auditing
* a particular exchange and what key the exchange is using.
*
* @param cls closure
* @param keys information about the various keys used
* by the exchange, NULL if /keys failed
* @param compat protocol compatibility information
*/
typedef void
(*TALER_EXCHANGE_CertificationCallback) (void *cls,
const struct TALER_EXCHANGE_Keys *keys,
enum
TALER_EXCHANGE_VersionCompatibility
compat);
/**
* @brief Handle to the exchange. This is where we interact with
* a particular exchange and keep the per-exchange information.
*/
struct TALER_EXCHANGE_Handle;
/**
* Initialise a connection to the exchange. Will connect to the
* exchange and obtain information about the exchange's master public
* key and the exchange's auditor. The respective information will
* be passed to the @a cert_cb once available, and all future
* interactions with the exchange will be checked to be signed
* (where appropriate) by the respective master key.
*
* @param ctx the context
* @param url HTTP base URL for the exchange
* @param cert_cb function to call with the exchange's certification information,
* possibly called repeatedly if the information changes
* @param cert_cb_cls closure for @a cert_cb
* @param ... list of additional arguments, terminated by #TALER_EXCHANGE_OPTION_END.
* @return the exchange handle; NULL upon error
*/
struct TALER_EXCHANGE_Handle *
TALER_EXCHANGE_connect (struct GNUNET_CURL_Context *ctx,
const char *url,
TALER_EXCHANGE_CertificationCallback cert_cb,
void *cert_cb_cls,
...);
/**
* Serialize the latest key data from @a exchange to be persisted
* on disk (to be used with #TALER_EXCHANGE_OPTION_DATA to more
* efficiently recover the state).
*
* @param exchange which exchange's key and wire data should be serialized
* @return NULL on error (i.e. no current data available); otherwise
* json object owned by the caller
*/
json_t *
TALER_EXCHANGE_serialize_data (struct TALER_EXCHANGE_Handle *exchange);
/**
* Disconnect from the exchange.
*
* @param exchange the exchange handle
*/
void
TALER_EXCHANGE_disconnect (struct TALER_EXCHANGE_Handle *exchange);
/**
* Obtain the keys from the exchange.
*
* @param exchange the exchange handle
* @return the exchange's key set
*/
const struct TALER_EXCHANGE_Keys *
TALER_EXCHANGE_get_keys (struct TALER_EXCHANGE_Handle *exchange);
/**
* Set the fake now to be used when requesting "/keys".
*
* @param exchange exchange handle.
* @param now fake now to use. Note: this value will be
* used _until_ its use will be unset via @a TALER_EXCHANGE_unset_now()
*/
void
TALER_EXCHANGE_set_now (struct TALER_EXCHANGE_Handle *exchange,
struct GNUNET_TIME_Absolute now);
/**
* Unset the fake now to be used when requesting "/keys".
*
* @param exchange exchange handle.
*/
void
TALER_EXCHANGE_unset_now (struct TALER_EXCHANGE_Handle *exchange);
/**
* Let the user set the last valid denomination time manually.
*
* @param exchange the exchange handle.
* @param last_denom_new new last denomination time.
*/
void
TALER_EXCHANGE_set_last_denom (struct TALER_EXCHANGE_Handle *exchange,
struct GNUNET_TIME_Absolute last_denom_new);
/**
* Check if our current response for /keys is valid, and if
* not, trigger /keys download.
*
* @param exchange exchange to check keys for
* @param force_download #GNUNET_YES to force download even if /keys is still valid
* @return until when the response is current, 0 if we are re-downloading
*/
struct GNUNET_TIME_Absolute
TALER_EXCHANGE_check_keys_current (struct TALER_EXCHANGE_Handle *exchange,
int force_download,
int pull_all_keys);
/**
* Obtain the keys from the exchange in the raw JSON format.
*
* @param exchange the exchange handle
* @return the exchange's keys in raw JSON
*/
json_t *
TALER_EXCHANGE_get_keys_raw (struct TALER_EXCHANGE_Handle *exchange);
/**
* Test if the given @a pub is a the current signing key from the exchange
* according to @a keys.
*
* @param keys the exchange's key set
* @param pub claimed current online signing key for the exchange
* @return #GNUNET_OK if @a pub is (according to /keys) a current signing key
*/
int
TALER_EXCHANGE_test_signing_key (const struct TALER_EXCHANGE_Keys *keys,
const struct TALER_ExchangePublicKeyP *pub);
/**
* Lookup the given @a pub in @a keys.
*
* @param keys the exchange's key set
* @param pub claimed current online signing key for the exchange
* @return NULL if @a pub was not found
*/
const struct TALER_EXCHANGE_SigningPublicKey *
TALER_EXCHANGE_get_signing_key_details (const struct TALER_EXCHANGE_Keys *keys,
const struct
TALER_ExchangePublicKeyP *pub);
/**
* Get exchange's base URL.
*
* @param exchange exchange handle.
* @return the base URL from the handle.
*/
const char *
TALER_EXCHANGE_get_base_url (const struct TALER_EXCHANGE_Handle *exchange);
/**
* Obtain the denomination key details from the exchange.
*
* @param keys the exchange's key set
* @param pk public key of the denomination to lookup
* @return details about the given denomination key, NULL if the key is not
* found
*/
const struct TALER_EXCHANGE_DenomPublicKey *
TALER_EXCHANGE_get_denomination_key (const struct TALER_EXCHANGE_Keys *keys,
const struct
TALER_DenominationPublicKey *pk);
/**
* Obtain the denomination key details from the exchange.
*
* @param keys the exchange's key set
* @param hc hash of the public key of the denomination to lookup
* @return details about the given denomination key
*/
const struct TALER_EXCHANGE_DenomPublicKey *
TALER_EXCHANGE_get_denomination_key_by_hash (const struct
TALER_EXCHANGE_Keys *keys,
const struct GNUNET_HashCode *hc);
/**
* Obtain meta data about an exchange (online) signing
* key.
*
* @param keys from where to obtain the meta data
* @param exchange_pub public key to lookup
* @return NULL on error (@a exchange_pub not known)
*/
const struct TALER_EXCHANGE_SigningPublicKey *
TALER_EXCHANGE_get_exchange_signing_key_info (const struct
TALER_EXCHANGE_Keys *keys,
const struct
TALER_ExchangePublicKeyP *
exchange_pub);
/* ********************* /wire *********************** */
/**
* Sorted list of fees to be paid for aggregate wire transfers.
*/
struct TALER_EXCHANGE_WireAggregateFees
{
/**
* This is a linked list.
*/
struct TALER_EXCHANGE_WireAggregateFees *next;
/**
* Fee to be paid whenever the exchange wires funds to the merchant.
*/
struct TALER_Amount wire_fee;
/**
* Fee to be paid when the exchange closes a reserve and wires funds
* back to a customer.
*/
struct TALER_Amount closing_fee;
/**
* Time when this fee goes into effect (inclusive)
*/
struct GNUNET_TIME_Absolute start_date;
/**
* Time when this fee stops being in effect (exclusive).
*/
struct GNUNET_TIME_Absolute end_date;
/**
* Signature affirming the above fee structure.
*/
struct TALER_MasterSignatureP master_sig;
};
/**
* Information about a wire account of the exchange.
*/
struct TALER_EXCHANGE_WireAccount
{
/**
* payto://-URL of the exchange.
*/
const char *url;
/**
* Signature of the exchange over the account (was checked by the API).
*/
struct TALER_MasterSignatureP master_sig;
/**
* Linked list of wire fees the exchange charges for
* accounts of the wire method matching @e url.
*/
const struct TALER_EXCHANGE_WireAggregateFees *fees;
};
/**
* Callbacks of this type are used to serve the result of submitting a
* wire format inquiry request to a exchange.
*
* If the request fails to generate a valid response from the
* exchange, @a http_status will also be zero.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful request;
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param accounts_len length of the @a accounts array
* @param accounts list of wire accounts of the exchange, NULL on error
*/
typedef void
(*TALER_EXCHANGE_WireResultCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
unsigned int accounts_len,
const struct
TALER_EXCHANGE_WireAccount *accounts);
/**
* @brief A Wire format inquiry handle
*/
struct TALER_EXCHANGE_WireHandle;
/**
* Obtain information about a exchange's wire instructions. A
* exchange may provide wire instructions for creating a reserve. The
* wire instructions also indicate which wire formats merchants may
* use with the exchange. This API is typically used by a wallet for
* wiring funds, and possibly by a merchant to determine supported
* wire formats.
*
* Note that while we return the (main) response verbatim to the
* caller for further processing, we do already verify that the
* response is well-formed (i.e. that signatures included in the
* response are all valid). If the exchange's reply is not
* well-formed, we return an HTTP status code of zero to @a cb.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param wire_cb the callback to call when a reply for this request is available
* @param wire_cb_cls closure for the above callback
* @return a handle for this request
*/
struct TALER_EXCHANGE_WireHandle *
TALER_EXCHANGE_wire (struct TALER_EXCHANGE_Handle *exchange,
TALER_EXCHANGE_WireResultCallback wire_cb,
void *wire_cb_cls);
/**
* Cancel a wire information request. This function cannot be used
* on a request handle if a response is already served for it.
*
* @param wh the wire information request handle
*/
void
TALER_EXCHANGE_wire_cancel (struct TALER_EXCHANGE_WireHandle *wh);
/* ********************* /deposit *********************** */
/**
* @brief A Deposit Handle
*/
struct TALER_EXCHANGE_DepositHandle;
/**
* Callbacks of this type are used to serve the result of submitting a
* deposit permission request to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit;
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param exchange_sig signature provided by the exchange
* @param sign_key exchange key used to sign @a obj, or NULL
* @param obj the received JSON reply, should be kept as proof (and, in case of errors,
* be forwarded to the customer)
*/
typedef void
(*TALER_EXCHANGE_DepositResultCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const struct
TALER_ExchangeSignatureP *exchange_sig,
const struct
TALER_ExchangePublicKeyP *sign_key,
const json_t *obj);
/**
* Submit a deposit permission to the exchange and get the exchange's
* response. This API is typically used by a merchant. Note that
* while we return the response verbatim to the caller for further
* processing, we do already verify that the response is well-formed
* (i.e. that signatures included in the response are all valid). If
* the exchange's reply is not well-formed, we return an HTTP status code
* of zero to @a cb.
*
* We also verify that the @a coin_sig is valid for this deposit
* request, and that the @a ub_sig is a valid signature for @a
* coin_pub. Also, the @a exchange must be ready to operate (i.e. have
* finished processing the /keys reply). If either check fails, we do
* NOT initiate the transaction with the exchange and instead return NULL.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param amount the amount to be deposited
* @param wire_deadline execution date, until which the merchant would like the exchange to settle the balance (advisory, the exchange cannot be
* forced to settle in the past or upon very short notice, but of course a well-behaved exchange will limit aggregation based on the advice received)
* @param wire_details the merchant’s account details, in a format supported by the exchange
* @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the exchange)
* @param coin_pub coin’s public key
* @param denom_pub denomination key with which the coin is signed
* @param denom_sig exchange’s unblinded signature of the coin
* @param timestamp timestamp when the contract was finalized, must match approximately the current time of the exchange
* @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests)
* @param refund_deadline date until which the merchant can issue a refund to the customer via the exchange (can be zero if refunds are not allowed); must not be after the @a wire_deadline
* @param coin_sig the signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT made by the customer with the coin’s private key.
* @param cb the callback to call when a reply for this request is available
* @param cb_cls closure for the above callback
* @return a handle for this request; NULL if the inputs are invalid (i.e.
* signatures fail to verify). In this case, the callback is not called.
*/
struct TALER_EXCHANGE_DepositHandle *
TALER_EXCHANGE_deposit (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_Amount *amount,
struct GNUNET_TIME_Absolute wire_deadline,
json_t *wire_details,
const struct GNUNET_HashCode *h_contract_terms,
const struct TALER_CoinSpendPublicKeyP *coin_pub,
const struct TALER_DenominationSignature *denom_sig,
const struct TALER_DenominationPublicKey *denom_pub,
struct GNUNET_TIME_Absolute timestamp,
const struct TALER_MerchantPublicKeyP *merchant_pub,
struct GNUNET_TIME_Absolute refund_deadline,
const struct TALER_CoinSpendSignatureP *coin_sig,
TALER_EXCHANGE_DepositResultCallback cb,
void *cb_cls);
/**
* Change the chance that our deposit confirmation will be given to the
* auditor to 100%.
*
* @param deposit the deposit permission request handle
*/
void
TALER_EXCHANGE_deposit_force_dc (struct TALER_EXCHANGE_DepositHandle *deposit);
/**
* Cancel a deposit permission request. This function cannot be used
* on a request handle if a response is already served for it.
*
* @param deposit the deposit permission request handle
*/
void
TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit);
/* ********************* /refund *********************** */
/**
* @brief A Refund Handle
*/
struct TALER_EXCHANGE_RefundHandle;
/**
* Callbacks of this type are used to serve the result of submitting a
* refund request to an exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit;
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param sign_key exchange key used to sign @a obj, or NULL
* @param obj the received JSON reply, should be kept as proof (and, in particular,
* be forwarded to the customer)
*/
typedef void
(*TALER_EXCHANGE_RefundResultCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const struct
TALER_ExchangePublicKeyP *sign_key,
const json_t *obj);
/**
* Submit a refund request to the exchange and get the exchange's
* response. This API is used by a merchant. Note that
* while we return the response verbatim to the caller for further
* processing, we do already verify that the response is well-formed
* (i.e. that signatures included in the response are all valid). If
* the exchange's reply is not well-formed, we return an HTTP status code
* of zero to @a cb.
*
* The @a exchange must be ready to operate (i.e. have
* finished processing the /keys reply). If this check fails, we do
* NOT initiate the transaction with the exchange and instead return NULL.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param amount the amount to be refunded; must be larger than the refund fee
* (as that fee is still being subtracted), and smaller than the amount
* (with deposit fee) of the original deposit contribution of this coin
* @param refund_fee fee applicable to this coin for the refund
* @param h_contract_terms hash of the contact of the merchant with the customer that is being refunded
* @param coin_pub coin’s public key of the coin from the original deposit operation
* @param rtransaction_id transaction id for the transaction between merchant and customer (of refunding operation);
* this is needed as we may first do a partial refund and later a full refund. If both
* refunds are also over the same amount, we need the @a rtransaction_id to make the disjoint
* refund requests different (as requests are idempotent and otherwise the 2nd refund might not work).
* @param merchant_priv the private key of the merchant, used to generate signature for refund request
* @param cb the callback to call when a reply for this request is available
* @param cb_cls closure for the above callback
* @return a handle for this request; NULL if the inputs are invalid (i.e.
* signatures fail to verify). In this case, the callback is not called.
*/
struct TALER_EXCHANGE_RefundHandle *
TALER_EXCHANGE_refund (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_Amount *amount,
const struct TALER_Amount *refund_fee,
const struct GNUNET_HashCode *h_contract_terms,
const struct TALER_CoinSpendPublicKeyP *coin_pub,
uint64_t rtransaction_id,
const struct TALER_MerchantPrivateKeyP *merchant_priv,
TALER_EXCHANGE_RefundResultCallback cb,
void *cb_cls);
/**
* Submit a refund request to the exchange and get the exchange's
* response. This API is used by a merchant. Note that
* while we return the response verbatim to the caller for further
* processing, we do already verify that the response is well-formed
* (i.e. that signatures included in the response are all valid). If
* the exchange's reply is not well-formed, we return an HTTP status code
* of zero to @a cb.
*
* The @a exchange must be ready to operate (i.e. have
* finished processing the /keys reply). If this check fails, we do
* NOT initiate the transaction with the exchange and instead return NULL.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param amount the amount to be refunded; must be larger than the refund fee
* (as that fee is still being subtracted), and smaller than the amount
* (with deposit fee) of the original deposit contribution of this coin
* @param refund_fee fee applicable to this coin for the refund
* @param h_contract_terms hash of the contact of the merchant with the customer that is being refunded
* @param coin_pub coin’s public key of the coin from the original deposit operation
* @param rtransaction_id transaction id for the transaction between merchant and customer (of refunding operation);
* this is needed as we may first do a partial refund and later a full refund. If both
* refunds are also over the same amount, we need the @a rtransaction_id to make the disjoint
* refund requests different (as requests are idempotent and otherwise the 2nd refund might not work).
* @param merchant_pub public key of the merchant
* @param merchant_sig signature affirming the refund from the merchant
* @param cb the callback to call when a reply for this request is available
* @param cb_cls closure for the above callback
* @return a handle for this request; NULL if the inputs are invalid (i.e.
* signatures fail to verify). In this case, the callback is not called.
*/
struct TALER_EXCHANGE_RefundHandle *
TALER_EXCHANGE_refund2 (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_Amount *amount,
const struct TALER_Amount *refund_fee,
const struct GNUNET_HashCode *h_contract_terms,
const struct TALER_CoinSpendPublicKeyP *coin_pub,
uint64_t rtransaction_id,
const struct TALER_MerchantPublicKeyP *merchant_pub,
const struct TALER_MerchantSignatureP *merchant_sig,
TALER_EXCHANGE_RefundResultCallback cb,
void *cb_cls);
/**
* Cancel a refund permission request. This function cannot be used
* on a request handle if a response is already served for it. If
* this function is called, the refund may or may not have happened.
* However, it is fine to try to refund the coin a second time.
*
* @param refund the refund request handle
*/
void
TALER_EXCHANGE_refund_cancel (struct TALER_EXCHANGE_RefundHandle *refund);
/* ********************* /reserve/status *********************** */
/**
* @brief A /reserve/status Handle
*/
struct TALER_EXCHANGE_ReserveStatusHandle;
/**
* Ways how a reserve's balance may change.
*/
enum TALER_EXCHANGE_ReserveTransactionType
{
/**
* Deposit into the reserve.
*/
TALER_EXCHANGE_RTT_DEPOSIT,
/**
* Withdrawal from the reserve.
*/
TALER_EXCHANGE_RTT_WITHDRAWAL,
/**
* /payback operation.
*/
TALER_EXCHANGE_RTT_PAYBACK,
/**
* Reserve closed operation.
*/
TALER_EXCHANGE_RTT_CLOSE
};
/**
* @brief Entry in the reserve's transaction history.
*/
struct TALER_EXCHANGE_ReserveHistory
{
/**
* Type of the transaction.
*/
enum TALER_EXCHANGE_ReserveTransactionType type;
/**
* Amount transferred (in or out).
*/
struct TALER_Amount amount;
/**
* Details depending on @e type.
*/
union
{
/**
* Information about a deposit that filled this reserve.
* @e type is #TALER_EXCHANGE_RTT_DEPOSIT.
*/
struct
{
/**
* Sender account payto://-URL of the incoming transfer.
*/
char *sender_url;
/**
* Information that uniquely identifies the wire transfer.
*/
void *wire_reference;
/**
* When did the wire transfer happen?
*/
struct GNUNET_TIME_Absolute timestamp;
/**
* Number of bytes stored in @e wire_reference.
*/
size_t wire_reference_size;
} in_details;
/**
* Signature authorizing the withdrawal for outgoing transaction.
* @e type is #TALER_EXCHANGE_RTT_WITHDRAWAL.
*/
json_t *out_authorization_sig;
/**
* Information provided if the reserve was filled via /payback.
* @e type is #TALER_EXCHANGE_RTT_PAYBACK.
*/
struct
{
/**
* Public key of the coin that was paid back.
*/
struct TALER_CoinSpendPublicKeyP coin_pub;
/**
* Signature of the coin of type
* #TALER_SIGNATURE_EXCHANGE_CONFIRM_PAYBACK.
*/
struct TALER_ExchangeSignatureP exchange_sig;
/**
* Public key of the exchange that was used for @e exchange_sig.
*/
struct TALER_ExchangePublicKeyP exchange_pub;
/**
* When did the /payback operation happen?
*/
struct GNUNET_TIME_Absolute timestamp;
} payback_details;
/**
* Information about a close operation of the reserve.
* @e type is #TALER_EXCHANGE_RTT_CLOSE.
*/
struct
{
/**
* Receiver account information for the outgoing wire transfer.
*/
const char *receiver_account_details;
/**
* Wire transfer details for the outgoing wire transfer.
*/
struct TALER_WireTransferIdentifierRawP wtid;
/**
* Signature of the coin of type
* #TALER_SIGNATURE_EXCHANGE_RESERVE_CLOSED.
*/
struct TALER_ExchangeSignatureP exchange_sig;
/**
* Public key of the exchange that was used for @e exchange_sig.
*/
struct TALER_ExchangePublicKeyP exchange_pub;
/**
* When did the wire transfer happen?
*/
struct GNUNET_TIME_Absolute timestamp;
} close_details;
} details;
};
/**
* Callbacks of this type are used to serve the result of submitting a
* reserve status request to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param[in] json original response in JSON format (useful only for diagnostics)
* @param balance current balance in the reserve, NULL on error
* @param history_length number of entries in the transaction history, 0 on error
* @param history detailed transaction history, NULL on error
*/
typedef void
(*TALER_EXCHANGE_ReserveStatusResultCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const json_t *json,
const struct
TALER_Amount *balance,
unsigned int history_length,
const struct
TALER_EXCHANGE_ReserveHistory *
history);
/**
* Submit a request to obtain the transaction history of a reserve
* from the exchange. Note that while we return the full response to the
* caller for further processing, we do already verify that the
* response is well-formed (i.e. that signatures included in the
* response are all valid and add up to the balance). If the exchange's
* reply is not well-formed, we return an HTTP status code of zero to
* @a cb.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param reserve_pub public key of the reserve to inspect
* @param cb the callback to call when a reply for this request is available
* @param cb_cls closure for the above callback
* @return a handle for this request; NULL if the inputs are invalid (i.e.
* signatures fail to verify). In this case, the callback is not called.
*/
struct TALER_EXCHANGE_ReserveStatusHandle *
TALER_EXCHANGE_reserve_status (struct TALER_EXCHANGE_Handle *exchange,
const struct
TALER_ReservePublicKeyP *reserve_pub,
TALER_EXCHANGE_ReserveStatusResultCallback cb,
void *cb_cls);
/**
* Cancel a reserve status request. This function cannot be used
* on a request handle if a response is already served for it.
*
* @param rsh the reserve status request handle
*/
void
TALER_EXCHANGE_reserve_status_cancel (struct
TALER_EXCHANGE_ReserveStatusHandle *rsh);
/* ********************* /reserve/withdraw *********************** */
/**
* @brief A /reserve/withdraw Handle
*/
struct TALER_EXCHANGE_ReserveWithdrawHandle;
/**
* Callbacks of this type are used to serve the result of submitting a
* withdraw request to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param sig signature over the coin, NULL on error
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_ReserveWithdrawResultCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const struct
TALER_DenominationSignature *
sig,
const json_t *full_response);
/**
* Withdraw a coin from the exchange using a /reserve/withdraw
* request. This API is typically used by a wallet to withdraw from a
* reserve.
*
* Note that to ensure that no money is lost in case of hardware
* failures, the caller must have committed (most of) the arguments to
* disk before calling, and be ready to repeat the request with the
* same arguments in case of failures.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param pk kind of coin to create
* @param reserve_priv private key of the reserve to withdraw from
* @param ps secrets of the planchet
* caller must have committed this value to disk before the call (with @a pk)
* @param res_cb the callback to call when the final result for this request is available
* @param res_cb_cls closure for @a res_cb
* @return NULL
* if the inputs are invalid (i.e. denomination key not with this exchange).
* In this case, the callback is not called.
*/
struct TALER_EXCHANGE_ReserveWithdrawHandle *
TALER_EXCHANGE_reserve_withdraw (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_EXCHANGE_DenomPublicKey *pk,
const struct
TALER_ReservePrivateKeyP *reserve_priv,
const struct TALER_PlanchetSecretsP *ps,
TALER_EXCHANGE_ReserveWithdrawResultCallback
res_cb,
void *res_cb_cls);
/**
* Withdraw a coin from the exchange using a /reserve/withdraw
* request. This API is typically used by a wallet to withdraw a tip
* where the reserve's signature was created by the merchant already.
*
* Note that to ensure that no money is lost in case of hardware
* failures, the caller must have committed (most of) the arguments to
* disk before calling, and be ready to repeat the request with the
* same arguments in case of failures.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param pk kind of coin to create
* @param reserve_sig signature from the reserve authorizing the withdrawal
* @param reserve_pub public key of the reserve to withdraw from
* @param ps secrets of the planchet
* caller must have committed this value to disk before the call (with @a pk)
* @param res_cb the callback to call when the final result for this request is available
* @param res_cb_cls closure for @a res_cb
* @return NULL
* if the inputs are invalid (i.e. denomination key not with this exchange).
* In this case, the callback is not called.
*/
struct TALER_EXCHANGE_ReserveWithdrawHandle *
TALER_EXCHANGE_reserve_withdraw2 (struct TALER_EXCHANGE_Handle *exchange,
const struct
TALER_EXCHANGE_DenomPublicKey *pk,
const struct
TALER_ReserveSignatureP *reserve_sig,
const struct
TALER_ReservePublicKeyP *reserve_pub,
const struct TALER_PlanchetSecretsP *ps,
TALER_EXCHANGE_ReserveWithdrawResultCallback
res_cb,
void *res_cb_cls);
/**
* Cancel a withdraw status request. This function cannot be used
* on a request handle if a response is already served for it.
*
* @param sign the withdraw sign request handle
*/
void
TALER_EXCHANGE_reserve_withdraw_cancel (struct
TALER_EXCHANGE_ReserveWithdrawHandle *
sign);
/* ********************* /refresh/melt+reveal ***************************** */
/**
* Melt (partially spent) coins to obtain fresh coins that are
* unlinkable to the original coin(s). Note that melting more
* than one coin in a single request will make those coins linkable,
* so the safest operation only melts one coin at a time.
*
* This API is typically used by a wallet. Note that to ensure that
* no money is lost in case of hardware failures, is operation does
* not actually initiate the request. Instead, it generates a buffer
* which the caller must store before proceeding with the actual call
* to #TALER_EXCHANGE_refresh_melt() that will generate the request.
*
* This function does verify that the given request data is internally
* consistent. However, the @a melts_sig is only verified if @a
* check_sig is set to #GNUNET_YES, as this may be relatively
* expensive and should be redundant.
*
* Aside from some non-trivial cryptographic operations that might
* take a bit of CPU time to complete, this function returns
* its result immediately and does not start any asynchronous
* processing. This function is also thread-safe.
*
* @param melt_priv private keys of the coin to melt
* @param melt_amount amount specifying how much
* the coin will contribute to the melt (including fee)
* @param melt_sig signatures affirming the
* validity of the public keys corresponding to the
* @a melt_priv private key
* @param melt_pk denomination key information
* record corresponding to the @a melt_sig
* validity of the keys
* @param check_sig verify the validity of the signatures of @a melt_sig
* @param fresh_pks_len length of the @a pks array
* @param fresh_pks array of @a pks_len denominations of fresh coins to create
* @param[out] res_size set to the size of the return value, or 0 on error
* @return NULL
* if the inputs are invalid (i.e. denomination key not with this exchange).
* Otherwise, pointer to a buffer of @a res_size to store persistently
* before proceeding to #TALER_EXCHANGE_refresh_melt().
* Non-null results should be freed using GNUNET_free().
*/
char *
TALER_EXCHANGE_refresh_prepare (const struct
TALER_CoinSpendPrivateKeyP *melt_priv,
const struct TALER_Amount *melt_amount,
const struct
TALER_DenominationSignature *melt_sig,
const struct
TALER_EXCHANGE_DenomPublicKey *melt_pk,
int check_sig,
unsigned int fresh_pks_len,
const struct
TALER_EXCHANGE_DenomPublicKey *fresh_pks,
size_t *res_size);
/* ********************* /refresh/melt ***************************** */
/**
* @brief A /refresh/melt Handle
*/
struct TALER_EXCHANGE_RefreshMeltHandle;
/**
* Callbacks of this type are used to notify the application about the
* result of the /refresh/melt stage. If successful, the @a noreveal_index
* should be committed to disk prior to proceeding #TALER_EXCHANGE_refresh_reveal().
*
* @param cls closure
* @param http_status HTTP response code, never #MHD_HTTP_OK (200) as for successful intermediate response this callback is skipped.
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param noreveal_index choice by the exchange in the cut-and-choose protocol,
* UINT32_MAX on error
* @param sign_key exchange key used to sign @a full_response, or NULL
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_RefreshMeltCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
uint32_t noreveal_index,
const struct
TALER_ExchangePublicKeyP *sign_key,
const json_t *full_response);
/**
* Submit a refresh melt request to the exchange and get the exchange's
* response.
*
* This API is typically used by a wallet. Note that to ensure that
* no money is lost in case of hardware failures, the provided
* argument should have been constructed using
* #TALER_EXCHANGE_refresh_prepare and committed to persistent storage
* prior to calling this function.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param refresh_data_length size of the @a refresh_data (returned
* in the `res_size` argument from #TALER_EXCHANGE_refresh_prepare())
* @param refresh_data the refresh data as returned from
#TALER_EXCHANGE_refresh_prepare())
* @param melt_cb the callback to call with the result
* @param melt_cb_cls closure for @a melt_cb
* @return a handle for this request; NULL if the argument was invalid.
* In this case, neither callback will be called.
*/
struct TALER_EXCHANGE_RefreshMeltHandle *
TALER_EXCHANGE_refresh_melt (struct TALER_EXCHANGE_Handle *exchange,
size_t refresh_data_length,
const char *refresh_data,
TALER_EXCHANGE_RefreshMeltCallback melt_cb,
void *melt_cb_cls);
/**
* Cancel a refresh melt request. This function cannot be used
* on a request handle if the callback was already invoked.
*
* @param rmh the refresh handle
*/
void
TALER_EXCHANGE_refresh_melt_cancel (struct
TALER_EXCHANGE_RefreshMeltHandle *rmh);
/* ********************* /refresh/reveal ***************************** */
/**
* Callbacks of this type are used to return the final result of
* submitting a refresh request to a exchange. If the operation was
* successful, this function returns the signatures over the coins
* that were remelted. The @a coin_privs and @a sigs arrays give the
* coins in the same order (and should have the same length) in which
* the original request specified the respective denomination keys.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param num_coins number of fresh coins created, length of the @a sigs and @a coin_privs arrays, 0 if the operation failed
* @param coin_privs array of @a num_coins private keys for the coins that were created, NULL on error
* @param sigs array of signature over @a num_coins coins, NULL on error
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_RefreshRevealCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
unsigned int num_coins,
const struct
TALER_PlanchetSecretsP *coin_privs,
const struct
TALER_DenominationSignature *sigs,
const json_t *full_response);
/**
* @brief A /refresh/reveal Handle
*/
struct TALER_EXCHANGE_RefreshRevealHandle;
/**
* Submit a /refresh/reval request to the exchange and get the exchange's
* response.
*
* This API is typically used by a wallet. Note that to ensure that
* no money is lost in case of hardware failures, the provided
* arguments should have been committed to persistent storage
* prior to calling this function.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param refresh_data_length size of the @a refresh_data (returned
* in the `res_size` argument from #TALER_EXCHANGE_refresh_prepare())
* @param refresh_data the refresh data as returned from
#TALER_EXCHANGE_refresh_prepare())
* @param noreveal_index response from the exchange to the
* #TALER_EXCHANGE_refresh_melt() invocation
* @param reveal_cb the callback to call with the final result of the
* refresh operation
* @param reveal_cb_cls closure for the above callback
* @return a handle for this request; NULL if the argument was invalid.
* In this case, neither callback will be called.
*/
struct TALER_EXCHANGE_RefreshRevealHandle *
TALER_EXCHANGE_refresh_reveal (struct TALER_EXCHANGE_Handle *exchange,
size_t refresh_data_length,
const char *refresh_data,
uint32_t noreveal_index,
TALER_EXCHANGE_RefreshRevealCallback reveal_cb,
void *reveal_cb_cls);
/**
* Cancel a refresh reveal request. This function cannot be used
* on a request handle if the callback was already invoked.
*
* @param rrh the refresh reval handle
*/
void
TALER_EXCHANGE_refresh_reveal_cancel (struct
TALER_EXCHANGE_RefreshRevealHandle *rrh);
/* ********************* /refresh/link ***************************** */
/**
* @brief A /refresh/link Handle
*/
struct TALER_EXCHANGE_RefreshLinkHandle;
/**
* Callbacks of this type are used to return the final result of
* submitting a /refresh/link request to a exchange. If the operation was
* successful, this function returns the signatures over the coins
* that were created when the original coin was melted.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param num_coins number of fresh coins created, length of the @a sigs and @a coin_privs arrays, 0 if the operation failed
* @param coin_privs array of @a num_coins private keys for the coins that were created, NULL on error
* @param sigs array of signature over @a num_coins coins, NULL on error
* @param pubs array of public keys for the @a sigs, NULL on error
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_RefreshLinkCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
unsigned int num_coins,
const struct
TALER_CoinSpendPrivateKeyP *coin_privs,
const struct
TALER_DenominationSignature *sigs,
const struct
TALER_DenominationPublicKey *pubs,
const json_t *full_response);
/**
* Submit a refresh link request to the exchange and get the
* exchange's response.
*
* This API is typically not used by anyone, it is more a threat
* against those trying to receive a funds transfer by abusing the
* /refresh protocol.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param coin_priv private key to request link data for
* @param link_cb the callback to call with the useful result of the
* refresh operation the @a coin_priv was involved in (if any)
* @param link_cb_cls closure for @a link_cb
* @return a handle for this request
*/
struct TALER_EXCHANGE_RefreshLinkHandle *
TALER_EXCHANGE_refresh_link (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_CoinSpendPrivateKeyP *coin_priv,
TALER_EXCHANGE_RefreshLinkCallback link_cb,
void *link_cb_cls);
/**
* Cancel a refresh link request. This function cannot be used
* on a request handle if the callback was already invoked.
*
* @param rlh the refresh link handle
*/
void
TALER_EXCHANGE_refresh_link_cancel (struct
TALER_EXCHANGE_RefreshLinkHandle *rlh);
/* ********************* /track/transfer *********************** */
/**
* @brief A /track/transfer Handle
*/
struct TALER_EXCHANGE_TrackTransferHandle;
/**
* Function called with detailed wire transfer data, including all
* of the coin transactions that were combined into the wire transfer.
*
* @param cls closure
* @param http_status HTTP status code we got, 0 on exchange protocol violation
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param sign_key exchange key used to sign @a json, or NULL
* @param json original json reply (may include signatures, those have then been
* validated already)
* @param h_wire hash of the wire transfer address the transfer went to, or NULL on error
* @param execution_time time when the exchange claims to have performed the wire transfer
* @param total_amount total amount of the wire transfer, or NULL if the exchange could
* not provide any @a wtid (set only if @a http_status is #MHD_HTTP_OK)
* @param wire_fee wire fee that was charged by the exchange
* @param details_length length of the @a details array
* @param details array with details about the combined transactions
*/
typedef void
(*TALER_EXCHANGE_TrackTransferCallback)(void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const struct
TALER_ExchangePublicKeyP *sign_key,
const json_t *json,
const struct GNUNET_HashCode *h_wire,
struct GNUNET_TIME_Absolute
execution_time,
const struct TALER_Amount *total_amount,
const struct TALER_Amount *wire_fee,
unsigned int details_length,
const struct
TALER_TrackTransferDetails *details);
/**
* Query the exchange about which transactions were combined
* to create a wire transfer.
*
* @param exchange exchange to query
* @param wtid raw wire transfer identifier to get information about
* @param cb callback to call
* @param cb_cls closure for @a cb
* @return handle to cancel operation
*/
struct TALER_EXCHANGE_TrackTransferHandle *
TALER_EXCHANGE_track_transfer (struct TALER_EXCHANGE_Handle *exchange,
const struct
TALER_WireTransferIdentifierRawP *wtid,
TALER_EXCHANGE_TrackTransferCallback cb,
void *cb_cls);
/**
* Cancel wire deposits request. This function cannot be used on a request
* handle if a response is already served for it.
*
* @param wdh the wire deposits request handle
*/
void
TALER_EXCHANGE_track_transfer_cancel (struct
TALER_EXCHANGE_TrackTransferHandle *wdh);
/* ********************* /track/transaction *********************** */
/**
* @brief A /track/transaction Handle
*/
struct TALER_EXCHANGE_TrackTransactionHandle;
/**
* Function called with detailed wire transfer data.
*
* @param cls closure
* @param http_status HTTP status code we got, 0 on exchange protocol violation
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param sign_key exchange key used to sign @a json, or NULL
* @param json original json reply (may include signatures, those have then been
* validated already)
* @param wtid wire transfer identifier used by the exchange, NULL if exchange did not
* yet execute the transaction
* @param execution_time actual or planned execution time for the wire transfer
* @param coin_contribution contribution to the @a total_amount of the deposited coin (may be NULL)
*/
typedef void
(*TALER_EXCHANGE_TrackTransactionCallback)(void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const struct
TALER_ExchangePublicKeyP *sign_key,
const json_t *json,
const struct
TALER_WireTransferIdentifierRawP *
wtid,
struct GNUNET_TIME_Absolute
execution_time,
const struct
TALER_Amount *coin_contribution);
/**
* Obtain the wire transfer details for a given transaction.
*
* @param exchange the exchange to query
* @param merchant_priv the merchant's private key
* @param h_wire hash of merchant's wire transfer details
* @param h_contract_terms hash of the proposal data
* @param coin_pub public key of the coin
* @param cb function to call with the result
* @param cb_cls closure for @a cb
* @return handle to abort request
*/
struct TALER_EXCHANGE_TrackTransactionHandle *
TALER_EXCHANGE_track_transaction (struct TALER_EXCHANGE_Handle *exchange,
const struct
TALER_MerchantPrivateKeyP *merchant_priv,
const struct GNUNET_HashCode *h_wire,
const struct
GNUNET_HashCode *h_contract_terms,
const struct
TALER_CoinSpendPublicKeyP *coin_pub,
TALER_EXCHANGE_TrackTransactionCallback cb,
void *cb_cls);
/**
* Cancel deposit wtid request. This function cannot be used on a request
* handle if a response is already served for it.
*
* @param dwh the wire deposits request handle
*/
void
TALER_EXCHANGE_track_transaction_cancel (struct
TALER_EXCHANGE_TrackTransactionHandle *
dwh);
/**
* Convenience function. Verifies a coin's transaction history as
* returned by the exchange.
*
* @param currency expected currency for the coin
* @param coin_pub public key of the coin
* @param history history of the coin in json encoding
* @param[out] total how much of the coin has been spent according to @a history
* @return #GNUNET_OK if @a history is valid, #GNUNET_SYSERR if not
*/
int
TALER_EXCHANGE_verify_coin_history (const char *currency,
const struct
TALER_CoinSpendPublicKeyP *coin_pub,
json_t *history,
struct TALER_Amount *total);
/* ********************* /payback *********************** */
/**
* @brief A /payback Handle
*/
struct TALER_EXCHANGE_PaybackHandle;
/**
* Callbacks of this type are used to return the final result of
* submitting a refresh request to a exchange. If the operation was
* successful, this function returns the signatures over the coins
* that were remelted. The @a coin_privs and @a sigs arrays give the
* coins in the same order (and should have the same length) in which
* the original request specified the respective denomination keys.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param ec taler-specific error code, #TALER_EC_NONE on success
* @param amount amount the exchange will wire back for this coin,
* on error the total balance remaining, or NULL
* @param timestamp what time did the exchange receive the /payback request
* @param reserve_pub public key of the reserve receiving the payback, NULL if refreshed or on error
* @param old_coin_pub public key of the dirty coin, NULL if not refreshed or on error
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_PaybackResultCallback) (void *cls,
unsigned int http_status,
enum TALER_ErrorCode ec,
const struct TALER_Amount *amount,
struct GNUNET_TIME_Absolute timestamp,
const struct
TALER_ReservePublicKeyP *reserve_pub,
const struct
TALER_CoinSpendPublicKeyP *old_coin_pub,
const json_t *full_response);
/**
* Ask the exchange to pay back a coin due to the exchange triggering
* the emergency payback protocol for a given denomination. The value
* of the coin will be refunded to the original customer (without fees).
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param pk kind of coin to pay back
* @param denom_sig signature over the coin by the exchange using @a pk
* @param ps secret internals of the original planchet
* @param was_refreshed #GNUNET_YES if the coin in @a ps was refreshed
* @param payback_cb the callback to call when the final result for this request is available
* @param payback_cb_cls closure for @a payback_cb
* @return NULL
* if the inputs are invalid (i.e. denomination key not with this exchange).
* In this case, the callback is not called.
*/
struct TALER_EXCHANGE_PaybackHandle *
TALER_EXCHANGE_payback (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_EXCHANGE_DenomPublicKey *pk,
const struct TALER_DenominationSignature *denom_sig,
const struct TALER_PlanchetSecretsP *ps,
int was_refreshed,
TALER_EXCHANGE_PaybackResultCallback payback_cb,
void *payback_cb_cls);
/**
* Cancel a payback request. This function cannot be used on a
* request handle if the callback was already invoked.
*
* @param ph the payback handle
*/
void
TALER_EXCHANGE_payback_cancel (struct TALER_EXCHANGE_PaybackHandle *ph);
#endif /* _TALER_EXCHANGE_SERVICE_H */
Reference in New Issue View Git Blame Copy Permalink