commit c4e57ab4afc161ec488a3337b8c8521606b35e14 parent 37fe8fa76cea4893ecb239043fdb2d2f06802a46 Author: Christian Grothoff <christian@grothoff.org> Date: Sun, 8 Feb 2026 22:37:43 +0100 break up auditor and donau API docs into one file per endpoint Diffstat:
66 files changed, 2662 insertions(+), 2598 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst @@ -50,48 +50,7 @@ This endpoint is used by merchants to obtain a list of all exchanges audited by this auditor. This may be required for the merchant to perform the required know-your-customer (KYC) registration before issuing contracts. -.. http:get:: /config - - Get the protocol version and some meta data about the auditor. - This specification corresponds to ``current`` protocol being version **v2**. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with an `AuditorVersion`_ object. This request should - virtually always be successful. - - **Details:** - - .. _AuditorVersion: - .. code-block:: tsref - - interface AuditorVersion { - // libtool-style representation of the Taler protocol version, see - // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning - // The format is "current:revision:age". Note that the auditor - // protocol is versioned independently of the exchange's protocol. - version: string; - - // URN of the implementation (needed to interpret 'revision' in version). - // @since v0, may become mandatory in the future. - implementation?: string; - - // Return which currency this auditor is auditing for. - currency: string; - - // EdDSA master public key of the auditor. - auditor_public_key: EddsaPublicKey; - - // EdDSA master public key of the exchange. - // Added in protocol v1. - exchange_master_public_key: EddsaPublicKey; - } - - .. note:: - - This endpoint is still experimental (and is not yet implemented at the - time of this writing). +.. include:: auditor/get-config.rst .. _deposit-confirmation: @@ -108,99 +67,7 @@ an exchange runs into financial trouble to pay its obligations, the merchants that did participate in detecting the bad behavior can be paid out first. -.. http:put:: /deposit-confirmation - - Submits a `DepositConfirmation` to the exchange. Should succeed - unless the signature provided is invalid or the exchange is not - audited by this auditor. - - **Response:** - - :http:statuscode:`200 Ok`: - The auditor responds with a `DepositAudited` object. - This request should virtually always be successful. - :http:statuscode:`403 Forbidden`: - The signature on the deposit confirmation is invalid. - :http:statuscode:`410 Gone`: - The public key used to sign the deposit confirmation - was revoked. - - **Details:** - - .. ts:def:: DepositAudited - - interface DepositAudited { - // TODO: maybe change to ``204 No content`` instead? - } - - .. ts:def:: DepositConfirmation - - interface DepositConfirmation { - - // Hash over the contract for which this deposit is made. - h_contract_terms: HashCode; - - // Hash over the extensions. - h_extensions: HashCode; - - // Hash over the wiring information of the merchant. - h_wire: HashCode; - - // Time when the deposit confirmation confirmation was generated. - 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. - amount_without_fee: Amount; - - // 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``. - 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; - - // Master public key of the exchange corresponding to ``master_sig``. - // Identifies the exchange this is about. - // @deprecated since v1 (now ignored, global per auditor) - master_pub: EddsaPublicKey; - - // When does the validity of the exchange_pub end? - ep_start: Timestamp; - - // When will the exchange stop using the signing key? - ep_expire: Timestamp; - - // When does the validity of the exchange_pub end? - ep_end: Timestamp; - - // Exchange master signature over ``exchange_sig``. - master_sig: EddsaSignature; - } - - .. note:: - - This endpoint is still experimental (and is not yet implemented at the - time of this writing). A key open question is whether the auditor - should sign the response information. +.. include:: auditor/put-deposit-confirmation.rst .. _auditor-monitoring-spa-api: @@ -240,70 +107,9 @@ unclear which fee really applies. This is a sign of a serious misconfiguration or data corruption as usually the exchange logic should prevent such a fee configuration from being accepted. -.. http:get:: /monitoring/fee-time-inconsistency - - Get a list of fee time inconsistencies 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:`FeeTimeInconsistency` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: FeeTimeInconsistency - - interface FeeTimeInconsistency { - - // Row ID of the fee in the exchange database. - row_id : Integer; - - // Specifies the wire method for which the fee is inconsistent. - type : string; - - // Gives the start date of the inconsistent fee. - time : Timestamp; - - // Human readable description of the problem. - diagnostic : string; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - -.. http:patch:: /monitoring/fee-time-inconsistency/$SERIAL_ID - - This endpoint is used to suppress selected elements of fee time - inconsistencies. Updates the 'suppressed' field of a fee time inconsistency - element with row ID ``$SERIAL_ID``. +.. include:: auditor/get-monitoring-fee-time-inconsistency.rst - **Request:** - - The body must be a `GenericAuditorMonitorPatchRequest`. - - **Response:** - - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-fee-time-inconsistency-SERIAL_ID.rst .. _emergency-list: @@ -329,79 +135,9 @@ Theroretically, counting coins should always detect an issue first, but given the importance of emergencies, the auditor checks both total amounts and total numbers of coins (they may differ as coins may be partially deposited). -.. 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: - - **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:`Emergency` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: Emergency - - interface Emergency { - - // Unique row identifier - row_id : Integer; - - // Hash of denomination public key - denompub_h : HashCode; - - // What is the total value of all coins of this denomination that - // were put into circulation (and thus the maximum loss the - // exchange may experience due to this emergency). - denom_risk : Amount; - - // What is the loss we have experienced so far (that - // is, the amount deposited in excess of the amount - // we issued). - denom_loss : Amount; - - // When did the exchange start issuing coins in this the denomination. - deposit_start : Timestamp; - - // When does the deposit period end for coins of this denomination. - deposit_end : Timestamp; - - // What is the value of an individual coin of this denomination. - value : Amount; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - -.. http:patch:: /monitoring/emergency/$SERIAL_ID - - This endpoint is used to suppress select elements of emergencies. - Update the 'suppressed' field of an emergency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. - - **Response:** +.. include:: auditor/get-monitoring-emergency.rst - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-emergency-SERIAL_ID.rst .. _emergency-by-count-list: @@ -427,88 +163,9 @@ into circulation and comparing it to the number of coins that were redeemed. If the number of redeemed coins is higher than the number of issued coins, the auditor reports an emergency-by-count. -.. http:get:: /monitoring/emergency-by-count - - Get a list of emergencies by count 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:`EmergencyByCount` objects. - - **Details:** - - .. ts:def:: EmergencyByCount - - interface EmergencyByCount { - - // Row ID of the fee in the exchange database. - row_id : Integer; - - // Hash of the public denomination key to which the - // emergency applies. - denompub_h : HashCode; - - // Number of coins the exchange officially issued of this - // denomination. - num_issued : Integer; - - // Number of coins that were redeemed. - num_known : Integer; - - // What is the total value of all coins of this denomination that - // were put into circulation (and thus the maximum loss the - // exchange may experience due to this emergency). - risk : Amount; - - // When did the exchange start issuing coins in this the denomination. - start : Timestamp; - - // When does the deposit period end for coins of this denomination. - deposit_end : Timestamp; - - // What is the value of an individual coin of this denomination. - value : Amount; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - -.. http:patch:: /monitoring/emergency-by-count/$SERIAL_ID - - This endpoint is used to suppress select elements of emergencies by count. - Update the 'suppressed' field of an emergency by count element with row ID - ``$SERIAL_ID``, according to :ts:type:`GenericAuditorMonitorPatchRequest`, - stored by the auditor. - - **Request:** - - The body must be a `GenericAuditorMonitorPatchRequest`. - - **Response:** +.. include:: auditor/get-monitoring-emergency-by-count.rst - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-emergency-by-count-SERIAL_ID.rst .. _row-inconsistency-list: @@ -524,63 +181,10 @@ if some signature fails to validate. The affected table is noted in the 'table' field. A description of the nature of the inconsistency is noted in 'diagnostic'. -.. http:get:: /monitoring/row-inconsistency - - Get a list of row inconsistencies 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:`RowInconsistency` objects. - - **Details:** - - .. ts:def:: RowInconsistency - - interface RowInconsistency { - - // Number of the affected row. - row_id : Integer; - - // Name of the affected exchange table. - row_table : string; - - // Human-readable diagnostic about what went wrong. - diagnostic : string; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - -.. http:patch:: /monitoring/row-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of row inconsistencies. - Update the 'suppressed' field of a row inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. +.. include:: auditor/get-monitoring-row-inconsistency.rst - **Response:** - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-row-inconsistency-SERIAL_ID.rst .. _reserve-in-inconsistency-list: @@ -595,905 +199,199 @@ either a customer loosing funds (by being issued less digital cash than they should be) or the exchange loosing funds (by issuing a customer more digital cash than they should be). -.. http:get:: /monitoring/reserve-in-inconsistency +.. include:: auditor/get-monitoring-reserve-in-inconsistency.rst - Get a list of reserve in inconsistencies 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. +.. include:: auditor/patch-monitoring-reserve-in-inconsistency-SERIAL_ID.rst - With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed. +.. _purse-not-closed-inconsistencies-list: - **Response:** +Purse Not Closed Inconsistencies +-------------------------------- - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`ReserveInInconsistency` objects. +This section highlights cases, in which either payer or payee did not finish +their part of a P2P payment. This caused a purse --– which may contain some +money --- to reach its expiration date. However, the exchange failed to +properly expire the purse, which means the payer did not get their money back. +The cause is usually that the **taler-exchange-expire** helper is not running +properly. - **Details:** - .. ts:def:: ReserveInInconsistency +.. include:: auditor/get-monitoring-purse-not-closed-inconsistencies.rst - interface ReserveInInconsistency { - // Unique row identifier - row_id : Integer; +.. include:: auditor/patch-monitoring-purse-not-closed-inconsistencies-SERIAL_ID.rst - // Amount the exchange expects to be in the reserve - amount_exchange_expected : Amount; - // Amount deposited into the reserve - amount_wired : Amount; +Early Aggregations +------------------ - // Public key of the reserve - reserve_pub : EddsaPublicKey; +.. _early-aggregation-list: - // Time of the deposit - timestamp : Timestamp; - // Account associated with the reserve - account : string; +This endpoint returns cases in which wire transfers are encountered before their +justifications. This can be harmless, if the justifications appear shortly afterwards. - // Human readable diagnostic of the problem - diagnostic : string; +.. include:: auditor/get-monitoring-early-aggregation.rst - // True if this diagnostic was suppressed. - suppressed : boolean; - } - .. note:: +Pending Deposits +---------------- - This endpoint is still experimental. The endpoint will be further developed as needed. +.. _pending-deposits-list: +This endpoint returns cases in which deposits are pending, that is an +expected wire transfer for a given deposit was not yet found even though +it is past the wire deadline. +This can be harmless, if the wire transfers appear shortly afterwards. +.. include:: auditor/get-monitoring-pending-deposits.rst -.. http:patch:: /monitoring/reserve-in-inconsistency/$SERIAL_ID - This endpoint is used to suppress select elements of reserve in inconsistencies. - Update the 'suppressed' field of a reserve in inconsistency 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:: +.. _reserve-not-closed-inconsistency-list: - This endpoint is still experimental. The endpoint will be further developed as needed. +Reserve Not Closed Inconsistencies +---------------------------------- +This section highlights cases, in which reserves were not closed, despite being expired. +As a result, customers that wired funds to the exchange and then failed to withdraw them +are not getting their money back. The cause is usually that the **taler-exchange-closer** +process is not running properly. -.. _purse-not-closed-inconsistencies-list: +.. include:: auditor/get-monitoring-reserve-not-closed-inconsistency.rst -Purse Not Closed Inconsistencies --------------------------------- -This section highlights cases, in which either payer or payee did not finish -their part of a P2P payment. This caused a purse --– which may contain some -money --- to reach its expiration date. However, the exchange failed to -properly expire the purse, which means the payer did not get their money back. -The cause is usually that the **taler-exchange-expire** helper is not running -properly. -.. http:get:: /monitoring/purse-not-closed-inconsistencies +.. include:: auditor/patch-monitoring-reserve-not-closed-inconsistency-SERIAL_ID.rst - Get a list of purse not closed inconsistencies 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. +.. _reserve-balance-insufficient-inconsistency-list: - With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed. +Reserve Balance Insufficient Inconsistencies +-------------------------------------------- - **Response:** +This section highlights cases where more coins were withdrawn from a +reserve than the reserve contained funding for. This is a serious +compromise resulting in proportional financial losses to the exchange. - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`PurseNotClosedInconsistencies` objects. +.. include:: auditor/get-monitoring-reserve-balance-insufficient-inconsistency.rst - **Details:** - .. ts:def:: PurseNotClosedInconsistencies - interface PurseNotClosedInconsistencies { +.. include:: auditor/patch-monitoring-reserve-balance-insufficient-inconsistency-SERIAL_ID.rst - // Unique row identifier. - row_id : Integer; - // Public key of the affected purse - purse_pub : EddsaPublicKey; +.. _invalid-signature-losses-list: - // Amount still in the purse, which should have been refunded - amount : Amount; +Invalid Signature Losses +------------------------ - // When the purse expired - expiration_date : Timestamp; +This section lists operations that the exchange performed, but for which the +signatures provided are invalid. Hence the operations are invalid and the +amount involved could be a loss for the exchange (as the involved parties +could successfully dispute the resulting transactions). - // True if this diagnostic was suppressed. - suppressed : boolean; +.. include:: auditor/get-monitoring-bad-sig-losses.rst - } - .. note:: +.. include:: auditor/patch-monitoring-bad-sig-losses-SERIAL_ID.rst - This endpoint is still experimental. The endpoint will be further developed as needed. +.. _coin-inconsistency-list: -.. http:patch:: /monitoring/purse-not-closed-inconsistencies/$SERIAL_ID +Coin Inconsistencies +-------------------- - This endpoint is used to suppress select elements of purse not closed - inconsistencies. Update the 'suppressed' field of a purse not closed - inconsistencies element with row ID ``$SERIAL_ID``, according to - :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. +This section lists cases where the exchange made arithmetic errors found when +looking at the transaction history of a coin. The totals sum up the differences +in amounts that matter for profit/loss calculations of the exchange. When an +exchange merely shifted money from customers to merchants (or vice versa) without +any effects on its own balance, those entries are excluded from the total. - **Response:** +.. include:: auditor/get-monitoring-coin-inconsistency.rst - :http:statuscode:`204 No Content`: - The element has been updated. - .. note:: +.. include:: auditor/patch-monitoring-coin-inconsistency-SERIAL_ID.rst - This endpoint is still experimental. The endpoint will be further developed as needed. -Early Aggregations ------------------- -.. _early-aggregation-list: +.. _denominations-without-signatures-list: +Denominations Without Signatures +-------------------------------- -This endpoint returns cases in which wire transfers are encountered before their -justifications. This can be harmless, if the justifications appear shortly afterwards. +This section highlights denomination keys that lack a proper +signature from the **taler-auditor-offline** tool. This may be +legitimate, say in case where the auditor's involvement in the +exchange business is ending and a new auditor is responsible for +future denominations. So this must be read with a keen eye on the +business situation. -.. http:get:: /monitoring/early-aggregation +.. include:: auditor/get-monitoring-denominations-without-sigs.rst - Get a list of early aggregations. - @since protocol **v2**. - The following query parameters are optional, and can be used to customise the response: - **Request:** +.. include:: auditor/patch-monitoring-denominations-without-sigs-SERIAL_ID.rst - :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. +.. _misattribution-in-inconsistency-list: - **Response:** +Misattribution In Inconsistencies +--------------------------------- - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`GetEarlyAggregationResponse` objects. +This section lists cases where the sender account record of an incoming wire +transfer differs between the exchange and the bank. This may cause funds to +be sent to the wrong account should the reserve be closed with a remaining +balance, as that balance would be credited to the original account. - **Details:** +.. include:: auditor/get-monitoring-misattribution-in-inconsistency.rst - .. ts:def:: GetEarlyAggregationResponse - interface GetEarlyAggregationResponse { - // Array of aggregations lacking a justification. - early_aggregations: EarlyAggregationEntry[]; +.. include:: auditor/patch-monitoring-misattribution-in-inconsistency-SERIAL_ID.rst - } - .. ts:def:: EarlyAggregationEntry - interface EarlyAggregationEntry { +.. _deposit-confirmations-list: - // Unique row identifier in the auditor table - row_id : Integer; +Deposit Confirmations +--------------------- - // Row identifier in the exchange's batch deposit table - batch_deposit_serial_id : Integer; +This section contains a list of deposits confirmations that an exchange +provided to merchants but *failed* to store in its own database. This is +indicative of potential fraud by the exchange operator, as the exchange should +only issue deposit confirmations after storing the respective deposit records +in its database. Not storing the deposit data means that the exchange would +not pay the merchant (pocketing the money) or allow the customer to +double-spend the money (which is naturally also not good). - // Row identifier in the exchange's tracking table - tracking_serial_id : Integer; +Note that entries could appear in this list also because the exchange database +replication is delayed. Hence, entries that are only a few seconds old might +not be indicative of an actual problem. If entries in this list are more than +a few seconds old, the first thing to check is whether or not the database +replication from the exchange is working properly. - // Amount that was aggregated early. - balance : Amount; +.. include:: auditor/get-monitoring-deposit-confirmations.rst - // True if this diagnostic was suppressed. - suppressed : boolean; - } +.. include:: auditor/patch-monitoring-deposit-confirmations-SERIAL_ID.rst - .. note:: - This endpoint is still experimental. The endpoint will be further developed as needed. - - - -Pending Deposits ----------------- - -.. _pending-deposits-list: - -This endpoint returns cases in which deposits are pending, that is an -expected wire transfer for a given deposit was not yet found even though -it is past the wire deadline. -This can be harmless, if the wire transfers appear shortly afterwards. - -.. http:get:: /monitoring/pending-deposits - - Get a list of pending deposits. - @since protocol **v2**. - - The following query parameters are optional, and can be used to customise the response: - - **Request:** - - :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. - :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. - :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false. - - With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`GetPendingDepositsResponse` objects. - - **Details:** - - .. ts:def:: GetPendingDepositsResponse - - interface GetPendingDepositsResponse { - - // Array of pending deposits. - pending_deposits: PendingDepositEntry[]; - - } - - .. ts:def:: PendingDepositEntry - - interface PendingDepositEntry { - - // Unique row identifier in the auditor table - row_id : Integer; - - // Row identifier in the exchange's batch deposit table - batch_deposit_serial_id : Integer; - - // Amount that was aggregated early. - total_amount : Amount; - - // Hash of the bank account that should have received the funds. - h_wire : HashCode; - - // When was the deadline for the transfer. - deadline : Timestamp; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - - - - - -.. _reserve-not-closed-inconsistency-list: - -Reserve Not Closed Inconsistencies ----------------------------------- - -This section highlights cases, in which reserves were not closed, despite being expired. -As a result, customers that wired funds to the exchange and then failed to withdraw them -are not getting their money back. The cause is usually that the **taler-exchange-closer** -process is not running properly. - -.. http:get:: /monitoring/reserve-not-closed-inconsistency - - Get a list of reserve not closed inconsistencies 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:`ReserveNotClosedInconsistency` objects. - - - - **Details:** - - .. ts:def:: ReserveNotClosedInconsistency - - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - - - -.. http:patch:: /monitoring/reserve-not-closed-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of reserve not closed - inconsistencies. Update the 'suppressed' field of a reserve not closed - inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. - - - - -.. _reserve-balance-insufficient-inconsistency-list: - -Reserve Balance Insufficient Inconsistencies --------------------------------------------- - -This section highlights cases where more coins were withdrawn from a -reserve than the reserve contained funding for. This is a serious -compromise resulting in proportional financial losses to the exchange. - -.. http:get:: /monitoring/reserve-balance-insufficient-inconsistency - - Get a list of reserve balance insufficient inconsistencies 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:`ReserveBalanceInsufficientInconsistency` objects. - - - - **Details:** - - .. ts:def:: ReserveBalanceInsufficientInconsistency - - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - - - - -.. http:patch:: /monitoring/reserve-balance-insufficient-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of reserve balance insufficient - inconsistencies. Update the 'suppressed' field of a reserve balance - insufficient inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. - - -.. _invalid-signature-losses-list: - -Invalid Signature Losses ------------------------- - -This section lists operations that the exchange performed, but for which the -signatures provided are invalid. Hence the operations are invalid and the -amount involved could be a loss for the exchange (as the involved parties -could successfully dispute the resulting transactions). - -.. http:get:: /monitoring/bad-sig-losses - - Get a list of invalid signature losses 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 operation: A string. If specified, only returns eligible rows with this :ts:type:`BadSigLosses`.operation value. The default value is NULL which means to not filter by operation. - :query op_spec_pub: An EddsaPublicKey (in base32 encoding). If given, use its value to only return rows with this :ts:type:`BadSigLosses`.operation_specific_pub value. 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:`BadSigLosses` objects. - - **Details:** - - .. ts:def:: BadSigLosses - - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - -.. http:patch:: /monitoring/bad-sig-losses/$SERIAL_ID - - This endpoint is used to suppress select elements of bad sig losses. Update the - 'suppressed' field of a bad sig losses 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 endpoint is still experimental. The endpoint will be further developed as needed. - - -.. _coin-inconsistency-list: - -Coin Inconsistencies --------------------- - -This section lists cases where the exchange made arithmetic errors found when -looking at the transaction history of a coin. The totals sum up the differences -in amounts that matter for profit/loss calculations of the exchange. When an -exchange merely shifted money from customers to merchants (or vice versa) without -any effects on its own balance, those entries are excluded from the total. - -.. http:get:: /monitoring/coin-inconsistency - - Get a list of coin inconsistencies 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:`CoinInconsistency` objects. - - **Details:** - - .. ts:def:: CoinInconsistency - - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - -.. http:patch:: /monitoring/coin-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of coin inconsistencies. - Update the 'suppressed' field of a coin inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. - - - - -.. _denominations-without-signatures-list: - -Denominations Without Signatures --------------------------------- - -This section highlights denomination keys that lack a proper -signature from the **taler-auditor-offline** tool. This may be -legitimate, say in case where the auditor's involvement in the -exchange business is ending and a new auditor is responsible for -future denominations. So this must be read with a keen eye on the -business situation. - -.. http:get:: /monitoring/denominations-without-sigs - - Get a list of denominations without signatures 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:`DenominationsWithoutSigs` objects. - - - - **Details:** - - .. ts:def:: DenominationsWithoutSigs - - interface DenominationsWithoutSigs { - - // Unique row identifier - row_id : Integer; - - // Hash of the denomination public key - denompub_h : HashCode; - - // Value of each coin of the denomination that lacks - // the auditor's signature. - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - - -.. http:patch:: /monitoring/denominations-without-sigs/$SERIAL_ID - - This endpoint is used to suppress select elements of denominations without sigs. - Update the 'suppressed' field of a denominations without signatures 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 endpoint is still experimental. The endpoint will be further developed as needed. - - -.. _misattribution-in-inconsistency-list: - -Misattribution In Inconsistencies ---------------------------------- - -This section lists cases where the sender account record of an incoming wire -transfer differs between the exchange and the bank. This may cause funds to -be sent to the wrong account should the reserve be closed with a remaining -balance, as that balance would be credited to the original account. - -.. http:get:: /monitoring/misattribution-in-inconsistency - - Get a list of misattribution in inconsistencies 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:`MisattributionInInconsistency` objects. - - - - **Details:** - - .. ts:def:: MisattributionInInconsistency - - interface MisattributionInInconsistency { - - // Unique row identifier in the exchange database. - row_id : Integer; - - // Amount of money sent to the wrong account - amount : Amount; - - // Row of the transaction in the bank database as - // returned by the bank revenue API. - bank_row : Integer; - - // Public key of the affected reserve - reserve_pub : EddsaPublicKey; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - - -.. http:patch:: /monitoring/misattribution-in-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of misattribution in - inconsistencies. Update the 'suppressed' field of an misattribution in - inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. - - - -.. _deposit-confirmations-list: - -Deposit Confirmations ---------------------- - -This section contains a list of deposits confirmations that an exchange -provided to merchants but *failed* to store in its own database. This is -indicative of potential fraud by the exchange operator, as the exchange should -only issue deposit confirmations after storing the respective deposit records -in its database. Not storing the deposit data means that the exchange would -not pay the merchant (pocketing the money) or allow the customer to -double-spend the money (which is naturally also not good). - -Note that entries could appear in this list also because the exchange database -replication is delayed. Hence, entries that are only a few seconds old might -not be indicative of an actual problem. If entries in this list are more than -a few seconds old, the first thing to check is whether or not the database -replication from the exchange is working properly. - -.. http:get:: /monitoring/deposit-confirmations - - Get a list of deposit confirmations 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:`DepositConfirmations` objects. - - **Details:** - - .. ts:def:: DepositConfirmations - - 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; - - // 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. - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - -.. http:patch:: /monitoring/deposit-confirmations/$SERIAL_ID - - This endpoint is used to suppress select elements of deposit confirmations. - Update the 'suppressed' field of an deposit confirmations 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 endpoint is still experimental. The endpoint will be further developed as needed. - - -.. _denomination-key-validity-withdraw-inconsistency-list: +.. _denomination-key-validity-withdraw-inconsistency-list: Denomination Key Validity Withdraw Inconsistencies -------------------------------------------------- @@ -1504,226 +402,50 @@ 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:** - - :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:`DenominationKeyValidityWithdrawInconsistency` objects. If no elements could be found, an empty array is returned - - - **Details:** - - .. ts:def:: DenominationKeyValidityWithdrawInconsistency +.. include:: auditor/get-monitoring-denomination-key-validity-withdraw-inconsistency.rst - interface DenominationKeyValidityWithdrawInconsistency { - - // Unique row identifier - row_id : Integer; - - // When the withdrawal took place - execution_date : Timestamp; - - // Public key of the reserve affected - reserve_pub : EddsaPublicKey; - - // Hash of the denomination public key involved in the withdrawal - denompub_h : HashCode; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - -.. http:patch:: /monitoring/denomination-key-validity-withdraw-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of denomination key validity withdraw inconsistencies. - Update the 'suppressed' field of a denomination key validity withdraw inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-denomination-key-validity-withdraw-inconsistency-SERIAL_ID.rst .. _amount-arithmetic-inconsistency-list: Amount Arithmetic Inconsistencies --------------------------------- -This endpoint is used to obtain a list of amount arithmetic inconsistencies. - -This section lists cases where the arithmetic of the exchange involving -amounts disagrees with the arithmetic of the auditor. Disagreements imply -that either the exchange made a loss (sending out too much money), or screwed -a customer (and thus at least needs to fix the financial damage done to the -customer). The profitable column is set to true if the arithmetic problem was -be determined to be profitable for the exchange, false if the problem resulted -in a net loss for the exchange. - - -.. http:get:: /monitoring/amount-arithmetic-inconsistency - - Get a list of amount arithmetic inconsistencies 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:`AmountArithmeticInconsistency` objects. If no elements could be found, an empty array is returned - - - - **Details:** - - .. ts:def:: AmountArithmeticInconsistency - - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - -.. http:patch:: /monitoring/amount-arithmetic-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of amount arithmetic inconsistencies. Update the 'suppressed' field of an amount arithmetic inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. - - -.. _wire-format-inconsistency-list: - -Wire Format Inconsistencies ---------------------------- - -This section highlights cases where the wire transfer subject -was used more than once and is thus not unique. This indicates -a problem with the bank's implementation of the revenue API, as -the bank is supposed to warrant uniqueness of wire transfer -subjects exposed via the revenue API (and bounce non-unique -transfers). - -.. 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: - - **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:`WireFormatInconsistency` objects. If no elements could be found, an empty array is returned - - - **Details:** - - .. ts:def:: WireFormatInconsistency - - interface WireFormatInconsistency { - - // Unique row identifier - row_id : Integer; - - // Amount that was part of the wire - amount : Amount; - - // Offset of the duplicate wire transfer subject - // in the bank database according to the revenue API. - wire_offset : Integer; - - // True if this diagnostic was suppressed. - diagnostic : string; +This endpoint is used to obtain a list of amount arithmetic inconsistencies. - // True if this diagnostic was suppressed. - suppressed : boolean; +This section lists cases where the arithmetic of the exchange involving +amounts disagrees with the arithmetic of the auditor. Disagreements imply +that either the exchange made a loss (sending out too much money), or screwed +a customer (and thus at least needs to fix the financial damage done to the +customer). The profitable column is set to true if the arithmetic problem was +be determined to be profitable for the exchange, false if the problem resulted +in a net loss for the exchange. - } +.. include:: auditor/get-monitoring-amount-arithmetic-inconsistency.rst - .. note:: - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-amount-arithmetic-inconsistency-SERIAL_ID.rst +.. _wire-format-inconsistency-list: +Wire Format Inconsistencies +--------------------------- -.. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID +This section highlights cases where the wire transfer subject +was used more than once and is thus not unique. This indicates +a problem with the bank's implementation of the revenue API, as +the bank is supposed to warrant uniqueness of wire transfer +subjects exposed via the revenue API (and bounce non-unique +transfers). - This endpoint is used to suppress select elements of wire format inconsistencies. - Update the 'suppressed' field of a wire format inconsistency element with row_id $SERIAL_ID, according to :ts:type:`GenericAuditorMonitorPatchRequest`, stored by the auditor. +.. include:: auditor/get-monitoring-wire-format-inconsistency.rst - **Response:** - :http:statuscode:`204 No Content`: - The element has been updated. - .. note:: - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-wire-format-inconsistency-SERIAL_ID.rst .. _closure-lags-list: @@ -1743,73 +465,10 @@ If closure lag is experienced, the administrator should check that the **taler-exchange-closer** component is operating correctly. -.. http:get:: /monitoring/closure-lags - - Get a list of closure lags 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:`ClosureLags` objects. If no elements could be found, an empty array is returned - - - - **Details:** - - .. ts:def:: ClosureLags - - interface ClosureLags { +.. include:: auditor/get-monitoring-closure-lags.rst - // Unique row identifier - row_id : Integer; - // Amount of money left in the reserve - amount : Amount; - - // When should the reserve have been closed - deadline : Timestamp; - - // The wire transfer identifier - wtid : HashCode; - - // Full payto:// URI (RFC 8905) of the account that - // should have been credited. - account : string; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - - -.. http:patch:: /monitoring/closure-lags/$SERIAL_ID - - This endpoint is used to suppress select elements of closure lags. - 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 endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-closure-lags-SERIAL_ID.rst @@ -1822,72 +481,13 @@ Wire Out Inconsistencies This section highlights cases where the exchange wired a different amount to a destimation account than the auditor expected. -.. http:get:: /monitoring/wire-out-inconsistency - - 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: - - **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:`WireOutInconsistency` objects. If no elements could be found, an empty array is returned - - - - **Details:** - - .. ts:def:: WireOutInconsistency - - interface WireOutInconsistency { - - // Unique row identifier - row_id : Integer; - - // Account money was wired to - destination_account : string; - - // How much was suppossed to be wired according to the auditor. - expected : Amount; - - // The amount the exchange claims to have wired. - claimed : Amount; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - +.. include:: auditor/get-monitoring-wire-out-inconsistency.rst -.. http:patch:: /monitoring/wire-out-inconsistency/$SERIAL_ID - This endpoint is used to suppress select elements of wire out inconsistencies. - 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:** - - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-wire-out-inconsistency-SERIAL_ID.rst .. _reserve-balance-summary-wrong-inconsistency-list: @@ -1898,65 +498,9 @@ Reserve Balance Summary Wrong Inconsistencies This section highlights cases, where the exchange's and auditors' expectation of the amount of money left in a reserve differs. -.. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency - - 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: - - **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:`ReserveBalanceSummaryWrongInconsistency` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: ReserveBalanceSummaryWrongInconsistency - - interface ReserveBalanceSummaryWrongInconsistency { - - // Unique row identifier - row_id : Integer; - - // Public key of the reserve affected - reserve_pub : EddsaPublicKey; - - // Amount of summary the exchange calculated - exchange_amount : Amount; - - // Amount of summary the auditor calculated - auditor_amount : Amount; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/get-monitoring-reserve-balance-summary-wrong-inconsistency.rst -.. http:patch:: /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID - - This endpoint is used to suppress select elements of reserve balance summary wrong inconsistencies. - 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:** - - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-reserve-balance-summary-wrong-inconsistency-SERIAL_ID.rst .. _row-minor-inconsistencies-list: @@ -1969,62 +513,9 @@ value that is does not satisfy expectations (such as a malformed signature). These are cause for concern, but not necessarily point to a monetary loss (yet). -.. http:get:: /monitoring/row-minor-inconsistencies - - 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: - - **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:`RowMinorInconsistencies` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: RowMinorInconsistencies - - interface RowMinorInconsistencies { - - // Number of the row in the affected table - row_id : Integer; +.. include:: auditor/get-monitoring-row-minor-inconsistencies.rst - // The row number in the affected table - row_table : Integer; - - // Human readable string describing the problem - diagnostic : string; - - // True if this diagnostic was suppressed. - suppressed : boolean; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. - -.. http:patch:: /monitoring/row-minor-inconsistencies/$SERIAL_ID - - This endpoint is used to suppress select elements of row minor inconsistencies. - 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:** - - :http:statuscode:`204 No Content`: - The element has been updated. - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/patch-monitoring-row-minor-inconsistencies-SERIAL_ID.rst ------------------------- @@ -2044,34 +535,7 @@ Balances Returns the various balances the auditor tracks for the exchange, such as coins in circulation, fees earned, losses experienced, etc. -.. 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 balance_key: a string identifying a balance. If specified, only returns the balance with this exact key. The default value is NULL. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`Balances` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: Balances - - interface Balances { - - // String identifying a balance - balance_key : string; - - // Amount of the balance - balance_value : Amount; - - } +.. include:: auditor/get-monitoring-balances.rst .. _historic-denomination-revenue-list: @@ -2084,55 +548,7 @@ is the profits and losses an exchange has made from coins of a particular denomination where the denomination is past its (deposit) expiration and thus all values are final. -.. http:get:: /monitoring/historic-denomination-revenue - - 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: - - **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. - - With the default settings, the endpoint returns at most the 20 latest elements. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`HistoricDenominationRevenue` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: HistoricDenominationRevenue - - interface HistoricDenominationRevenue { - - // Unique row identifier - row_id : Integer; - - // Hash code of the denomination public key involved - denom_pub_hash : HashCode; - - // Time when the denomination expired and thus the revenue - // was computed. - revenue_timestamp : Timestamp; - - // Total fee revenue the exchange earned from coins of this - // denomination. - revenue_balance : Amount; - - // Total losses the exchange experienced from this denomination - // (this basically only happens if someone was able to forge - // denomination signatures). So non-zero values are indicative - // of a serious problem. - loss_balance : Amount; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/get-monitoring-historic-denomination-revenue.rst .. _denomination-pending-list: @@ -2143,63 +559,7 @@ This endpoint is used to obtain a list of balances for denominations that are st active, that is coins may still be deposited (or possibly even withdrawn) and thus the amounts given are not final. -.. http:get:: /monitoring/denomination-pending - - Get a list of denomination pending 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. - - With the default settings, the endpoint returns at most the 20 latest elements. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`DenominationPending` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: DenominationPending - - interface DenominationPending { - - // Unique row identifier - row_id : Integer; - - // Hash of the denomination public key - denom_pub_hash : HashCode; - - // Total value of coins remaining in circulation (excluding - // the value of coins that were recouped, those are always - // just under recoup_loss). - denom_balance : Amount; - - // Total value of coins redeemed that exceeds the amount we - // put into circulation. Basically, this value grows if we - // wanted to reduce denom_balance (because a coin was deposited) - // but we could not because the denom_balance was already zero. - denom_loss : Amount; - - // Total number of coins of this denomination that were - // put into circulation. - num_issued : Integer; - - // Total value of the coins put into circulation. - denom_risk : Amount; - - // Losses the exchange had from this denomination due to coins - // that were recouped (after the denomination was revoked). - recoup_loss : Amount; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/get-monitoring-denomination-pending.rst .. _historic-reserve-summary-list: @@ -2211,47 +571,7 @@ This section summarizes historic profits an exchange made from reserves and associated reserve-specific fees. -.. http:get:: /monitoring/historic-reserve-summary - - 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: - - **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. - - With the default settings, the endpoint returns at most the 20 latest elements. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`HistoricReserveSummary` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: HistoricReserveSummary - - 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; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/get-monitoring-historic-reserve-summary.rst .. _reserves-list: @@ -2263,75 +583,7 @@ Reserves This endpoint is used to obtain a list of open reserves that the auditor is currently tracking balances for. -.. 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. - - - With the default settings, the endpoint returns at most the 20 latest elements. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`Reserves` objects. If no elements could be found, an empty array is returned - - - **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; - - // Reserve losses are incurred if (a) a reserve is - // incorrectly credited from a recoup for a non-revoked - // coin, or (b) if the exchange allowed more digital cash - // to be withdrawn from a reserve than the balance of the - // reserve should have permitted. FIXME: We may want to - // distinguish these two cases in the future. - 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; - - // Total purse fees earned from this reserve - purse_fee_balance : Amount; - - // Total reserve open fees earned from the reserve - open_fee_balance : Amount; - - // Total reserve history fees earned from this reserve - history_fee_balance : Amount; - - // When the purse expires - expiration_date : Timestamp; - - // Who created the account - origin_account : string; - - } - - .. note:: - - This endpoint is still experimental. The endpoint will be further developed as needed. +.. include:: auditor/get-monitoring-reserves.rst .. _purses-list: @@ -2341,85 +593,14 @@ Purses This endpoint is used to obtain information about open purses. -.. 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. - - With the default settings, the endpoint returns at most the 20 latest elements. - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`Purses` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: Purses - - 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 endpoint is still experimental. The endpoint will be further developed as needed. - - .. _progress-list: +.. include:: auditor/get-monitoring-purses.rst Progress -------- This section contains information about the auditing progress an auditor has made. -.. http:get:: /monitoring/progress - - Get the progress stored by the auditor. - - **Request:** - - :query progress_key: a string identifying a progress point. If specified, only returns the element with this exact key. The default value is NULL. - - - **Response:** - - :http:statuscode:`200 OK`: - The auditor responds with a top level array of :ts:type:`Progress` objects. If no elements could be found, an empty array is returned - - **Details:** - - .. ts:def:: Progress - - interface Progress { - - // Key associated with a given progress point - progress_key: string; - - // How much of the exchanges data has been processed so far - progress_offset: Integer; - - } +.. include:: auditor/get-monitoring-progress.rst ---------- Complaints @@ -2432,6 +613,6 @@ misbehavior of an exchange to the auditor. To be designed and implemented. -.. http:put:: /complain +.. include:: auditor/put-complain.rst Complain about misbehavior to the auditor. diff --git a/core/api-donau.rst b/core/api-donau.rst @@ -63,159 +63,11 @@ required to process all of the other interactions with the Donau. The returned information is secured by signature(s) from the Donau, especially the long-term offline signing key of the Donau, which clients should cache. -.. http:get:: /keys +.. include:: donau/get-keys.rst - Get a list of all donation units keys offered by the Donau, - as well as the Donau's current online signing key (used for donation statements). +.. include:: donau/get-seed.rst - **Request:** - - **Response:** - - :http:statuscode:`200 OK`: - The Donau responds with a `DonauKeysResponse` object. This request should - virtually always be successful. It only fails if the Donau is misconfigured. - - **Details:** - - .. ts:def:: DonauKeysResponse - - interface DonauKeysResponse { - // libtool-style representation of the Donau protocol version, see - // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning - // The format is "current:revision:age". - version: string; - - // Legal/financial domain this Donau operates for. Shown to the - // user by the wallet when selecting a Donau. Should match the - // name of the financial authority that the user would recognize. - legal_domain: string; - - // The Donau's base URL. - base_url: string; - - // The Donau's currency. - currency: string; - - // Donation units offered by this Donau. Each entry enumerates a - // specific key together with its value and status. - donation_units: DonationUnit[]; - - // The Donau's signing keys. - signkeys: SignKey[]; - - } - - .. ts:def:: DonationUnit - - interface DonationUnit extends DonationUnitKeyCommon { - // How much a receipt signed with this key is worth. - value: Amount; - - // Public key material of the donation unit. - donation_unit_pub: DonationUnitKey; - } - - .. ts:def:: DonationUnitKeyCommon - - interface DonationUnitKeyCommon { - - // For which year is this donation unit key valid. - year: Integer; - - // Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not - // revoked, but still cannot be used to withdraw receipts at this time (theoretically, - // the private key could be recovered in the future; receipts signed with the private key - // remain valid). - lost?: boolean; - } - - .. ts:def:: DonationUnitKey - - type DonationUnitKey = - | RsaDonationUnitKey - | CSDonationUnitKey; - - .. ts:def:: RsaDonationUnitKey - - interface RsaDonationUnitKey { - cipher: "RSA"; - - // RSA public key - rsa_public_key: RsaPublicKey; - - // Hash of the RSA public key, as used in other API calls. - pub_key_hash: HashCode; - } - - .. ts:def:: CSDonationUnitKey - - interface CSDonationUnitKey { - cipher: "CS"; - - // Public key of the donation unit. - cs_public_key: Cs25519Point; - - // Hash of the CS public key, as used in other API calls. - pub_key_hash: HashCode; - } - - A signing key in the ``signkeys`` list is a JSON object with the following fields: - - .. ts:def:: SignKey - - interface SignKey { - // The actual Donau's EdDSA signing public key. - key: EddsaPublicKey; - - // Initial validity date for the signing key. - year: Integer; - - } - - - .. note:: - - Both the individual donation units *and* the donation units list is signed, - allowing customers to prove that they received an inconsistent list. - -.. http:get:: /seed - - Return an entropy seed. The Donau will return a high-entropy - value that will differ for every call. The response is NOT in - JSON, but simply high-entropy binary data in the HTTP body. - This API should be used by wallets to guard themselves against - running on low-entropy (bad PRNG) hardware. Naturally, the entropy - returned MUST be mixed with locally generated entropy. - -.. http:get:: /config - - Return the protocol version, financial domain and currency supported by this - Donau backend. - - **Response:** - - :http:statuscode:`200 OK`: - The body is a `DonauVersionResponse`. - - .. ts:def:: DonauVersionResponse - - interface DonauVersionResponse { - // libtool-style representation of the Donau protocol version, see - // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning - // The format is "current:revision:age". - version: string; - - // Name of the protocol. - name: "donau"; - - // Currency supported by this Donau. - currency: string; - - // Financial domain by this Donau. - domain: string; - - } +.. include:: donau/get-config.rst .. _donau_issue: @@ -232,72 +84,7 @@ Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donatio CSR Issue ~~~~~~~~~~~ -.. http:post:: /csr-issue - - Obtain donau-side input values in preparation for a - issue receipt step for certain donation unit cipher types, - specifically at this point for Clause-Schnorr blind - signatures. This API is used by the donor. - - **Request:** The request body must be a `IssuePrepareRequest` object. - - **Response:** - - :http:statuscode:`200 OK`: - The request was successful, and the response is a `IssuePrepareResponse`. Note that repeating exactly the same request - will again yield the same response (assuming none of the donation unit is expired). - :http:statuscode:`404 Not found`: - The donation unit key is not known to the donau. - :http:statuscode:`410 Gone`: - The requested donation unit key is not yet or no longer valid. It either before the validity year, past the - year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to - understand which of the cases this is and handle it accordingly. - - **Details:** - - .. ts:def:: IssuePrepareRequest - - interface IssuePrepareRequest { - - // Nonce to be used by the donau to derive - // its private inputs from. Must not have ever - // been used before. - nonce: CSNonce; - - // Hash of the public key of the donation unit - // the request relates to. - du_pub_hash: HashCode; - - } - - .. ts:def:: IssuePrepareResponse - - type IssuePrepareResponse = - | DonauIssueValue; - - .. ts:def:: DonauIssueValue - - type DonauIssueValue = - | DonauRsaIssueValue - | DonauCsIssueValue; - - .. ts:def:: DonauRsaIssueValue - - interface DonauRsaIssueValue { - cipher: "RSA"; - } - - .. ts:def:: DonauCsIssueValue - - interface DonauCsIssueValue { - cipher: "CS"; - - // CSR R0 value - r_pub_0: CSRPublic; - - // CSR R1 value - r_pub_1: CSRPublic; - } +.. include:: donau/post-csr-issue.rst Batch Issue @@ -310,154 +97,7 @@ This API is used by the charity but the array of `BlindedDonationReceiptKeyPair` To make the request idempotent, the hash of the hole request is recorded under the corresponding charity_id by the Donau. -.. http:POST:: /batch-issue/$CHARITY_ID - - Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained BUDIs. - - **Request:** `IssueReceiptsRequest` - - **Response:** - - :http:statuscode:`200 OK`: - The request was successful, and the response is a `BlindedDonationReceiptSignaturesResponse`. - :http:statuscode:`403 Forbidden`: - The charity signature is invalid. This response comes with a standard `ErrorDetail` response. - :http:statuscode:`404 Not found`: - At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`. - This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`. - :http:statuscode:`409 Conflict`: - The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis. - The response is a `IssueError` object. - :http:statuscode:`410 Gone`: - The requested donation unit key is not yet or no longer valid. It either before the validity year, past the - year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code - provided to understand which of the cases this is and handle it accordingly. - - **Details:** - - .. ts:def:: IssueReceiptsRequest - - interface IssueReceiptsRequest { - - // Signature by the charity approving that the - // Donau should sign the donation receipts below. - charity_sig: EddsaSignature; - - // Year for which the donation receipts are expected. - // Also determines which keys are used to sign the - // blinded donation receipts. - year: Integer; - - // Array of blinded donation receipts to sign. - // Must NOT be empty (if no donation receipts - // are desired, just leave the entire ``donau`` - // argument blank). - budikeypairs: BlindedDonationReceiptKeyPair[]; - } - - .. ts:def:: BlindedDonationReceiptKeyPair - - interface BlindedDonationReceiptKeyPair { - // Hash of the public key that should be used to sign - // the donation receipt. - h_donation_unit_pub: HashCode; - - // Blinded value to give to the Donau to sign over. - blinded_udi: BlindedUniqueDonationIdentifier; - } - - .. ts:def:: BlindedUniqueDonationIdentifier - - type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ; - - .. ts:def:: RSABUDI - - interface RSABUDI { - cipher: "RSA"; - rsa_blinded_identifier: string; // Crockford Base32 encoded - } - - .. ts:def:: CSBUDI - - // For donation unit signatures based on Blind Clause-Schnorr, the BUDI - // consists of the public nonce and two Curve25519 scalars which are two - // blinded challenges in the Blinded Clause-Schnorr signature scheme. - // See https://taler.net/papers/cs-thesis.pdf for details. - interface CSBUDI { - cipher: "CS"; - cs_nonce: string; // Crockford Base32 encoded - cs_blinded_c0: string; // Crockford Base32 encoded - cs_blinded_c1: string; // Crockford Base32 encoded - } - - .. ts:def:: BUDIBlindingKeyP - - // Secret for blinding/unblinding. - // An RSA blinding secret, which is basically - // a 256-bit nonce, converted to Crockford Base32. - type BUDIBlindingKeyP = string; - - .. ts:def:: BlindedDonationReceiptSignaturesResponse - - interface BlindedDonationReceiptSignaturesResponse { - // Total amount over which all the blind signatures are signing. - issued_amount: Amount; - - // Array of the blind signatures. - blind_signatures: BlindedDonationReceiptSignature[]; - } - - .. ts:def:: BlindedDonationReceiptSignature - - type BlindedDonationReceiptSignature = - | RSABlindedDonationReceiptSignature - | CSBlindedDonationReceiptSignature; - - .. ts:def:: RSABlindedDonationReceiptSignature - - interface RSABlindedDonationReceiptSignature { - cipher: "RSA"; - - // (blinded) RSA signature - blinded_rsa_signature: BlindedRsaSignature; - } - - .. ts:def:: CSBlindedDonationReceiptSignature - - interface CSBlindedDonationReceiptSignature { - cipher: "CS"; - - // Signer chosen bit value, 0 or 1, used - // in Clause Blind Schnorr to make the - // ROS problem harder. - b: Integer; - - // Blinded scalar calculated from c_b. - s: Cs25519Scalar; - } - - .. ts:def:: IssueError - - interface IssueError{ - max_per_year: Amount; - current_year: Amount; - } - - .. ts:def:: DonationUnitUnknownError - - interface DonationUnitUnknownError{ - unknown_hash_pub_donation_unit: HashCode[]; - donau_pub: EddsaPublicKey; - donau_sig: EddsaSignature; - } - - .. ts:def:: DonationUnitExpiredMessage - - interface DonationUnitExpiredMessage{ - h_donation_unit_pub: HashCode; - donau_pub: EddsaPublicKey; - donau_sig: EddsaSignature; - } +.. include:: donau/post-batch-issue-CHARITY_ID.rst .. _donation_statement: @@ -469,96 +109,9 @@ Inspired by the Taler exchange :ref:`Deposit<deposit-par>`. Donation statement operations are requested by a donor. -.. http:POST:: /batch-submit - - Send in donation receipts for the current or one of the past fiscal years. - The donor will reveive the signed total back, which is called the - donation statement. - - **Request:** `SubmitDonationReceiptsRequest` - - **Response:** - - :http:statuscode:`201 Created`: - The request was successful, and a donation statement is now available. The response will be empty. - :http:statuscode:`403 Forbidden`: - One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. - :http:statuscode:`404 Not found`: - At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`. - - **Details:** - - .. ts:def:: SubmitDonationReceiptsRequest - - interface SubmitDonationReceiptsRequest{ - // hashed taxpayer ID plus salt - h_donor_tax_id: HashCode; - // All donation receipts must be for this year. - donation_year: Integer; - // Receipts should be sorted by amount. - donation_receipts: DonationReceipt[]; - } - - .. ts:def:: DonationReceipt - - interface DonationReceipt { - h_donation_unit_pub: HashCode; - nonce: string; - donation_unit_sig: DonationReceiptSignature; - } - - .. ts:def:: DonationReceiptSignature - - type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ; +.. include:: donau/post-batch-submit.rst - .. ts:def:: RSADonationReceiptSignature - - interface RSADonationReceiptSignature { - cipher: "RSA"; - - // RSA signature - rsa_signature: RsaSignature; - } - - .. ts:def:: CSDonationReceiptSignature - - interface CSDonationReceiptSignature { - cipher: "CS"; - - // R value component of the signature. - cs_signature_r: Cs25519Point; - - // s value component of the signature. - cs_signature_s: Cs25519Scalar; - } - -.. http:GET:: /donation-statement/$YEAR/$HASH_DONOR_ID - - Get the donation statement for a specific year and donor. - - **Request:** - - **Response:** - - :http:statuscode:`200 OK`: - The request was successful, and the response is a `DonationStatementResponse`. - :http:statuscode:`403 Forbidden`: - One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. - :http:statuscode:`404 Not found`: - Either the donor or the year or the corresponding donation statement was not found. - This response comes with a standard `ErrorDetail` response. - - **Details:** - - .. ts:def:: DonationStatementResponse - - interface DonationStatementResponse { - total: Amount; - // signature over h_donor_tax_id, total, donation_year - donation_statement_sig: EddsaSignature; - // the corresponding public key to the signature - donau_pub: EddsaPublicKey; - } +.. include:: donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst .. _donau_charity: @@ -569,186 +122,16 @@ Charity administration and status information The administration requests require an authorized bearer token to be set in the HTTP "Authorization" Header. This token can be set by a proxy validating authentication/authorization (using e.g. LDAP). The GET status requests require an authorized bearer token as well. -.. http:GET:: /charities - - GET all charities. Only allowed if the request comes with the administration bearer token. - - return all charities - - **Request:** - - **Reponse:** - - :http:statuscode:`200 OK`: - The request was successful, and the response is a `Charities`. - - **Details:** - - .. ts:def:: Charities - - interface Charities{ - charities: CharitySummary[]; - } - - .. ts:def:: CharitySummary - - interface CharitySummary { - - // Unique ID of the charity within the Donau. - charity_id: Integer; - - // Public key of the charity, used by the charity to - // authorize issuing donation receipts. - charity_pub: EddsaPublicKey; - - // Human-readable name of the charity. - charity_name: string; - - // Maximum amount of donation receipts this charity is - // allowed to issue per year. - max_per_year: Amount; - - // Year for which ``receipts_to_date`` is given. - current_year: Integer; - - // Total amount of donation receipts the donau has - // issued for this charity so far this year. - receipts_to_date: Amount; - } +.. include:: donau/get-charities.rst .. _donau_charity_get: -.. http:get:: /charity/$CHARITY_ID - - Request information about a specific charity. - Only allowed if the request comes with a signature by - the respective charity. - - **Request:** - - *Charity-Signature*: - - The client must provide Base-32 encoded EdDSA signature with - ``$CHARITY_PRIV``, affirming the desire to obtain the charity status. - Note that this is merely a simple authentication mechanism, - the details of the request are not protected by the signature. - The ``$CHARITY_PRIV`` is usually the merchant instance - private key. - - **Response:** - - :http:statuscode:`200 OK`: - The Donau responds with a `Charity` object - :http:statuscode:`404 Not found`: - The charity id does not belong to a charity known to the Donau. - - .. ts:def:: Charity - - interface Charity { - charity_pub: EddsaPublicKey; - name: string; - url: string; - max_per_year: Amount; - receipts_to_date: Amount; - current_year: Integer; - } - -.. http:POST:: /charities - - Register a new charity with the Donau. Only allowed if the request comes with the - administrator bearer token. The request body defines the charity's signing key, - contact information, and the initial accounting values for the current business - year. On success the Donau assigns a numeric identifier to the charity record. - - **Request:** `CharityRequest` - - **Response:** - - **Details:** - - :http:statuscode:`201 Created`: - The request was successful, and the response is a `CharityResponse`. - - :http:statuscode:`403 Forbidden`: - The request did not contain an accepted administrator bearer token in its header. - - :http:statuscode:`404 Not found`: - The referenced resource needed to create the charity was not found. This response - comes with a standard `ErrorDetail` response. - - :http:statuscode:`409 Conflict`: - A charity with the same public key exists in the backend, but it - has different details. This response - comes with a standard `ErrorDetail` response. - - .. ts:def:: CharityRequest - - interface CharityRequest { - - // Long-term EdDSA public key that identifies the charity. - charity_pub: EddsaPublicKey; - - // Canonical URL that should be presented to donors. - charity_url: string; - - // Human-readable display name of the charity. - charity_name: string; - - // Allowed donation volume for the charity per calendar year. - max_per_year: Amount; - } - - .. ts:def:: CharityResponse - - interface CharityResponse { - - // Unique ID assigned to the charity in the backend. - charity_id: Integer; - } - - -.. http:PATCH:: /charities/{charity_id} - - Modify a charity. - Only allowed if the request comes with the administrator bearer token. - - **Request:** ``CharityRequest`` - - **Response:** - - :http:statuscode:`200 OK`: - The update succeeded. The response body is empty. - - :http:statuscode:`400 Bad Request`: - The request was malformed. For example, ``max_per_year`` must not be - smaller than the current ``receipts_to_date`` of the charity. - - :http:statuscode:`401 Unauthorized`: - Missing or invalid bearer token. - - :http:statuscode:`403 Forbidden`: - The request did not contain an accepted administrator bearer token in its header. - - :http:statuscode:`404 Not Found`: - The charity ID is unknown to the Donau. - - **Details:** - - The request body has the same shape as :ts:type:`CharityRequest` used by - :http:POST:`/charities`. All fields are required and will replace the stored - values of the charity. - - -.. http:DELETE:: /charities/{charity_id} +.. include:: donau/get-charity-CHARITY_ID.rst - Delete (or deactivate) a charity. Only allowed if the request comes with the administrator bearer token. +.. include:: donau/post-charities.rst - **Request:** - **Response:** +.. include:: donau/patch-charities-{charity_id}.rst - :http:statuscode:`204 No content`: - The request was successful. - :http:statuscode:`403 Forbidden`: - The request did not contain an accepted administrator bearer token in it's header. +.. include:: donau/delete-charities-{charity_id}.rst diff --git a/core/auditor/get-config.rst b/core/auditor/get-config.rst @@ -0,0 +1,42 @@ +.. http:get:: /config + + Get the protocol version and some meta data about the auditor. + This specification corresponds to ``current`` protocol being version **v2**. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with an `AuditorVersion`_ object. This request should + virtually always be successful. + + **Details:** + + .. _AuditorVersion: + .. code-block:: tsref + + interface AuditorVersion { + // libtool-style representation of the Taler protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". Note that the auditor + // protocol is versioned independently of the exchange's protocol. + version: string; + + // URN of the implementation (needed to interpret 'revision' in version). + // @since v0, may become mandatory in the future. + implementation?: string; + + // Return which currency this auditor is auditing for. + currency: string; + + // EdDSA master public key of the auditor. + auditor_public_key: EddsaPublicKey; + + // EdDSA master public key of the exchange. + // Added in protocol v1. + exchange_master_public_key: EddsaPublicKey; + } + + .. note:: + + This endpoint is still experimental (and is not yet implemented at the + time of this writing). diff --git a/core/auditor/get-monitoring-amount-arithmetic-inconsistency.rst b/core/auditor/get-monitoring-amount-arithmetic-inconsistency.rst @@ -0,0 +1,51 @@ +.. http:get:: /monitoring/amount-arithmetic-inconsistency + + Get a list of amount arithmetic inconsistencies 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:`AmountArithmeticInconsistency` objects. If no elements could be found, an empty array is returned + + + + **Details:** + + .. ts:def:: AmountArithmeticInconsistency + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-bad-sig-losses.rst b/core/auditor/get-monitoring-bad-sig-losses.rst @@ -0,0 +1,47 @@ +.. http:get:: /monitoring/bad-sig-losses + + Get a list of invalid signature losses 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 operation: A string. If specified, only returns eligible rows with this :ts:type:`BadSigLosses`.operation value. The default value is NULL which means to not filter by operation. + :query op_spec_pub: An EddsaPublicKey (in base32 encoding). If given, use its value to only return rows with this :ts:type:`BadSigLosses`.operation_specific_pub value. 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:`BadSigLosses` objects. + + **Details:** + + .. ts:def:: BadSigLosses + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-balances.rst b/core/auditor/get-monitoring-balances.rst @@ -0,0 +1,28 @@ +.. 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 balance_key: a string identifying a balance. If specified, only returns the balance with this exact key. The default value is NULL. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`Balances` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: Balances + + interface Balances { + + // String identifying a balance + balance_key : string; + + // Amount of the balance + balance_value : Amount; + + } diff --git a/core/auditor/get-monitoring-closure-lags.rst b/core/auditor/get-monitoring-closure-lags.rst @@ -0,0 +1,52 @@ +.. http:get:: /monitoring/closure-lags + + Get a list of closure lags 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:`ClosureLags` objects. If no elements could be found, an empty array is returned + + + + **Details:** + + .. ts:def:: ClosureLags + + interface ClosureLags { + + // Unique row identifier + row_id : Integer; + + // Amount of money left in the reserve + amount : Amount; + + // When should the reserve have been closed + deadline : Timestamp; + + // The wire transfer identifier + wtid : HashCode; + + // Full payto:// URI (RFC 8905) of the account that + // should have been credited. + account : string; + + // 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/get-monitoring-coin-inconsistency.rst b/core/auditor/get-monitoring-coin-inconsistency.rst @@ -0,0 +1,52 @@ +.. http:get:: /monitoring/coin-inconsistency + + Get a list of coin inconsistencies 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:`CoinInconsistency` objects. + + **Details:** + + .. ts:def:: CoinInconsistency + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-denomination-key-validity-withdraw-inconsistency.rst b/core/auditor/get-monitoring-denomination-key-validity-withdraw-inconsistency.rst @@ -0,0 +1,45 @@ +.. 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:** + + :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:`DenominationKeyValidityWithdrawInconsistency` objects. If no elements could be found, an empty array is returned + + + **Details:** + + .. ts:def:: DenominationKeyValidityWithdrawInconsistency + + interface DenominationKeyValidityWithdrawInconsistency { + + // Unique row identifier + row_id : Integer; + + // When the withdrawal took place + execution_date : Timestamp; + + // Public key of the reserve affected + reserve_pub : EddsaPublicKey; + + // Hash of the denomination public key involved in the withdrawal + denompub_h : HashCode; + + // 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/get-monitoring-denomination-pending.rst b/core/auditor/get-monitoring-denomination-pending.rst @@ -0,0 +1,57 @@ +.. http:get:: /monitoring/denomination-pending + + Get a list of denomination pending 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. + + With the default settings, the endpoint returns at most the 20 latest elements. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`DenominationPending` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: DenominationPending + + interface DenominationPending { + + // Unique row identifier + row_id : Integer; + + // Hash of the denomination public key + denom_pub_hash : HashCode; + + // Total value of coins remaining in circulation (excluding + // the value of coins that were recouped, those are always + // just under recoup_loss). + denom_balance : Amount; + + // Total value of coins redeemed that exceeds the amount we + // put into circulation. Basically, this value grows if we + // wanted to reduce denom_balance (because a coin was deposited) + // but we could not because the denom_balance was already zero. + denom_loss : Amount; + + // Total number of coins of this denomination that were + // put into circulation. + num_issued : Integer; + + // Total value of the coins put into circulation. + denom_risk : Amount; + + // Losses the exchange had from this denomination due to coins + // that were recouped (after the denomination was revoked). + recoup_loss : Amount; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-denominations-without-sigs.rst b/core/auditor/get-monitoring-denominations-without-sigs.rst @@ -0,0 +1,52 @@ +.. http:get:: /monitoring/denominations-without-sigs + + Get a list of denominations without signatures 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:`DenominationsWithoutSigs` objects. + + + + **Details:** + + .. ts:def:: DenominationsWithoutSigs + + interface DenominationsWithoutSigs { + + // Unique row identifier + row_id : Integer; + + // Hash of the denomination public key + denompub_h : HashCode; + + // Value of each coin of the denomination that lacks + // the auditor's signature. + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-deposit-confirmations.rst b/core/auditor/get-monitoring-deposit-confirmations.rst @@ -0,0 +1,80 @@ +.. http:get:: /monitoring/deposit-confirmations + + Get a list of deposit confirmations 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:`DepositConfirmations` objects. + + **Details:** + + .. ts:def:: DepositConfirmations + + 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; + + // 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. + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-early-aggregation.rst b/core/auditor/get-monitoring-early-aggregation.rst @@ -0,0 +1,55 @@ +.. http:get:: /monitoring/early-aggregation + + Get a list of early aggregations. + @since protocol **v2**. + + The following query parameters are optional, and can be used to customise the response: + + **Request:** + + :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. + :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. + :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false. + + With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`GetEarlyAggregationResponse` objects. + + **Details:** + + .. ts:def:: GetEarlyAggregationResponse + + interface GetEarlyAggregationResponse { + + // Array of aggregations lacking a justification. + early_aggregations: EarlyAggregationEntry[]; + + } + + .. ts:def:: EarlyAggregationEntry + + interface EarlyAggregationEntry { + + // Unique row identifier in the auditor table + row_id : Integer; + + // Row identifier in the exchange's batch deposit table + batch_deposit_serial_id : Integer; + + // Row identifier in the exchange's tracking table + tracking_serial_id : Integer; + + // Amount that was aggregated early. + balance : Amount; + + // True if this diagnostic was suppressed. + suppressed : boolean; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-emergency-by-count.rst b/core/auditor/get-monitoring-emergency-by-count.rst @@ -0,0 +1,62 @@ +.. http:get:: /monitoring/emergency-by-count + + Get a list of emergencies by count 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:`EmergencyByCount` objects. + + **Details:** + + .. ts:def:: EmergencyByCount + + interface EmergencyByCount { + + // Row ID of the fee in the exchange database. + row_id : Integer; + + // Hash of the public denomination key to which the + // emergency applies. + denompub_h : HashCode; + + // Number of coins the exchange officially issued of this + // denomination. + num_issued : Integer; + + // Number of coins that were redeemed. + num_known : Integer; + + // What is the total value of all coins of this denomination that + // were put into circulation (and thus the maximum loss the + // exchange may experience due to this emergency). + risk : Amount; + + // When did the exchange start issuing coins in this the denomination. + start : Timestamp; + + // When does the deposit period end for coins of this denomination. + deposit_end : Timestamp; + + // What is the value of an individual coin of this denomination. + value : Amount; + + // 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/get-monitoring-emergency.rst b/core/auditor/get-monitoring-emergency.rst @@ -0,0 +1,59 @@ +.. 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: + + **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:`Emergency` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: Emergency + + interface Emergency { + + // Unique row identifier + row_id : Integer; + + // Hash of denomination public key + denompub_h : HashCode; + + // What is the total value of all coins of this denomination that + // were put into circulation (and thus the maximum loss the + // exchange may experience due to this emergency). + denom_risk : Amount; + + // What is the loss we have experienced so far (that + // is, the amount deposited in excess of the amount + // we issued). + denom_loss : Amount; + + // When did the exchange start issuing coins in this the denomination. + deposit_start : Timestamp; + + // When does the deposit period end for coins of this denomination. + deposit_end : Timestamp; + + // What is the value of an individual coin of this denomination. + value : Amount; + + // 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/get-monitoring-fee-time-inconsistency.rst b/core/auditor/get-monitoring-fee-time-inconsistency.rst @@ -0,0 +1,45 @@ +.. http:get:: /monitoring/fee-time-inconsistency + + Get a list of fee time inconsistencies 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:`FeeTimeInconsistency` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: FeeTimeInconsistency + + interface FeeTimeInconsistency { + + // Row ID of the fee in the exchange database. + row_id : Integer; + + // Specifies the wire method for which the fee is inconsistent. + type : string; + + // Gives the start date of the inconsistent fee. + time : Timestamp; + + // Human readable description of the problem. + diagnostic : string; + + // 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/get-monitoring-historic-denomination-revenue.rst b/core/auditor/get-monitoring-historic-denomination-revenue.rst @@ -0,0 +1,49 @@ +.. http:get:: /monitoring/historic-denomination-revenue + + 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: + + **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. + + With the default settings, the endpoint returns at most the 20 latest elements. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`HistoricDenominationRevenue` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: HistoricDenominationRevenue + + interface HistoricDenominationRevenue { + + // Unique row identifier + row_id : Integer; + + // Hash code of the denomination public key involved + denom_pub_hash : HashCode; + + // Time when the denomination expired and thus the revenue + // was computed. + revenue_timestamp : Timestamp; + + // Total fee revenue the exchange earned from coins of this + // denomination. + revenue_balance : Amount; + + // Total losses the exchange experienced from this denomination + // (this basically only happens if someone was able to forge + // denomination signatures). So non-zero values are indicative + // of a serious problem. + loss_balance : Amount; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-historic-reserve-summary.rst b/core/auditor/get-monitoring-historic-reserve-summary.rst @@ -0,0 +1,41 @@ +.. http:get:: /monitoring/historic-reserve-summary + + 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: + + **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. + + With the default settings, the endpoint returns at most the 20 latest elements. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`HistoricReserveSummary` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: HistoricReserveSummary + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-misattribution-in-inconsistency.rst b/core/auditor/get-monitoring-misattribution-in-inconsistency.rst @@ -0,0 +1,49 @@ +.. http:get:: /monitoring/misattribution-in-inconsistency + + Get a list of misattribution in inconsistencies 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:`MisattributionInInconsistency` objects. + + + + **Details:** + + .. ts:def:: MisattributionInInconsistency + + interface MisattributionInInconsistency { + + // Unique row identifier in the exchange database. + row_id : Integer; + + // Amount of money sent to the wrong account + amount : Amount; + + // Row of the transaction in the bank database as + // returned by the bank revenue API. + bank_row : Integer; + + // Public key of the affected reserve + reserve_pub : EddsaPublicKey; + + // 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/get-monitoring-pending-deposits.rst b/core/auditor/get-monitoring-pending-deposits.rst @@ -0,0 +1,58 @@ +.. http:get:: /monitoring/pending-deposits + + Get a list of pending deposits. + @since protocol **v2**. + + The following query parameters are optional, and can be used to customise the response: + + **Request:** + + :query limit: A signed integer, indicating how many elements relative to the offset query parameter should be returned. The default value is -20. + :query offset: An unsigned integer, indicating from which row onward to return elements. The default value is INT_MAX. + :query return_suppressed: A boolean. If true, returns all eligible rows, otherwise only returns eligible rows that are not suppressed. The default value is false. + + With the default settings, the endpoint returns at most the 20 latest elements that are not suppressed. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`GetPendingDepositsResponse` objects. + + **Details:** + + .. ts:def:: GetPendingDepositsResponse + + interface GetPendingDepositsResponse { + + // Array of pending deposits. + pending_deposits: PendingDepositEntry[]; + + } + + .. ts:def:: PendingDepositEntry + + interface PendingDepositEntry { + + // Unique row identifier in the auditor table + row_id : Integer; + + // Row identifier in the exchange's batch deposit table + batch_deposit_serial_id : Integer; + + // Amount that was aggregated early. + total_amount : Amount; + + // Hash of the bank account that should have received the funds. + h_wire : HashCode; + + // When was the deadline for the transfer. + deadline : 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/get-monitoring-progress.rst b/core/auditor/get-monitoring-progress.rst @@ -0,0 +1,27 @@ +.. http:get:: /monitoring/progress + + Get the progress stored by the auditor. + + **Request:** + + :query progress_key: a string identifying a progress point. If specified, only returns the element with this exact key. The default value is NULL. + + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`Progress` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: Progress + + interface Progress { + + // Key associated with a given progress point + progress_key: string; + + // How much of the exchanges data has been processed so far + progress_offset: Integer; + + } diff --git a/core/auditor/get-monitoring-purse-not-closed-inconsistencies.rst b/core/auditor/get-monitoring-purse-not-closed-inconsistencies.rst @@ -0,0 +1,47 @@ +.. http:get:: /monitoring/purse-not-closed-inconsistencies + + Get a list of purse not closed inconsistencies 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:`PurseNotClosedInconsistencies` objects. + + + + **Details:** + + .. ts:def:: PurseNotClosedInconsistencies + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-purses.rst b/core/auditor/get-monitoring-purses.rst @@ -0,0 +1,46 @@ +.. 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. + + With the default settings, the endpoint returns at most the 20 latest elements. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`Purses` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: Purses + + 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 endpoint is still experimental. The endpoint will be further developed as needed. + + .. _progress-list: diff --git a/core/auditor/get-monitoring-reserve-balance-insufficient-inconsistency.rst b/core/auditor/get-monitoring-reserve-balance-insufficient-inconsistency.rst @@ -0,0 +1,48 @@ +.. http:get:: /monitoring/reserve-balance-insufficient-inconsistency + + Get a list of reserve balance insufficient inconsistencies 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:`ReserveBalanceInsufficientInconsistency` objects. + + + + **Details:** + + .. ts:def:: ReserveBalanceInsufficientInconsistency + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-reserve-balance-summary-wrong-inconsistency.rst b/core/auditor/get-monitoring-reserve-balance-summary-wrong-inconsistency.rst @@ -0,0 +1,45 @@ +.. http:get:: /monitoring/reserve-balance-summary-wrong-inconsistency + + 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: + + **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:`ReserveBalanceSummaryWrongInconsistency` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: ReserveBalanceSummaryWrongInconsistency + + interface ReserveBalanceSummaryWrongInconsistency { + + // Unique row identifier + row_id : Integer; + + // Public key of the reserve affected + reserve_pub : EddsaPublicKey; + + // Amount of summary the exchange calculated + exchange_amount : Amount; + + // Amount of summary the auditor calculated + auditor_amount : Amount; + + // 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/get-monitoring-reserve-in-inconsistency.rst b/core/auditor/get-monitoring-reserve-in-inconsistency.rst @@ -0,0 +1,55 @@ +.. http:get:: /monitoring/reserve-in-inconsistency + + Get a list of reserve in inconsistencies 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:`ReserveInInconsistency` objects. + + **Details:** + + .. ts:def:: ReserveInInconsistency + + interface ReserveInInconsistency { + + // 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-reserve-not-closed-inconsistency.rst b/core/auditor/get-monitoring-reserve-not-closed-inconsistency.rst @@ -0,0 +1,50 @@ +.. http:get:: /monitoring/reserve-not-closed-inconsistency + + Get a list of reserve not closed inconsistencies 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:`ReserveNotClosedInconsistency` objects. + + + + **Details:** + + .. ts:def:: ReserveNotClosedInconsistency + + 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; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-reserves.rst b/core/auditor/get-monitoring-reserves.rst @@ -0,0 +1,69 @@ +.. 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. + + + With the default settings, the endpoint returns at most the 20 latest elements. + + **Response:** + + :http:statuscode:`200 OK`: + The auditor responds with a top level array of :ts:type:`Reserves` objects. If no elements could be found, an empty array is returned + + + **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; + + // Reserve losses are incurred if (a) a reserve is + // incorrectly credited from a recoup for a non-revoked + // coin, or (b) if the exchange allowed more digital cash + // to be withdrawn from a reserve than the balance of the + // reserve should have permitted. FIXME: We may want to + // distinguish these two cases in the future. + 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; + + // Total purse fees earned from this reserve + purse_fee_balance : Amount; + + // Total reserve open fees earned from the reserve + open_fee_balance : Amount; + + // Total reserve history fees earned from this reserve + history_fee_balance : Amount; + + // When the purse expires + expiration_date : Timestamp; + + // Who created the account + origin_account : string; + + } + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/get-monitoring-row-inconsistency.rst b/core/auditor/get-monitoring-row-inconsistency.rst @@ -0,0 +1,42 @@ +.. http:get:: /monitoring/row-inconsistency + + Get a list of row inconsistencies 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:`RowInconsistency` objects. + + **Details:** + + .. ts:def:: RowInconsistency + + interface RowInconsistency { + + // Number of the affected row. + row_id : Integer; + + // Name of the affected exchange table. + row_table : string; + + // Human-readable diagnostic about what went wrong. + diagnostic : string; + + // 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/get-monitoring-row-minor-inconsistencies.rst b/core/auditor/get-monitoring-row-minor-inconsistencies.rst @@ -0,0 +1,42 @@ +.. http:get:: /monitoring/row-minor-inconsistencies + + 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: + + **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:`RowMinorInconsistencies` objects. If no elements could be found, an empty array is returned + + **Details:** + + .. ts:def:: RowMinorInconsistencies + + interface RowMinorInconsistencies { + + // Number of the row in the affected table + row_id : Integer; + + // The row number in the affected table + row_table : Integer; + + // Human readable string describing the problem + diagnostic : string; + + // 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/get-monitoring-wire-format-inconsistency.rst b/core/auditor/get-monitoring-wire-format-inconsistency.rst @@ -0,0 +1,48 @@ +.. 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: + + **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:`WireFormatInconsistency` objects. If no elements could be found, an empty array is returned + + + **Details:** + + .. ts:def:: WireFormatInconsistency + + interface WireFormatInconsistency { + + // Unique row identifier + row_id : Integer; + + // Amount that was part of the wire + amount : Amount; + + // Offset of the duplicate wire transfer subject + // in the bank database according to the revenue API. + wire_offset : Integer; + + // True if this diagnostic was suppressed. + diagnostic : string; + + // 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/get-monitoring-wire-out-inconsistency.rst b/core/auditor/get-monitoring-wire-out-inconsistency.rst @@ -0,0 +1,48 @@ +.. http:get:: /monitoring/wire-out-inconsistency + + 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: + + **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:`WireOutInconsistency` objects. If no elements could be found, an empty array is returned + + + + **Details:** + + .. ts:def:: WireOutInconsistency + + interface WireOutInconsistency { + + // Unique row identifier + row_id : Integer; + + // Account money was wired to + destination_account : string; + + // How much was suppossed to be wired according to the auditor. + expected : Amount; + + // The amount the exchange claims to have wired. + claimed : Amount; + + // 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-amount-arithmetic-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-amount-arithmetic-inconsistency-SERIAL_ID.rst @@ -0,0 +1,12 @@ +.. http:patch:: /monitoring/amount-arithmetic-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of amount arithmetic inconsistencies. Update the 'suppressed' field of an amount arithmetic inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-bad-sig-losses-SERIAL_ID.rst b/core/auditor/patch-monitoring-bad-sig-losses-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/bad-sig-losses/$SERIAL_ID + + This endpoint is used to suppress select elements of bad sig losses. Update the + 'suppressed' field of a bad sig losses 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-closure-lags-SERIAL_ID.rst b/core/auditor/patch-monitoring-closure-lags-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/closure-lags/$SERIAL_ID + + This endpoint is used to suppress select elements of closure lags. + 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-coin-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-coin-inconsistency-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/coin-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of coin inconsistencies. + Update the 'suppressed' field of a coin inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-denomination-key-validity-withdraw-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-denomination-key-validity-withdraw-inconsistency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/denomination-key-validity-withdraw-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of denomination key validity withdraw inconsistencies. + Update the 'suppressed' field of a denomination key validity withdraw inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-denominations-without-sigs-SERIAL_ID.rst b/core/auditor/patch-monitoring-denominations-without-sigs-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/denominations-without-sigs/$SERIAL_ID + + This endpoint is used to suppress select elements of denominations without sigs. + Update the 'suppressed' field of a denominations without signatures 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-deposit-confirmations-SERIAL_ID.rst b/core/auditor/patch-monitoring-deposit-confirmations-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/deposit-confirmations/$SERIAL_ID + + This endpoint is used to suppress select elements of deposit confirmations. + Update the 'suppressed' field of an deposit confirmations 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-emergency-SERIAL_ID.rst b/core/auditor/patch-monitoring-emergency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/emergency/$SERIAL_ID + + This endpoint is used to suppress select elements of emergencies. + Update the 'suppressed' field of an emergency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-emergency-by-count-SERIAL_ID.rst b/core/auditor/patch-monitoring-emergency-by-count-SERIAL_ID.rst @@ -0,0 +1,19 @@ +.. http:patch:: /monitoring/emergency-by-count/$SERIAL_ID + + This endpoint is used to suppress select elements of emergencies by count. + Update the 'suppressed' field of an emergency by count element with row ID + ``$SERIAL_ID``, according to :ts:type:`GenericAuditorMonitorPatchRequest`, + stored by the auditor. + + **Request:** + + The body must be a `GenericAuditorMonitorPatchRequest`. + + **Response:** + + :http:statuscode:`204 No Content`: + The element has been updated. + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-fee-time-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-fee-time-inconsistency-SERIAL_ID.rst @@ -0,0 +1,18 @@ +.. http:patch:: /monitoring/fee-time-inconsistency/$SERIAL_ID + + This endpoint is used to suppress selected elements of fee time + inconsistencies. Updates the 'suppressed' field of a fee time inconsistency + element with row ID ``$SERIAL_ID``. + + **Request:** + + The body must be a `GenericAuditorMonitorPatchRequest`. + + **Response:** + + :http:statuscode:`204 No Content`: + The element has been updated. + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-misattribution-in-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-misattribution-in-inconsistency-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/misattribution-in-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of misattribution in + inconsistencies. Update the 'suppressed' field of an misattribution in + inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-purse-not-closed-inconsistencies-SERIAL_ID.rst b/core/auditor/patch-monitoring-purse-not-closed-inconsistencies-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/purse-not-closed-inconsistencies/$SERIAL_ID + + This endpoint is used to suppress select elements of purse not closed + inconsistencies. Update the 'suppressed' field of a purse not closed + inconsistencies 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-reserve-balance-insufficient-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-reserve-balance-insufficient-inconsistency-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/reserve-balance-insufficient-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of reserve balance insufficient + inconsistencies. Update the 'suppressed' field of a reserve balance + insufficient inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-reserve-balance-summary-wrong-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-reserve-balance-summary-wrong-inconsistency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/reserve-balance-summary-wrong-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of reserve balance summary wrong inconsistencies. + 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:** + + :http:statuscode:`204 No Content`: + The element has been updated. + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-reserve-in-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-reserve-in-inconsistency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/reserve-in-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of reserve in inconsistencies. + Update the 'suppressed' field of a reserve in inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-reserve-not-closed-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-reserve-not-closed-inconsistency-SERIAL_ID.rst @@ -0,0 +1,15 @@ +.. http:patch:: /monitoring/reserve-not-closed-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of reserve not closed + inconsistencies. Update the 'suppressed' field of a reserve not closed + inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-row-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-row-inconsistency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/row-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of row inconsistencies. + Update the 'suppressed' field of a row inconsistency 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 endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-row-minor-inconsistencies-SERIAL_ID.rst b/core/auditor/patch-monitoring-row-minor-inconsistencies-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/row-minor-inconsistencies/$SERIAL_ID + + This endpoint is used to suppress select elements of row minor inconsistencies. + 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:** + + :http:statuscode:`204 No Content`: + The element has been updated. + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-wire-format-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-wire-format-inconsistency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/wire-format-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of wire format inconsistencies. + 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:** + + :http:statuscode:`204 No Content`: + The element has been updated. + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/patch-monitoring-wire-out-inconsistency-SERIAL_ID.rst b/core/auditor/patch-monitoring-wire-out-inconsistency-SERIAL_ID.rst @@ -0,0 +1,13 @@ +.. http:patch:: /monitoring/wire-out-inconsistency/$SERIAL_ID + + This endpoint is used to suppress select elements of wire out inconsistencies. + 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:** + + :http:statuscode:`204 No Content`: + The element has been updated. + + .. note:: + + This endpoint is still experimental. The endpoint will be further developed as needed. diff --git a/core/auditor/put-complain.rst b/core/auditor/put-complain.rst @@ -0,0 +1 @@ +.. http:put:: /complain diff --git a/core/auditor/put-deposit-confirmation.rst b/core/auditor/put-deposit-confirmation.rst @@ -0,0 +1,93 @@ +.. http:put:: /deposit-confirmation + + Submits a `DepositConfirmation` to the exchange. Should succeed + unless the signature provided is invalid or the exchange is not + audited by this auditor. + + **Response:** + + :http:statuscode:`200 Ok`: + The auditor responds with a `DepositAudited` object. + This request should virtually always be successful. + :http:statuscode:`403 Forbidden`: + The signature on the deposit confirmation is invalid. + :http:statuscode:`410 Gone`: + The public key used to sign the deposit confirmation + was revoked. + + **Details:** + + .. ts:def:: DepositAudited + + interface DepositAudited { + // TODO: maybe change to ``204 No content`` instead? + } + + .. ts:def:: DepositConfirmation + + interface DepositConfirmation { + + // Hash over the contract for which this deposit is made. + h_contract_terms: HashCode; + + // Hash over the extensions. + h_extensions: HashCode; + + // Hash over the wiring information of the merchant. + h_wire: HashCode; + + // Time when the deposit confirmation confirmation was generated. + 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. + amount_without_fee: Amount; + + // 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``. + 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; + + // Master public key of the exchange corresponding to ``master_sig``. + // Identifies the exchange this is about. + // @deprecated since v1 (now ignored, global per auditor) + master_pub: EddsaPublicKey; + + // When does the validity of the exchange_pub end? + ep_start: Timestamp; + + // When will the exchange stop using the signing key? + ep_expire: Timestamp; + + // When does the validity of the exchange_pub end? + ep_end: Timestamp; + + // Exchange master signature over ``exchange_sig``. + master_sig: EddsaSignature; + } + + .. note:: + + This endpoint is still experimental (and is not yet implemented at the + time of this writing). A key open question is whether the auditor + should sign the response information. diff --git a/core/donau/delete-charities-{charity_id}.rst b/core/donau/delete-charities-{charity_id}.rst @@ -0,0 +1,13 @@ +.. http:DELETE:: /charities/{charity_id} + + Delete (or deactivate) a charity. Only allowed if the request comes with the administrator bearer token. + + **Request:** + + **Response:** + + :http:statuscode:`204 No content`: + The request was successful. + + :http:statuscode:`403 Forbidden`: + The request did not contain an accepted administrator bearer token in it's header. diff --git a/core/donau/get-charities.rst b/core/donau/get-charities.rst @@ -0,0 +1,46 @@ +.. http:GET:: /charities + + GET all charities. Only allowed if the request comes with the administration bearer token. + + return all charities + + **Request:** + + **Reponse:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `Charities`. + + **Details:** + + .. ts:def:: Charities + + interface Charities{ + charities: CharitySummary[]; + } + + .. ts:def:: CharitySummary + + interface CharitySummary { + + // Unique ID of the charity within the Donau. + charity_id: Integer; + + // Public key of the charity, used by the charity to + // authorize issuing donation receipts. + charity_pub: EddsaPublicKey; + + // Human-readable name of the charity. + charity_name: string; + + // Maximum amount of donation receipts this charity is + // allowed to issue per year. + max_per_year: Amount; + + // Year for which ``receipts_to_date`` is given. + current_year: Integer; + + // Total amount of donation receipts the donau has + // issued for this charity so far this year. + receipts_to_date: Amount; + } diff --git a/core/donau/get-charity-CHARITY_ID.rst b/core/donau/get-charity-CHARITY_ID.rst @@ -0,0 +1,34 @@ +.. http:get:: /charity/$CHARITY_ID + + Request information about a specific charity. + Only allowed if the request comes with a signature by + the respective charity. + + **Request:** + + *Charity-Signature*: + + The client must provide Base-32 encoded EdDSA signature with + ``$CHARITY_PRIV``, affirming the desire to obtain the charity status. + Note that this is merely a simple authentication mechanism, + the details of the request are not protected by the signature. + The ``$CHARITY_PRIV`` is usually the merchant instance + private key. + + **Response:** + + :http:statuscode:`200 OK`: + The Donau responds with a `Charity` object + :http:statuscode:`404 Not found`: + The charity id does not belong to a charity known to the Donau. + + .. ts:def:: Charity + + interface Charity { + charity_pub: EddsaPublicKey; + name: string; + url: string; + max_per_year: Amount; + receipts_to_date: Amount; + current_year: Integer; + } diff --git a/core/donau/get-config.rst b/core/donau/get-config.rst @@ -0,0 +1,28 @@ +.. http:get:: /config + + Return the protocol version, financial domain and currency supported by this + Donau backend. + + **Response:** + + :http:statuscode:`200 OK`: + The body is a `DonauVersionResponse`. + + .. ts:def:: DonauVersionResponse + + interface DonauVersionResponse { + // libtool-style representation of the Donau protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Name of the protocol. + name: "donau"; + + // Currency supported by this Donau. + currency: string; + + // Financial domain by this Donau. + domain: string; + + } diff --git a/core/donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst b/core/donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst @@ -0,0 +1,27 @@ +.. http:GET:: /donation-statement/$YEAR/$HASH_DONOR_ID + + Get the donation statement for a specific year and donor. + + **Request:** + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `DonationStatementResponse`. + :http:statuscode:`403 Forbidden`: + One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + Either the donor or the year or the corresponding donation statement was not found. + This response comes with a standard `ErrorDetail` response. + + **Details:** + + .. ts:def:: DonationStatementResponse + + interface DonationStatementResponse { + total: Amount; + // signature over h_donor_tax_id, total, donation_year + donation_statement_sig: EddsaSignature; + // the corresponding public key to the signature + donau_pub: EddsaPublicKey; + } diff --git a/core/donau/get-keys.rst b/core/donau/get-keys.rst @@ -0,0 +1,115 @@ +.. http:get:: /keys + + Get a list of all donation units keys offered by the Donau, + as well as the Donau's current online signing key (used for donation statements). + + **Request:** + + **Response:** + + :http:statuscode:`200 OK`: + The Donau responds with a `DonauKeysResponse` object. This request should + virtually always be successful. It only fails if the Donau is misconfigured. + + **Details:** + + .. ts:def:: DonauKeysResponse + + interface DonauKeysResponse { + // libtool-style representation of the Donau protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Legal/financial domain this Donau operates for. Shown to the + // user by the wallet when selecting a Donau. Should match the + // name of the financial authority that the user would recognize. + legal_domain: string; + + // The Donau's base URL. + base_url: string; + + // The Donau's currency. + currency: string; + + // Donation units offered by this Donau. Each entry enumerates a + // specific key together with its value and status. + donation_units: DonationUnit[]; + + // The Donau's signing keys. + signkeys: SignKey[]; + + } + + .. ts:def:: DonationUnit + + interface DonationUnit extends DonationUnitKeyCommon { + // How much a receipt signed with this key is worth. + value: Amount; + + // Public key material of the donation unit. + donation_unit_pub: DonationUnitKey; + } + + .. ts:def:: DonationUnitKeyCommon + + interface DonationUnitKeyCommon { + + // For which year is this donation unit key valid. + year: Integer; + + // Set to 'true' if the Donau somehow "lost" the private key. The donation unit was not + // revoked, but still cannot be used to withdraw receipts at this time (theoretically, + // the private key could be recovered in the future; receipts signed with the private key + // remain valid). + lost?: boolean; + } + + .. ts:def:: DonationUnitKey + + type DonationUnitKey = + | RsaDonationUnitKey + | CSDonationUnitKey; + + .. ts:def:: RsaDonationUnitKey + + interface RsaDonationUnitKey { + cipher: "RSA"; + + // RSA public key + rsa_public_key: RsaPublicKey; + + // Hash of the RSA public key, as used in other API calls. + pub_key_hash: HashCode; + } + + .. ts:def:: CSDonationUnitKey + + interface CSDonationUnitKey { + cipher: "CS"; + + // Public key of the donation unit. + cs_public_key: Cs25519Point; + + // Hash of the CS public key, as used in other API calls. + pub_key_hash: HashCode; + } + + A signing key in the ``signkeys`` list is a JSON object with the following fields: + + .. ts:def:: SignKey + + interface SignKey { + // The actual Donau's EdDSA signing public key. + key: EddsaPublicKey; + + // Initial validity date for the signing key. + year: Integer; + + } + + + .. note:: + + Both the individual donation units *and* the donation units list is signed, + allowing customers to prove that they received an inconsistent list. diff --git a/core/donau/get-seed.rst b/core/donau/get-seed.rst @@ -0,0 +1,8 @@ +.. http:get:: /seed + + Return an entropy seed. The Donau will return a high-entropy + value that will differ for every call. The response is NOT in + JSON, but simply high-entropy binary data in the HTTP body. + This API should be used by wallets to guard themselves against + running on low-entropy (bad PRNG) hardware. Naturally, the entropy + returned MUST be mixed with locally generated entropy. diff --git a/core/donau/patch-charities-{charity_id}.rst b/core/donau/patch-charities-{charity_id}.rst @@ -0,0 +1,30 @@ +.. http:PATCH:: /charities/{charity_id} + + Modify a charity. + Only allowed if the request comes with the administrator bearer token. + + **Request:** ``CharityRequest`` + + **Response:** + + :http:statuscode:`200 OK`: + The update succeeded. The response body is empty. + + :http:statuscode:`400 Bad Request`: + The request was malformed. For example, ``max_per_year`` must not be + smaller than the current ``receipts_to_date`` of the charity. + + :http:statuscode:`401 Unauthorized`: + Missing or invalid bearer token. + + :http:statuscode:`403 Forbidden`: + The request did not contain an accepted administrator bearer token in its header. + + :http:statuscode:`404 Not Found`: + The charity ID is unknown to the Donau. + + **Details:** + + The request body has the same shape as :ts:type:`CharityRequest` used by + :http:POST:`/charities`. All fields are required and will replace the stored + values of the charity. diff --git a/core/donau/post-batch-issue-CHARITY_ID.rst b/core/donau/post-batch-issue-CHARITY_ID.rst @@ -0,0 +1,148 @@ +.. http:POST:: /batch-issue/$CHARITY_ID + + Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained BUDIs. + + **Request:** `IssueReceiptsRequest` + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `BlindedDonationReceiptSignaturesResponse`. + :http:statuscode:`403 Forbidden`: + The charity signature is invalid. This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`. + This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`. + :http:statuscode:`409 Conflict`: + The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis. + The response is a `IssueError` object. + :http:statuscode:`410 Gone`: + The requested donation unit key is not yet or no longer valid. It either before the validity year, past the + year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code + provided to understand which of the cases this is and handle it accordingly. + + **Details:** + + .. ts:def:: IssueReceiptsRequest + + interface IssueReceiptsRequest { + + // Signature by the charity approving that the + // Donau should sign the donation receipts below. + charity_sig: EddsaSignature; + + // Year for which the donation receipts are expected. + // Also determines which keys are used to sign the + // blinded donation receipts. + year: Integer; + + // Array of blinded donation receipts to sign. + // Must NOT be empty (if no donation receipts + // are desired, just leave the entire ``donau`` + // argument blank). + budikeypairs: BlindedDonationReceiptKeyPair[]; + } + + .. ts:def:: BlindedDonationReceiptKeyPair + + interface BlindedDonationReceiptKeyPair { + // Hash of the public key that should be used to sign + // the donation receipt. + h_donation_unit_pub: HashCode; + + // Blinded value to give to the Donau to sign over. + blinded_udi: BlindedUniqueDonationIdentifier; + } + + .. ts:def:: BlindedUniqueDonationIdentifier + + type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ; + + .. ts:def:: RSABUDI + + interface RSABUDI { + cipher: "RSA"; + rsa_blinded_identifier: string; // Crockford Base32 encoded + } + + .. ts:def:: CSBUDI + + // For donation unit signatures based on Blind Clause-Schnorr, the BUDI + // consists of the public nonce and two Curve25519 scalars which are two + // blinded challenges in the Blinded Clause-Schnorr signature scheme. + // See https://taler.net/papers/cs-thesis.pdf for details. + interface CSBUDI { + cipher: "CS"; + cs_nonce: string; // Crockford Base32 encoded + cs_blinded_c0: string; // Crockford Base32 encoded + cs_blinded_c1: string; // Crockford Base32 encoded + } + + .. ts:def:: BUDIBlindingKeyP + + // Secret for blinding/unblinding. + // An RSA blinding secret, which is basically + // a 256-bit nonce, converted to Crockford Base32. + type BUDIBlindingKeyP = string; + + .. ts:def:: BlindedDonationReceiptSignaturesResponse + + interface BlindedDonationReceiptSignaturesResponse { + // Total amount over which all the blind signatures are signing. + issued_amount: Amount; + + // Array of the blind signatures. + blind_signatures: BlindedDonationReceiptSignature[]; + } + + .. ts:def:: BlindedDonationReceiptSignature + + type BlindedDonationReceiptSignature = + | RSABlindedDonationReceiptSignature + | CSBlindedDonationReceiptSignature; + + .. ts:def:: RSABlindedDonationReceiptSignature + + interface RSABlindedDonationReceiptSignature { + cipher: "RSA"; + + // (blinded) RSA signature + blinded_rsa_signature: BlindedRsaSignature; + } + + .. ts:def:: CSBlindedDonationReceiptSignature + + interface CSBlindedDonationReceiptSignature { + cipher: "CS"; + + // Signer chosen bit value, 0 or 1, used + // in Clause Blind Schnorr to make the + // ROS problem harder. + b: Integer; + + // Blinded scalar calculated from c_b. + s: Cs25519Scalar; + } + + .. ts:def:: IssueError + + interface IssueError{ + max_per_year: Amount; + current_year: Amount; + } + + .. ts:def:: DonationUnitUnknownError + + interface DonationUnitUnknownError{ + unknown_hash_pub_donation_unit: HashCode[]; + donau_pub: EddsaPublicKey; + donau_sig: EddsaSignature; + } + + .. ts:def:: DonationUnitExpiredMessage + + interface DonationUnitExpiredMessage{ + h_donation_unit_pub: HashCode; + donau_pub: EddsaPublicKey; + donau_sig: EddsaSignature; + } diff --git a/core/donau/post-batch-submit.rst b/core/donau/post-batch-submit.rst @@ -0,0 +1,62 @@ +.. http:POST:: /batch-submit + + Send in donation receipts for the current or one of the past fiscal years. + The donor will reveive the signed total back, which is called the + donation statement. + + **Request:** `SubmitDonationReceiptsRequest` + + **Response:** + + :http:statuscode:`201 Created`: + The request was successful, and a donation statement is now available. The response will be empty. + :http:statuscode:`403 Forbidden`: + One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. + :http:statuscode:`404 Not found`: + At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`. + + **Details:** + + .. ts:def:: SubmitDonationReceiptsRequest + + interface SubmitDonationReceiptsRequest{ + // hashed taxpayer ID plus salt + h_donor_tax_id: HashCode; + // All donation receipts must be for this year. + donation_year: Integer; + // Receipts should be sorted by amount. + donation_receipts: DonationReceipt[]; + } + + .. ts:def:: DonationReceipt + + interface DonationReceipt { + h_donation_unit_pub: HashCode; + nonce: string; + donation_unit_sig: DonationReceiptSignature; + } + + .. ts:def:: DonationReceiptSignature + + type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ; + + .. ts:def:: RSADonationReceiptSignature + + interface RSADonationReceiptSignature { + cipher: "RSA"; + + // RSA signature + rsa_signature: RsaSignature; + } + + .. ts:def:: CSDonationReceiptSignature + + interface CSDonationReceiptSignature { + cipher: "CS"; + + // R value component of the signature. + cs_signature_r: Cs25519Point; + + // s value component of the signature. + cs_signature_s: Cs25519Scalar; + } diff --git a/core/donau/post-charities.rst b/core/donau/post-charities.rst @@ -0,0 +1,52 @@ +.. http:POST:: /charities + + Register a new charity with the Donau. Only allowed if the request comes with the + administrator bearer token. The request body defines the charity's signing key, + contact information, and the initial accounting values for the current business + year. On success the Donau assigns a numeric identifier to the charity record. + + **Request:** `CharityRequest` + + **Response:** + + **Details:** + + :http:statuscode:`201 Created`: + The request was successful, and the response is a `CharityResponse`. + + :http:statuscode:`403 Forbidden`: + The request did not contain an accepted administrator bearer token in its header. + + :http:statuscode:`404 Not found`: + The referenced resource needed to create the charity was not found. This response + comes with a standard `ErrorDetail` response. + + :http:statuscode:`409 Conflict`: + A charity with the same public key exists in the backend, but it + has different details. This response + comes with a standard `ErrorDetail` response. + + .. ts:def:: CharityRequest + + interface CharityRequest { + + // Long-term EdDSA public key that identifies the charity. + charity_pub: EddsaPublicKey; + + // Canonical URL that should be presented to donors. + charity_url: string; + + // Human-readable display name of the charity. + charity_name: string; + + // Allowed donation volume for the charity per calendar year. + max_per_year: Amount; + } + + .. ts:def:: CharityResponse + + interface CharityResponse { + + // Unique ID assigned to the charity in the backend. + charity_id: Integer; + } diff --git a/core/donau/post-csr-issue.rst b/core/donau/post-csr-issue.rst @@ -0,0 +1,66 @@ +.. http:post:: /csr-issue + + Obtain donau-side input values in preparation for a + issue receipt step for certain donation unit cipher types, + specifically at this point for Clause-Schnorr blind + signatures. This API is used by the donor. + + **Request:** The request body must be a `IssuePrepareRequest` object. + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful, and the response is a `IssuePrepareResponse`. Note that repeating exactly the same request + will again yield the same response (assuming none of the donation unit is expired). + :http:statuscode:`404 Not found`: + The donation unit key is not known to the donau. + :http:statuscode:`410 Gone`: + The requested donation unit key is not yet or no longer valid. It either before the validity year, past the + year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to + understand which of the cases this is and handle it accordingly. + + **Details:** + + .. ts:def:: IssuePrepareRequest + + interface IssuePrepareRequest { + + // Nonce to be used by the donau to derive + // its private inputs from. Must not have ever + // been used before. + nonce: CSNonce; + + // Hash of the public key of the donation unit + // the request relates to. + du_pub_hash: HashCode; + + } + + .. ts:def:: IssuePrepareResponse + + type IssuePrepareResponse = + | DonauIssueValue; + + .. ts:def:: DonauIssueValue + + type DonauIssueValue = + | DonauRsaIssueValue + | DonauCsIssueValue; + + .. ts:def:: DonauRsaIssueValue + + interface DonauRsaIssueValue { + cipher: "RSA"; + } + + .. ts:def:: DonauCsIssueValue + + interface DonauCsIssueValue { + cipher: "CS"; + + // CSR R0 value + r_pub_0: CSRPublic; + + // CSR R1 value + r_pub_1: CSRPublic; + }