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