commit 700a7116309c355f1557b841356e826b6d4c34de
parent 83d19c91d889d7d7234b83ac19a8c29563059b5d
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 5 Aug 2026 21:30:48 +0200
expand auditor specs to match latest code
Diffstat:
2 files changed, 109 insertions(+), 0 deletions(-)
diff --git a/core/auditor/get-monitoring-aml-holds.rst b/core/auditor/get-monitoring-aml-holds.rst
@@ -0,0 +1,77 @@
+.. http:get:: /monitoring/aml-holds
+
+ Get a list of the wire transfers the exchange aggregated but did not execute.
+
+ 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:`AmlHold` objects. If no elements could be found, an empty array is returned
+ :http:statuscode:`400 Bad request`:
+ The request is malformed. Returned with an
+ ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` error code.
+ :http:statuscode:`401 Unauthorized`:
+ The request lacks valid authentication credentials.
+ The response comes with a ``TALER_EC_AUDITOR_GENERIC_UNAUTHORIZED``.
+ :http:statuscode:`500 Internal Server Error`:
+ The server experienced an internal error.
+ The response comes with a ``TALER_EC_GENERIC_DB_SETUP_FAILED`` or
+ ``TALER_EC_GENERIC_DB_FETCH_FAILED`` error code.
+
+
+
+ **Details:**
+
+ .. ts:def:: AmlHold
+
+ interface AmlHold {
+
+ // Unique row identifier
+ row_id : Integer;
+
+ // The wire transfer identifier the deposits were aggregated into.
+ wtid : HashCode;
+
+ // Hash of the payto:// URI of the account that should be credited.
+ wire_target_h_payto : HashCode;
+
+ // Full payto:// URI (RFC 8905) of the account that
+ // should be credited.
+ account : string;
+
+ // What the exchange still owes on this wire transfer: the
+ // deposits aggregated into it, minus refunds, minus deposit
+ // fees. The wire fee is not yet deducted.
+ amount : Amount;
+
+ // True if the exchange has a KYC measure open against the
+ // recipient, so that withholding the funds is explained.
+ // False if the auditor found no legitimization requirement,
+ // in which case the exchange is simply not paying.
+ aml_hold : boolean;
+
+ // The open measure the hold was attributed to, or 0 if
+ // aml_hold is false.
+ legitimization_measure_serial_id : Integer;
+
+ // When the auditor first saw this transfer being withheld.
+ first_seen : Timestamp;
+
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
+
+ }
+
+ .. note::
+
+ This endpoint is still experimental. The endpoint will be further developed as needed.
diff --git a/core/auditor/patch-monitoring-aml-holds-SERIAL_ID.rst b/core/auditor/patch-monitoring-aml-holds-SERIAL_ID.rst
@@ -0,0 +1,32 @@
+.. http:patch:: /monitoring/aml-holds/$SERIAL_ID
+
+ This endpoint is used to suppress select elements of the AML hold list.
+ Update the 'suppressed' field of an AML hold element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+
+ Note that suppressing a hold only hides it from this listing. The funds are
+ withheld either way, so the amount continues to count towards the
+ ``total_aml_hold`` and ``total_transfer_lag`` balances.
+
+ **Response:**
+
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
+ :http:statuscode:`400 Bad Request`:
+ The request body is invalid or the ``$SERIAL_ID`` is not a valid row identifier.
+ The response comes with a ``TALER_EC_GENERIC_JSON_INVALID`` or
+ ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` error code.
+ :http:statuscode:`401 Unauthorized`:
+ The request lacks valid authentication credentials.
+ The response comes with a ``TALER_EC_AUDITOR_GENERIC_UNAUTHORIZED``.
+ :http:statuscode:`404 Not found`:
+ The specified row was not found.
+ The response comes with a ``TALER_EC_AUDITOR_RESOURCE_NOT_FOUND`` error code.
+ :http:statuscode:`500 Internal Server Error`:
+ The server experienced an internal error.
+ The response comes with a ``TALER_EC_GENERIC_DB_SETUP_FAILED``,
+ ``TALER_EC_GENERIC_DB_STORE_FAILED``, or
+ ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE`` error code.
+
+ .. note::
+
+ This endpoint is still experimental. The endpoint will be further developed as needed.
