1.6. The Auditor RESTful JSON API¶

The API specified here follows the general conventions for all details not specified in the individual requests. The glossary defines all specific terms used in this section.

1.6.1. Authentication ¶

Each auditor instance has separate authentication settings for the private API resources of that instance.

Currently, the API supports two main authentication methods:

external: With this method, no checks are done by the auditor backend. Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
token: With this method, the client must provide a Authorization: Bearer $TOKEN header, where $TOKEN is a secret authentication token configured for the instance which must begin with the RFC 8959 prefix.

1.6.2. Obtaining Auditor Version ¶

This endpoint 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 /config¶

Get the protocol version and some meta data about the auditor. This specification corresponds to current protocol being version 1.

Response:

200 OK:: The auditor responds with an 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;

  // URN of the implementation (needed to interpret 'revision' in version).
  // @since v0, may become mandatory in the future.
  implementation?: string;

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

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

  // EdDSA master public key of the exchange.
  // Added in protocol v1.
  exchange_master_public_key: EddsaPublicKey;
}

Note

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

1.6.3. 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:

200 Ok:: The auditor responds with a DepositAudited object. This request should virtually always be successful.
403 Forbidden:: The signature on the deposit confirmation is invalid.
410 Gone:: The public key used to sign the deposit confirmation was revoked.

Details:

interface DepositAudited {
  // TODO: maybe change to 204 No content instead?
}

interface DepositConfirmation {

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

  // Hash over the extensions.
  h_extensions: 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;

  // By what time does the exchange have to wire the funds?
  wire_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;

  // Array of public keys of the deposited coins.
  coin_pubs: EddsaPublicKey[];

  // Array of deposit signatures of the deposited coins.
  // Must have the same length as coin_pubs.
  coin_sigs: EddsaSignature[];

  // 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 exchange_sig.
  exchange_pub: EddsaPublicKey;

  // Master public key of the exchange corresponding to master_sig.
  // Identifies the exchange this is about.
  // @deprecated since v1 (now ignored, global per auditor)
  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 exchange_sig.
  master_sig: EddsaSignature;
}

Note

This endpoint 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.

1.6.4. Monitoring API ¶

The following entries specify how to access the results of an audit.

For most endpoints, rows may be marked as ‘suppressed’ to not send them again upon subsequent GET requests. To do this, a GenericAuditorMonitorPatchRequest object is used in the respective PATCH request.

Details:

interface GenericAuditorMonitorPatchRequest {

  // If true, subsequent GET requests will not return this element by default
  suppressed : boolean;

}

1.6.4.1. Fee Time Inconsistencies ¶

This section highlights cases where validity periods associated with wire fees the exchange may charge merchants are invalid. This usually means that the validity periods given for the same type of fee are overlapping and it is thus unclear which fee really applies. This is a sign of a serious misconfiguration or data corruption as usually the exchange logic should prevent such a fee configuration from being accepted.

GET /monitoring/fee-time-inconsistency¶

Get a list of fee time inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of FeeTimeInconsistency objects. If no elements could be found, an empty array is returned

Details:

interface FeeTimeInconsistency {

  // Row ID of the fee in the exchange database.
  row_id : Integer;

  // Specifies the wire method for which the fee is inconsistent.
  type : string;

  // Gives the start date of the inconsistent fee.
  time : Timestamp;

  // Human readable description of the problem.
  diagnostic : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/fee-time-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress selected elements of fee time inconsistencies. Updates the ‘suppressed’ field of a fee time inconsistency element with row ID $SERIAL_ID.

Request:

The body must be a GenericAuditorMonitorPatchRequest.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.2. Emergencies ¶

This endpoint is used to obtain a list of emergencies.

Emergencies are errors where the total value of coins deposited (of a particular denomination) exceeds the total value that the exchange remembers issuing. This usually means that the private keys of the exchange were compromised (stolen or factored) and subsequently used to sign coins off the books. If this happens, all coins of the respective denomination that the exchange has redeemed so far may have been created by the attacker, and the exchange would have to refund all of the outstanding coins from ordinary users. Thus, the risk exposure is the amount of coins in circulation for a particular denomination and the maximum loss for the exchange from this type of compromise.

The difference between emergencies and emergencies by count is how the auditor detected the problem: by comparing amounts, or by counting coins. Theroretically, counting coins should always detect an issue first, but given the importance of emergencies, the auditor checks both total amounts and total numbers of coins (they may differ as coins may be partially deposited).

GET /monitoring/emergency¶

Get a list of emergencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of Emergency objects. If no elements could be found, an empty array is returned

Details:

interface Emergency {

