commit 2b39474adc7c32826cec8d8afdba49bfa67293ae
parent dc99efe66e3f8d10b22d0a4237785a0bb02106df
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 4 Jun 2024 16:07:18 +0200
auditor API review
Diffstat:
| M | core/api-auditor.rst | | | 976 | ++++++++++++++++++++++++++++++++++++++++--------------------------------------- |
1 file changed, 497 insertions(+), 479 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -562,28 +562,28 @@ cash than they should be).
interface ReserveInInconsistency {
- // Unique row identifier
- row_id : Integer;
+ // Unique row identifier
+ row_id : Integer;
- // Amount the exchange expects to be in the reserve
+ // Amount the exchange expects to be in the reserve
amount_exchange_expected : Amount;
- // Amount deposited into the reserve
+ // Amount deposited into the reserve
amount_wired : Amount;
- // Public key of the reserve
+ // Public key of the reserve
reserve_pub : EddsaPublicKey;
- // Time of the deposit
+ // Time of the deposit
timestamp : Timestamp;
- // Account associated with the reserve
+ // Account associated with the reserve
account : string;
- // Human readable diagnostic of the problem
+ // Human readable diagnostic of the problem
diagnostic : string;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -653,19 +653,19 @@ properly.
interface PurseNotClosedInconsistencies {
- // Unique row identifier.
+ // Unique row identifier.
row_id : Integer;
- // Public key of the affected purse
+ // Public key of the affected purse
purse_pub : EddsaPublicKey;
- // Amount still in the purse, which should have been refunded
+ // Amount still in the purse, which should have been refunded
amount : Amount;
- // When the purse expired
+ // When the purse expired
expiration_date : Timestamp;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -735,22 +735,22 @@ process is not running properly.
interface ReserveNotClosedInconsistency {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // Public key of the reserve
+ // Public key of the reserve
reserve_pub : EddsaPublicKey;
- // Amount still in the reserve at the time of expiration
+ // Amount still in the reserve at the time of expiration
balance : Amount;
- // Date the reserve expired
+ // Date the reserve expired
expiration_time : Timestamp;
- // Human readable string describing the problem
+ // Human readable string describing the problem
diagnostic : string;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -822,19 +822,19 @@ compromise resulting in proportional financial losses to the exchange.
interface ReserveBalanceInsufficientInconsistency {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // Public key of the affected reserve
+ // Public key of the affected reserve
reserve_pub : EddsaPublicKey;
- // Whether this inconsistency is profitable for the exchange
+ // Whether this inconsistency is profitable for the exchange
inconsistency_gain : boolean;
- // Amount possibly lost or gained by the exchange
+ // Amount possibly lost or gained by the exchange
inconsistency_amount : Amount;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -907,19 +907,19 @@ could successfully dispute the resulting transactions).
interface BadSigLosses {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // Operation performed, even though a signature was invalid
+ // Operation performed, even though a signature was invalid
operation : string;
- // Amount considered lost by the exchange
+ // Amount considered lost by the exchange
loss : Amount;
- // Public key associated with an operation
+ // Public key associated with an operation
operation_specific_pub : EddsaPublicKey;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -989,25 +989,25 @@ any effects on its own balance, those entries are excluded from the total.
interface CoinInconsistency {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // The operation performed by the exchange
+ // The operation performed by the exchange
operation : string;
- // Total the exchange calculated
+ // Total the exchange calculated
exchange_amount : Amount;
- // Total the auditor calculated
+ // Total the auditor calculated
auditor_amount : Amount;
- // Public key of the coin in question
+ // Public key of the coin in question
coin_pub : EddsaPublicKey;
- // Whether this arithmetic error was profitable for the exchange
+ // Whether this arithmetic error was profitable for the exchange
profitable : boolean;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -1080,22 +1080,23 @@ business situation.
interface DenominationsWithoutSigs {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // Hash of the denomination public key
+ // 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 of each coin of the denomination that lacks
+ // the auditor's signature.
value : Amount;
- // From when the denomination key in question is valid
+ // From when the denomination key in question is valid
start_time : Timestamp;
- // When the denomination key in question expires
+ // When the denomination key in question expires
end_time : Timestamp;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -1165,19 +1166,20 @@ balance, as that balance would be credited to the original account.
interface MisattributionInInconsistency {
- // Unique row identifier
+ // Unique row identifier in the exchange database.
row_id : Integer;
- // Amount of money sent to the wrong account
+ // Amount of money sent to the wrong account
amount : Amount;
- // #FIXME: not sure
+ // Row of the transaction in the bank database as
+ // returned by the bank revenue API.
bank_row : Integer;
- // Public key of the affected reserve
+ // Public key of the affected reserve
reserve_pub : EddsaPublicKey;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -1256,54 +1258,54 @@ replication from the exchange is working properly.
interface DepositConfirmations {
- // Row id in the exchange database
+ // Row id in the exchange database
deposit_confirmation_serial_id : Integer;
- // Hash over the contract for which this deposit is made.
+ // Hash over the contract for which this deposit is made.
h_contract_terms : HashCode;
- // Hash over the policy concerning this deposit
+ // Hash over the policy concerning this deposit
h_policy : HashCode;
- // Hash over the wiring information of the merchant.
+ // Hash over the wiring information of the merchant.
h_wire : HashCode;
- // Time when the deposit confirmation confirmation was generated.
+ // 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.
+ // 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?
+ // 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.
+ // Amount to be deposited, excluding fee. Calculated from the
+ // amount with fee and the fee from the deposit request.
total_without_fee : Amount;
- // Array of public keys of the deposited coins.
+ // Array of public keys of the deposited coins.
coin_pubs : EddsaPublicKey[];
- // Array of deposit signatures of the deposited coins.
- // Must have the same length as coin_pubs.
+ // 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.
+ // 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.
+ // Signature from the exchange of type
+ // TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT.
exchange_sig : EddsaSignature;
- // Public signing key from the exchange matching exchange_sig.
+ // Public signing key from the exchange matching exchange_sig.
exchange_pub : EddsaPublicKey;
- // Exchange master signature over exchange_sig.
+ // Exchange master signature over exchange_sig.
master_sig : EddsaSignature;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
}
@@ -1331,22 +1333,20 @@ replication from the exchange is working properly.
This API is still experimental. The API will be further developed as needed.
-# FIXME-CG: review from here...
-
-.. denomination-key-validity-withdraw-inconsistency-list:
+.. _denomination-key-validity-withdraw-inconsistency-list:
Denomination Key Validity Withdraw Inconsistencies
--------------------------------------------------
-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
+This section highlights cases, where denomination keys were used to sign coins
+withdrawn from a reserve before the denomination was valid or after it was
+already expired for signing. This doesn't exactly imply any financial loss
+for anyone, it is mostly weird and may have affected the fees the customer
+paid.
.. http:get:: /monitoring/denomination-key-validity-withdraw-inconsistency
Get a list of denomination key validity withdraw inconsistencies stored by the auditor.
-
The following query parameters are optional, and can be used to customise the response:
**Request:**
@@ -1355,19 +1355,22 @@ after they were already expired.
: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:`DenominationKeyValidityWithdrawInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`DenominationKeyValidityWithdrawInconsistency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
+ FIXME: We don't generally document this for every endpoint, way too redundant.
+ State this once, globally (say for the entire section!).
:http:statuscode:`404 Not Found`:
No elements could be found.
+ FIXME: this MUST be a 204 No Content. 4xx means client error (!), and
+ 404 means the *endpoint* is not known! This comment also applies to other endpoints!
**Details:**
@@ -1375,22 +1378,21 @@ after they were already expired.
interface DenominationKeyValidityWithdrawInconsistency {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // When the withdrawal took place
+ // When the withdrawal took place
execution_date : Timestamp;
- // Public key of the reserve affected
+ // Public key of the reserve affected
reserve_pub : EddsaPublicKey;
- // Hash of the denomination public key involved in the withdrawal
+ // Hash of the denomination public key involved in the withdrawal
denompub_h : HashCode;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
-
}
.. note::
@@ -1398,7 +1400,7 @@ after they were already expired.
This API is still experimental. The API will be further developed as needed.
-
+FIXME-CG: discuss this with students...
This API is used to suppress select elements of denomination key validity withdraw inconsistencies
@@ -1416,7 +1418,7 @@ This API is used to suppress select elements of denomination key validity withdr
This API is still experimental. The API will be further developed as needed.
-
+FIXME-CG: discuss this with students...
.. amount-arithmetic-inconsistency-list:
@@ -1424,7 +1426,7 @@ This API is used to suppress select elements of denomination key validity withdr
Amount Arithmetic Inconsistencies
---------------------------------
-This API is used to obtain a list of amount arithmetic inconsistencies
+This API 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.
@@ -1435,6 +1437,11 @@ The profitable column is set to true if the arithmetic problem was be determined
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
+to be optional. Are you sure this covers all cases?
+
+
.. http:get:: /monitoring/amount-arithmetic-inconsistency
Get a list of amount arithmetic inconsistencies stored by the auditor.
@@ -1453,7 +1460,7 @@ the exchange.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`AmountArithmeticInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`AmountArithmeticInconsistency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1467,24 +1474,23 @@ the exchange.
interface AmountArithmeticInconsistency {
- // Unique row identifier
- row_id : Integer;
-
- // Name of the arithmetic operation performed
- operation : string;
+ // Unique row identifier
+ row_id : Integer;
- // Amount according to the exchange
- exchange_amount : Amount;
+ // Name of the arithmetic operation performed
+ operation : string;
- // Amount according to the auditor
- auditor_amount : Amount;
+ // Amount according to the exchange
+ exchange_amount : Amount;
- // Whether the miscalculation is profitable for the exchange
- profitable : boolean;
+ // Amount according to the auditor
+ auditor_amount : Amount;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
+ // Whether the miscalculation is profitable for the exchange
+ profitable : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -1513,18 +1519,18 @@ This API is used to suppress select elements of amount arithmetic inconsistencie
-.. historic-denomination-revenue-list:
-Historic Denomination Revenue
------------------------------
-This API is used to obtain a list of historic denomination revenue
+.. wire-format-inconsistency-list:
-#FIXME: this is missing some information
+Wire Format Inconsistencies
+---------------------------
-.. http:get:: /monitoring/historic-denomination-revenue
+This section highlights cases, where the format of a wire transaction was malformed in some way.
- Get a list of historic denomination revenue stored by the auditor.
+.. http:get:: /monitoring/wire-format-inconsistency
+
+ Get a list of wire format inconsistencies stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -1540,7 +1546,7 @@ This API is used to obtain a list of historic denomination revenue
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`HistoricDenominationRevenue` objecs.
+ The auditor responds with a top level array of :ts:type:`WireFormatInconsistency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1550,27 +1556,24 @@ This API is used to obtain a list of historic denomination revenue
**Details:**
- .. ts:def:: HistoricDenominationRevenue
-
- interface HistoricDenominationRevenue {
+ .. ts:def:: WireFormatInconsistency
- // Unique row identifier
- row_id : Integer;
+ interface WireFormatInconsistency {
- // Hash code of the denomination public key involved
- denom_pub_hash : HashCode;
+ // Unique row identifier
+ row_id : Integer;
- // #FIXME not sure
- revenue_timestamp : Timestamp;
+ // Amount that was part of the wire
+ amount : Amount;
- // #FIXME not sure
- revenue_balance : Amount;
+ #FIXME not sure
+ wire_offset : Integer;
- // #FIXME not sure
- loss_balance : Amount;
+ // True if this diagnostic was suppressed.
+ diagnostic : string;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -1582,11 +1585,11 @@ This API is used to obtain a list of historic denomination revenue
-This API is used to suppress select elements of historic denomination revenue
+This API is used to suppress select elements of wire format inconsistencies
-.. http:patch:: /monitoring/historic-denomination-revenue/$SERIAL_ID
+.. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a historic denomination revenue element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a wire format inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1600,18 +1603,20 @@ This API is used to suppress select elements of historic denomination revenue
-.. denomination-pending-list:
+.. refreshes-hanging-list:
-Denomination Pending
---------------------
+Refreshes Hanging
+-----------------
-This API is used to obtain a list of denomination pending
+This section highlights cases, where refreshed (and then revealed) coins could not be found in an exchanges database.
+This might happen, even if the exchange is operating correctly. In that case, the exchange might simply be slower than
+the auditor.
-#FIXME: this is missing some information
+#FIXME: this might be inaccurate
-.. http:get:: /monitoring/denomination-pending
+.. http:get:: /monitoring/refreshes-hanging
- Get a list of denomination pending stored by the auditor.
+ Get a list of refreshes hanging stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -1627,7 +1632,7 @@ This API is used to obtain a list of denomination pending
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`DenominationPending` objecs.
+ The auditor responds with a top level array of :ts:type:`RefreshesHanging` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1637,29 +1642,21 @@ This API is used to obtain a list of denomination pending
**Details:**
- .. ts:def:: DenominationPending
-
- interface DenominationPending {
-
- // Unique row identifier
- row_id : Integer;
-
- // Hash of the denomination public key
- denom_pub_hash : HashCode;
-
- // #FIXME not sure
- denom_balance : Amount;
+ .. ts:def:: RefreshesHanging
- denom_loss : Amount;
+ interface RefreshesHanging {
- num_issued : Integer;
+ // Unique row identifier
+ row_id : Integer;
- denom_risk : Amount;
+ // Amount in coin not found in the exchange
+ amount : Amount;
- recoup_loss : Amount;
+ // Public key of coin
+ coin_pub : EddsaPublicKey;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -1671,11 +1668,11 @@ This API is used to obtain a list of denomination pending
-This API is used to suppress select elements of denomination pending
+This API is used to suppress select elements of refreshes hanging
-.. http:patch:: /monitoring/denomination-pending/$SERIAL_ID
+.. http:patch:: /monitoring/refreshes-hanging/$SERIAL_ID
- Update the 'suppressed' field of a denomination pending element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a refreshes hanging element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1689,19 +1686,29 @@ This API is used to suppress select elements of denomination pending
-.. historic-reserve-summary-list:
+.. emergency-list:
-Historic Reserve Summary
-------------------------
+Emergencies
+-----------
-This section highlights cases, where the exchanges expectation of the summary in a reserve
-differs from its actual summary.
+This API is used to obtain a list of emergencies.
-#FIXME: this might be inaccurate
+Emergencies are errors where more coins were deposited than the
+exchange remembers issuing. This usually means that the private keys
+of the exchange were compromised (stolen or factored) and subsequently
+used to sign coins off the books. If this happens, all coins of the
+respective denomination that the exchange has redeemed so far may have
+been created by the attacker, and the exchange would have to refund
+all of the outstanding coins from ordinary users. Thus, the risk
+exposure is the amount of coins in circulation for a particular
+denomination and the maximum loss for the exchange from this type of
+compromise.
-.. http:get:: /monitoring/historic-reserve-summary
+#FIXME: what is the difference between Emergencies and Emergencies by Count
- Get a list of historic reserve summary stored by the auditor.
+.. http:get:: /monitoring/emergency
+
+ Get a list of emergencies stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -1717,7 +1724,7 @@ differs from its actual summary.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`HistoricReserveSummary` objecs.
+ The auditor responds with a top level array of :ts:type:`Emergency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1727,24 +1734,30 @@ differs from its actual summary.
**Details:**
- .. ts:def:: HistoricReserveSummary
+ .. ts:def:: Emergency
- interface HistoricReserveSummary {
+ interface Emergency {
- // Unique row identifier
- row_id : Integer;
+ // Unique row identifier
+ row_id : Integer;
- // From when the summary starts
- start_date : Timestamp;
+ // Hash of denomination public key
+ denompub_h : HashCode;
- // When the summary ends
- end_date : Timestamp;
+ #FIXME not sure
+ denom_risk : Amount;
- // Profits the exchange charged for the reserve
- reserve_profits : Amount;
+ denom_loss : Amount;
+
+ deposit_start : Timestamp;
+
+ deposit_end : Timestamp;
+
+ value : Amount;
+
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
}
@@ -1755,11 +1768,11 @@ differs from its actual summary.
-This API is used to suppress select elements of historic reserve summary
+This API is used to suppress select elements of emergencies
-.. http:patch:: /monitoring/historic-reserve-summary/$SERIAL_ID
+.. http:patch:: /monitoring/emergency/$SERIAL_ID
- Update the 'suppressed' field of a historic reserve summary element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of an emergency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1773,18 +1786,23 @@ This API is used to suppress select elements of historic reserve summary
-.. exchange-signkeys-list:
+.. closure-lags-list:
-Exchange Signkeys
------------------
+Closure Lags
+------------
-This API is used to obtain a list of exchange signkeys
+This API is used to obtain a list of closure lags.
-#FIXME: this is missing some information
+Lag can be due to some component being behind in
+executing transactions. This is usually either the exchange's aggregator, the
+bank's wire transfer logic, or the synchronization of databases between
+exchange and auditor. Significant lag may be indicative of fraud, while
+moderate lag is indicative that the systems may be too slow to handle the
+load. Small amounts of lag can occur in normal operation.
-.. http:get:: /monitoring/exchange-signkeys
+.. http:get:: /monitoring/closure-lags
- Get a list of exchange signkeys stored by the auditor.
+ Get a list of closure lags stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -1800,7 +1818,7 @@ This API is used to obtain a list of exchange signkeys
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`ExchangeSignkeys` objecs.
+ The auditor responds with a top level array of :ts:type:`ClosureLags` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1810,28 +1828,23 @@ This API is used to obtain a list of exchange signkeys
**Details:**
- .. ts:def:: ExchangeSignkeys
-
- interface ExchangeSignkeys {
+ .. ts:def:: ClosureLags
- // Unique row identifier
- row_id : Integer
+ interface ClosureLags {
- // Public key of the exchange
- exchange_pub : EddsaPublicKey;
+ // Unique row identifier
+ row_id : Integer;
- #FIXME not sure
- master_sig : EddsaSignature;
+ # FIXME not sure
+ amount : Amount;
- // From when the exchange public key is valid
- ep_valid_from : Timestamp;
+ deadline : Timestamp;
- #FIXMME not sure
- ep_expire_sign : Timestamp;
+ wtid : Integer;
- ep_expire_legal : Timestamp;
+ account : string;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -1844,11 +1857,11 @@ This API is used to obtain a list of exchange signkeys
-This API is used to suppress select elements of exchange signkeys
+This API is used to suppress select elements of closure lags
-.. http:patch:: /monitoring/exchange-signkeys/$SERIAL_ID
+.. http:patch:: /monitoring/closure-lags/$SERIAL_ID
- Update the 'suppressed' field of an exchange signkeys element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a closure lags element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1862,16 +1875,17 @@ This API is used to suppress select elements of exchange signkeys
-.. wire-format-inconsistency-list:
+.. wire-out-inconsistency-list:
-Wire Format Inconsistencies
----------------------------
+Wire Out Inconsistencies
+------------------------
-This section highlights cases, where the format of a wire transaction was malformed in some way.
+This section highlights cases where the exchange's record about
+outgoing wire transfers does not match with that of the bank.
-.. http:get:: /monitoring/wire-format-inconsistency
+.. http:get:: /monitoring/wire-out-inconsistency
- Get a list of wire format inconsistencies stored by the auditor.
+ Get a list of wire out inconsistencies stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -1887,7 +1901,7 @@ This section highlights cases, where the format of a wire transaction was malfor
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`WireFormatInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`WireOutInconsistency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1897,23 +1911,23 @@ This section highlights cases, where the format of a wire transaction was malfor
**Details:**
- .. ts:def:: WireFormatInconsistency
+ .. ts:def:: WireOutInconsistency
- interface WireFormatInconsistency {
+ interface WireOutInconsistency {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // Amount that was part of the wire
- amount : Amount;
+ // Account money was wired to
+ destination_account : string;
- #FIXME not sure
- wire_offset : Integer;
+ // How much was suppossed to be wired
+ expected : Amount;
- // True if this diagnostic was suppressed.
- diagnostic : string;
+ # FIXME not sure
+ claimed : Amount;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -1926,11 +1940,11 @@ This section highlights cases, where the format of a wire transaction was malfor
-This API is used to suppress select elements of wire format inconsistencies
+This API is used to suppress select elements of wire out inconsistencies
-.. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID
+.. http:patch:: /monitoring/wire-out-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a wire format inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a wire out inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -1944,20 +1958,17 @@ This API is used to suppress select elements of wire format inconsistencies
-.. refreshes-hanging-list:
+.. reserve-balance-summary-wrong-inconsistency-list:
-Refreshes Hanging
------------------
+Reserve Balance Summary Wrong Inconsistencies
+---------------------------------------------
-This section highlights cases, where refreshed (and then revealed) coins could not be found in an exchanges database.
-This might happen, even if the exchange is operating correctly. In that case, the exchange might simply be slower than
-the auditor.
-
-#FIXME: this might be inaccurate
+This section highlights cases, where the exchange's and auditors'
+expectation of the amount of money in a reserve differs.
-.. http:get:: /monitoring/refreshes-hanging
+.. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency
- Get a list of refreshes hanging stored by the auditor.
+ Get a list of reserve balance summary wrong inconsistencies stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -1973,7 +1984,7 @@ the auditor.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`RefreshesHanging` objecs.
+ The auditor responds with a top level array of :ts:type:`ReserveBalanceSummaryWrongInconsistency` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -1983,20 +1994,23 @@ the auditor.
**Details:**
- .. ts:def:: RefreshesHanging
+ .. ts:def:: ReserveBalanceSummaryWrongInconsistency
- interface RefreshesHanging {
+ interface ReserveBalanceSummaryWrongInconsistency {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- // Amount in coin not found in the exchange
- amount : Amount;
+ // Public key of the reserve affected
+ reserve_pub : EddsaPublicKey;
- // Public key of coin
- coin_pub : EddsaPublicKey;
+ // Amount of summary the exchange calculated
+ exchange_amount : Amount;
- // True if this diagnostic was suppressed.
+ // Amount of summary the auditor calculated
+ auditor_amount : Amount;
+
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -2009,11 +2023,11 @@ the auditor.
-This API is used to suppress select elements of refreshes hanging
+This API is used to suppress select elements of reserve balance summary wrong inconsistencies
-.. http:patch:: /monitoring/refreshes-hanging/$SERIAL_ID
+.. http:patch:: /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID
- Update the 'suppressed' field of a refreshes hanging element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a reserve balance summary wrong inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2027,29 +2041,19 @@ This API is used to suppress select elements of refreshes hanging
-.. emergency-list:
-
-Emergencies
------------
+.. row-minor-inconsistencies-list:
-This API is used to obtain a list of emergencies.
+Row Minor Inconsistencies
+-------------------------
-Emergencies are errors where more coins were deposited than the
-exchange remembers issuing. This usually means that the private keys
-of the exchange were compromised (stolen or factored) and subsequently
-used to sign coins off the books. If this happens, all coins of the
-respective denomination that the exchange has redeemed so far may have
-been created by the attacker, and the exchange would have to refund
-all of the outstanding coins from ordinary users. Thus, the risk
-exposure is the amount of coins in circulation for a particular
-denomination and the maximum loss for the exchange from this type of
-compromise.
+The section highlights inconsistencies, which are cause for concern,
+but not necessarily point to a monetary loss (yet).
-#FIXME: what is the difference between Emergencies and Emergencies by Count
+#FIXME: might not be accurate
-.. http:get:: /monitoring/emergency
+.. http:get:: /monitoring/row-minor-inconsistencies
- Get a list of emergencies stored by the auditor.
+ Get a list of row minor inconsistencies stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -2065,7 +2069,7 @@ compromise.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`Emergency` objecs.
+ The auditor responds with a top level array of :ts:type:`RowMinorInconsistencies` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2075,28 +2079,20 @@ compromise.
**Details:**
- .. ts:def:: Emergency
+ .. ts:def:: RowMinorInconsistencies
- interface Emergency {
+ interface RowMinorInconsistencies {
- // Unique row identifier
+ // Number of the row in the affected table
row_id : Integer;
- // Hash of denomination public key
- denompub_h : HashCode;
-
- #FIXME not sure
- denom_risk : Amount;
-
- denom_loss : Amount;
-
- deposit_start : Timestamp;
-
- deposit_end : Timestamp;
+ // The row number in the affected table
+ row_table : Integer;
- value : Amount;
+ // Human readable string describing the problem
+ diagnostic : string;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -2109,11 +2105,11 @@ compromise.
-This API is used to suppress select elements of emergencies
+This API is used to suppress select elements of row minor inconsistencies
-.. http:patch:: /monitoring/emergency/$SERIAL_ID
+.. http:patch:: /monitoring/row-minor-inconsistencies/$SERIAL_ID
- Update the 'suppressed' field of an emergency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a row minor inconsistencies element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2125,25 +2121,27 @@ This API is used to suppress select elements of emergencies
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.
-.. closure-lags-list:
+.. _balances-list:
-Closure Lags
-------------
+Balances
+--------
-This API is used to obtain a list of closure lags.
+Contains a record of balances alongside the exchange.
-Lag can be due to some component being behind in
-executing transactions. This is usually either the exchange's aggregator, the
-bank's wire transfer logic, or the synchronization of databases between
-exchange and auditor. Significant lag may be indicative of fraud, while
-moderate lag is indicative that the systems may be too slow to handle the
-load. Small amounts of lag can occur in normal operation.
+#FIXME: this might be inaccurate
-.. http:get:: /monitoring/closure-lags
- Get a list of closure lags stored by the auditor.
+.. 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:
@@ -2152,6 +2150,7 @@ load. Small amounts of lag can occur in normal operation.
: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.
@@ -2159,7 +2158,7 @@ load. Small amounts of lag can occur in normal operation.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`ClosureLags` objecs.
+ The auditor responds with a top level array of :ts:type:`Balances` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2169,25 +2168,18 @@ load. Small amounts of lag can occur in normal operation.
**Details:**
- .. ts:def:: ClosureLags
+ .. ts:def:: Balances
- interface ClosureLags {
+ interface Balances {
- // Unique row identifier
+ // Unique row identifier
row_id : Integer;
- # FIXME not sure
- amount : Amount;
-
- deadline : Timestamp;
-
- wtid : Integer;
-
- account : string;
-
- // True if this diagnostic was suppressed.
- suppressed : boolean;
+ // String identifying a balance
+ balance_key : string;
+ // Amount of the balance
+ balance_value : Amount;
}
@@ -2196,37 +2188,18 @@ load. Small amounts of lag can occur in normal operation.
This API is still experimental. The API will be further developed as needed.
+.. historic-denomination-revenue-list:
+Historic Denomination Revenue
+-----------------------------
-This API is used to suppress select elements of closure lags
-
-.. http:patch:: /monitoring/closure-lags/$SERIAL_ID
-
- Update the 'suppressed' field of a closure lags element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
-
- **Response:**
-
- :http:statuscode:`204 No Content`:
- The element has been updated.
-
- .. note::
-
- This API is still experimental. The API will be further developed as needed.
-
-
-
-
-.. wire-out-inconsistency-list:
-
-Wire Out Inconsistencies
-------------------------
+This API is used to obtain a list of historic denomination revenue
-This section highlights cases where the exchange's record about
-outgoing wire transfers does not match with that of the bank.
+#FIXME: this is missing some information
-.. http:get:: /monitoring/wire-out-inconsistency
+.. http:get:: /monitoring/historic-denomination-revenue
- Get a list of wire out inconsistencies stored by the auditor.
+ Get a list of historic denomination revenue stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -2242,7 +2215,7 @@ outgoing wire transfers does not match with that of the bank.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`WireOutInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`HistoricDenominationRevenue` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2252,23 +2225,26 @@ outgoing wire transfers does not match with that of the bank.
**Details:**
- .. ts:def:: WireOutInconsistency
+ .. ts:def:: HistoricDenominationRevenue
- interface WireOutInconsistency {
+ interface HistoricDenominationRevenue {
- // Unique row identifier
- row_id : Integer;
+ // Unique row identifier
+ row_id : Integer;
- // Account money was wired to
- destination_account : string;
+ // Hash code of the denomination public key involved
+ denom_pub_hash : HashCode;
- // How much was suppossed to be wired
- expected : Amount;
+ // #FIXME not sure
+ revenue_timestamp : Timestamp;
- # FIXME not sure
- claimed : Amount;
+ // #FIXME not sure
+ revenue_balance : Amount;
+
+ // #FIXME not sure
+ loss_balance : Amount;
- // True if this diagnostic was suppressed.
+ // True if this diagnostic was suppressed.
suppressed : boolean;
@@ -2279,13 +2255,13 @@ outgoing wire transfers does not match with that of the bank.
This API is still experimental. The API will be further developed as needed.
+FIXME: again, suppression makes no sense for this endpoint!
+This API is used to suppress select elements of historic denomination revenue
-This API is used to suppress select elements of wire out inconsistencies
-
-.. http:patch:: /monitoring/wire-out-inconsistency/$SERIAL_ID
+.. http:patch:: /monitoring/historic-denomination-revenue/$SERIAL_ID
- Update the 'suppressed' field of a wire out inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a historic denomination revenue element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2297,19 +2273,18 @@ This API is used to suppress select elements of wire out inconsistencies
This API is still experimental. The API will be further developed as needed.
+.. denomination-pending-list:
+Denomination Pending
+--------------------
-.. reserve-balance-summary-wrong-inconsistency-list:
-
-Reserve Balance Summary Wrong Inconsistencies
----------------------------------------------
+This API is used to obtain a list of denomination pending
-This section highlights cases, where the exchange's and auditors'
-expectation of the amount of money in a reserve differs.
+#FIXME: this is missing some information
-.. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency
+.. http:get:: /monitoring/denomination-pending
- Get a list of reserve balance summary wrong inconsistencies stored by the auditor.
+ Get a list of denomination pending stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -2325,7 +2300,7 @@ expectation of the amount of money in a reserve differs.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`ReserveBalanceSummaryWrongInconsistency` objecs.
+ The auditor responds with a top level array of :ts:type:`DenominationPending` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2335,24 +2310,29 @@ expectation of the amount of money in a reserve differs.
**Details:**
- .. ts:def:: ReserveBalanceSummaryWrongInconsistency
+ .. ts:def:: DenominationPending
- interface ReserveBalanceSummaryWrongInconsistency {
+ interface DenominationPending {
- // Unique row identifier
- row_id : Integer;
+ // Unique row identifier
+ row_id : Integer;
- // Public key of the reserve affected
- reserve_pub : EddsaPublicKey;
+ // Hash of the denomination public key
+ denom_pub_hash : HashCode;
- // Amount of summary the exchange calculated
- exchange_amount : Amount;
+ // #FIXME not sure
+ denom_balance : Amount;
- // Amount of summary the auditor calculated
- auditor_amount : Amount;
+ denom_loss : Amount;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
+ num_issued : Integer;
+
+ denom_risk : Amount;
+
+ recoup_loss : Amount;
+
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2362,13 +2342,14 @@ expectation of the amount of money in a reserve differs.
This API is still experimental. The API will be further developed as needed.
+FIXME: again, suppression makes no sense for this endpoint!
-This API is used to suppress select elements of reserve balance summary wrong inconsistencies
+This API is used to suppress select elements of denomination pending
-.. http:patch:: /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID
+.. http:patch:: /monitoring/denomination-pending/$SERIAL_ID
- Update the 'suppressed' field of a reserve balance summary wrong inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a denomination pending element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2382,19 +2363,19 @@ This API is used to suppress select elements of reserve balance summary wrong in
-.. row-minor-inconsistencies-list:
+.. historic-reserve-summary-list:
-Row Minor Inconsistencies
--------------------------
+Historic Reserve Summary
+------------------------
-The section highlights inconsistencies, which are cause for concern,
-but not necessarily point to a monetary loss (yet).
+This section highlights cases, where the exchanges expectation of the summary in a reserve
+differs from its actual summary.
-#FIXME: might not be accurate
+#FIXME: this might be inaccurate
-.. http:get:: /monitoring/row-minor-inconsistencies
+.. http:get:: /monitoring/historic-reserve-summary
- Get a list of row minor inconsistencies stored by the auditor.
+ Get a list of historic reserve summary stored by the auditor.
The following query parameters are optional, and can be used to customise the response:
@@ -2410,7 +2391,7 @@ but not necessarily point to a monetary loss (yet).
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`RowMinorInconsistencies` objecs.
+ The auditor responds with a top level array of :ts:type:`HistoricReserveSummary` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2420,22 +2401,24 @@ but not necessarily point to a monetary loss (yet).
**Details:**
- .. ts:def:: RowMinorInconsistencies
+ .. ts:def:: HistoricReserveSummary
- interface RowMinorInconsistencies {
+ interface HistoricReserveSummary {
- // Number of the row in the affected table
- row_id : Integer;
+ // Unique row identifier
+ row_id : Integer;
- // The row number in the affected table
- row_table : Integer;
+ // From when the summary starts
+ start_date : Timestamp;
- // Human readable string describing the problem
- diagnostic : string;
+ // When the summary ends
+ end_date : Timestamp;
- // True if this diagnostic was suppressed.
- suppressed : boolean;
+ // Profits the exchange charged for the reserve
+ reserve_profits : Amount;
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
}
@@ -2444,13 +2427,14 @@ but not necessarily point to a monetary loss (yet).
This API is still experimental. The API will be further developed as needed.
+FIXME: again, suppression makes no sense for this endpoint!
-This API is used to suppress select elements of row minor inconsistencies
+This API is used to suppress select elements of historic reserve summary
-.. http:patch:: /monitoring/row-minor-inconsistencies/$SERIAL_ID
+.. http:patch:: /monitoring/historic-reserve-summary/$SERIAL_ID
- Update the 'suppressed' field of a row minor inconsistencies element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+ Update the 'suppressed' field of a historic reserve summary element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
**Response:**
@@ -2462,71 +2446,7 @@ This API is used to suppress select elements of row minor inconsistencies
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:
@@ -2557,7 +2477,7 @@ This API is used to obtain a list of reserves
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`Reserves` objecs.
+ The auditor responds with a top level array of :ts:type:`Reserves` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2571,22 +2491,22 @@ This API is used to obtain a list of reserves
interface Reserves {
- // Unique row identifier
+ // Unique row identifier
auditor_reserves_rowid : Integer;
- // Public key of the reserve
+ // Public key of the reserve
reserve_pub : EddsaPublicKey;
- // Amount in the balance
+ // Amount in the balance
reserve_balance : Amount;
#FIMXE not sure
reserve_loss : Amount;
- // Amount earned by charging withdraw fees
+ // Amount earned by charging withdraw fees
withdraw_fee_balance : Amount;
- // Amount earned by charging a closing fee on the reserve
+ // Amount earned by charging a closing fee on the reserve
close_fee_balance : Amount;
#FIXME not sure
@@ -2596,10 +2516,10 @@ This API is used to obtain a list of reserves
history_fee_balance : Amount;
- // When the purse expires
+ // When the purse expires
expiration_date : Timestamp;
- // Who created the account
+ // Who created the account
origin_account : string;
}
@@ -2636,7 +2556,7 @@ This section is used to obtain a list of purses.
**Response:**
:http:statuscode:`200 OK`:
- The auditor responds with a top level array of :ts:type:`Purses` objecs.
+ The auditor responds with a top level array of :ts:type:`Purses` objects.
:http:statuscode:`403 Forbidden`:
No or bad Bearer token provided.
@@ -2650,19 +2570,19 @@ This section is used to obtain a list of purses.
interface Purses {
- // Unique row identifier
+ // Unique row identifier
auditor_purses_rowid : Integer;
- // Public key of the purse
+ // Public key of the purse
purse_pub : EddsaPublicKey;
- // Amount currently stored in the purse
+ // Amount currently stored in the purse
balance : Amount;
- // Amount the purse is intended for / the maximum amount that can be in the purse
+ // Amount the purse is intended for / the maximum amount that can be in the purse
target : Amount;
- // When the purse expires
+ // When the purse expires
expiration_date : Timestamp;
}
@@ -2691,3 +2611,101 @@ misbehavior of an exchange to the auditor.
.. http:put:: /complain
Complain about misbehavior to the auditor.
+
+
+
+---------
+REMOVE ME
+---------
+
+
+.. exchange-signkeys-list:
+
+Exchange Signkeys
+-----------------
+
+This API is used to obtain a list of exchange signkeys.
+
+FIXME: this endpoint doesn't make *any* sense, this is
+purely boring internal cached information of the auditor,
+nothing interesting to report on at all!
+
+#FIXME: this is missing some information
+
+.. http:get:: /monitoring/exchange-signkeys
+
+ Get a list of exchange signkeys 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:`ExchangeSignkeys` objects.
+
+ :http:statuscode:`403 Forbidden`:
+ No or bad Bearer token provided.
+
+ :http:statuscode:`404 Not Found`:
+ No elements could be found.
+
+ **Details:**
+
+ .. ts:def:: ExchangeSignkeys
+
+ interface ExchangeSignkeys {
+
+ // Unique row identifier
+ row_id : Integer
+
+ // Public key of the exchange
+ exchange_pub : EddsaPublicKey;
+
+ #FIXME not sure
+ master_sig : EddsaSignature;
+
+ // From when the exchange public key is valid
+ ep_valid_from : Timestamp;
+
+ #FIXMME not sure
+ ep_expire_sign : Timestamp;
+
+ ep_expire_legal : Timestamp;
+
+ // True if this diagnostic was suppressed.
+ suppressed : boolean;
+
+
+ }
+
+ .. note::
+
+ This API is still experimental. The API will be further developed as needed.
+
+
+FIXME: again, suppression makes no sense for this endpoint!
+
+
+This API is used to suppress select elements of exchange signkeys
+
+.. http:patch:: /monitoring/exchange-signkeys/$SERIAL_ID
+
+ Update the 'suppressed' field of an exchange signkeys element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor.
+
+ **Response:**
+
+ :http:statuscode:`204 No Content`:
+ The element has been updated.
+
+ .. note::
+
+ This API is still experimental. The API will be further developed as needed.
