[taler-docs] branch master updated: work on auditor API (WiP)

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 65bffa85 work on auditor API (WiP)
65bffa85 is described below

commit 65bffa85789339148b7e23e470f8c37267a10a91
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Thu Jun 6 17:26:22 2024 +0200

    work on auditor API (WiP)
---
 core/api-auditor.rst | 179 ++++++++++++++++++---------------------------------
 1 file changed, 63 insertions(+), 116 deletions(-)

diff --git a/core/api-auditor.rst b/core/api-auditor.rst
index 6004a286..d80debca 100644
--- 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.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.