  // Unique row identifier
  row_id : Integer;

  // Hash of denomination public key
  denompub_h : HashCode;

  // What is the total value of all coins of this denomination that
  // were put into circulation (and thus the maximum loss the
  // exchange may experience due to this emergency).
  denom_risk : Amount;

  // What is the loss we have experienced so far (that
  // is, the amount deposited in excess of the amount
  // we issued).
  denom_loss : Amount;

  // When did the exchange start issuing coins in this the denomination.
  deposit_start : Timestamp;

  // When does the deposit period end for coins of this denomination.
  deposit_end : Timestamp;

  // What is the value of an individual coin of this denomination.
  value : Amount;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/emergency/$SERIAL_ID¶

This endpoint is used to suppress select elements of emergencies. Update the ‘suppressed’ field of an emergency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.3. Emergencies By Count ¶

This endpoint is used to obtain a list of emergencies by count.

Emergencies are errors where more coins were deposited than the exchange remembers issuing. This usually means that the private keys of the exchange were compromised (stolen or factored) and subsequently used to sign coins off the books. If this happens, all coins of the respective denomination that the exchange has redeemed so far may have been created by the attacker, and the exchange would have to refund all of the outstanding coins from ordinary users. Thus, the risk exposure is the amount of coins in circulation for a particular denomination and the maximum loss for the exchange from this type of compromise.

Emergencies “by count” are cases where this type of money printing was detected simply by counting the number of coins the exchange officially put into circulation and comparing it to the number of coins that were redeemed. If the number of redeemed coins is higher than the number of issued coins, the auditor reports an emergency-by-count.

GET /monitoring/emergency-by-count¶

Get a list of emergencies by count stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of EmergencyByCount objects.

Details:

interface EmergencyByCount {

  // Row ID of the fee in the exchange database.
  row_id : Integer;

  // Hash of the public denomination key to which the
  // emergency applies.
  denompub_h : HashCode;

  // Number of coins the exchange officially issued of this
  // denomination.
  num_issued : Integer;

  // Number of coins that were redeemed.
  num_known : Integer;

  // What is the total value of all coins of this denomination that
  // were put into circulation (and thus the maximum loss the
  // exchange may experience due to this emergency).
  risk : Amount;

  // When did the exchange start issuing coins in this the denomination.
  start : Timestamp;

  // When does the deposit period end for coins of this denomination.
  deposit_end : Timestamp;

  // What is the value of an individual coin of this denomination.
  value : Amount;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/emergency-by-count/$SERIAL_ID¶

This endpoint is used to suppress select elements of emergencies by count. Update the ‘suppressed’ field of an emergency by count element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Request:

The body must be a GenericAuditorMonitorPatchRequest.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.4. Row Inconsistencies ¶

This section highlights inconsistencies in a specific row of a specific table of the exchange. Row inconsistencies are reported from different sources, and largely point to some kind of data corruption (or bug). Nothing is implied about the seriousness of the inconsistency. Most inconsistencies are detected if some signature fails to validate. The affected table is noted in the ‘table’ field. A description of the nature of the inconsistency is noted in ‘diagnostic’.

GET /monitoring/row-inconsistency¶

Get a list of row inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of RowInconsistency objects.

Details:

interface RowInconsistency {

  // Number of the affected row.
  row_id : Integer;

  // Name of the affected exchange table.
  row_table : string;

