commit bd9c5dbf226ab66bd1a0358b5596a94301d2eb7d
parent 921df3b49c6adb1ff9e322d3dae739979e1a695e
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 31 Oct 2025 18:56:10 +0100
expand auditor API spec with new endpoints for #9316 / #9436
Diffstat:
| M | core/api-auditor.rst | | | 136 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- |
1 file changed, 135 insertions(+), 1 deletion(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -56,7 +56,7 @@ know-your-customer (KYC) registration before issuing contracts.
.. http:get:: /config
Get the protocol version and some meta data about the auditor.
- This specification corresponds to ``current`` protocol being version **1**.
+ This specification corresponds to ``current`` protocol being version **v2**.
**Response:**
@@ -752,6 +752,140 @@ properly.
+.. _early-aggregation-list:
+
+This endpoint returns cases in which wire transfers are encountered before their
+justifications. This can be harmless, if the justifications appear shortly afterwards.
+
+.. http:get:: /monitoring/early-aggregation
+
+ Get a list of early aggregations.
+ @since protocol **v2**.
+
+ 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:`GetEarlyAggregationResponse` objects.
+
+ **Details:**
+
+ .. ts:def:: GetEarlyAggregationResponse
+
+ interface GetEarlyAggregationResponse {
+
+ // Array of aggregations lacking a justification.
+ early_aggregations: EarlyAggregationEntry[];
+
+ }
+
+ .. ts:def:: EarlyAggregationEntry
+
+ interface EarlyAggregationEntry {
+
+ // Unique row identifier in the auditor table
+ row_id : Integer;
+
+ // Row identifier in the exchange's batch deposit table
+ batch_deposit_serial_id : Integer;
+
+ // Row identifier in the exchange's tracking table
+ tracking_serial_id : Integer;
+
+ // Amount that was aggregated early.
+ balance : Amount;
+
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
+
+ }
+
+ .. note::
+
+ This endpoint is still experimental. The endpoint will be further developed as needed.
+
+
+
+
+.. _pending-deposits-list:
+
+This endpoint returns cases in which deposits are pending, that is an
+expected wire transfer for a given deposit was not yet found even though
+it is past the wire deadline.
+This can be harmless, if the wire transfers appear shortly afterwards.
+
+.. http:get:: /monitoring/pending-deposits
+
+ Get a list of pending deposits.
+ @since protocol **v2**.
+
+ 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:`GetPendingDepositsResponse` objects.
+
+ **Details:**
+
+ .. ts:def:: GetPendingDepositsResponse
+
+ interface GetPendingDepositsResponse {
+
+ // Array of pending deposits.
+ pending_deposits: PendingDepositEntry[];
+
+ }
+
+ .. ts:def:: PendingDepositEntry
+
+ interface PendingDepositEntry {
+
+ // Unique row identifier in the auditor table
+ row_id : Integer;
+
+ // Row identifier in the exchange's batch deposit table
+ batch_deposit_serial_id : Integer;
+
+ // Hash of the bank account that should have received the funds.
+ h_wire : HashCode;
+
+ // When was the deadline for the transfer.
+ deadline : Timestamp;
+
+ // Amount that was aggregated early.
+ total_amount : Amount;
+
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
+
+ }
+
+ .. note::
+
+ This endpoint is still experimental. The endpoint will be further developed as needed.
+
+
+
+
+
.. _reserve-not-closed-inconsistency-list:
