commit d1759de4fb97c8b0754f7f81ae1348782c193e50
parent ea54375ab9194a9b95691aacad4e42a631dda67c
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 2 Jun 2024 21:56:02 +0200
review auditor API
Diffstat:
| M | core/api-auditor.rst | | | 755 | ++++++++++++++++++++++++++++++++++++++++--------------------------------------- |
1 file changed, 387 insertions(+), 368 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -206,43 +206,42 @@ paid out first.
should sign the response information.
-.. _spa-api:
+.. _auditor-monitoring-spa-api:
----------------------------
+--------------
Monitoring API
----------------------------
+--------------
-The following entries specify how to access the results of an audit.
+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:`GenericUpdate` object may be used.
+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:: GenericUpdate
+ .. ts:def:: GenericAuditorMonitorPatchRequest
- interface GenericUpdate {
+ interface GenericAuditorMonitorPatchRequest {
- // if true, subsequent GET requests will not this element by default
- suppressed : boolean;
-
- // unused
- ancient? : boolean;
-
- }
+ // If true, subsequent GET requests will not return this element by default
+ suppressed : boolean;
+ }
-.. fee-time-inconsistency-list:
+.. _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 a start date of a fee is set to a later date than its end date.
-
-#FIXME: this might be inaccurate
+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
@@ -255,14 +254,13 @@ This usually means that a start date of a fee is set to a later date than its en
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ 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` objecs.
+ The auditor responds with a top level array of :ts:type:`FeeTimeInconsistency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -276,18 +274,21 @@ This usually means that a start date of a fee is set to a later date than its en
interface FeeTimeInconsistency {
-
- row_id : Integer;
+ // Row ID of the fee in the exchange database.
+ row_id : Integer;
- type : string;
+ // Specifies the wire method for which the fee is inconsistent.
+ type : string;
- time : Timestamp;
+ // Gives the start date of the inconsistent fee.
+ time : Timestamp;
- diagnostic : string;
+ // Human readable description of the problem.
+ diagnostic : string;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
-
}
.. note::
@@ -296,12 +297,15 @@ This usually means that a start date of a fee is set to a later date than its en
+.. http:patch:: /monitoring/fee-time-inconsistency/$SERIAL_ID
-This API is used to suppress select elements of fee time inconsistencies
+ 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``.
-.. http:patch:: /monitoring/fee-time-inconsistency/$SERIAL_ID
+ **Request:**
- Update the 'suppressed' field of a fee time inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ The body must be a `GenericAuditorMonitorPatchRequest`.
**Response:**
@@ -311,11 +315,10 @@ This API is used to suppress select elements of fee time inconsistencies
.. note::
This API is still experimental. The API will be further developed as needed.
+ FIMXE: we usually simply return 204 No Content on success for such APIs.
-
-
-.. emergency-by-count-list:
+.. _emergency-by-count-list:
Emergencies By Count
--------------------
@@ -333,6 +336,12 @@ 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.
@@ -344,9 +353,9 @@ compromise.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -365,26 +374,37 @@ compromise.
interface EmergencyByCount {
-
- row_id : Integer;
+ // Row ID of the fee in the exchange database.
+ row_id : Integer;
- denompub_h : HashCode;
+ // Hash of the public denomination key to which the
+ // emergency applies.
+ denompub_h : HashCode;
- num_issued : Integer;
+ // Number of coins the exchange officially issued of this
+ // denomination.
+ num_issued : Integer;
- num_known : Integer;
+ // Number of coins that were redeemed.
+ num_known : Integer;
- risk : Amount;
+ // 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;
- start : Timestamp;
+ // When did the exchange start issuing coins in this the denomination.
+ start : Timestamp;
- deposit_end : Timestamp;
+ // When does the deposit period end for coins of this denomination.
+ deposit_end : Timestamp;
- value : Amount;
+ // What is the value of an individual coin of this denomination.
+ value : Amount;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
-
}
.. note::
@@ -392,13 +412,16 @@ compromise.
This API is still experimental. The API will be further developed as needed.
+.. http:patch:: /monitoring/emergency-by-count/$SERIAL_ID
+ This API 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.
-This API is used to suppress select elements of emergencies by count
-
-.. http:patch:: /monitoring/emergency-by-count/$SERIAL_ID
+ **Request:**
- Update the 'suppressed' field of an emergency by count element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ The body must be a `GenericAuditorMonitorPatchRequest`.
**Response:**
@@ -408,23 +431,21 @@ This API is used to suppress select elements of emergencies by count
.. note::
This API is still experimental. The API will be further developed as needed.
+ FIMXE: we usually simply return 204 No Content on success for such APIs.
-
-
-.. row-inconsistency-list:
+.. _row-inconsistency-list:
Row Inconsistencies
-------------------
-This section highlights serious row inconsistencies of the exchange.
-Row inconsistencies are reported from different sources,
-and might point data that is (suddenly) missing from the exchange, or has been manipulated in
-illogical ways. The affected table is noted in the 'table' field. A description of the nature of the
-inconsistency is noted in 'diagnostic'.
-
-#FIXME: this might be inaccurate
-
+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
@@ -437,9 +458,8 @@ inconsistency is noted in 'diagnostic'.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -458,16 +478,18 @@ inconsistency is noted in 'diagnostic'.
interface RowInconsistency {
-
- row_id : Integer;
+ // Number of the affected row.
+ row_id : Integer;
- row_table : string;
+ // Name of the affected exchange table.
+ row_table : string;
- diagnostic : string;
+ // Human-readable diagnostic about what went wrong.
+ diagnostic : string;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
-
}
.. note::
@@ -481,7 +503,7 @@ This API is used to suppress select elements of row inconsistencies
.. http:patch:: /monitoring/row-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a row inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a row inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -500,10 +522,13 @@ This API is used to suppress select elements of row inconsistencies
Reserve In Inconsistencies
--------------------------
-This section lists cases where the exchange's and auditor's expectation of amounts transerred
-into a reserve differs.
-
-#FIXME: not sure if this is accurate
+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
@@ -516,9 +541,9 @@ into a reserve differs.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -537,24 +562,22 @@ into a reserve differs.
interface ReserveInInconsistency {
-
- row_id : Integer;
+ row_id : Integer;
- amount_exchange_expected : Amount;
+ amount_exchange_expected : Amount;
- amount_wired : Amount;
+ amount_wired : Amount;
- reserve_pub : EddsaPublicKey;
+ reserve_pub : EddsaPublicKey;
- timestamp : Timestamp;
+ timestamp : Timestamp;
- account : string;
+ account : string;
- diagnostic : string;
+ diagnostic : string;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -562,13 +585,11 @@ into a reserve differs.
This API is still experimental. The API will be further developed as needed.
-
-
This API is used to suppress select elements of reserve in inconsistencies
.. http:patch:: /monitoring/reserve-in-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a reserve in inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -580,17 +601,17 @@ This API is used to suppress select elements of reserve in inconsistencies
This API is still experimental. The API will be further developed as needed.
-
-
-.. purse-not-closed-inconsistencies-list:
+.. _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 transaction,
-causing a purse – which may contain some currency – to expire.
-
-#FIXME: this might be inaccurate
+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
@@ -604,9 +625,8 @@ causing a purse – which may contain some currency – to expire.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -625,18 +645,16 @@ causing a purse – which may contain some currency – to expire.
interface PurseNotClosedInconsistencies {
-
- row_id : Integer;
+ row_id : Integer;
- purse_pub : EddsaPublicKey;
+ purse_pub : EddsaPublicKey;
- amount : Amount;
+ amount : Amount;
- expiration_date : Timestamp;
+ expiration_date : Timestamp;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -644,13 +662,12 @@ causing a purse – which may contain some currency – to expire.
This API is still experimental. The API will be further developed as needed.
-
-
-This API is used to suppress select elements of purse not closed inconsistencies
-
.. http:patch:: /monitoring/purse-not-closed-inconsistencies/$SERIAL_ID
- Update the 'suppressed' field of a purse not closed inconsistencies element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -664,12 +681,15 @@ This API is used to suppress select elements of purse not closed inconsistencies
-.. reserve-not-closed-inconsistency-list:
+.. _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
@@ -682,9 +702,8 @@ This section highlights cases, in which reserves were not closed, despite being
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -703,20 +722,18 @@ This section highlights cases, in which reserves were not closed, despite being
interface ReserveNotClosedInconsistency {
-
- row_id : Integer;
+ row_id : Integer;
- reserve_pub : EddsaPublicKey;
+ reserve_pub : EddsaPublicKey;
- balance : Amount;
+ balance : Amount;
- expiration_time : Timestamp;
+ expiration_time : Timestamp;
- diagnostic : string;
+ diagnostic : string;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -726,11 +743,12 @@ This section highlights cases, in which reserves were not closed, despite being
-This API is used to suppress select elements of reserve not closed inconsistencies
-
.. http:patch:: /monitoring/reserve-not-closed-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a reserve not closed inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -744,7 +762,7 @@ This API is used to suppress select elements of reserve not closed inconsistenci
-.. reserve-balance-insufficient-inconsistency-list:
+.. _reserve-balance-insufficient-inconsistency-list:
Reserve Balance Insufficient Inconsistencies
--------------------------------------------
@@ -753,8 +771,6 @@ 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.
-#FIXME: this might be inaccurate
-
.. http:get:: /monitoring/reserve-balance-insufficient-inconsistency
Get a list of reserve balance insufficient inconsistencies stored by the auditor.
@@ -766,9 +782,9 @@ compromise resulting in proportional financial losses to the exchange.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -787,18 +803,16 @@ compromise resulting in proportional financial losses to the exchange.
interface ReserveBalanceInsufficientInconsistency {
-
- row_id : Integer;
+ row_id : Integer;
- reserve_pub : EddsaPublicKey;
+ reserve_pub : EddsaPublicKey;
- inconsistency_gain : boolean;
+ inconsistency_gain : boolean;
- inconsistency_amount : Amount;
+ inconsistency_amount : Amount;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -808,11 +822,13 @@ compromise resulting in proportional financial losses to the exchange.
-This API is used to suppress select elements of reserve balance insufficient inconsistencies
.. http:patch:: /monitoring/reserve-balance-insufficient-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a reserve balance insufficient inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -824,16 +840,15 @@ This API is used to suppress select elements of reserve balance insufficient inc
This API is still experimental. The API will be further developed as needed.
-
-
-.. invalid-signature-losses-list:
+.. _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 were
-invalid and the amount involved should be considered lost.
+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
@@ -846,11 +861,10 @@ invalid and the amount involved should be considered lost.
: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.
+ :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 operaiton.
:query use_op_spec_pub: A boolean. If true, use the value of :ts:type:`OpSpecPub` to only return eligible rows with this :ts:type:`BadSigLosses`.operation_specific_pub value. The default value is NULL.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -869,18 +883,16 @@ invalid and the amount involved should be considered lost.
interface BadSigLosses {
-
- row_id : Integer;
+ row_id : Integer;
- operation : string;
+ operation : string;
- loss : Amount;
+ loss : Amount;
- operation_specific_pub : EddsaPublicKey;
+ operation_specific_pub : EddsaPublicKey;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -888,13 +900,12 @@ invalid and the amount involved should be considered lost.
This API is still experimental. The API will be further developed as needed.
-
-
-This API is used to suppress select elements of bad sig losses
-
.. http:patch:: /monitoring/bad-sig-losses/$SERIAL_ID
- Update the 'suppressed' field of a bad sig losses element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -906,9 +917,7 @@ This API is used to suppress select elements of bad sig losses
This API is still experimental. The API will be further developed as needed.
-
-
-.. coin-inconsistency-list:
+.. _coin-inconsistency-list:
Coin Inconsistencies
--------------------
@@ -930,9 +939,9 @@ any effects on its own balance, those entries are excluded from the total.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -951,22 +960,20 @@ any effects on its own balance, those entries are excluded from the total.
interface CoinInconsistency {
-
- row_id : Integer;
+ row_id : Integer;
- operation : string;
+ operation : string;
- exchange_amount : Amount;
+ exchange_amount : Amount;
- auditor_amount : Amount;
+ auditor_amount : Amount;
- coin_pub : EddsaPublicKey;
+ coin_pub : EddsaPublicKey;
- profitable : boolean;
+ profitable : boolean;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -974,13 +981,12 @@ any effects on its own balance, those entries are excluded from the total.
This API is still experimental. The API will be further developed as needed.
-
-
-This API is used to suppress select elements of coin inconsistencies
-
.. http:patch:: /monitoring/coin-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a coin inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -992,19 +998,25 @@ This API is used to suppress select elements of coin inconsistencies
This API is still experimental. The API will be further developed as needed.
-
-
-.. balances-list:
+.. _balances-list:
Balances
--------
-Unlike many other sections of the auditor, entries in the balances table do not necessarily represent misbehaviour
-or unusual findings. Instead, the auditor keeps its own record of the current balances of purses, to compare them with the
-purse balances.
+Unlike many other sections of the auditor, entries in the balances table do
+not necessarily represent misbehaviour or unusual findings. Instead, the
+auditor keeps its own record of the current balances of purses, to compare
+them with the purse balances.
+
+# FIXME: if this is the *new* balances table, it has nothing to do with
+# just *purses*. Also, it makes no sense to apply *suppression* to this
+# table!!! Plus, we probably want this endpoint in a different section,
+# balances are like the progress points something for the global
+# dashboard, not for incidents!
#FIXME: this might be inaccurate
+
.. http:get:: /monitoring/balances
Get a list of balances stored by the auditor.
@@ -1019,7 +1031,7 @@ purse balances.
:query balance_key: a string identifying a balance. If specified, only returns elements with this exact key. The default value is NULL.
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1038,16 +1050,14 @@ purse balances.
interface Balances {
-
- row_id : Integer;
+ row_id : Integer;
- balance_key : string;
+ balance_key : string;
- balance_value : Amount;
+ balance_value : Amount;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -1059,9 +1069,15 @@ purse balances.
This API is used to suppress select elements of balances
+# FIXME: this endpoint makes no sense!
+# However, you MAY want a
+# GET /monitoring/balances/$BALANCE_KEY endpoint
+# to only return a *specific* balance instead of
+# all of them.
+
.. http:patch:: /monitoring/balances/$SERIAL_ID
- Update the 'suppressed' field of a balances element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a balances element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1073,15 +1089,13 @@ This API is used to suppress select elements of balances
This API is still experimental. The API will be further developed as needed.
-
-
-.. denominations-without-signatures-list:
+.. _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
+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
@@ -1098,9 +1112,9 @@ business situation.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1119,20 +1133,18 @@ business situation.
interface DenominationsWithoutSigs {
-
- row_id : Integer;
+ row_id : Integer;
- denompub_h : HashCode;
+ denompub_h : HashCode;
- value : Amount;
+ value : Amount;
- start_time : Timestamp;
+ start_time : Timestamp;
- end_time : Timestamp;
+ end_time : Timestamp;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -1141,12 +1153,12 @@ business situation.
-
-This API is used to suppress select elements of denominations without sigs
-
.. http:patch:: /monitoring/denominations-without-sigs/$SERIAL_ID
- Update the 'suppressed' field of a denominations without signatures element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -1158,20 +1170,15 @@ This API is used to suppress select elements of denominations without sigs
This API is still experimental. The API will be further developed as needed.
-
-
-.. misattribution-in-inconsistency-list:
+.. _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 will cause funds to be sent to the wrong account when the reserve
-is closed and the remaining balance is refunded to the original
-account.
-
-#FIXME: not sure if this is accurate
+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
@@ -1184,9 +1191,9 @@ account.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1205,18 +1212,16 @@ account.
interface MisattributionInInconsistency {
-
- row_id : Integer;
+ row_id : Integer;
- amount : Amount;
+ amount : Amount;
- bank_row : Integer;
+ bank_row : Integer;
- reserve_pub : EddsaPublicKey;
+ reserve_pub : EddsaPublicKey;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -1225,12 +1230,12 @@ account.
-
-This API is used to suppress select elements of misattribution in inconsistencies
-
.. http:patch:: /monitoring/misattribution-in-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of an misattribution in inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -1241,15 +1246,19 @@ This API is used to suppress select elements of misattribution in inconsistencie
This API is still experimental. The API will be further developed as needed.
-.. reserves-list:
-
+.. _reserves-list:
Reserves
--------
-This API is used to obtain a list of reserves
+This API is used to obtain a list of reserves
+
+FIXME: like the /monitoring/balances API, this endpoint returns status
+information about an exchange that is not at all indicative of an error. It
+should thus be moved into another section (and there is again no point in
+having the suppression capability here!).
#FIXME: this is missing some information
@@ -1263,10 +1272,10 @@ This API is used to obtain a list of reserves
: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 return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false. FIXME: instead of a suppression filter, it would be useful to filter reserves with a balance of zero *or* below a certain threshold (default: minimum denomination unit?).
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1285,32 +1294,30 @@ This API is used to obtain a list of reserves
interface Reserves {
-
- auditor_reserves_rowid : Integer;
+ auditor_reserves_rowid : Integer;
- reserve_pub : EddsaPublicKey;
+ reserve_pub : EddsaPublicKey;
- reserve_balance : Amount;
+ reserve_balance : Amount;
- reserve_loss : Amount;
+ reserve_loss : Amount;
- withdraw_fee_balance : Amount;
+ withdraw_fee_balance : Amount;
- close_fee_balance : Amount;
+ close_fee_balance : Amount;
- purse_fee_balance : Amount;
+ purse_fee_balance : Amount;
- open_fee_balance : Amount;
+ open_fee_balance : Amount;
- history_fee_balance : Amount;
+ history_fee_balance : Amount;
- expiration_date : Timestamp;
+ expiration_date : Timestamp;
- origin_account : string;
+ origin_account : string;
- suppressed : boolean;
+ suppressed : boolean;
-
}
.. note::
@@ -1322,9 +1329,11 @@ This API is used to obtain a list of reserves
This API is used to suppress select elements of reserves
+FIXME: this makes no sense.
+
.. http:patch:: /monitoring/reserves/$SERIAL_ID
- Update the 'suppressed' field of an reserves element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of an reserves element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1336,15 +1345,24 @@ This API is used to suppress select elements of reserves
This API is still experimental. The API will be further developed as needed.
-
-
-.. deposit-confirmations-list:
+.. _deposit-confirmations-list:
Deposit Confirmations
---------------------
-This section contains a list of deposits the merchant made to the exchange, provided by a merchant.
-This list can be cross-referenced with the exchanges deposits; any discrepancies could be a sign of misbehaviour.
+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
@@ -1357,9 +1375,8 @@ This list can be cross-referenced with the exchanges deposits; any discrepancies
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1378,40 +1395,40 @@ This list can be cross-referenced with the exchanges deposits; any discrepancies
interface DepositConfirmations {
-
- deposit_confirmation_serial_id : Integer;
+ deposit_confirmation_serial_id : Integer;
- h_contract_terms : HashCode;
+ h_contract_terms : HashCode;
- h_policy : HashCode;
+ h_policy : HashCode;
- h_wire : HashCode;
+ h_wire : HashCode;
- exchange_timestamp : Timestamp;
+ exchange_timestamp : Timestamp;
- refund_deadline : Timestamp;
+ refund_deadline : Timestamp;
- wire_deadline : Timestamp;
+ wire_deadline : Timestamp;
- total_without_fee : Amount;
+ total_without_fee : Amount;
- coin_pubs : EddsaPublicKey;
+ // FIXME: is this correct? Not an array?
+ coin_pubs : EddsaPublicKey;
- coin_sigs : EddsaSignature;
+ // FIXME: is this correct? Not an array?
+ coin_sigs : EddsaSignature;
- merchant_pub : EddsaPublicKey;
+ merchant_pub : EddsaPublicKey;
- exchange_sig : EddsaSignature;
+ exchange_sig : EddsaSignature;
- exchange_pub : EddsaPublicKey;
+ exchange_pub : EddsaPublicKey;
- master_sig : EddsaSignature;
+ master_sig : EddsaSignature;
- suppressed : boolean;
+ suppressed : boolean;
- ancient : boolean;
+ ancient : boolean;
-
}
.. note::
@@ -1420,12 +1437,12 @@ This list can be cross-referenced with the exchanges deposits; any discrepancies
-
-This API is used to suppress select elements of deposit confirmations
-
.. http:patch:: /monitoring/deposit-confirmations/$SERIAL_ID
- Update the 'suppressed' field of an deposit confirmations element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ This API 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:**
@@ -1437,13 +1454,15 @@ This API is used to suppress select elements of deposit confirmations
This API is still experimental. The API will be further developed as needed.
+# FIXME-CG: review from here...
+
.. denomination-key-validity-withdraw-inconsistency-list:
Denomination Key Validity Withdraw Inconsistencies
--------------------------------------------------
-This section highlights cases, where denomination keys were used to withdraw coins from a reserve,
-after they were already expired.
+This section highlights cases, where denomination keys were used to withdraw coins from a reserve,
+after they were already expired.
#FIXME: this might be inaccurate
@@ -1458,9 +1477,9 @@ after they were already expired.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1479,7 +1498,7 @@ after they were already expired.
interface DenominationKeyValidityWithdrawInconsistency {
-
+
row_id : Integer;
execution_date : Timestamp;
@@ -1490,7 +1509,7 @@ after they were already expired.
suppressed : boolean;
-
+
}
.. note::
@@ -1504,7 +1523,7 @@ This API is used to suppress select elements of denomination key validity withdr
.. http:patch:: /monitoring/denomination-key-validity-withdraw-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a denomination key validity withdraw inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -1524,7 +1543,7 @@ Purses
------
This section highlights cases, in which a purses summary (balance) does
-not match the balance an exchange expects it to be.
+not match the balance an exchange expects it to be.
#FIXME: this might be inaccurate
@@ -1539,9 +1558,9 @@ not match the balance an exchange expects it to be.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1560,7 +1579,7 @@ not match the balance an exchange expects it to be.
interface Purses {
-
+
auditor_purses_rowid : Integer;
purse_pub : EddsaPublicKey;
@@ -1573,7 +1592,7 @@ not match the balance an exchange expects it to be.
suppressed : boolean;
-
+
}
.. note::
@@ -1587,7 +1606,7 @@ This API is used to suppress select elements of purses
.. http:patch:: /monitoring/purses/$SERIAL_ID
- Update the 'suppressed' field of a purses element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a purses element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1628,9 +1647,9 @@ the exchange.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1649,7 +1668,7 @@ the exchange.
interface AmountArithmeticInconsistency {
-
+
row_id : Integer;
operation : string;
@@ -1662,7 +1681,7 @@ the exchange.
suppressed : boolean;
-
+
}
.. note::
@@ -1676,7 +1695,7 @@ This API is used to suppress select elements of amount arithmetic inconsistencie
.. http:patch:: /monitoring/amount-arithmetic-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of an amount arithmetic inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -1710,9 +1729,9 @@ This API is used to obtain a list of historic denomination revenue
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1731,7 +1750,7 @@ This API is used to obtain a list of historic denomination revenue
interface HistoricDenominationRevenue {
-
+
denom_pub_hash : HashCode;
revenue_timestamp : Timestamp;
@@ -1742,7 +1761,7 @@ This API is used to obtain a list of historic denomination revenue
suppressed : boolean;
-
+
}
.. note::
@@ -1756,7 +1775,7 @@ This API is used to suppress select elements of historic denomination revenue
.. http:patch:: /monitoring/historic-denomination-revenue/$SERIAL_ID
- Update the 'suppressed' field of a historic denomination revenue element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a historic denomination revenue element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1790,9 +1809,9 @@ This API is used to obtain a list of denomination pending
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1811,7 +1830,7 @@ This API is used to obtain a list of denomination pending
interface DenominationPending {
-
+
denom_pub_hash : HashCode;
denom_balance : Amount;
@@ -1826,7 +1845,7 @@ This API is used to obtain a list of denomination pending
suppressed : boolean;
-
+
}
.. note::
@@ -1840,7 +1859,7 @@ This API is used to suppress select elements of denomination pending
.. http:patch:: /monitoring/denomination-pending/$SERIAL_ID
- Update the 'suppressed' field of a denomination pending element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a denomination pending element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1859,8 +1878,8 @@ This API is used to suppress select elements of denomination pending
Historic Reserve Summary
------------------------
-This section highlights cases, where the exchanges expectation of the summary in a reserve
-differs from its actual summary.
+This section highlights cases, where the exchanges expectation of the summary in a reserve
+differs from its actual summary.
#FIXME: this might be inaccurate
@@ -1875,9 +1894,9 @@ differs from its actual summary.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1896,7 +1915,7 @@ differs from its actual summary.
interface HistoricReserveSummary {
-
+
row_id : Integer;
start_date : Timestamp;
@@ -1905,7 +1924,7 @@ differs from its actual summary.
reserve_profits : Amount;
-
+
}
.. note::
@@ -1919,7 +1938,7 @@ This API is used to suppress select elements of historic reserve summary
.. http:patch:: /monitoring/historic-reserve-summary/$SERIAL_ID
- Update the 'suppressed' field of a historic reserve summary element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a historic reserve summary element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1953,9 +1972,9 @@ This API is used to obtain a list of exchange signkeys
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -1974,7 +1993,7 @@ This API is used to obtain a list of exchange signkeys
interface ExchangeSignkeys {
-
+
exchange_pub : EddsaPublicKey;
master_sig : EddsaSignature;
@@ -1987,7 +2006,7 @@ This API is used to obtain a list of exchange signkeys
suppressed : boolean;
-
+
}
.. note::
@@ -2001,7 +2020,7 @@ This API is used to suppress select elements of exchange signkeys
.. http:patch:: /monitoring/exchange-signkeys/$SERIAL_ID
- Update the 'suppressed' field of an exchange signkeys element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of an exchange signkeys element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2020,7 +2039,7 @@ This API is used to suppress select elements of exchange signkeys
Wire Format Inconsistencies
---------------------------
-This section highlights cases, where the format of a wire transaction was malformed in some way.
+This section highlights cases, where the format of a wire transaction was malformed in some way.
.. http:get:: /monitoring/wire-format-inconsistency
@@ -2033,9 +2052,9 @@ This section highlights cases, where the format of a wire transaction was malfor
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2054,7 +2073,7 @@ This section highlights cases, where the format of a wire transaction was malfor
interface WireFormatInconsistency {
-
+
row_id : Integer;
amount : Amount;
@@ -2065,7 +2084,7 @@ This section highlights cases, where the format of a wire transaction was malfor
suppressed : boolean;
-
+
}
.. note::
@@ -2079,7 +2098,7 @@ This API is used to suppress select elements of wire format inconsistencies
.. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a wire format inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -2100,7 +2119,7 @@ Refreshes Hanging
This section highlights cases, where refreshed (and then revealed) coins could not be found in an exchanges database.
This might happen, even if the exchange is operating correctly. In that case, the exchange might simply be slower than
-the auditor.
+the auditor.
#FIXME: this might be inaccurate
@@ -2115,9 +2134,9 @@ the auditor.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2136,7 +2155,7 @@ the auditor.
interface RefreshesHanging {
-
+
row_id : Integer;
amount : Amount;
@@ -2145,7 +2164,7 @@ the auditor.
suppressed : boolean;
-
+
}
.. note::
@@ -2159,7 +2178,7 @@ This API is used to suppress select elements of refreshes hanging
.. http:patch:: /monitoring/refreshes-hanging/$SERIAL_ID
- Update the 'suppressed' field of a refreshes hanging element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a refreshes hanging element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2189,7 +2208,7 @@ 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.
+compromise.
#FIXME: what is the difference between Emergencies and Emergencies by Count
@@ -2204,9 +2223,9 @@ compromise.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2225,7 +2244,7 @@ compromise.
interface Emergency {
-
+
row_id : Integer;
denompub_h : HashCode;
@@ -2240,7 +2259,7 @@ compromise.
value : Amount;
-
+
}
.. note::
@@ -2254,7 +2273,7 @@ This API is used to suppress select elements of emergencies
.. http:patch:: /monitoring/emergency/$SERIAL_ID
- Update the 'suppressed' field of an emergency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of an emergency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2293,9 +2312,9 @@ load. Small amounts of lag can occur in normal operation.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2314,7 +2333,7 @@ load. Small amounts of lag can occur in normal operation.
interface ClosureLags {
-
+
row_id : Integer;
amount : Amount;
@@ -2327,7 +2346,7 @@ load. Small amounts of lag can occur in normal operation.
suppressed : boolean;
-
+
}
.. note::
@@ -2341,7 +2360,7 @@ This API is used to suppress select elements of closure lags
.. http:patch:: /monitoring/closure-lags/$SERIAL_ID
- Update the 'suppressed' field of a closure lags element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ Update the 'suppressed' field of a closure lags element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2374,9 +2393,9 @@ outgoing wire transfers does not match with that of the bank.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2395,7 +2414,7 @@ outgoing wire transfers does not match with that of the bank.
interface WireOutInconsistency {
-
+
row_id : Integer;
destination_account : string;
@@ -2406,7 +2425,7 @@ outgoing wire transfers does not match with that of the bank.
suppressed : boolean;
-
+
}
.. note::
@@ -2420,7 +2439,7 @@ This API is used to suppress select elements of wire out inconsistencies
.. http:patch:: /monitoring/wire-out-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a wire out inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -2439,7 +2458,7 @@ This API is used to suppress select elements of wire out inconsistencies
Reserve Balance Summary Wrong Inconsistencies
---------------------------------------------
-This section highlights cases, where the exchange's and auditors'
+This section highlights cases, where the exchange's and auditors'
expectation of the amount of money in a reserve differs.
.. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency
@@ -2453,9 +2472,9 @@ expectation of the amount of money in a reserve differs.
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2474,7 +2493,7 @@ expectation of the amount of money in a reserve differs.
interface ReserveBalanceSummaryWrongInconsistency {
-
+
row_id : Integer;
reserve_pub : EddsaPublicKey;
@@ -2485,7 +2504,7 @@ expectation of the amount of money in a reserve differs.
suppressed : boolean;
-
+
}
.. note::
@@ -2499,7 +2518,7 @@ This API is used to suppress select elements of reserve balance summary wrong in
.. http:patch:: /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a reserve balance summary wrong inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
@@ -2518,7 +2537,7 @@ This API is used to suppress select elements of reserve balance summary wrong in
Row Minor Inconsistencies
-------------------------
-The section highlights inconsistencies, which are cause for concern,
+The section highlights inconsistencies, which are cause for concern,
but not necessarily point to a monetary loss (yet).
#FIXME: might not be accurate
@@ -2534,9 +2553,9 @@ but not necessarily point to a monetary loss (yet).
: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.
-
- The default values, thus, return at max the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
**Response:**
@@ -2555,7 +2574,7 @@ but not necessarily point to a monetary loss (yet).
interface RowMinorInconsistencies {
-
+
row_id : Integer;
row_table : Integer;
@@ -2564,7 +2583,7 @@ but not necessarily point to a monetary loss (yet).
suppressed : boolean;
-
+
}
.. note::
@@ -2578,7 +2597,7 @@ This API is used to suppress select elements of row minor inconsistencies
.. http:patch:: /monitoring/row-minor-inconsistencies/$SERIAL_ID
- Update the 'suppressed' field of a row minor inconsistencies element with row_id $SERIAL_ID, according to :ts:type:`GenericUpdate`, stored by the auditor.
+ 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:**