  // Human-readable diagnostic about what went wrong.
  diagnostic : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/row-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of row inconsistencies. Update the ‘suppressed’ field of a row inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.5. Reserve In Inconsistencies ¶

This section lists cases where the exchange’s and auditor’s expectation of amounts transferred into a reserve differs. Basically, the exchange database states that a certain reserve was credited for a certain amount via a wire transfer, but the auditor disagrees about this basic fact. This may result in either a customer loosing funds (by being issued less digital cash than they should be) or the exchange loosing funds (by issuing a customer more digital cash than they should be).

GET /monitoring/reserve-in-inconsistency¶

Get a list of reserve in inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of ReserveInInconsistency objects.

Details:

interface ReserveInInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Amount the exchange expects to be in the reserve
  amount_exchange_expected : Amount;

  // Amount deposited into the reserve
  amount_wired : Amount;

  // Public key of the reserve
  reserve_pub : EddsaPublicKey;

  // Time of the deposit
  timestamp : Timestamp;

  // Account associated with the reserve
  account : string;

  // Human readable diagnostic of the problem
  diagnostic : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/reserve-in-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of reserve in inconsistencies. Update the ‘suppressed’ field of a reserve in inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.6. Purse Not Closed Inconsistencies ¶

This section highlights cases, in which either payer or payee did not finish their part of a P2P payment. This caused a purse –– which may contain some money — to reach its expiration date. However, the exchange failed to properly expire the purse, which means the payer did not get their money back. The cause is usually that the taler-exchange-expire helper is not running properly.

GET /monitoring/purse-not-closed-inconsistencies¶

Get a list of purse not closed inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of PurseNotClosedInconsistencies objects.

Details:

interface PurseNotClosedInconsistencies {

  // Unique row identifier.
  row_id : Integer;

  // Public key of the affected purse
  purse_pub : EddsaPublicKey;

  // Amount still in the purse, which should have been refunded
  amount : Amount;

  // When the purse expired
  expiration_date : Timestamp;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/purse-not-closed-inconsistencies/$SERIAL_ID¶

This endpoint is used to suppress select elements of purse not closed inconsistencies. Update the ‘suppressed’ field of a purse not closed inconsistencies element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.7. Reserve Not Closed Inconsistencies ¶

This section highlights cases, in which reserves were not closed, despite being expired. As a result, customers that wired funds to the exchange and then failed to withdraw them are not getting their money back. The cause is usually that the taler-exchange-closer process is not running properly.

GET /monitoring/reserve-not-closed-inconsistency¶

Get a list of reserve not closed inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of ReserveNotClosedInconsistency objects.

Details:

interface ReserveNotClosedInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Public key of the reserve
  reserve_pub : EddsaPublicKey;

  // Amount still in the reserve at the time of expiration
  balance : Amount;

  // Date the reserve expired
  expiration_time : Timestamp;

  // Human readable string describing the problem
  diagnostic : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/reserve-not-closed-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of reserve not closed inconsistencies. Update the ‘suppressed’ field of a reserve not closed inconsistency element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.8. Reserve Balance Insufficient Inconsistencies ¶

This section highlights cases where more coins were withdrawn from a reserve than the reserve contained funding for. This is a serious compromise resulting in proportional financial losses to the exchange.

GET /monitoring/reserve-balance-insufficient-inconsistency¶

Get a list of reserve balance insufficient inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of ReserveBalanceInsufficientInconsistency objects.

Details:

interface ReserveBalanceInsufficientInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Public key of the affected reserve
  reserve_pub : EddsaPublicKey;

  // Whether this inconsistency is profitable for the exchange
  inconsistency_gain : boolean;

