commit 65bffa85789339148b7e23e470f8c37267a10a91
parent cafc717a1ef3f8923967828d75593cec7aadcc02
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Thu, 6 Jun 2024 17:26:22 +0200
work on auditor API (WiP)
Diffstat:
| M | core/api-auditor.rst | | | 180 | ++++++++++++++++++++++++++++--------------------------------------------------- |
1 file changed, 63 insertions(+), 117 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -262,8 +262,6 @@ prevent such a fee configuration from being accepted.
: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
@@ -310,8 +308,6 @@ prevent such a fee configuration from being accepted.
This endpoint is still experimental. The endpoint will be further developed as needed.
-
-
.. _emergency-list:
Emergencies
@@ -356,8 +352,6 @@ numbers of coins (they may differ as coins may be partially deposited).
: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
@@ -412,9 +406,6 @@ numbers of coins (they may differ as coins may be partially deposited).
This endpoint is still experimental. The endpoint will be further developed as needed.
-
-
-
.. _emergency-by-count-list:
Emergencies By Count
@@ -457,9 +448,7 @@ auditor reports an emergency-by-count.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`EmergencyByCount` objecs.
-
-
+ The auditor responds with a top level array of :ts:type:`EmergencyByCount` objects.
**Details:**
@@ -504,7 +493,6 @@ auditor reports an emergency-by-count.
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.
@@ -556,9 +544,7 @@ if some signature fails to validate. The affected table is noted in the
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`RowInconsistency` objecs.
-
-
+ The auditor responds with a top level array of :ts:type:`RowInconsistency` objects.
**Details:**
@@ -599,9 +585,6 @@ if some signature fails to validate. The affected table is noted in the
This endpoint is still experimental. The endpoint will be further developed as needed.
-
-
-
.. _reserve-in-inconsistency-list:
Reserve In Inconsistencies
@@ -633,9 +616,7 @@ cash than they should be).
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`ReserveInInconsistency` objecs.
-
-
+ The auditor responds with a top level array of :ts:type:`ReserveInInconsistency` objects.
**Details:**
@@ -721,7 +702,7 @@ properly.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`PurseNotClosedInconsistencies` objecs.
+ The auditor responds with a top level array of :ts:type:`PurseNotClosedInconsistencies` objects.
@@ -799,7 +780,7 @@ process is not running properly.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`ReserveNotClosedInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`ReserveNotClosedInconsistency` objects.
@@ -882,7 +863,7 @@ compromise resulting in proportional financial losses to the exchange.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`ReserveBalanceInsufficientInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`ReserveBalanceInsufficientInconsistency` objects.
@@ -963,9 +944,7 @@ could successfully dispute the resulting transactions).
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`BadSigLosses` objecs.
-
-
+ The auditor responds with a top level array of :ts:type:`BadSigLosses` objects.
**Details:**
@@ -1041,9 +1020,7 @@ any effects on its own balance, those entries are excluded from the total.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`CoinInconsistency` objecs.
-
-
+ The auditor responds with a top level array of :ts:type:`CoinInconsistency` objects.
**Details:**
@@ -1128,7 +1105,7 @@ business situation.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`DenominationsWithoutSigs` objecs.
+ The auditor responds with a top level array of :ts:type:`DenominationsWithoutSigs` objects.
@@ -1210,7 +1187,7 @@ balance, as that balance would be credited to the original account.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`MisattributionInInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`MisattributionInInconsistency` objects.
@@ -1298,9 +1275,7 @@ replication from the exchange is working properly.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`DepositConfirmations` objecs.
-
-
+ The auditor responds with a top level array of :ts:type:`DepositConfirmations` objects.
**Details:**
@@ -1460,14 +1435,13 @@ 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.
+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.
FIXME: IIRC there **used to be** cases where we did not know if the
arithemtic issue was profitable or not. So the field probably needs
@@ -1565,7 +1539,6 @@ transfers).
: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:**
@@ -1573,7 +1546,6 @@ transfers).
: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:**
@@ -1621,9 +1593,6 @@ transfers).
This endpoint is still experimental. The endpoint will be further developed as needed.
-
-
-
.. _refreshes-hanging-list:
Refreshes Hanging
@@ -1657,8 +1626,6 @@ operation. If many operations are hanging, this might be indicative of a bug
: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
@@ -1796,9 +1763,8 @@ the **taler-exchange-closer** component is operating correctly.
Wire Out Inconsistencies
------------------------
-This section highlights cases where the exchange wired a different amount to a destimation account
-than the auditor expected.
-
+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
@@ -1868,15 +1834,13 @@ than the auditor expected.
This endpoint is still experimental. The endpoint will be further developed as needed.
-FIXME-CG: review from here...
-
.. _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 in a reserve differs.
+expectation of the amount of money left in a reserve differs.
.. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency
@@ -1890,7 +1854,6 @@ expectation of the amount of money in a reserve differs.
: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:**
@@ -1898,8 +1861,6 @@ expectation of the amount of money in a reserve differs.
: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
@@ -1921,7 +1882,6 @@ expectation of the amount of money in a reserve differs.
// True if this diagnostic was suppressed.
suppressed : boolean;
-
}
.. note::
@@ -1943,17 +1903,15 @@ expectation of the amount of money in a reserve differs.
This endpoint is still experimental. The endpoint will be further developed as needed.
-
-
.. _row-minor-inconsistencies-list:
Row Minor Inconsistencies
-------------------------
-The section highlights inconsistencies, which are cause for concern,
-but not necessarily point to a monetary loss (yet).
-
-#FIXME: might not be accurate
+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
@@ -1967,7 +1925,6 @@ but not necessarily point to a monetary loss (yet).
: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:**
@@ -1975,8 +1932,6 @@ but not necessarily point to a monetary loss (yet).
: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
@@ -1995,18 +1950,12 @@ but not necessarily point to a monetary loss (yet).
// 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.
@@ -2026,19 +1975,18 @@ but not necessarily point to a monetary loss (yet).
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.
+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
--------
-Contains a record of balances alongside the exchange.
-
-#FIXME: this might be inaccurate
-
+Returns the various balances the auditor tracks for the exchange, such as
+coins in circulation, fees earned, losses experienced, etc.
.. http:get:: /monitoring/balances
@@ -2052,7 +2000,6 @@ Contains a record of balances alongside the exchange.
: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.
**Response:**
@@ -2060,8 +2007,6 @@ Contains a record of balances alongside the exchange.
: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
@@ -2089,9 +2034,10 @@ Contains a record of balances alongside the exchange.
Historic Denomination Revenue
-----------------------------
-This endpoint is used to obtain a list of historic denomination revenue
-
-#FIXME: this is missing some information
+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
@@ -2103,7 +2049,6 @@ This endpoint 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.
-
With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
@@ -2112,8 +2057,6 @@ This endpoint is used to obtain a list of historic denomination revenue
: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
@@ -2126,19 +2069,23 @@ This endpoint is used to obtain a list of historic denomination revenue
// Hash code of the denomination public key involved
denom_pub_hash : HashCode;
- // #FIXME not sure
+ // Time when the denomination expired and thus the revenue
+ // was computed.
revenue_timestamp : Timestamp;
- //FIXME not sure
+ // Total fee revenue the exchange earned from coins of this
+ // denomination.
revenue_balance : Amount;
- //FIXME not sure
+ // 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;
// True if this diagnostic was suppressed.
suppressed : boolean;
-
}
.. note::
@@ -2150,9 +2097,9 @@ This endpoint is used to obtain a list of historic denomination revenue
Denomination Pending
--------------------
-This endpoint is used to obtain a list of denomination pending
-
-#FIXME: this is missing some information
+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
@@ -2164,7 +2111,6 @@ This endpoint 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.
-
With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed.
@@ -2173,8 +2119,6 @@ This endpoint is used to obtain a list of denomination pending
: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
@@ -2187,15 +2131,25 @@ This endpoint is used to obtain a list of denomination pending
// Hash of the denomination public key
denom_pub_hash : HashCode;
- //FIXME not sure
+ // Total value of the coins put into circulation.
+ // FIXME-CG: double-check
denom_balance : Amount;
+ // FIXME-CG: unclear
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
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.
@@ -2229,7 +2183,6 @@ 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.
@@ -2238,8 +2191,6 @@ differs from its actual summary.
: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
@@ -2322,11 +2273,13 @@ This endpoint is used to obtain a list of reserves
// Amount earned by charging a closing fee on the reserve
close_fee_balance : Amount;
- //FIXME not sure
+ // 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
@@ -2347,9 +2300,7 @@ This endpoint is used to obtain a list of reserves
Purses
------
-This section is used to obtain a list of purses.
-
-#FIXME: this might be inaccurate
+This endpoint is used to obtain information about open purses.
.. http:get:: /monitoring/purses
@@ -2369,8 +2320,6 @@ This section is used to obtain a list of purses.
: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
@@ -2403,7 +2352,7 @@ This section is used to obtain a list of purses.
Progress
--------
-This section contains information about the auditing progress an auditor has made.
+This section contains information about the auditing progress an auditor has made.
.. http:get:: /monitoring/progress
@@ -2414,8 +2363,6 @@ This section contains information about the auditing progress an auditor has mad
: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
@@ -2447,4 +2394,4 @@ misbehavior of an exchange to the auditor.
.. http:put:: /complain
-Complain about misbehavior to the auditor.
-\ No newline at end of file
+Complain about misbehavior to the auditor.
