commit 147196e36efa7b1c3af87b71c135586e83cf15b6
parent 938db656dd3aa2d2cec772440b1d5c8021d509b8
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 11 Jun 2024 16:09:12 +0200
address more FIXMEs
Diffstat:
| M | core/api-auditor.rst | | | 76 | +++++++++++++++++++++++++++++++++++----------------------------------------- |
1 file changed, 35 insertions(+), 41 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -704,7 +704,7 @@ properly.
:http:statuscode:`200 OK`:
The auditor responds with a top level array of :ts:type:`PurseNotClosedInconsistencies` objects.
-
+
**Details:**
@@ -782,7 +782,7 @@ process is not running properly.
:http:statuscode:`200 OK`:
The auditor responds with a top level array of :ts:type:`ReserveNotClosedInconsistency` objects.
-
+
**Details:**
@@ -865,7 +865,7 @@ compromise resulting in proportional financial losses to the exchange.
:http:statuscode:`200 OK`:
The auditor responds with a top level array of :ts:type:`ReserveBalanceInsufficientInconsistency` objects.
-
+
**Details:**
@@ -1107,7 +1107,7 @@ business situation.
:http:statuscode:`200 OK`:
The auditor responds with a top level array of :ts:type:`DenominationsWithoutSigs` objects.
-
+
**Details:**
@@ -1189,7 +1189,7 @@ balance, as that balance would be credited to the original account.
:http:statuscode:`200 OK`:
The auditor responds with a top level array of :ts:type:`MisattributionInInconsistency` objects.
-
+
**Details:**
@@ -1468,7 +1468,7 @@ to be optional. Are you sure this covers all cases?
: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:**
@@ -1707,7 +1707,7 @@ the **taler-exchange-closer** component is operating correctly.
: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:**
@@ -1743,7 +1743,7 @@ the **taler-exchange-closer** component is operating correctly.
.. http:patch:: /monitoring/closure-lags/$SERIAL_ID
- This endpoint is used to suppress select elements of closure lags.
+ 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:**
@@ -1786,7 +1786,7 @@ destimation account than the auditor expected.
: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:**
@@ -2000,7 +2000,7 @@ coins in circulation, fees earned, losses experienced, etc.
:query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX.
:query balance_key: a string identifying a balance. If specified, only returns elements with this exact key. The default value is NULL.
- With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements.
**Response:**
@@ -2050,7 +2050,7 @@ all values are final.
: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 that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements.
**Response:**
@@ -2083,9 +2083,6 @@ all values are final.
// of a serious problem.
loss_balance : Amount;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
-
}
.. note::
@@ -2112,7 +2109,7 @@ the amounts given are not final.
: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 that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements.
**Response:**
@@ -2131,31 +2128,28 @@ the amounts given are not final.
// Hash of the denomination public key
denom_pub_hash : HashCode;
- // Total value of the coins put into circulation.
- // FIXME-CG: double-check
+ // 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;
- // FIXME-CG: unclear
+ // 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
- // minus the amount that was recouped.
- // FIXME-CG: double-check
+ // 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).
- // FIXME-CG: double-check
recoup_loss : Amount;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
-
-
}
.. note::
@@ -2168,10 +2162,9 @@ the amounts given are not final.
Historic Reserve 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
+This section summarizes historic profits an exchange
+made from reserves and associated reserve-specific
+fees.
.. http:get:: /monitoring/historic-reserve-summary
@@ -2184,7 +2177,7 @@ 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.
- With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements.
**Response:**
@@ -2209,9 +2202,6 @@ differs from its actual summary.
// Profits the exchange charged for the reserve
reserve_profits : Amount;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
-
}
.. note::
@@ -2225,9 +2215,8 @@ differs from its actual summary.
Reserves
--------
-This endpoint is used to obtain a list of reserves
-
-#FIXME: this is missing some information
+This endpoint is used to obtain a list of open reserves that the auditor is
+currently tracking balances for.
.. http:get:: /monitoring/reserves
@@ -2239,9 +2228,9 @@ This endpoint 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.
-
- With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
+
+ With the default settings, the endpoint returns at most the 20 latest elements.
**Response:**
@@ -2264,7 +2253,12 @@ This endpoint is used to obtain a list of reserves
// Amount in the balance
reserve_balance : Amount;
- //FIMXE not sure
+ // 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
@@ -2313,7 +2307,7 @@ This endpoint is used to obtain information about open purses.
: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 that are not suppressed.
+ With the default settings, the endpoint returns at most the 20 latest elements.
**Response:**