  // Amount possibly lost or gained by the exchange
  inconsistency_amount : Amount;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/reserve-balance-insufficient-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of reserve balance insufficient inconsistencies. Update the ‘suppressed’ field of a reserve balance insufficient inconsistency element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.9. Invalid Signature Losses ¶

This section lists operations that the exchange performed, but for which the signatures provided are invalid. Hence the operations are invalid and the amount involved could be a loss for the exchange (as the involved parties could successfully dispute the resulting transactions).

GET /monitoring/bad-sig-losses¶

Get a list of invalid signature losses stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.
operation – A string. If specified, only returns eligible rows with this BadSigLosses.operation value. The default value is NULL which means to not filter by operation.
op_spec_pub – An EddsaPublicKey (in base32 encoding). If given, use its value to only return rows with this BadSigLosses.operation_specific_pub value. The default value is NULL.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of BadSigLosses objects.

Details:

interface BadSigLosses {

  // Unique row identifier
  row_id : Integer;

  // Operation performed, even though a signature was invalid
  operation : string;

  // Amount considered lost by the exchange
  loss : Amount;

  // Public key associated with an operation
  operation_specific_pub : EddsaPublicKey;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/bad-sig-losses/$SERIAL_ID¶

This endpoint is used to suppress select elements of bad sig losses. Update the ‘suppressed’ field of a bad sig losses element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.10. Coin Inconsistencies ¶

This section lists cases where the exchange made arithmetic errors found when looking at the transaction history of a coin. The totals sum up the differences in amounts that matter for profit/loss calculations of the exchange. When an exchange merely shifted money from customers to merchants (or vice versa) without any effects on its own balance, those entries are excluded from the total.

GET /monitoring/coin-inconsistency¶

Get a list of coin inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of CoinInconsistency objects.

Details:

interface CoinInconsistency {

  // Unique row identifier
  row_id : Integer;

  // The operation performed by the exchange
  operation : string;

  // Total the exchange calculated
  exchange_amount : Amount;

  // Total the auditor calculated
  auditor_amount : Amount;

  // Public key of the coin in question
  coin_pub : EddsaPublicKey;

  // Whether this arithmetic error was profitable for the exchange
  profitable : boolean;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/coin-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of coin inconsistencies. Update the ‘suppressed’ field of a coin inconsistency element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.11. Denominations Without Signatures ¶

This section highlights denomination keys that lack a proper signature from the taler-auditor-offline tool. This may be legitimate, say in case where the auditor’s involvement in the exchange business is ending and a new auditor is responsible for future denominations. So this must be read with a keen eye on the business situation.

GET /monitoring/denominations-without-sigs¶

Get a list of denominations without signatures stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of DenominationsWithoutSigs objects.

Details:

interface DenominationsWithoutSigs {

  // Unique row identifier
  row_id : Integer;

  // Hash of the denomination public key
  denompub_h : HashCode;

  // Value of each coin of the denomination that lacks
  // the auditor's signature.
  value : Amount;

  // From when the denomination key in question is valid
  start_time : Timestamp;

  // When the denomination key in question expires
  end_time : Timestamp;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/denominations-without-sigs/$SERIAL_ID¶

This endpoint is used to suppress select elements of denominations without sigs. Update the ‘suppressed’ field of a denominations without signatures element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.12. Misattribution In Inconsistencies ¶

This section lists cases where the sender account record of an incoming wire transfer differs between the exchange and the bank. This may cause funds to be sent to the wrong account should the reserve be closed with a remaining balance, as that balance would be credited to the original account.

GET /monitoring/misattribution-in-inconsistency¶

Get a list of misattribution in inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of MisattributionInInconsistency objects.

Details:

interface MisattributionInInconsistency {

  // Unique row identifier in the exchange database.
  row_id : Integer;

  // Amount of money sent to the wrong account
  amount : Amount;

  // Row of the transaction in the bank database as
  // returned by the bank revenue API.
  bank_row : Integer;

  // Public key of the affected reserve
  reserve_pub : EddsaPublicKey;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/misattribution-in-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of misattribution in inconsistencies. Update the ‘suppressed’ field of an misattribution in inconsistency element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.13. Deposit Confirmations ¶

This section contains a list of deposits confirmations that an exchange provided to merchants but failed to store in its own database. This is indicative of potential fraud by the exchange operator, as the exchange should only issue deposit confirmations after storing the respective deposit records in its database. Not storing the deposit data means that the exchange would not pay the merchant (pocketing the money) or allow the customer to double-spend the money (which is naturally also not good).

Note that entries could appear in this list also because the exchange database replication is delayed. Hence, entries that are only a few seconds old might not be indicative of an actual problem. If entries in this list are more than a few seconds old, the first thing to check is whether or not the database replication from the exchange is working properly.

GET /monitoring/deposit-confirmations¶

Get a list of deposit confirmations stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of DepositConfirmations objects.

Details:

interface DepositConfirmations {

