testingCheckCoins

Validate exchange coin histories and compare balances of unspent coins against the exchange’s view.

Request:

The request must be a TestingCheckCoinsRequest object.

Response:

On success, the result is a TestingCheckCoinsResponse object.

Side effects:

Queries the coin history from the exchange over the network for every checked coin.

interface TestingCheckCoinsRequest {
  // Canonicalized before selecting coins.
  // Only this exchange is contacted.
  exchangeBaseUrl: string;

  // Default true: check only fresh coins.  False validates every coin
  // status, comparing denomination value only for fresh or
  // suspended-fresh coins.
  onlyFresh?: boolean;
}

interface TestingCheckCoinsResponse {
  exchangeBaseUrl: string;

  // Denomination value of fresh coins under the exchange's current
  // master key in the initial snapshot.  Null if local data is
  // unavailable.
  expectedMaterialBalance: AmountString | null;

  // Verified remaining exchange balance of those same coins.  Null
  // if any relevant history could not be verified or the material
  // balance changed during the check; never a partial total.
  actualMaterialBalance: AmountString | null;

  // Coins selected by the exchange and onlyFresh filter
  // in the initial snapshot.
  numCoins: number;

  // Validated histories with stable coin data,
  // including balance mismatches.
  numChecked: number;

  // Balance differences, invalid exchange histories,
  // and unavailable coin data.
  issues: TestingCheckCoinsIssue[];
}

interface TestingCheckCoinsIssue {
  coinPub: string;
  denomPubHash: string;
  category: "mismatch" | "error" | "incomplete";
  reason:
    | "balance-difference"
    | "invalid-history"
    | "request-failed"
    | "missing-local-data"
    | "local-data-changed";
  description: string;
  expected?: Record<string, string | number | boolean>;
  actual?: Record<string, string | number | boolean>;

  // On balance differences: exchange history in offset order,
  // including credits.
  exchangeOperations?: Array<
    [operation: CoinSpendHistoryItem["type"], amount: AmountString]
  >;
}