taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

testing-check-coins.rst (2393B)

      1 .. ts:op:: testingCheckCoins
      2 
      3   Validate exchange coin histories and compare balances of unspent
      4   coins against the exchange's view.
      5 
      6   **Request:**
      7 
      8     The request must be a `TestingCheckCoinsRequest` object.
      9 
     10   **Response:**
     11 
     12     On success, the result is a `TestingCheckCoinsResponse` object.
     13 
     14   **Side effects:**
     15 
     16     Queries the coin history from the exchange over the network for
     17     every checked coin.
     18 
     19 .. ts:def:: TestingCheckCoinsRequest
     20 
     21   interface TestingCheckCoinsRequest {
     22     // Canonicalized before selecting coins.
     23     // Only this exchange is contacted.
     24     exchangeBaseUrl: string;
     25 
     26     // Default true: check only fresh coins.  False validates every coin
     27     // status, comparing denomination value only for fresh or
     28     // suspended-fresh coins.
     29     onlyFresh?: boolean;
     30   }
     31 
     32 .. ts:def:: TestingCheckCoinsResponse
     33 
     34   interface TestingCheckCoinsResponse {
     35     exchangeBaseUrl: string;
     36 
     37     // Denomination value of fresh coins under the exchange's current
     38     // master key in the initial snapshot.  Null if local data is
     39     // unavailable.
     40     expectedMaterialBalance: AmountString | null;
     41 
     42     // Verified remaining exchange balance of those same coins.  Null
     43     // if any relevant history could not be verified or the material
     44     // balance changed during the check; never a partial total.
     45     actualMaterialBalance: AmountString | null;
     46 
     47     // Coins selected by the exchange and onlyFresh filter
     48     // in the initial snapshot.
     49     numCoins: number;
     50 
     51     // Validated histories with stable coin data,
     52     // including balance mismatches.
     53     numChecked: number;
     54 
     55     // Balance differences, invalid exchange histories,
     56     // and unavailable coin data.
     57     issues: TestingCheckCoinsIssue[];
     58   }
     59 
     60 .. ts:def:: TestingCheckCoinsIssue
     61 
     62   interface TestingCheckCoinsIssue {
     63     coinPub: string;
     64     denomPubHash: string;
     65     category: "mismatch" | "error" | "incomplete";
     66     reason:
     67       | "balance-difference"
     68       | "invalid-history"
     69       | "request-failed"
     70       | "missing-local-data"
     71       | "local-data-changed";
     72     description: string;
     73     expected?: Record<string, string | number | boolean>;
     74     actual?: Record<string, string | number | boolean>;
     75 
     76     // On balance differences: exchange history in offset order,
     77     // including credits.
     78     exchangeOperations?: Array<
     79       [operation: CoinSpendHistoryItem["type"], amount: AmountString]
     80     >;
     81   }