  // Row id in the exchange database
  deposit_confirmation_serial_id : Integer;

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

  // Hash over the policy concerning this deposit
  h_policy : HashCode;

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

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

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

  // By what time does the exchange have to wire the funds?
  wire_deadline : Timestamp;

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

  // Array of public keys of the deposited coins.
  coin_pubs : EddsaPublicKey[];

  // Array of deposit signatures of the deposited coins.
  // Must have the same length as coin_pubs.
  coin_sigs : EddsaSignature[];

  // 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 exchange_sig.
  exchange_pub : EddsaPublicKey;

  // Exchange master signature over exchange_sig.
  master_sig : EddsaSignature;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/deposit-confirmations/$SERIAL_ID¶

This endpoint is used to suppress select elements of deposit confirmations. Update the ‘suppressed’ field of an deposit confirmations element with row ID $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.14. Denomination Key Validity Withdraw Inconsistencies ¶

This section highlights cases, where denomination keys were used to sign coins withdrawn from a reserve before the denomination was valid or after it was already expired for signing. This doesn’t exactly imply any financial loss for anyone, it is mostly weird and may have affected the fees the customer paid.

GET /monitoring/denomination-key-validity-withdraw-inconsistency¶

Get a list of denomination key validity withdraw inconsistencies stored by the auditor. The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of DenominationKeyValidityWithdrawInconsistency objects. If no elements could be found, an empty array is returned

Details:

interface DenominationKeyValidityWithdrawInconsistency {

  // Unique row identifier
  row_id : Integer;

  // When the withdrawal took place
  execution_date : Timestamp;

  // Public key of the reserve affected
  reserve_pub : EddsaPublicKey;

  // Hash of the denomination public key involved in the withdrawal
  denompub_h : HashCode;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/denomination-key-validity-withdraw-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of denomination key validity withdraw inconsistencies. Update the ‘suppressed’ field of a denomination key validity withdraw inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.15. Amount Arithmetic Inconsistencies ¶

This endpoint is used to obtain a list of amount arithmetic inconsistencies.

This section lists cases where the arithmetic of the exchange involving amounts disagrees with the arithmetic of the auditor. Disagreements imply that either the exchange made a loss (sending out too much money), or screwed a customer (and thus at least needs to fix the financial damage done to the customer). The profitable column is set to true if the arithmetic problem was be determined to be profitable for the exchange, false if the problem resulted in a net loss for the exchange.

GET /monitoring/amount-arithmetic-inconsistency¶

Get a list of amount arithmetic inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of AmountArithmeticInconsistency objects. If no elements could be found, an empty array is returned

Details:

interface AmountArithmeticInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Name of the arithmetic operation performed
  operation : string;

  // Amount according to the exchange
  exchange_amount : Amount;

  // Amount according to the auditor
  auditor_amount : Amount;

  // Whether the miscalculation is profitable for the exchange
  profitable : boolean;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/amount-arithmetic-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of amount arithmetic inconsistencies. Update the ‘suppressed’ field of an amount arithmetic inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.16. Wire Format Inconsistencies ¶

This section highlights cases where the wire transfer subject was used more than once and is thus not unique. This indicates a problem with the bank’s implementation of the revenue API, as the bank is supposed to warrant uniqueness of wire transfer subjects exposed via the revenue API (and bounce non-unique transfers).

GET /monitoring/wire-format-inconsistency¶

Get a list of wire format inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of WireFormatInconsistency objects. If no elements could be found, an empty array is returned

Details:

interface WireFormatInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Amount that was part of the wire
  amount : Amount;

