renaming mint->exchange

1 files changed, 1220 insertions, 0 deletions

diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h
new file mode 100644
index 000000000..566dec6f8
--- /dev/null
+++ b/src/include/taler_exchange_service.h
@@ -0,0 +1,1220 @@
+/*
+  This file is part of TALER
+  Copyright (C) 2014, 2015 GNUnet e.V.
+
+  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, 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 "taler_util.h"
+
+/* ********************* event loop *********************** */
+
+/**
+ * @brief Handle to this library context.  This is where the
+ * main event loop logic lives.
+ */
+struct TALER_EXCHANGE_Context;
+
+
+/**
+ * Initialise a context.  A context should be used for each thread and should
+ * not be shared among multiple threads.
+ *
+ * @return the context, NULL on error (failure to initialize)
+ */
+struct TALER_EXCHANGE_Context *
+TALER_EXCHANGE_init (void);
+
+
+/**
+ * Obtain the information for a select() call to wait until
+ * #TALER_EXCHANGE_perform() is ready again.  Note that calling
+ * any other TALER_EXCHANGE-API may also imply that the library
+ * is again ready for #TALER_EXCHANGE_perform().
+ *
+ * Basically, a client should use this API to prepare for select(),
+ * then block on select(), then call #TALER_EXCHANGE_perform() and then
+ * start again until the work with the context is done.
+ *
+ * This function will NOT zero out the sets and assumes that @a max_fd
+ * and @a timeout are already set to minimal applicable values.  It is
+ * safe to give this API FD-sets and @a max_fd and @a timeout that are
+ * already initialized to some other descriptors that need to go into
+ * the select() call.
+ *
+ * @param ctx context to get the event loop information for
+ * @param read_fd_set will be set for any pending read operations
+ * @param write_fd_set will be set for any pending write operations
+ * @param except_fd_set is here because curl_multi_fdset() has this argument
+ * @param max_fd set to the highest FD included in any set;
+ *        if the existing sets have no FDs in it, the initial
+ *        value should be "-1". (Note that `max_fd + 1` will need
+ *        to be passed to select().)
+ * @param timeout set to the timeout in milliseconds (!); -1 means
+ *        no timeout (NULL, blocking forever is OK), 0 means to
+ *        proceed immediately with #TALER_EXCHANGE_perform().
+ */
+void
+TALER_EXCHANGE_get_select_info (struct TALER_EXCHANGE_Context *ctx,
+                            fd_set *read_fd_set,
+                            fd_set *write_fd_set,
+                            fd_set *except_fd_set,
+                            int *max_fd,
+                            long *timeout);
+
+
+/**
+ * Run the main event loop for the Taler interaction.
+ *
+ * @param ctx the library context
+ */
+void
+TALER_EXCHANGE_perform (struct TALER_EXCHANGE_Context *ctx);
+
+
+/**
+ * Cleanup library initialisation resources.  This function should be called
+ * after using this library to cleanup the resources occupied during library's
+ * initialisation.
+ *
+ * @param ctx the library context
+ */
+void
+TALER_EXCHANGE_fini (struct TALER_EXCHANGE_Context *ctx);
+
+
+/* *********************  /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
+
+};
+
+
+/**
+ * @brief Exchange's signature key
+ */
+struct TALER_EXCHANGE_SigningPublicKey
+{
+  /**
+   * The signing public key
+   */
+  struct TALER_ExchangePublicKeyP key;
+
+  /**
+   * Validity start time
+   */
+  struct GNUNET_TIME_Absolute valid_from;
+
+  /**
+   * Validity expiration time
+   */
+  struct GNUNET_TIME_Absolute valid_until;
+};
+
+
+/**
+ * @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;
+
+  /**
+   * 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 deposit_valid_until;
+
+  /**
+   * 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_spend (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;
+};
+
+
+/**
+ * @brief Information we get from the exchange about auditors.
+ */
+struct TALER_EXCHANGE_AuditorInformation
+{
+  /**
+   * Public key of the auditing institution.
+   */
+  struct TALER_AuditorPublicKeyP auditor_pub;
+
+  /**
+   * URL of the auditing institution.  The application must check that
+   * this is an acceptable auditor for its purpose and also verify
+   * that the @a auditor_pub matches the auditor's public key given at
+   * that website.  We expect that in practice software is going to
+   * often ship with an initial list of accepted auditors, just like
+   * browsers ship with a CA root store.
+   *
+   * This field may be NULL. (#3987).
+   */
+  const char *auditor_url;
+
+  /**
+   * Number of denomination keys audited by this auditor.
+   */
+  unsigned int num_denom_keys;
+
+  /**
+   * Array of length @a denom_keys with the denomination
+   * keys audited by this auditor.  Note that the array
+   * elements point to the same locations as the entries
+   * in the key's main `denom_keys` array.
+   */
+  const struct TALER_EXCHANGE_DenomPublicKey **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;
+
+  /**
+   * Length of the @e sign_keys array.
+   */
+  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;
+
+};
+
+
+/**
+ * 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
+ */
+typedef void
+(*TALER_EXCHANGE_CertificationCallback) (void *cls,
+                                     const struct TALER_EXCHANGE_Keys *keys);
+
+
+/**
+ * @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
+ * @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 TALER_EXCHANGE_Context *ctx,
+                    const char *url,
+                    TALER_EXCHANGE_CertificationCallback cert_cb,
+                    void *cert_cb_cls,
+                    ...);
+
+
+/**
+ * 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 (const 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);
+
+
+/**
+ * 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);
+
+
+/* *********************  /wire *********************** */
+
+
+/**
+ * @brief A Wire format inquiry handle
+ */
+struct TALER_EXCHANGE_WireHandle;
+
+
+/**
+ * Callbacks of this type are used to serve the result of submitting a
+ * wire format inquiry request to a exchange.
+ *
+ * The callback is invoked multiple times, once for each supported @a
+ * method.  Finally, it is invoked one more time with cls/0/NULL/NULL
+ * to indicate the end of the iteration.  If any request fails to
+ * generate a valid response from the exchange, @a http_status will also
+ * be zero and the iteration will also end.  Thus, the iteration
+ * always ends with a final call with an @a http_status of 0. If the
+ * @a http_status is already 0 on the first call, then the response to
+ * the /wire request was invalid.  Later, clients can tell the
+ * difference between @a http_status of 0 indicating a failed
+ * /wire/method request and a regular end of the iteration by @a
+ * method being non-NULL.  If the exchange simply correctly asserts that
+ * it does not support any methods, @a method will be NULL but the @a
+ * http_status will be #MHD_HTTP_OK for the first call (followed by a
+ * cls/0/NULL/NULL call to signal the end of the iteration).
+ *
+ * @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 method wire format method supported, i.e. "test" or "sepa", or NULL
+ *            if already the /wire request failed.
+ * @param obj the received JSON reply, if successful this should be the wire
+ *            format details as provided by /wire/METHOD/, or NULL if the
+ *            reply was not in JSON format (in this case, the client might
+ *            want to do an HTTP request to /wire/METHOD/ with a browser to
+ *            provide more information to the user about the @a method).
+ */
+typedef void
+(*TALER_EXCHANGE_WireResultCallback) (void *cls,
+                                  unsigned int http_status,
+                                  const char *method,
+                                  json_t *obj);
+
+
+/**
+ * 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 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,
+                                     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 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 transaction_id transaction id for the transaction between merchant and customer
+ * @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)
+ * @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,
+                    const struct TALER_CoinSpendPublicKeyP *coin_pub,
+                    const struct TALER_DenominationSignature *denom_sig,
+                    const struct TALER_DenominationPublicKey *denom_pub,
+                    struct GNUNET_TIME_Absolute timestamp,
+                    uint64_t transaction_id,
+                    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);
+
+
+/**
+ * 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);
+
+
+/* ********************* /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
+
+};
+
+
+/**
+ * @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 {
+
+    /**
+     * Transaction details for the incoming transaction.
+     */
+    json_t *wire_in_details;
+
+    /**
+     * Signature authorizing the withdrawal for outgoing transaction.
+     */
+    json_t *out_authorization_sig;
+
+  } details;
+
+};
+
+
+/**
+ * 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 status request
+ *                    0 if the exchange's reply is bogus (fails to follow the protocol)
+ * @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,
+                                           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 withdraw status request.  This function cannot be used
+ * on a request handle if a response is already served for it.
+ *
+ * @param wsh the withdraw status request handle
+ */
+void
+TALER_EXCHANGE_reserve_status_cancel (struct TALER_EXCHANGE_ReserveStatusHandle *wsh);
+
+
+/* ********************* /reserve/withdraw *********************** */
+
+
+/**
+ * @brief A /reserve/withdraw Handle
+ */
+struct TALER_EXCHANGE_ReserveWithdrawHandle;
+
+
+/**
+ * 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 status request
+ *                    0 if the exchange's reply is bogus (fails to follow the protocol)
+ * @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,
+                                             const struct TALER_DenominationSignature *sig,
+                                             json_t *full_response);
+
+
+/**
+ * Withdraw a coin from the exchange using a /reserve/withdraw request.  This
+ * API is typically used by a wallet.  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 coin_priv where to store the coin's private key,
+ *        caller must have committed this value to disk before the call (with @a pk)
+ * @param blinding_key where to store the coin's blinding key
+ *        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_CoinSpendPrivateKeyP *coin_priv,
+                             const struct TALER_DenominationBlindingKey *blinding_key,
+                             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_sigs are only verified if @a
+ * check_sigs 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 num_melts number of coins that are being melted (typically 1)
+ * @param melt_privs array of @a num_melts private keys of the coins to melt
+ * @param melt_amounts array of @a num_melts amounts specifying how much
+ *                     each coin will contribute to the melt (including fee)
+ * @param melt_sigs array of @a num_melts signatures affirming the
+ *                   validity of the public keys corresponding to the
+ *                   @a melt_privs private keys
+ * @param melt_pks array of @a num_melts denomination key information
+ *                   records corresponding to the @a melt_sigs
+ *                   validity of the keys
+ * @param check_sigs verify the validity of the signatures of @a melt_sigs
+ * @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 (unsigned int num_melts,
+                            const struct TALER_CoinSpendPrivateKeyP *melt_privs,
+                            const struct TALER_Amount *melt_amounts,
+                            const struct TALER_DenominationSignature *melt_sigs,
+                            const struct TALER_EXCHANGE_DenomPublicKey *melt_pks,
+                            int check_sigs,
+                            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 noreveal_index choice by the exchange in the cut-and-choose protocol,
+ *                    UINT16_MAX on error
+ * @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,
+                                   uint16_t noreveal_index,
+                                   json_t *full_response);
+
+
+/**
+ * Submit a 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 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,
+
+                                     unsigned int num_coins,
+                                     const struct TALER_CoinSpendPrivateKeyP *coin_privs,
+                                     const struct TALER_DenominationSignature *sigs,
+                                     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,
+                           uint16_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 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,
+                                   unsigned int num_coins,
+                                   const struct TALER_CoinSpendPrivateKeyP *coin_privs,
+                                   const struct TALER_DenominationSignature *sigs,
+                                   const struct TALER_DenominationPublicKey *pubs,
+                                   json_t *full_response);
+
+
+/**
+ * Submit a 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);
+
+
+/* ********************* /admin/add/incoming *********************** */
+
+
+/**
+ * @brief A /admin/add/incoming Handle
+ */
+struct TALER_EXCHANGE_AdminAddIncomingHandle;
+
+
+/**
+ * Callbacks of this type are used to serve the result of submitting
+ * information about an incoming transaction 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 full_response full response from the exchange (for logging, in case of errors)
+ */
+typedef void
+(*TALER_EXCHANGE_AdminAddIncomingResultCallback) (void *cls,
+                                              unsigned int http_status,
+                                              json_t *full_response);
+
+
+/**
+ * Notify the exchange that we have received an incoming transaction
+ * which fills a reserve.  Note that this API is an administrative
+ * API and thus not accessible to typical exchange clients, but only
+ * to the operators of the exchange.
+ *
+ * @param exchange the exchange handle; the exchange must be ready to operate
+ * @param reserve_pub public key of the reserve
+ * @param amount amount that was deposited
+ * @param execution_date when did we receive the amount
+ * @param wire wire details
+ * @param res_cb the callback to call when the final result for this request is available
+ * @param res_cb_cls closure for the above callback
+ * @return NULL
+ *         if the inputs are invalid (i.e. invalid amount).
+ *         In this case, the callback is not called.
+ */
+struct TALER_EXCHANGE_AdminAddIncomingHandle *
+TALER_EXCHANGE_admin_add_incoming (struct TALER_EXCHANGE_Handle *exchange,
+                               const struct TALER_ReservePublicKeyP *reserve_pub,
+                               const struct TALER_Amount *amount,
+                               struct GNUNET_TIME_Absolute execution_date,
+                               const json_t *wire,
+                               TALER_EXCHANGE_AdminAddIncomingResultCallback res_cb,
+                               void *res_cb_cls);
+
+
+/**
+ * Cancel an add incoming.  This function cannot be used on a request
+ * handle if a response is already served for it.
+ *
+ * @param aai the admin add incoming request handle
+ */
+void
+TALER_EXCHANGE_admin_add_incoming_cancel (struct TALER_EXCHANGE_AdminAddIncomingHandle *aai);
+
+
+/* ********************* /wire/deposits *********************** */
+
+/**
+ * @brief A /wire/deposits Handle
+ */
+struct TALER_EXCHANGE_WireDepositsHandle;
+
+
+/**
+ * Details for one of the /deposit operations that the
+ * exchange combined into a single wire transfer.
+ */
+struct TALER_WireDepositDetails
+{
+  /**
+   * Hash of the contract.
+   */
+  struct GNUNET_HashCode h_contract;
+
+  /**
+   * Which coin was deposited?
+   */
+  struct TALER_CoinSpendPublicKeyP coin_pub;
+
+  /**
+   * Value of the deposit (including fee).
+   */
+  struct TALER_Amount coin_value;
+
+  /**
+   * Fee charged by the exchange for the deposit.
+   */
+  struct TALER_Amount coin_fee;
+
+  /**
+   * Merchant's transaction identifier.
+   */
+  uint64_t transaction_id;
+
+};
+
+
+/**
+ * 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 json original json reply (may include signatures, those have then been
+ *        validated already)
+ * @param wtid extracted wire transfer identifier, or NULL if the exchange could
+ *             not provide any (set only if @a http_status is #MHD_HTTP_OK)
+ * @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 details_length length of the @a details array
+ * @param details array with details about the combined transactions
+ */
+typedef void
+(*TALER_EXCHANGE_WireDepositsCallback)(void *cls,
+                                   unsigned int http_status,
+                                   json_t *json,
+                                   const struct GNUNET_HashCode *h_wire,
+                                   const struct TALER_Amount *total_amount,
+                                   unsigned int details_length,
+                                   const struct TALER_WireDepositDetails *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_WireDepositsHandle *
+TALER_EXCHANGE_wire_deposits (struct TALER_EXCHANGE_Handle *exchange,
+                          const struct TALER_WireTransferIdentifierRawP *wtid,
+                          TALER_EXCHANGE_WireDepositsCallback 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_wire_deposits_cancel (struct TALER_EXCHANGE_WireDepositsHandle *wdh);
+
+
+/* ********************* /deposit/wtid *********************** */
+
+
+/**
+ * @brief A /deposit/wtid Handle
+ */
+struct TALER_EXCHANGE_DepositWtidHandle;
+
+
+/**
+ * Function called with detailed wire transfer data.
+ *
+ * @param cls closure
+ * @param http_status HTTP status code we got, 0 on exchange protocol violation
+ * @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_DepositWtidCallback)(void *cls,
+                                  unsigned int http_status,
+                                  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 deposit.
+ *
+ * @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 hash of the contract
+ * @param coin_pub public key of the coin
+ * @param transaction_id transaction identifier
+ * @param cb function to call with the result
+ * @param cb_cls closure for @a cb
+ * @return handle to abort request
+ */
+struct TALER_EXCHANGE_DepositWtidHandle *
+TALER_EXCHANGE_deposit_wtid (struct TALER_EXCHANGE_Handle *exchange,
+                         const struct TALER_MerchantPrivateKeyP *merchant_priv,
+                         const struct GNUNET_HashCode *h_wire,
+                         const struct GNUNET_HashCode *h_contract,
+                         const struct TALER_CoinSpendPublicKeyP *coin_pub,
+                         uint64_t transaction_id,
+                         TALER_EXCHANGE_DepositWtidCallback 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_deposit_wtid_cancel (struct TALER_EXCHANGE_DepositWtidHandle *dwh);
+
+
+#endif  /* _TALER_EXCHANGE_SERVICE_H */