The Auditor RESTful JSON API

The API specified here follows the general conventions for all details not specified in the individual requests. The glossary <https://docs.taler.net/glossary.html#glossary> defines all specific terms used in this section.

Obtaining Auditor Version

This API is used by merchants to obtain a list of all exchanges audited by this auditor. This may be required for the merchant to perform the required know-your-customer (KYC) registration before issuing contracts.

GET /version

Get the protocol version and some meta data about the auditor.

Response:

Status Codes:
  • 200 OK – The auditor responds with a `AuditorVersion`_ object. This request should virtually always be successful.

Details:

interface AuditorVersion {
  // libtool-style representation of the Taler protocol version, see
  // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
  // The format is "current:revision:age".  Note that the auditor
  // protocol is versioned independently of the exchange's protocol.
  version: String;

  // Return which currency this auditor is auditing for.
  currency: String;

  // EdDSA master public key of the auditor
  auditor_public_key: EddsaPublicKey;
}

Note

This API is still experimental (and is not yet implemented at the time of this writing).

Obtaining Exchange List

This API is used by merchants to obtain a list of all exchanges audited by this auditor. This may be required for the merchant to perform the required know-your-customer (KYC) registration before issuing contracts.

GET /exchanges

Get a list of all exchanges audited by the auditor.

Response:

Status Codes:
  • 200 OK – The auditor responds with a `ExchangeList`_ object. This request should virtually always be successful.

Details:

interface ExchangeList {
  // Exchanges audited by this auditor
  exchanges: ExchangeEntry[];
}
interface ExchangeEntry {

  // Public key of the exchange
  exchange_pub: EddsaPublicKey;

  // Base URL of the exchange
  exchange_url: string;
}

Note

This API is still experimental (and is not yet implemented at the time of this writing). A key open question is whether the auditor should sign the information. We might also want to support more delta downloads in the future.

Submitting deposit confirmations

Merchants should probabilistically submit some of the deposit confirmations they receive from the exchange to auditors to ensure that the exchange does not lie about recording deposit confirmations with the exchange. Participating in this scheme ensures that in case an exchange runs into financial trouble to pay its obligations, the merchants that did participate in detecting the bad behavior can be paid out first.

PUT /deposit-confirmation
Submits a DepositConfirmation to the exchange. Should succeed unless the signature provided is invalid or the exchange is not audited by this auditor.

Response:

Status Codes:
  • 200 – The auditor responds with a DepositAudited object. This request should virtually always be successful.

Details:

interface DepositAudited {
    // TODO: do we care for the auditor to sign this?
}
interface DepositConfirmation {

  // Hash over the contract for which this deposit is made.
  h_contract_terms: HashCode;

  // Hash over the wiring information of the merchant.
  h_wire: HashCode;

  // Time when the deposit confirmation confirmation was generated.
  timestamp: Timestamp;

  // How much time does the merchant have to issue a refund
  // request?  Zero if refunds are not allowed.
  refund_deadline : Timestamp;

  // Amount to be deposited, excluding fee.  Calculated from the
  // amount with fee and the fee from the deposit request.
  amount_without_fee: Amount;

  // The coin's public key.  This is the value that must have been
  // signed (blindly) by the Exchange.  The deposit request is to be
  // signed by the corresponding private key (using EdDSA).
  coin_pub: CoinPublicKey;

  // The Merchant's public key.  Allows the merchant to later refund
  // the transaction or to inquire about the wire transfer identifier.
  merchant_pub: EddsaPublicKey;

  // Signature from the exchange of type
  // TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT.
  exchange_sig: EddsaSignature;

  // Public signing key from the exchange matching @e exchange_sig.
  exchange_pub: EddsaPublicKey;

  // Master public key of the exchange corresponding to @e master_sig.
  // Identifies the exchange this is about.
  master_pub: EddsaPublicKey;

  // When does the validity of the exchange_pub end?
  ep_start: Timestamp;

  // When will the exchange stop using the signing key?
  ep_expire: Timestamp;

  // When does the validity of the exchange_pub end?
  ep_end: Timestamp;

  // Exchange master signature over @e exchange_sig.
  master_sig: EddsaSignature;
}

Note

This API is still experimental (and is not yet implemented at the time of this writing). A key open question is whether the auditor should sign the response information.

Complaints

This API is used by the wallet or merchants to submit proof of misbehavior of an exchange to the auditor.

Note

To be designed and implemented.

PUT /complain

Complain about missbehavior to the auditor.