  // Offset of the duplicate wire transfer subject
  // in the bank database according to the revenue API.
  wire_offset : Integer;

  // True if this diagnostic was suppressed.
  diagnostic : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;


}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/wire-format-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of wire format inconsistencies. Update the ‘suppressed’ field of a wire format inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.17. Refreshes Hanging ¶

This section highlights cases, where a coin was melted but the reveal process was not finished by the wallet. Usually, a wallet will do both requests in rapid succession to refresh a coin. This might happen, even if the exchange is operating correctly, if a wallet goes offline after melting. However, after some time wallets should in most cases come back online and finish the operation. If many operations are hanging, this might be indicative of a bug (exchange failing on reveal, or wallets not implementing refresh correctly).

GET /monitoring/refreshes-hanging¶

Get a list of refreshes hanging stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of RefreshesHanging objects. If no elements could be found, an empty array is returned

Details:

interface RefreshesHanging {

  // Unique row identifier
  row_id : Integer;

  // Amount in coin not found in the exchange
  amount : Amount;

  // Public key of coin
  coin_pub : EddsaPublicKey;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/refreshes-hanging/$SERIAL_ID¶

This endpoint is used to suppress select elements of refreshes hanging. Update the ‘suppressed’ field of a refreshes hanging element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.18. Closure Lags ¶

This endpoint is used to obtain a list of closure lags.

A closure lag happens if a reserve should have closed a reserve and wired (remaining) funds back to the originating account, but did not do so on time. Significant lag may be indicative of fraud, while moderate lag is indicative that the systems may be too slow to handle the load. Small amounts of lag can occur in normal operation.

If closure lag is experienced, the administrator should check that the taler-exchange-closer component is operating correctly.

GET /monitoring/closure-lags¶

Get a list of closure lags stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of ClosureLags objects. If no elements could be found, an empty array is returned

Details:

interface ClosureLags {

  // Unique row identifier
  row_id : Integer;

  // Amount of money left in the reserve
  amount : Amount;

  // When should the reserve have been closed
  deadline : Timestamp;

  // The wire transfer identifier
  wtid : HashCode;

  // Full payto:// URI (RFC 8905) of the account that
  // should have been credited.
  account : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/closure-lags/$SERIAL_ID¶

This endpoint is used to suppress select elements of closure lags. Update the ‘suppressed’ field of a closure lags element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.19. Wire Out Inconsistencies ¶

This section highlights cases where the exchange wired a different amount to a destimation account than the auditor expected.

GET /monitoring/wire-out-inconsistency¶

Get a list of wire out inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of WireOutInconsistency objects. If no elements could be found, an empty array is returned

Details:

interface WireOutInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Account money was wired to
  destination_account : string;

  // How much was suppossed to be wired according to the auditor.
  expected : Amount;

  // The amount the exchange claims to have wired.
  claimed : Amount;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/wire-out-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of wire out inconsistencies. Update the ‘suppressed’ field of a wire out inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.20. Reserve Balance Summary Wrong Inconsistencies ¶

This section highlights cases, where the exchange’s and auditors’ expectation of the amount of money left in a reserve differs.

GET /monitoring/reserve-balance-summary-wrong-inconsistency¶

Get a list of reserve balance summary wrong inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of ReserveBalanceSummaryWrongInconsistency objects. If no elements could be found, an empty array is returned

Details:

interface ReserveBalanceSummaryWrongInconsistency {

  // Unique row identifier
  row_id : Integer;

  // Public key of the reserve affected
  reserve_pub : EddsaPublicKey;

  // Amount of summary the exchange calculated
  exchange_amount : Amount;

  // Amount of summary the auditor calculated
  auditor_amount : Amount;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID¶

This endpoint is used to suppress select elements of reserve balance summary wrong inconsistencies. Update the ‘suppressed’ field of a reserve balance summary wrong inconsistency element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.4.21. Row Minor Inconsistencies ¶

The section highlights inconsistencies where a row in an exchange table has a value that is does not satisfy expectations (such as a malformed signature). These are cause for concern, but not necessarily point to a monetary loss (yet).

GET /monitoring/row-minor-inconsistencies¶

Get a list of row minor inconsistencies stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
return_suppressed – A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false.

With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.

Response:

200 OK:: The auditor responds with a top level array of RowMinorInconsistencies objects. If no elements could be found, an empty array is returned

Details:

interface RowMinorInconsistencies {

