commit 08c0eac8280a4796b8f23459f57f58846b7aff76
parent 2b39474adc7c32826cec8d8afdba49bfa67293ae
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 4 Jun 2024 16:25:18 +0200
-more auditor API review
Diffstat:
| M | core/api-auditor.rst | | | 277 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
1 file changed, 149 insertions(+), 128 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -318,6 +318,118 @@ prevent such a fee configuration from being accepted.
FIMXE: we usually simply return 204 No Content on success for such APIs.
+
+.. _emergency-list:
+
+Emergencies
+-----------
+
+This API 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.
+
+ :http:statuscode:`403 Forbidden`:
+ No or bad Bearer token provided.
+
+ :http:statuscode:`404 Not Found`:
+ No elements could be found.
+
+ **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 API is still experimental. The API will be further developed as needed.
+
+
+
+
+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:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+
+ **Response:**
+
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
+
+ .. note::
+
+ This API is still experimental. The API will be further developed as needed.
+
+
+
+
.. _emergency-by-count-list:
Emergencies By Count
@@ -1499,7 +1611,7 @@ to be optional. Are you sure this covers all cases?
This API is still experimental. The API will be further developed as needed.
-
+FIXME
This API is used to suppress select elements of amount arithmetic inconsistencies
@@ -1517,16 +1629,17 @@ This API is used to suppress select elements of amount arithmetic inconsistencie
This API is still experimental. The API will be further developed as needed.
-
-
-
-
-.. wire-format-inconsistency-list:
+.. _wire-format-inconsistency-list:
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 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
@@ -1566,7 +1679,8 @@ This section highlights cases, where the format of a wire transaction was malfor
// Amount that was part of the wire
amount : Amount;
- #FIXME not sure
+ // 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.
@@ -1583,8 +1697,6 @@ This section highlights cases, where the format of a wire transaction was malfor
This API is still experimental. The API will be further developed as needed.
-
-
This API is used to suppress select elements of wire format inconsistencies
.. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID
@@ -1608,11 +1720,13 @@ This API is used to suppress select elements of wire format inconsistencies
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.
-
-#FIXME: this might be inaccurate
+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
@@ -1658,7 +1772,6 @@ the auditor.
// True if this diagnostic was suppressed.
suppressed : boolean;
-
}
.. note::
@@ -1666,8 +1779,6 @@ the auditor.
This API is still experimental. The API will be further developed as needed.
-
-
This API is used to suppress select elements of refreshes hanging
.. http:patch:: /monitoring/refreshes-hanging/$SERIAL_ID
@@ -1686,106 +1797,6 @@ This API is used to suppress select elements of refreshes hanging
-.. emergency-list:
-
-Emergencies
------------
-
-This API is used to obtain a list of emergencies.
-
-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.
-
-#FIXME: what is the difference between Emergencies and Emergencies by Count
-
-.. 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.
-
- :http:statuscode:`403 Forbidden`:
- No or bad Bearer token provided.
-
- :http:statuscode:`404 Not Found`:
- No elements could be found.
-
- **Details:**
-
- .. ts:def:: Emergency
-
- interface Emergency {
-
- // Unique row identifier
- row_id : Integer;
-
- // Hash of denomination public key
- denompub_h : HashCode;
-
- #FIXME not sure
- denom_risk : Amount;
-
- denom_loss : Amount;
-
- deposit_start : Timestamp;
-
- deposit_end : Timestamp;
-
- value : Amount;
-
- // True if this diagnostic was suppressed.
- suppressed : boolean;
-
-
- }
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-
-
-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:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
-
- **Response:**
-
- :http:statuscode:`204 No Content`:
- The element has been updated.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-
-
.. closure-lags-list:
Closure Lags
@@ -1793,13 +1804,16 @@ Closure Lags
This API is used to obtain a list of closure lags.
-Lag can be due to some component being behind in
-executing transactions. This is usually either the exchange's aggregator, the
-bank's wire transfer logic, or the synchronization of databases between
-exchange and auditor. Significant lag may be indicative of fraud, while
+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.
@@ -1835,19 +1849,22 @@ load. Small amounts of lag can occur in normal operation.
// Unique row identifier
row_id : Integer;
- # FIXME not sure
+ // Amount of money left in the reserve
amount : Amount;
+ // When should the reserve have been closed
deadline : Timestamp;
+ // FIXME: ???? Integer???
wtid : Integer;
+ // payto URI (RFC 8905) of the account that
+ // should have been credited.
account : string;
// True if this diagnostic was suppressed.
suppressed : boolean;
-
}
.. note::
@@ -1883,6 +1900,11 @@ Wire Out Inconsistencies
This section highlights cases where the exchange's record about
outgoing wire transfers does not match with that of the bank.
+FIXME: there were *two types* of wire-out-inconsistencies: one detected by the
+aggregation helper, and another one by the *wire* helper. The comment fits the
+one of the wire helper, but the API fits the one of the aggregation helper!
+Did you distinguish the two?
+
.. http:get:: /monitoring/wire-out-inconsistency
Get a list of wire out inconsistencies stored by the auditor.
@@ -1921,16 +1943,15 @@ outgoing wire transfers does not match with that of the bank.
// Account money was wired to
destination_account : string;
- // How much was suppossed to be wired
+ // How much was suppossed to be wired according to the auditor.
expected : Amount;
- # FIXME not sure
+ // The amount the exchange claims to have wired.
claimed : Amount;
// True if this diagnostic was suppressed.
suppressed : boolean;
-
}
.. note::
@@ -1956,7 +1977,7 @@ This API is used to suppress select elements of wire out inconsistencies
This API is still experimental. The API will be further developed as needed.
-
+FIXME-CG: review from here...
.. reserve-balance-summary-wrong-inconsistency-list:
