.. This file is part of GNU TALER. Copyright (C) 2018-2024 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 2.1, or (at your option) any later version. TALER is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with TALER; see the file COPYING. If not, see @author Christian Grothoff ============================ The Auditor RESTful JSON API ============================ The API specified here follows the :ref:`general conventions ` for all details not specified in the individual requests. The `glossary `_ defines all specific terms used in this section. .. contents:: Table of Contents :local: .. _authentication: -------------- 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. .. _auditor-version: ------------------------- 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. .. http:get:: /config Get the protocol version and some meta data about the auditor. This specification corresponds to ``current`` protocol being version **1**. **Response:** :http:statuscode:`200 OK`: The auditor responds with an `AuditorVersion`_ object. This request should virtually always be successful. **Details:** .. _AuditorVersion: .. code-block:: tsref 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). .. _deposit-confirmation: --------------------- 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. .. http: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:** :http:statuscode:`200 Ok`: The auditor responds with a `DepositAudited` object. This request should virtually always be successful. :http:statuscode:`403 Forbidden`: The signature on the deposit confirmation is invalid. :http:statuscode:`410 Gone`: The public key used to sign the deposit confirmation was revoked. **Details:** .. ts:def:: DepositAudited interface DepositAudited { // TODO: maybe change to ``204 No content`` instead? } .. ts:def:: DepositConfirmation 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. .. _auditor-monitoring-spa-api: -------------- 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 :ts:type:`GenericAuditorMonitorPatchRequest` object is used in the respective PATCH request. **Details:** .. ts:def:: GenericAuditorMonitorPatchRequest interface GenericAuditorMonitorPatchRequest { // If true, subsequent GET requests will not return this element by default suppressed : boolean; } .. _fee-time-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`FeeTimeInconsistency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: FeeTimeInconsistency 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. .. http: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:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _emergency-list: 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). .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`Emergency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: Emergency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _emergency-by-count-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`EmergencyByCount` objects. **Details:** .. ts:def:: EmergencyByCount 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Request:** The body must be a `GenericAuditorMonitorPatchRequest`. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _row-inconsistency-list: 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'. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`RowInconsistency` objects. **Details:** .. ts:def:: RowInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _reserve-in-inconsistency-list: 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). .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`ReserveInInconsistency` objects. **Details:** .. ts:def:: ReserveInInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _purse-not-closed-inconsistencies-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`PurseNotClosedInconsistencies` objects. **Details:** .. ts:def:: PurseNotClosedInconsistencies 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _reserve-not-closed-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`ReserveNotClosedInconsistency` objects. **Details:** .. ts:def:: ReserveNotClosedInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _reserve-balance-insufficient-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`ReserveBalanceInsufficientInconsistency` objects. **Details:** .. ts:def:: ReserveBalanceInsufficientInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _invalid-signature-losses-list: 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). .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false. :query operation: A string. If specified, only returns eligible rows with this :ts:type:`BadSigLosses`.operation value. The default value is NULL which means to not filter by operation. :query op_spec_pub: An EddsaPublicKey (in base32 encoding). If given, use its value to only return rows with this :ts:type:`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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`BadSigLosses` objects. **Details:** .. ts:def:: BadSigLosses 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _coin-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`CoinInconsistency` objects. **Details:** .. ts:def:: CoinInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _denominations-without-signatures-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`DenominationsWithoutSigs` objects. **Details:** .. ts:def:: DenominationsWithoutSigs 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _misattribution-in-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`MisattributionInInconsistency` objects. **Details:** .. ts:def:: MisattributionInInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _deposit-confirmations-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`DepositConfirmations` objects. **Details:** .. ts:def:: DepositConfirmations 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _denomination-key-validity-withdraw-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`DenominationKeyValidityWithdrawInconsistency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: DenominationKeyValidityWithdrawInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _amount-arithmetic-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`AmountArithmeticInconsistency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: AmountArithmeticInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _wire-format-inconsistency-list: 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). .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`WireFormatInconsistency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: WireFormatInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _refreshes-hanging-list: 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). .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`RefreshesHanging` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: RefreshesHanging 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _closure-lags-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`ClosureLags` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: ClosureLags 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; // 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _wire-out-inconsistency-list: Wire Out Inconsistencies ------------------------ This section highlights cases where the exchange wired a different amount to a destimation account than the auditor expected. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`WireOutInconsistency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: WireOutInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _reserve-balance-summary-wrong-inconsistency-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`ReserveBalanceSummaryWrongInconsistency` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: ReserveBalanceSummaryWrongInconsistency 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. .. _row-minor-inconsistencies-list: 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). .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`RowMinorInconsistencies` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: RowMinorInconsistencies 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. .. http: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 :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. **Response:** :http:statuscode:`204 No Content`: The element has been updated. .. note:: This endpoint is still experimental. The endpoint will be further developed as needed. ------------------------- 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. .. _balances-list: Balances -------- Returns the various balances the auditor tracks for the exchange, such as coins in circulation, fees earned, losses experienced, etc. .. http: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 balance_key: a string identifying a balance. If specified, only returns the balance with this exact key. The default value is NULL. **Response:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`Balances` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: Balances interface Balances { // String identifying a balance balance_key : string; // Amount of the balance balance_value : Amount; } .. _historic-denomination-revenue-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`HistoricDenominationRevenue` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: HistoricDenominationRevenue 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. .. _denomination-pending-list: 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. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`DenominationPending` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: DenominationPending 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. .. _historic-reserve-summary-list: Historic Reserve Summary ------------------------ This section summarizes historic profits an exchange made from reserves and associated reserve-specific fees. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`HistoricReserveSummary` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: HistoricReserveSummary 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. .. _reserves-list: Reserves -------- This endpoint is used to obtain a list of open reserves that the auditor is currently tracking balances for. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`Reserves` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: Reserves 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. .. _purses-list: Purses ------ This endpoint is used to obtain information about open purses. .. http: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 limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. :query 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:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`Purses` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: Purses 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. .. _progress-list: Progress -------- This section contains information about the auditing progress an auditor has made. .. http:get:: /monitoring/progress Get the progress stored by the auditor. **Request:** :query progress_key: a string identifying a progress point. If specified, only returns the element with this exact key. The default value is NULL. **Response:** :http:statuscode:`200 OK`: The auditor responds with a top level array of :ts:type:`Progress` objects. If no elements could be found, an empty array is returned **Details:** .. ts:def:: Progress 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; } ---------- 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. .. http:put:: /complain Complain about misbehavior to the auditor.