  // Number of the row in the affected table
  row_id : Integer;

  // The row number in the affected table
  row_table : Integer;

  // Human readable string describing the problem
  diagnostic : string;

  // True if this diagnostic was suppressed.
  suppressed : boolean;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

PATCH /monitoring/row-minor-inconsistencies/$SERIAL_ID¶

This endpoint is used to suppress select elements of row minor inconsistencies. Update the ‘suppressed’ field of a row minor inconsistencies element with row_id $SERIAL_ID, according to GenericAuditorMonitorPatchRequest, stored by the auditor.

Response:

204 No Content:: The element has been updated.

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.5. Monitoring Auditor Status ¶

The following entries specify how to access information the auditor keeps to properly perform audits. These tables do not contain inconsistencies, instead they store information about balances, reserves, purses etc. Values in these tables should not differ from their respective exchanges’ version.

1.6.5.1. Balances ¶

Returns the various balances the auditor tracks for the exchange, such as coins in circulation, fees earned, losses experienced, etc.

GET /monitoring/balances¶

Get a list of balances stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

balance_key – a string identifying a balance. If specified, only returns the balance with this exact key. The default value is NULL.

Response:

200 OK:: The auditor responds with a top level array of Balances objects. If no elements could be found, an empty array is returned

Details:

interface Balances {

  // String identifying a balance
  balance_key : string;

  // Amount of the balance
  balance_value : Amount;

}

1.6.5.2. Historic Denomination Revenue ¶

This endpoint is used to obtain a list of historic denomination revenue, that is the profits and losses an exchange has made from coins of a particular denomination where the denomination is past its (deposit) expiration and thus all values are final.

GET /monitoring/historic-denomination-revenue¶

Get a list of historic denomination revenue stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.

With the default settings, the endpoint returns at most the 20 latest elements.

Response:

200 OK:: The auditor responds with a top level array of HistoricDenominationRevenue objects. If no elements could be found, an empty array is returned

Details:

interface HistoricDenominationRevenue {

  // Unique row identifier
  row_id : Integer;

  // Hash code of the denomination public key involved
  denom_pub_hash : HashCode;

  // Time when the denomination expired and thus the revenue
  // was computed.
  revenue_timestamp : Timestamp;

  // Total fee revenue the exchange earned from coins of this
  // denomination.
  revenue_balance : Amount;

  // Total losses the exchange experienced from this denomination
  // (this basically only happens if someone was able to forge
  // denomination signatures). So non-zero values are indicative
  // of a serious problem.
  loss_balance : Amount;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.5.3. Denomination Pending ¶

This endpoint is used to obtain a list of balances for denominations that are still active, that is coins may still be deposited (or possibly even withdrawn) and thus the amounts given are not final.

GET /monitoring/denomination-pending¶

Get a list of denomination pending stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.

With the default settings, the endpoint returns at most the 20 latest elements.

Response:

200 OK:: The auditor responds with a top level array of DenominationPending objects. If no elements could be found, an empty array is returned

Details:

interface DenominationPending {

  // Unique row identifier
  row_id : Integer;

  // Hash of the denomination public key
  denom_pub_hash : HashCode;

  // Total value of coins remaining in circulation (excluding
  // the value of coins that were recouped, those are always
  // just under recoup_loss).
  denom_balance : Amount;

  // Total value of coins redeemed that exceeds the amount we
  // put into circulation. Basically, this value grows if we
  // wanted to reduce denom_balance (because a coin was deposited)
  // but we could not because the denom_balance was already zero.
  denom_loss : Amount;

  // Total number of coins of this denomination that were
  // put into circulation.
  num_issued : Integer;

