commit eda568554ba138897294530068f7d830c5bdf7d9
parent 245a6bcf2ff3cc0f3d813ab7f3d8c25e8bf1120c
Author: Cedric Zwahlen <cedric.zwahlen@students.bfh.ch>
Date: Tue, 4 Jun 2024 00:02:35 +0200
Add more annotations
Diffstat:
| M | core/api-auditor.rst | | | 830 | +++++++++++++++++++++++++++++++++++++++++++------------------------------------ |
1 file changed, 448 insertions(+), 382 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -309,8 +309,8 @@ prevent such a fee configuration from being accepted.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -425,8 +425,8 @@ auditor reports an emergency-by-count.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -507,8 +507,8 @@ This API is used to suppress select elements of row inconsistencies
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -562,20 +562,28 @@ cash than they should be).
interface ReserveInInconsistency {
- row_id : Integer;
+ // Unique row identifier
+ row_id : Integer;
+ // Amount the exchange expects to be in the reserve
amount_exchange_expected : Amount;
+ // Amount deposited into the reserve
amount_wired : Amount;
+ // Public key of the reserve
reserve_pub : EddsaPublicKey;
+ // Time of the deposit
timestamp : Timestamp;
+ // Account associated with the reserve
account : string;
+ // Human readable diagnostic of the problem
diagnostic : string;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -593,8 +601,8 @@ This API is used to suppress select elements of reserve in inconsistencies
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -645,14 +653,19 @@ properly.
interface PurseNotClosedInconsistencies {
+ // Unique row identifier.
row_id : Integer;
+ // Public key of the affected purse
purse_pub : EddsaPublicKey;
+ // Amount still in the purse, which should have been refunded
amount : Amount;
+ // When the purse expired
expiration_date : Timestamp;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -671,8 +684,8 @@ properly.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -722,16 +735,22 @@ process is not running properly.
interface ReserveNotClosedInconsistency {
+ // Unique row identifier
row_id : Integer;
+ // Public key of the reserve
reserve_pub : EddsaPublicKey;
+ // Amount still in the reserve at the time of expiration
balance : Amount;
+ // Date the reserve expired
expiration_time : Timestamp;
+ // Human readable string describing the problem
diagnostic : string;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -752,8 +771,8 @@ process is not running properly.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -803,14 +822,19 @@ compromise resulting in proportional financial losses to the exchange.
interface ReserveBalanceInsufficientInconsistency {
+ // Unique row identifier
row_id : Integer;
+ // Public key of the affected reserve
reserve_pub : EddsaPublicKey;
+ // Whether this inconsistency is profitable for the exchange
inconsistency_gain : boolean;
+ // Amount possibly lost or gained by the exchange
inconsistency_amount : Amount;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -832,8 +856,8 @@ compromise resulting in proportional financial losses to the exchange.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -883,14 +907,19 @@ could successfully dispute the resulting transactions).
interface BadSigLosses {
+ // Unique row identifier
row_id : Integer;
+ // Operation performed, even though a signature was invalid
operation : string;
+ // Amount considered lost by the exchange
loss : Amount;
+ // Public key associated with an operation
operation_specific_pub : EddsaPublicKey;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -909,8 +938,8 @@ could successfully dispute the resulting transactions).
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -960,18 +989,25 @@ any effects on its own balance, those entries are excluded from the total.
interface CoinInconsistency {
+ // Unique row identifier
row_id : Integer;
+ // The operation performed by the exchange
operation : string;
+ // Total the exchange calculated
exchange_amount : Amount;
+ // Total the auditor calculated
auditor_amount : Amount;
+ // Public key of the coin in question
coin_pub : EddsaPublicKey;
+ // Whether this arithmetic error was profitable for the exchange
profitable : boolean;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -990,75 +1026,8 @@ any effects on its own balance, those entries are excluded from the total.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-.. _balances-list:
-
-Balances
---------
-
-Unlike many other sections of the auditor, entries in the balances table do
-not necessarily represent misbehaviour or unusual findings. Instead, the
-auditor keeps its own record of the current balances of purses, to compare
-them with the purse balances.
-
-# FIXME: if this is the *new* balances table, it has nothing to do with
-# just *purses*. Also, it makes no sense to apply *suppression* to this
-# table!!! Plus, we probably want this endpoint in a different section,
-# balances are like the progress points something for the global
-# dashboard, not for incidents!
-
-#FIXME: this might be inaccurate
-
-
-.. http:get:: /monitoring/balances
-
- Get a list of balances stored by the auditor.
-
- 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.
- :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:**
-
- :http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`Balances` objecs.
-
- :http:statuscode:`403 Forbidden`:
- No or bad Bearer token provided.
-
- :http:statuscode:`404 Not Found`:
- No elements could be found.
-
- **Details:**
-
- .. ts:def:: Balances
-
- interface Balances {
-
- row_id : Integer;
-
- balance_key : string;
-
- balance_value : Amount;
-
- suppressed : boolean;
-
- }
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1067,28 +1036,6 @@ them with the purse balances.
-This API is used to suppress select elements of balances
-
-# FIXME: this endpoint makes no sense!
-# However, you MAY want a
-# GET /monitoring/balances/$BALANCE_KEY endpoint
-# to only return a *specific* balance instead of
-# all of them.
-
-.. http:patch:: /monitoring/balances/$SERIAL_ID
-
- Update the 'suppressed' field of a balances element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
-
- **Response:**
-
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
.. _denominations-without-signatures-list:
Denominations Without Signatures
@@ -1133,16 +1080,22 @@ business situation.
interface DenominationsWithoutSigs {
+ // Unique row identifier
row_id : Integer;
+ // Hash of the denomination public key
denompub_h : HashCode;
+ // Total amount of coins without proper denomination keys signatures – according to this auditor #FIXME not sure
value : Amount;
+ // From when the denomination key in question is valid
start_time : Timestamp;
+ // When the denomination key in question expires
end_time : Timestamp;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -1162,8 +1115,8 @@ business situation.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1212,14 +1165,19 @@ balance, as that balance would be credited to the original account.
interface MisattributionInInconsistency {
+ // Unique row identifier
row_id : Integer;
+ // Amount of money sent to the wrong account
amount : Amount;
+ // #FIXME: not sure
bank_row : Integer;
+ // Public key of the affected reserve
reserve_pub : EddsaPublicKey;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -1239,86 +1197,8 @@ balance, as that balance would be credited to the original account.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-.. _reserves-list:
-
-
-Reserves
---------
-
-This API is used to obtain a list of reserves
-
-FIXME: like the /monitoring/balances API, this endpoint returns status
-information about an exchange that is not at all indicative of an error. It
-should thus be moved into another section (and there is again no point in
-having the suppression capability here!).
-
-#FIXME: this is missing some information
-
-.. http:get:: /monitoring/reserves
-
- Get a list of reserves stored by the auditor.
-
- 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. FIXME: instead of a suppression filter, it would be useful to filter reserves with a balance of zero *or* below a certain threshold (default: minimum denomination unit?).
-
-
- 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:`Reserves` objecs.
-
- :http:statuscode:`403 Forbidden`:
- No or bad Bearer token provided.
-
- :http:statuscode:`404 Not Found`:
- No elements could be found.
-
- **Details:**
-
- .. ts:def:: Reserves
-
- interface Reserves {
-
- auditor_reserves_rowid : Integer;
-
- reserve_pub : EddsaPublicKey;
-
- reserve_balance : Amount;
-
- reserve_loss : Amount;
-
- withdraw_fee_balance : Amount;
-
- close_fee_balance : Amount;
-
- purse_fee_balance : Amount;
-
- open_fee_balance : Amount;
-
- history_fee_balance : Amount;
-
- expiration_date : Timestamp;
-
- origin_account : string;
-
- suppressed : boolean;
-
- }
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1326,25 +1206,6 @@ having the suppression capability here!).
-
-This API is used to suppress select elements of reserves
-
-FIXME: this makes no sense.
-
-.. http:patch:: /monitoring/reserves/$SERIAL_ID
-
- Update the 'suppressed' field of an reserves element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
-
- **Response:**
-
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
.. _deposit-confirmations-list:
Deposit Confirmations
@@ -1395,40 +1256,56 @@ replication from the exchange is working properly.
interface DepositConfirmations {
+ // Row id in the exchange database
deposit_confirmation_serial_id : Integer;
+ // Hash over the contract for which this deposit is made.
h_contract_terms : HashCode;
+ // Hash over the policy concerning this deposit
h_policy : HashCode;
+ // Hash over the wiring information of the merchant.
h_wire : HashCode;
+ // Time when the deposit confirmation confirmation was generated.
exchange_timestamp : Timestamp;
+ // How much time does the merchant have to issue a refund
+ // request? Zero if refunds are not allowed.
refund_deadline : Timestamp;
+ // By what time does the exchange have to wire the funds?
wire_deadline : Timestamp;
+ // Amount to be deposited, excluding fee. Calculated from the
+ // amount with fee and the fee from the deposit request.
total_without_fee : Amount;
- // FIXME: is this correct? Not an array?
- coin_pubs : EddsaPublicKey;
+ // Array of public keys of the deposited coins.
+ coin_pubs : EddsaPublicKey[];
- // FIXME: is this correct? Not an array?
- coin_sigs : EddsaSignature;
+ // Array of deposit signatures of the deposited coins.
+ // Must have the same length as coin_pubs.
+ coin_sigs : EddsaSignature[];
+ // The Merchant's public key. Allows the merchant to later refund
+ // the transaction or to inquire about the wire transfer identifier.
merchant_pub : EddsaPublicKey;
+ // Signature from the exchange of type
+ // TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT.
exchange_sig : EddsaSignature;
+ // Public signing key from the exchange matching exchange_sig.
exchange_pub : EddsaPublicKey;
+ // Exchange master signature over exchange_sig.
master_sig : EddsaSignature;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
- ancient : boolean;
-
}
.. note::
@@ -1446,8 +1323,8 @@ replication from the exchange is working properly.
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1461,7 +1338,7 @@ replication from the exchange is working properly.
Denomination Key Validity Withdraw Inconsistencies
--------------------------------------------------
-This section highlights cases, where denomination keys were used to withdraw coins from a reserve,
+This section highlights cases, where denomination keys were used to sign coins withdrawn from a reserve,
after they were already expired.
#FIXME: this might be inaccurate
@@ -1498,16 +1375,20 @@ after they were already expired.
interface DenominationKeyValidityWithdrawInconsistency {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
-
- execution_date : Timestamp;
+ // When the withdrawal took place
+ execution_date : Timestamp;
- reserve_pub : EddsaPublicKey;
+ // Public key of the reserve affected
+ reserve_pub : EddsaPublicKey;
- denompub_h : HashCode;
+ // Hash of the denomination public key involved in the withdrawal
+ denompub_h : HashCode;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -1527,8 +1408,8 @@ This API is used to suppress select elements of denomination key validity withdr
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1537,88 +1418,6 @@ This API is used to suppress select elements of denomination key validity withdr
-.. purses-list:
-
-Purses
-------
-
-This section highlights cases, in which a purses summary (balance) does
-not match the balance an exchange expects it to be.
-
-#FIXME: this might be inaccurate
-
-.. http:get:: /monitoring/purses
-
- Get a list of purses stored by the auditor.
-
- 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:`Purses` objecs.
-
- :http:statuscode:`403 Forbidden`:
- No or bad Bearer token provided.
-
- :http:statuscode:`404 Not Found`:
- No elements could be found.
-
- **Details:**
-
- .. ts:def:: Purses
-
- interface Purses {
-
-
- auditor_purses_rowid : Integer;
-
- purse_pub : EddsaPublicKey;
-
- balance : Amount;
-
- target : Amount;
-
- expiration_date : Timestamp;
-
- suppressed : boolean;
-
-
- }
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-
-
-This API is used to suppress select elements of purses
-
-.. http:patch:: /monitoring/purses/$SERIAL_ID
-
- Update the 'suppressed' field of a purses element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
-
- **Response:**
-
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-
.. amount-arithmetic-inconsistency-list:
@@ -1668,17 +1467,22 @@ the exchange.
interface AmountArithmeticInconsistency {
-
+ // Unique row identifier
row_id : Integer;
+ // Name of the arithmetic operation performed
operation : string;
+ // Amount according to the exchange
exchange_amount : Amount;
+ // Amount according to the auditor
auditor_amount : Amount;
+ // Whether the miscalculation is profitable for the exchange
profitable : boolean;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -1699,8 +1503,8 @@ This API is used to suppress select elements of amount arithmetic inconsistencie
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1750,15 +1554,22 @@ This API is used to obtain a list of historic denomination revenue
interface HistoricDenominationRevenue {
+ // Unique row identifier
+ row_id : Integer;
+ // Hash code of the denomination public key involved
denom_pub_hash : HashCode;
+ // #FIXME not sure
revenue_timestamp : Timestamp;
+ // #FIXME not sure
revenue_balance : Amount;
+ // #FIXME not sure
loss_balance : Amount;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -1779,8 +1590,8 @@ This API is used to suppress select elements of historic denomination revenue
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1830,9 +1641,13 @@ This API is used to obtain a list of denomination pending
interface DenominationPending {
+ // Unique row identifier
+ row_id : Integer;
+ // Hash of the denomination public key
denom_pub_hash : HashCode;
+ // #FIXME not sure
denom_balance : Amount;
denom_loss : Amount;
@@ -1843,6 +1658,7 @@ This API is used to obtain a list of denomination pending
recoup_loss : Amount;
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -1863,8 +1679,8 @@ This API is used to suppress select elements of denomination pending
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1915,15 +1731,20 @@ differs from its actual summary.
interface HistoricReserveSummary {
-
+ // Unique row identifier
row_id : Integer;
+ // From when the summary starts
start_date : Timestamp;
+ // When the summary ends
end_date : Timestamp;
+ // Profits the exchange charged for the reserve
reserve_profits : Amount;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -1942,8 +1763,8 @@ This API is used to suppress select elements of historic reserve summary
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -1993,18 +1814,25 @@ This API is used to obtain a list of exchange signkeys
interface ExchangeSignkeys {
+ // Unique row identifier
+ row_id : Integer
- exchange_pub : EddsaPublicKey;
+ // Public key of the exchange
+ exchange_pub : EddsaPublicKey;
- master_sig : EddsaSignature;
+ #FIXME not sure
+ master_sig : EddsaSignature;
- ep_valid_from : Timestamp;
+ // From when the exchange public key is valid
+ ep_valid_from : Timestamp;
- ep_expire_sign : Timestamp;
+ #FIXMME not sure
+ ep_expire_sign : Timestamp;
- ep_expire_legal : Timestamp;
+ ep_expire_legal : Timestamp;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2024,8 +1852,8 @@ This API is used to suppress select elements of exchange signkeys
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2073,16 +1901,20 @@ This section highlights cases, where the format of a wire transaction was malfor
interface WireFormatInconsistency {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
-
- amount : Amount;
+ // Amount that was part of the wire
+ amount : Amount;
- wire_offset : Integer;
+ #FIXME not sure
+ wire_offset : Integer;
- diagnostic : string;
+ // True if this diagnostic was suppressed.
+ diagnostic : string;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2102,8 +1934,8 @@ This API is used to suppress select elements of wire format inconsistencies
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2155,14 +1987,17 @@ the auditor.
interface RefreshesHanging {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
-
- amount : Amount;
+ // Amount in coin not found in the exchange
+ amount : Amount;
- coin_pub : EddsaPublicKey;
+ // Public key of coin
+ coin_pub : EddsaPublicKey;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2182,8 +2017,8 @@ This API is used to suppress select elements of refreshes hanging
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2244,20 +2079,25 @@ compromise.
interface Emergency {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
+ // Hash of denomination public key
+ denompub_h : HashCode;
- denompub_h : HashCode;
+ #FIXME not sure
+ denom_risk : Amount;
- denom_risk : Amount;
+ denom_loss : Amount;
- denom_loss : Amount;
+ deposit_start : Timestamp;
- deposit_start : Timestamp;
+ deposit_end : Timestamp;
- deposit_end : Timestamp;
+ value : Amount;
- value : Amount;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2277,8 +2117,8 @@ This API is used to suppress select elements of emergencies
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2333,18 +2173,20 @@ load. Small amounts of lag can occur in normal operation.
interface ClosureLags {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
-
- amount : Amount;
+ # FIXME not sure
+ amount : Amount;
- deadline : Timestamp;
+ deadline : Timestamp;
- wtid : Integer;
+ wtid : Integer;
- account : string;
+ account : string;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2364,8 +2206,8 @@ This API is used to suppress select elements of closure lags
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2414,16 +2256,20 @@ outgoing wire transfers does not match with that of the bank.
interface WireOutInconsistency {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
-
- destination_account : string;
+ // Account money was wired to
+ destination_account : string;
- expected : Amount;
+ // How much was suppossed to be wired
+ expected : Amount;
- claimed : Amount;
+ # FIXME not sure
+ claimed : Amount;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2443,8 +2289,8 @@ This API is used to suppress select elements of wire out inconsistencies
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2493,16 +2339,20 @@ expectation of the amount of money in a reserve differs.
interface ReserveBalanceSummaryWrongInconsistency {
+ // Unique row identifier
+ row_id : Integer;
- row_id : Integer;
-
- reserve_pub : EddsaPublicKey;
+ // Public key of the reserve affected
+ reserve_pub : EddsaPublicKey;
- exchange_amount : Amount;
+ // Amount of summary the exchange calculated
+ exchange_amount : Amount;
- auditor_amount : Amount;
+ // Amount of summary the auditor calculated
+ auditor_amount : Amount;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2522,8 +2372,8 @@ This API is used to suppress select elements of reserve balance summary wrong in
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
@@ -2574,14 +2424,17 @@ but not necessarily point to a monetary loss (yet).
interface RowMinorInconsistencies {
+ // Number of the row in the affected table
+ row_id : Integer;
- row_id : Integer;
-
- row_table : Integer;
+ // The row number in the affected table
+ row_table : Integer;
- diagnostic : string;
+ // Human readable string describing the problem
+ diagnostic : string;
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2601,14 +2454,227 @@ This API is used to suppress select elements of row minor inconsistencies
**Response:**
- :http:statuscode:`202 Accepted`:
- The element has been accepted for processing.
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
.. note::
This API is still experimental. The API will be further developed as needed.
+-------------------------
+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.
+
+.. _balances-list:
+
+Balances
+--------
+
+Contains a record of balances alongside the exchange.
+
+#FIXME: this might be inaccurate
+
+
+.. http:get:: /monitoring/balances
+
+ Get a list of balances stored by the auditor.
+
+ 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.
+ :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:**
+
+ :http:statuscode:`200 OK`:
+ The auditor responds with a top level array of :ts:type:`Balances` objecs.
+
+ :http:statuscode:`403 Forbidden`:
+ No or bad Bearer token provided.
+
+ :http:statuscode:`404 Not Found`:
+ No elements could be found.
+
+ **Details:**
+
+ .. ts:def:: Balances
+
+ interface Balances {
+
+ // Unique row identifier
+ row_id : Integer;
+
+ // String identifying a balance
+ balance_key : string;
+
+ // Amount of the balance
+ balance_value : Amount;
+
+ }
+
+ .. note::
+
+ This API is still experimental. The API will be further developed as needed.
+
+
+.. _reserves-list:
+
+
+Reserves
+--------
+
+This API is used to obtain a list of reserves
+
+#FIXME: this is missing some information
+
+.. http:get:: /monitoring/reserves
+
+ Get a list of reserves stored by the auditor.
+
+ 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. FIXME: instead of a suppression filter, it would be useful to filter reserves with a balance of zero *or* below a certain threshold (default: minimum denomination unit?).
+
+
+ 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:`Reserves` objecs.
+
+ :http:statuscode:`403 Forbidden`:
+ No or bad Bearer token provided.
+
+ :http:statuscode:`404 Not Found`:
+ No elements could be found.
+
+ **Details:**
+
+ .. ts:def:: Reserves
+
+ interface Reserves {
+
+ // Unique row identifier
+ auditor_reserves_rowid : Integer;
+
+ // Public key of the reserve
+ reserve_pub : EddsaPublicKey;
+
+ // Amount in the balance
+ reserve_balance : Amount;
+
+#FIMXE not sure
+ reserve_loss : Amount;
+
+ // Amount earned by charging withdraw fees
+ withdraw_fee_balance : Amount;
+
+ // Amount earned by charging a closing fee on the reserve
+ close_fee_balance : Amount;
+
+#FIXME not sure
+ purse_fee_balance : Amount;
+
+ open_fee_balance : Amount;
+
+ history_fee_balance : Amount;
+
+ // When the purse expires
+ expiration_date : Timestamp;
+
+ // Who created the account
+ origin_account : string;
+
+ }
+
+ .. note::
+
+ This API is still experimental. The API will be further developed as needed.
+
+
+.. purses-list:
+
+Purses
+------
+
+This section is used to obtain a list of purses.
+
+#FIXME: this might be inaccurate
+
+.. http:get:: /monitoring/purses
+
+ Get a list of purses stored by the auditor.
+
+ 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:`Purses` objecs.
+
+ :http:statuscode:`403 Forbidden`:
+ No or bad Bearer token provided.
+
+ :http:statuscode:`404 Not Found`:
+ No elements could be found.
+
+ **Details:**
+
+ .. ts:def:: Purses
+
+ interface Purses {
+
+ // Unique row identifier
+ auditor_purses_rowid : Integer;
+
+ // Public key of the purse
+ purse_pub : EddsaPublicKey;
+
+ // Amount currently stored in the purse
+ balance : Amount;
+
+ // Amount the purse is intended for / the maximum amount that can be in the purse
+ target : Amount;
+
+ // When the purse expires
+ expiration_date : Timestamp;
+
+ }
+
+ .. note::
+
+ This API is still experimental. The API will be further developed as needed.
+
+
+
+
+This API is used to suppress select elements of purses
----------
