taler-docs

api-auditor.rst (20493B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2018-2024 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
 
 ===================
 Auditor RESTful API
 ===================
 
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
 defines all specific terms used in this section.
 
 
 ---------------
 Version History
 ---------------
 
 The current protocol version is **v2**.
 
 * The auditor SPA currently targeting protocol version **v1**.
 
 **Version history:**
 
 * ``v2``: Adds a few additional GET endpoints to expose more auditor data
 
 **Upcoming versions:**
 
 * none anticipated
 
 **Ideas for future version:**
 
 * ``vXXX``: marker for features not yet targeted for release
 
 
 .. _authentication:
 
 --------------
 Authentication
 --------------
 
 Each auditor instance has separate authentication settings for the private API resources
 of that instance.
 
 Currently, the API supports two main authentication methods:
 
 * ``external``:  With this method, no checks are done by the auditor backend.
   Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
 * ``token``: With this method, the client must provide a ``Authorization: Bearer $TOKEN``
   header, where ``$TOKEN`` is a secret authentication token configured for the instance which must begin with the RFC 8959 prefix.
 
 .. _auditor-version:
 
 -------------------------
 Obtaining Auditor Version
 -------------------------
 
 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.
 
 .. include:: auditor/get-config.rst
 
 
 .. _deposit-confirmation:
 
 ---------------------
 Deposit Confirmations
 ---------------------
 
 Merchants should probabilistically submit some of the deposit
 confirmations they receive from the exchange to auditors to ensure
 that the exchange does not lie about recording deposit confirmations
 with the exchange. Participating in this scheme ensures that in case
 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.
 
 .. include:: auditor/put-deposit-confirmation.rst
 
 
 .. _auditor-monitoring-spa-api:
 
 --------------
 Monitoring API
 --------------
 
 The following entries specify how to access the results of an audit.
 
 For most endpoints, rows may be marked as 'suppressed' to not send them again
 upon subsequent GET requests.  To do this, a
 :ts:type:`GenericAuditorMonitorPatchRequest` object is used in the respective
 PATCH request.
 
 **Details:**
 
   .. ts:def:: GenericAuditorMonitorPatchRequest
 
     interface GenericAuditorMonitorPatchRequest {
 
       // If true, subsequent GET requests will not return this element by default
       suppressed : boolean;
 
     }
 
 
 .. _fee-time-inconsistency-list:
 
 Fee Time Inconsistencies
 ------------------------
 
 This section highlights cases where validity periods associated with wire fees
 the exchange may charge merchants are invalid.  This usually means that the
 validity periods given for the same type of fee are overlapping and it is thus
 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.
 
 .. include:: auditor/get-monitoring-fee-time-inconsistency.rst
 
 .. include:: auditor/patch-monitoring-fee-time-inconsistency-SERIAL_ID.rst
 
 .. _emergency-list:
 
 Emergencies
 -----------
 
 This endpoint is used to obtain a list of emergencies.
 
 Emergencies are errors where the total value of coins deposited (of a
 particular denomination) exceeds the total value that the exchange remembers
 issuing.  This usually means that the private keys of the exchange were
 compromised (stolen or factored) and subsequently used to sign coins off the
 books.  If this happens, all coins of the respective denomination that the
 exchange has redeemed so far may have been created by the attacker, and the
 exchange would have to refund all of the outstanding coins from ordinary
 users.  Thus, the risk exposure is the amount of coins in circulation for a
 particular denomination and the maximum loss for the exchange from this type
 of compromise.
 
 The difference between emergencies and emergencies by count is how the auditor
 detected the problem: by comparing amounts, or by counting coins.
 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).
 
 .. include:: auditor/get-monitoring-emergency.rst
 
 .. include:: auditor/patch-monitoring-emergency-SERIAL_ID.rst
 
 .. _emergency-by-count-list:
 
 Emergencies By Count
 --------------------
 
 This endpoint is used to obtain a list of emergencies by count.
 
 Emergencies are errors where more coins were deposited than the
 exchange remembers issuing.  This usually means that the private keys
 of the exchange were compromised (stolen or factored) and subsequently
 used to sign coins off the books.  If this happens, all coins of the
 respective denomination that the exchange has redeemed so far may have
 been created by the attacker, and the exchange would have to refund
 all of the outstanding coins from ordinary users.  Thus, the risk
 exposure is the amount of coins in circulation for a particular
 denomination and the maximum loss for the exchange from this type of
 compromise.
 
 Emergencies "by count" are cases where this type of money printing was
 detected simply by counting the number of coins the exchange officially put
 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.
 
 .. include:: auditor/get-monitoring-emergency-by-count.rst
 
 .. include:: auditor/patch-monitoring-emergency-by-count-SERIAL_ID.rst
 
 
 .. _row-inconsistency-list:
 
 Row Inconsistencies
 -------------------
 
 This section highlights inconsistencies in a specific row of a specific table
 of the exchange.  Row inconsistencies are reported from different sources, and
 largely point to some kind of data corruption (or bug). Nothing is implied
 about the seriousness of the inconsistency. Most inconsistencies are detected
 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'.
 
 .. include:: auditor/get-monitoring-row-inconsistency.rst
 
 
 .. include:: auditor/patch-monitoring-row-inconsistency-SERIAL_ID.rst
 
 .. _reserve-in-inconsistency-list:
 
 Reserve In Inconsistencies
 --------------------------
 
 This section lists cases where the exchange's and auditor's expectation of
 amounts transferred into a reserve differs.  Basically, the exchange database
 states that a certain reserve was credited for a certain amount via a wire
 transfer, but the auditor disagrees about this basic fact.  This may result in
 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).
 
 .. include:: auditor/get-monitoring-reserve-in-inconsistency.rst
 
 
 
 
 .. include:: auditor/patch-monitoring-reserve-in-inconsistency-SERIAL_ID.rst
 
 
 .. _purse-not-closed-inconsistencies-list:
 
 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.
 
 
 .. include:: auditor/get-monitoring-purse-not-closed-inconsistencies.rst
 
 
 .. include:: auditor/patch-monitoring-purse-not-closed-inconsistencies-SERIAL_ID.rst
 
 
 Early Aggregations
 ------------------
 
 .. _early-aggregation-list:
 
 
 This endpoint returns cases in which wire transfers are encountered before their
 justifications. This can be harmless, if the justifications appear shortly afterwards.
 
 .. include:: auditor/get-monitoring-early-aggregation.rst
 
 
 
 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.
 
 .. include:: auditor/get-monitoring-pending-deposits.rst
 
 
 
 
 
 
 .. _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.
 
 .. include:: auditor/get-monitoring-reserve-not-closed-inconsistency.rst
 
 
 
 
 .. include:: auditor/patch-monitoring-reserve-not-closed-inconsistency-SERIAL_ID.rst
 
 
 
 
 .. _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.
 
 .. include:: auditor/get-monitoring-reserve-balance-insufficient-inconsistency.rst
 
 
 
 
 
 .. include:: auditor/patch-monitoring-reserve-balance-insufficient-inconsistency-SERIAL_ID.rst
 
 
 .. _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).
 
 .. include:: auditor/get-monitoring-bad-sig-losses.rst
 
 
 .. include:: auditor/patch-monitoring-bad-sig-losses-SERIAL_ID.rst
 
 
 .. _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.
 
 .. include:: auditor/get-monitoring-coin-inconsistency.rst
 
 
 .. include:: auditor/patch-monitoring-coin-inconsistency-SERIAL_ID.rst
 
 
 
 
 .. _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.
 
 .. include:: auditor/get-monitoring-denominations-without-sigs.rst
 
 
 
 .. include:: auditor/patch-monitoring-denominations-without-sigs-SERIAL_ID.rst
 
 
 .. _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.
 
 .. include:: auditor/get-monitoring-misattribution-in-inconsistency.rst
 
 
 
 .. include:: auditor/patch-monitoring-misattribution-in-inconsistency-SERIAL_ID.rst
 
 
 
 .. _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.
 
 .. include:: auditor/get-monitoring-deposit-confirmations.rst
 
 
 .. include:: auditor/patch-monitoring-deposit-confirmations-SERIAL_ID.rst
 
 
 .. _denomination-key-validity-withdraw-inconsistency-list:
 
 Denomination Key Validity Withdraw Inconsistencies
 --------------------------------------------------
 
 This section highlights cases, where denomination keys were used to sign coins
 withdrawn from a reserve before the denomination was valid or after it was
 already expired for signing.  This doesn't exactly imply any financial loss
 for anyone, it is mostly weird and may have affected the fees the customer
 paid.
 
 .. include:: auditor/get-monitoring-denomination-key-validity-withdraw-inconsistency.rst
 
 .. 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.
 
 
 .. include:: auditor/get-monitoring-amount-arithmetic-inconsistency.rst
 
 
 .. include:: auditor/patch-monitoring-amount-arithmetic-inconsistency-SERIAL_ID.rst
 
 
 .. _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).
 
 .. include:: auditor/get-monitoring-wire-format-inconsistency.rst
 
 
 
 
 .. include:: auditor/patch-monitoring-wire-format-inconsistency-SERIAL_ID.rst
 
 
 .. _closure-lags-list:
 
 Closure Lags
 ------------
 
 This endpoint is used to obtain a list of closure lags.
 
 A closure lag happens if a reserve should have closed a reserve and
 wired (remaining) funds back to the originating account, but did not
 do so on time.  Significant lag may be indicative of fraud, while
 moderate lag is indicative that the systems may be too slow to handle the
 load. Small amounts of lag can occur in normal operation.
 
 If closure lag is experienced, the administrator should check that
 the **taler-exchange-closer** component is operating correctly.
 
 
 .. include:: auditor/get-monitoring-closure-lags.rst
 
 
 .. include:: auditor/patch-monitoring-closure-lags-SERIAL_ID.rst
 
 
 
 
 .. _wire-out-inconsistency-list:
 
 Wire Out Inconsistencies
 ------------------------
 
 This section highlights cases where the exchange wired a different amount to a
 destimation account than the auditor expected.
 
 .. include:: auditor/get-monitoring-wire-out-inconsistency.rst
 
 
 
 
 
 .. include:: auditor/patch-monitoring-wire-out-inconsistency-SERIAL_ID.rst
 
 
 .. _reserve-balance-summary-wrong-inconsistency-list:
 
 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.
 
 .. include:: auditor/get-monitoring-reserve-balance-summary-wrong-inconsistency.rst
 
 .. include:: auditor/patch-monitoring-reserve-balance-summary-wrong-inconsistency-SERIAL_ID.rst
 
 
 .. _row-minor-inconsistencies-list:
 
 Row Minor Inconsistencies
 -------------------------
 
 The section highlights inconsistencies where a row in an exchange table has a
 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).
 
 .. include:: auditor/get-monitoring-row-minor-inconsistencies.rst
 
 .. include:: auditor/patch-monitoring-row-minor-inconsistencies-SERIAL_ID.rst
 
 
 -------------------------
 Monitoring Auditor Status
 -------------------------
 
 The following entries specify how to access information the auditor keeps to
 properly perform audits.  These tables do not contain inconsistencies, instead
 they store information about balances, reserves, purses etc.  Values in these
 tables should not differ from their respective exchanges' version.
 
 .. _balances-list:
 
 Balances
 --------
 
 Returns the various balances the auditor tracks for the exchange, such as
 coins in circulation, fees earned, losses experienced, etc.
 
 .. include:: auditor/get-monitoring-balances.rst
 
 
 .. _historic-denomination-revenue-list:
 
 Historic Denomination Revenue
 -----------------------------
 
 This endpoint is used to obtain a list of historic denomination revenue, that
 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.
 
 .. include:: auditor/get-monitoring-historic-denomination-revenue.rst
 
 .. _denomination-pending-list:
 
 Denomination Pending
 --------------------
 
 This endpoint is used to obtain a list of balances for denominations that are still
 active, that is coins may still be deposited (or possibly even withdrawn) and thus
 the amounts given are not final.
 
 .. include:: auditor/get-monitoring-denomination-pending.rst
 
 
 .. _historic-reserve-summary-list:
 
 Historic Reserve Summary
 ------------------------
 
 This section summarizes historic profits an exchange
 made from reserves and associated reserve-specific
 fees.
 
 .. include:: auditor/get-monitoring-historic-reserve-summary.rst
 
 
 .. _reserves-list:
 
 
 Reserves
 --------
 
 This endpoint is used to obtain a list of open reserves that the auditor is
 currently tracking balances for.
 
 .. include:: auditor/get-monitoring-reserves.rst
 
 
 .. _purses-list:
 
 Purses
 ------
 
 This endpoint is used to obtain information about open purses.
 
 .. include:: auditor/get-monitoring-purses.rst
 
 Progress
 --------
 
 This section contains information about the auditing progress an auditor has made.
 
 .. include:: auditor/get-monitoring-progress.rst
 
 ----------
 Complaints
 ----------
 
 This endpoint is used by the wallet or merchants to submit proof of
 misbehavior of an exchange to the auditor.
 
 .. note::
 
    To be designed and implemented.
 
 .. include:: auditor/put-complain.rst
 
 Complain about misbehavior to the auditor.