  // Total value of the coins put into circulation.
  denom_risk : Amount;

  // Losses the exchange had from this denomination due to coins
  // that were recouped (after the denomination was revoked).
  recoup_loss : Amount;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.5.4. Historic Reserve Summary ¶

This section summarizes historic profits an exchange made from reserves and associated reserve-specific fees.

GET /monitoring/historic-reserve-summary¶

Get a list of historic reserve summary stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.

With the default settings, the endpoint returns at most the 20 latest elements.

Response:

200 OK:: The auditor responds with a top level array of HistoricReserveSummary objects. If no elements could be found, an empty array is returned

Details:

interface HistoricReserveSummary {

  // Unique row identifier
  row_id : Integer;

  // From when the summary starts
  start_date : Timestamp;

  // When the summary ends
  end_date : Timestamp;

  // Profits the exchange charged for the reserve
  reserve_profits : Amount;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.5.5. Reserves ¶

This endpoint is used to obtain a list of open reserves that the auditor is currently tracking balances for.

GET /monitoring/reserves¶

Get a list of reserves stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.

With the default settings, the endpoint returns at most the 20 latest elements.

Response:

200 OK:: The auditor responds with a top level array of Reserves objects. If no elements could be found, an empty array is returned

Details:

interface Reserves {

  // Unique row identifier
  auditor_reserves_rowid : Integer;

  // Public key of the reserve
  reserve_pub : EddsaPublicKey;

  // Amount in the balance
  reserve_balance : Amount;

  // Reserve losses are incurred if (a) a reserve is
  // incorrectly credited from a recoup for a non-revoked
  // coin, or (b) if the exchange allowed more digital cash
  // to be withdrawn from a reserve than the balance of the
  // reserve should have permitted.  FIXME: We may want to
  // distinguish these two cases in the future.
  reserve_loss : Amount;

  // Amount earned by charging withdraw fees
  withdraw_fee_balance : Amount;

  // Amount earned by charging a closing fee on the reserve
  close_fee_balance : Amount;

  // Total purse fees earned from this reserve
  purse_fee_balance : Amount;

  // Total reserve open fees earned from the reserve
  open_fee_balance : Amount;

  // Total reserve history fees earned from this reserve
  history_fee_balance : Amount;

  // When the purse expires
  expiration_date : Timestamp;

  // Who created the account
  origin_account : string;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.5.6. Purses ¶

This endpoint is used to obtain information about open purses.

GET /monitoring/purses¶

Get a list of purses stored by the auditor.

The following query parameters are optional, and can be used to customise the response:

Request:

Query Parameters:

limit – A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20.
offset – An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.

With the default settings, the endpoint returns at most the 20 latest elements.

Response:

200 OK:: The auditor responds with a top level array of Purses objects. If no elements could be found, an empty array is returned

Details:

interface Purses {

  // Unique row identifier
  auditor_purses_rowid : Integer;

  // Public key of the purse
  purse_pub : EddsaPublicKey;

  // Amount currently stored in the purse
  balance : Amount;

  // Amount the purse is intended for / the maximum amount that can be in the purse
  target : Amount;

  // When the purse expires
  expiration_date : Timestamp;

}

Note

This endpoint is still experimental. The endpoint will be further developed as needed.

1.6.5.7. Progress ¶

This section contains information about the auditing progress an auditor has made.

GET /monitoring/progress¶

Get the progress stored by the auditor.

Request:

Query Parameters:

progress_key – a string identifying a progress point. If specified, only returns the element with this exact key. The default value is NULL.

Response:

200 OK:: The auditor responds with a top level array of Progress objects. If no elements could be found, an empty array is returned

Details:

interface Progress {

  // Key associated with a given progress point
  progress_key: string;

  // How much of the exchanges data has been processed so far
  progress_offset: Integer;

}

1.6.6. Complaints ¶

This endpoint 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 misbehavior to the auditor.

1.5. Wallet-Core API Documentation

1.7. Backup and Synchronization RESTful API

GNU Taler

1.6. The Auditor RESTful JSON API¶