@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/clearing-custody.ts

@@ -0,0 +1,665 @@
+import {
+  BaseError,
+  ContractFunctionRevertedError,
+  concatHex,
+  createPublicClient,
+  createWalletClient,
+  encodeFunctionData,
+  erc20Abi,
+  FeeCapTooHighError,
+  FeeCapTooLowError,
+  http,
+  InsufficientFundsError,
+  IntrinsicGasTooHighError,
+  IntrinsicGasTooLowError,
+  keccak256,
+  NonceMaxValueError,
+  NonceTooHighError,
+  parseEventLogs,
+  sha256,
+  stringToHex,
+  TipAboveFeeCapError,
+  TransactionTypeNotSupportedError,
+  type Abi,
+  type Address,
+  type Hex,
+  type LocalAccount,
+  type TransactionReceipt,
+} from "viem";
+import { getNodeError } from "viem/utils";
+import { clearingAbi } from "./clearing-abi.js";
+import { clearingUint64, clearingUnits } from "./clearing-codec.js";
+import type { ClearingSigner } from "./clearing-client.js";
+
+export interface ClearingLogProof {
+  location: string;
+  leaves: string;
+  inactivePeaks: number;
+  digests: Hex[];
+}
+export interface ClearingBalance {
+  state: Hex;
+  amount: string;
+  opening:
+    | null
+    | (ClearingLogProof & {
+        amount: string;
+        nextKey: Hex;
+        chunk: Hex;
+        opsRoot: Hex;
+        pending: Hex;
+        partialDigest: Hex;
+      });
+}
+export function clearingLogProof<T extends ClearingLogProof>(proof: T) {
+  return {
+    ...proof,
+    location: BigInt(proof.location),
+    leaves: BigInt(proof.leaves),
+    inactivePeaks: BigInt(proof.inactivePeaks),
+  };
+}
+/** Authorize an epoch-tail close to a fixed EVM destination. */
+export async function clearingClose(
+  signer: ClearingSigner,
+  deployment: Hex,
+  balance: ClearingBalance,
+  destination: Hex,
+  deadline: bigint,
+) {
+  if (!balance.opening) throw new Error("no retained balance proof");
+  const body = concatHex([
+    deployment,
+    balance.state,
+    "0x14",
+    destination,
+    "0x02",
+    clearingUint64(deadline),
+  ]);
+  const { amount, nextKey, ...proof } = balance.opening;
+  return {
+    withdrawal: {
+      account: signer.publicKey,
+      deployment,
+      state: balance.state,
+      destination,
+      amount: 0n,
+      deadline,
+      signature: await signer.sign(
+        "_COMMONWARE_CLEARING_BOUNDARY_WITHDRAWAL",
+        body,
+      ),
+    },
+    opening: {
+      amount: BigInt(amount),
+      nextKey,
+      proof: clearingLogProof(proof),
+    },
+  };
+}
+
+/** The most the Clearing contract holds in all, in clearing units: it
+ * counts `uint64` units of `Clearing.unit()` token base units each, a
+ * millionth of the token (its base unit at six decimals or fewer). */
+export const CLEARING_MAX_AMOUNT = 2n ** 64n - 1n;
+
+async function serviceGet<T>(
+  serviceUrl: string,
+  path: string,
+  fetcher: typeof globalThis.fetch,
+): Promise<T> {
+  const response = await fetcher(new URL(path, serviceUrl), {
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok)
+    throw new Error(`clearing service returned ${response.status} for ${path}`);
+  return (await response.json()) as T;
+}
+
+/** What `account` can still spend in the open epoch, in the token's base
+ * units: the operator's estimate from the balance and deposits it has
+ * counted and the payments it has acknowledged. */
+export async function clearingSpendable(opts: {
+  rpcUrl: string;
+  settlement: Address;
+  serviceUrl: string;
+  account: Hex;
+  fetch?: typeof globalThis.fetch;
+}): Promise<bigint> {
+  const pub = createPublicClient({ transport: http(opts.rpcUrl) });
+  const [{ amount }, unit] = await Promise.all([
+    serviceGet<{ amount: string }>(
+      opts.serviceUrl,
+      `/spendable/${opts.account}`,
+      opts.fetch ?? globalThis.fetch,
+    ),
+    pub.readContract({ address: opts.settlement, abi: clearingAbi, functionName: "unit" }),
+  ]);
+  // The service counts clearing units.
+  return BigInt(amount) * unit;
+}
+
+/** `account`'s finalized balance in clearing units and, when the service
+ * retains one, the proof `withdrawFromClearing` closes it with. */
+export function clearingBalance(
+  serviceUrl: string,
+  account: Hex,
+  fetcher: typeof globalThis.fetch = globalThis.fetch,
+): Promise<ClearingBalance> {
+  return serviceGet<ClearingBalance>(serviceUrl, `/balance/${account}`, fetcher);
+}
+
+export interface ClearingChain {
+  rpcUrl: string;
+  chainId: number;
+  /** The EVM account that sends the transactions and pays their gas. */
+  from: LocalAccount;
+  settlement: Address;
+}
+
+/** What a node answers when it refuses a transaction outright, leaving
+ * nothing in its pool. */
+const REFUSALS = [
+  InsufficientFundsError,
+  FeeCapTooLowError,
+  FeeCapTooHighError,
+  TipAboveFeeCapError,
+  IntrinsicGasTooLowError,
+  IntrinsicGasTooHighError,
+  NonceTooHighError,
+  NonceMaxValueError,
+  TransactionTypeNotSupportedError,
+];
+
+/** Gas and fees are set here: on Metal, a fee-carrying `eth_estimateGas`
+ * from an account with no native balance fails. */
+function chainClients({ rpcUrl, chainId, from, timeoutMs = 60_000, pollMs = 500 }: ClearingChain & { timeoutMs?: number; pollMs?: number }) {
+  const transport = http(rpcUrl);
+  const pub = createPublicClient({ transport });
+  const wallet = createWalletClient({ account: from, transport });
+  // The dry run first, under the gas the transaction is sent with, so a
+  // refusal comes back with its reason. The transaction is signed here, so
+  // its hash is known before it is broadcast: once broadcast, any failure to
+  // learn its outcome leaves it in doubt, named, and never sent again here.
+  const send = async (
+    call: { address: Address; abi: Abi; functionName: string; args: readonly unknown[] },
+    gas: bigint,
+  ): Promise<TransactionReceipt> => {
+    await pub.simulateContract({ ...call, account: from.address, gas } as Parameters<typeof pub.simulateContract>[0]);
+    const [block, nonce] = await Promise.all([
+      pub.getBlock({ blockTag: "latest" }),
+      pub.getTransactionCount({ address: from.address, blockTag: "pending" }),
+    ]);
+    const raw = await wallet.signTransaction({
+      chain: null,
+      chainId,
+      to: call.address,
+      data: encodeFunctionData(call as Parameters<typeof encodeFunctionData>[0]),
+      value: 0n,
+      gas,
+      maxFeePerGas: (block.baseFeePerGas ?? 0n) * 2n + 1n,
+      maxPriorityFeePerGas: 1n,
+      nonce,
+      type: "eip1559",
+    });
+    const hash = keccak256(raw);
+    // The node's error, if any, rides along: a refusal its hash cannot show.
+    const inDoubt = (cause: unknown) =>
+      new Error(`${call.functionName} ${hash} with nonce ${nonce} was sent and its outcome is unknown: look it up before sending it again`, {
+        cause,
+      });
+    await pub.sendRawTransaction({ serializedTransaction: raw }).catch((error: unknown) => {
+      const refusal = error instanceof BaseError ? getNodeError(error, {}) : undefined;
+      if (REFUSALS.some((type) => refusal instanceof type))
+        throw new Error(`the node refused ${call.functionName}: ${refusal!.shortMessage}`, { cause: error });
+      throw inDoubt(error);
+    });
+    // A failed read of the receipt is not yet, until the deadline.
+    const deadline = Date.now() + timeoutMs;
+    let unread: unknown;
+    for (;;) {
+      const receipt = await pub.getTransactionReceipt({ hash }).catch((error: unknown) => {
+        unread = error;
+        return null;
+      });
+      if (receipt) return receipt;
+      if (Date.now() >= deadline) throw inDoubt(unread);
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+  };
+  return { pub, send };
+}
+
+function succeeded(functionName: string, receipt: TransactionReceipt): Hex {
+  if (receipt.status !== "success") throw new Error(`${functionName} reverted: ${receipt.transactionHash}`);
+  return receipt.transactionHash;
+}
+
+/** Put `amount` token base units into clearing custody under `account`, a
+ * clearing key; it must be a whole number of the contract's clearing
+ * units. `from` pays: an approval for the amount unless one that covers it
+ * stands, then the deposit. The contract takes deposits only between
+ * registrations, so the deposit waits for that window and is sent again
+ * if the window closes under it, up to `timeoutMs` (default 60 s). It
+ * refuses at once a contract that holds another token, and a deposit past
+ * what the contract holds in all. A deposit whose outcome is unknown is not
+ * sent again: the error names it. */
+export async function depositToClearing(
+  opts: ClearingChain & {
+    asset: Address;
+    account: Hex;
+    amount: bigint;
+    timeoutMs?: number;
+    pollMs?: number;
+  },
+): Promise<{ approveTx: Hex | null; depositTx: Hex }> {
+  if (opts.amount <= 0n) throw new Error("deposit amount must be positive");
+  const { pub, send } = chainClients(opts);
+  const contract = { address: opts.settlement, abi: clearingAbi } as const;
+  const [token, unit] = await Promise.all([
+    pub.readContract({ ...contract, functionName: "token" }),
+    pub.readContract({ ...contract, functionName: "unit" }),
+  ]);
+  if (token.toLowerCase() !== opts.asset.toLowerCase())
+    throw new Error(`this Clearing contract holds ${token}, not ${opts.asset}`);
+  // The contract counts clearing units; the approval moves base units.
+  const units = clearingUnits(opts.amount, unit);
+  // The contract refuses a deposit past this, with the same error as a closed window.
+  const assertRoom = async () => {
+    const [active, reserve] = await Promise.all([
+      pub.readContract({ ...contract, functionName: "activeCustody" }),
+      pub.readContract({ ...contract, functionName: "claimReserve" }),
+    ]);
+    const room = CLEARING_MAX_AMOUNT - active - reserve;
+    if (units > room)
+      throw new Error(
+        `this Clearing contract holds at most ${CLEARING_MAX_AMOUNT * unit} base units in all, and has room for ${room * unit} more`,
+      );
+  };
+  await assertRoom();
+  const allowance = await pub.readContract({
+    address: opts.asset,
+    abi: erc20Abi,
+    functionName: "allowance",
+    args: [opts.from.address, opts.settlement],
+  });
+  const approveTx =
+    allowance >= opts.amount
+      ? null
+      : succeeded(
+          "approve",
+          await send({ address: opts.asset, abi: erc20Abi, functionName: "approve", args: [opts.settlement, opts.amount] }, 100_000n),
+        );
+  const deposit = { ...contract, functionName: "deposit", args: [opts.account, units] } as const;
+  // About 450k on Metal, which charges 64 times Ethereum's gas for the modexp
+  // that decompresses the account's key.
+  const depositGas = 1_000_000n;
+  const deadline = Date.now() + (opts.timeoutMs ?? 60_000);
+  // Only the closed window is waited out; any other refusal is the caller's.
+  // A full contract reverts the same way, and `assertRoom` tells them apart.
+  const windowClosed = (error: unknown) =>
+    error instanceof BaseError &&
+    error.walk((e) => e instanceof ContractFunctionRevertedError && e.data?.errorName === "InvalidBoundary") !== null;
+  for (;;) {
+    // A deposit that reverts deposited nothing, and the next dry run says
+    // why: if the window closed under it, the next round waits for the next
+    // one; any other reason is named with the reverted deposit.
+    try {
+      const receipt = await send(deposit, depositGas);
+      if (receipt.status === "success") return { approveTx, depositTx: receipt.transactionHash };
+      const why = await pub
+        .simulateContract({ ...deposit, account: opts.from.address, gas: depositGas } as Parameters<typeof pub.simulateContract>[0])
+        .then(() => undefined, (error: unknown) => error);
+      if (!windowClosed(why))
+        throw new Error(
+          `deposit ${receipt.transactionHash} reverted${why instanceof BaseError ? `: ${why.shortMessage}` : ", and its dry run now passes"}`,
+        );
+    } catch (error) {
+      if (!windowClosed(error)) throw error;
+    }
+    await assertRoom();
+    if (Date.now() >= deadline) throw new Error("the Clearing contract took no deposits before the timeout");
+    await new Promise((resolve) => setTimeout(resolve, opts.pollMs ?? 500));
+  }
+}
+
+const accountKey = (account: Hex) =>
+  sha256(concatHex([stringToHex("_COMMONWARE_CLEARING_ACCOUNT_KEY"), account]));
+
+/** A payout claimed, `amount` in token base units. */
+type ClearingClaim = { amount: bigint; tx: Hex; deferred: boolean };
+type ClearingPayout = { destination: Hex; amount: string; proof: ClearingLogProof };
+
+/** `account`'s payout of its withdrawal in the finalized epoch `epoch` to
+ * `destination`, the one the withdrawal named, from the first of
+ * `serviceUrls` that proves it. */
+async function lookupPayout(
+  serviceUrls: readonly string[],
+  fetcher: typeof globalThis.fetch,
+  epoch: bigint,
+  account: Hex,
+  destination: Address,
+): Promise<ClearingPayout> {
+  const failures: string[] = [];
+  for (const serviceUrl of serviceUrls) {
+    try {
+      const payout = await serviceGet<ClearingPayout | null>(serviceUrl, `/payout/${epoch}/${account}`, fetcher);
+      if (!payout) failures.push(`${serviceUrl} has none`);
+      else if (payout.destination.toLowerCase() !== destination.toLowerCase())
+        failures.push(`${serviceUrl} names ${payout.destination}, not ${destination}, the destination the withdrawal named`);
+      else return payout;
+    } catch (error) {
+      failures.push(`${serviceUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  throw new Error(
+    `no clearing service named proves the payout of this account's withdrawal in epoch ${epoch}; a validator proves it once it has retained that epoch (${failures.join("; ")})`,
+  );
+}
+
+/** Claims `payout` to `destination` unless it is 0 or claimed already. The
+ * claim is pushed to `claimed` as it lands. */
+async function claimPayout(
+  { pub, send, settlement, unit }: ReturnType<typeof chainClients> & { settlement: Address; unit: bigint },
+  payout: ClearingPayout,
+  destination: Address,
+  claimed: ClearingClaim[],
+): Promise<void> {
+  const contract = { address: settlement, abi: clearingAbi } as const;
+  if (BigInt(payout.amount) === 0n) return;
+  const position = BigInt(payout.proof.location);
+  const consumed = await pub.readContract({ ...contract, functionName: "claimedPayouts", args: [position >> 8n] });
+  if (consumed & (1n << (position & 255n))) return;
+  const receipt = await send(
+    { ...contract, functionName: "claim", args: [destination, BigInt(payout.amount), clearingLogProof(payout.proof)] },
+    1_000_000n,
+  );
+  const tx = succeeded("claim", receipt);
+  const deferred = parseEventLogs({ abi: clearingAbi, eventName: "PayoutDeferred", logs: receipt.logs }).length > 0;
+  claimed.push({ amount: BigInt(payout.amount) * unit, tx, deferred });
+}
+
+export type ClearingWithdrawal =
+  /** A withdrawal is queued and `epoch`, the one that carries it, has not
+   * finalized; nothing can be sent until it does. */
+  | { status: "waiting"; epoch: bigint }
+  /** What this call sent: the account's payout it claimed, to the
+   * destination the finalized withdrawal named, and the withdrawal it
+   * queued for the account's finalized balance, or `null` when that balance
+   * is zero. A
+   * deferred payout is one the destination refused: it waits in the
+   * contract's `unclaimedPayout` until the destination calls
+   * `withdrawUnclaimed`. */
+  | { status: "sent"; claimed: ClearingClaim[]; queued: { tx: Hex } | null };
+
+/** Take `signer`'s funds out of clearing: claim the account's payout of a
+ * withdrawal that has finalized, to the destination it named, then queue a
+ * withdrawal of whatever finalized balance remains, to `destination` (`from` itself
+ * unless given). A payer's unused deposit and a seller's earnings leave the
+ * same way. Call again after the queued withdrawal's epoch finalizes. A
+ * failure after a claim names the claims made before it. */
+export async function withdrawFromClearing(
+  opts: ClearingChain & {
+    signer: ClearingSigner;
+    serviceUrl: string;
+    destination?: Address;
+    fetch?: typeof globalThis.fetch;
+  },
+): Promise<ClearingWithdrawal> {
+  const { pub, send } = chainClients(opts);
+  const fetcher = opts.fetch ?? globalThis.fetch;
+  const destination = opts.destination ?? opts.from.address;
+  const contract = { address: opts.settlement, abi: clearingAbi } as const;
+  const key = accountKey(opts.signer.publicKey);
+  if ((await pub.readContract({ ...contract, functionName: "fault" })) !== 0)
+    throw new Error("this Clearing deployment has faulted and takes no withdrawals: take the account's funds out with recoverFromClearing");
+  const [status, finalized, unit] = await Promise.all([
+    pub.readContract({ ...contract, functionName: "withdrawals", args: [key] }),
+    pub.readContract({ ...contract, functionName: "finalizedCount" }),
+    pub.readContract({ ...contract, functionName: "unit" }),
+  ]);
+  const [encodedHash, epochPlusOne, , , queuedTo] = status;
+  if (encodedHash !== `0x${"00".repeat(32)}` && (epochPlusOne === 0n || epochPlusOne > finalized)) {
+    if (epochPlusOne > 0n) return { status: "waiting", epoch: epochPlusOne - 1n };
+    // Not yet registered: the next registration carries it.
+    const [registered, admitted] = await Promise.all([
+      pub.readContract({ ...contract, functionName: "registered" }),
+      pub.readContract({ ...contract, functionName: "admittedCount" }),
+    ]);
+    return { status: "waiting", epoch: registered ? admitted + 1n : admitted };
+  }
+  const claimed: ClearingClaim[] = [];
+  try {
+    return await claimThenQueue();
+  } catch (error) {
+    if (claimed.length === 0) throw error;
+    const made = claimed.map((c) => `${c.amount} in ${c.tx}`).join(", ");
+    throw new Error(`${error instanceof Error ? error.message : String(error)}; claimed before it: ${made}`, { cause: error });
+  }
+
+  async function claimThenQueue(): Promise<ClearingWithdrawal> {
+    if (epochPlusOne > 0n)
+      await claimPayout(
+        { pub, send, settlement: opts.settlement, unit },
+        await lookupPayout([opts.serviceUrl], fetcher, epochPlusOne - 1n, opts.signer.publicKey, queuedTo),
+        queuedTo,
+        claimed,
+      );
+    // The service proves balances only against a finalized epoch.
+    if (finalized === 0n) return { status: "sent", claimed, queued: null };
+    const balance = await clearingBalance(opts.serviceUrl, opts.signer.publicKey, fetcher);
+    if (BigInt(balance.amount) === 0n || !balance.opening) return { status: "sent", claimed, queued: null };
+    const [deployment, policy, block] = await Promise.all([
+      pub.readContract({ ...contract, functionName: "deployment" }),
+      pub.readContract({ ...contract, functionName: "policy" }),
+      pub.getBlock(),
+    ]);
+    const close = await clearingClose(opts.signer, deployment, balance, destination, block.timestamp + policy[5]);
+    // The balance is proven against the finalized state: an epoch that
+    // finalizes before the withdrawal lands moves it, and the contract
+    // refuses the withdrawal with `InvalidBoundary`.
+    const receipt = await send({ ...contract, functionName: "queueWithdrawal", args: [close.withdrawal, close.opening] }, 2_000_000n).catch(
+      (error: unknown) => {
+        if (revertOf(error) !== "InvalidBoundary") throw error;
+        throw new Error("the withdrawal was refused because an epoch finalized under it: call withdrawFromClearing again", { cause: error });
+      },
+    );
+    return { status: "sent", claimed, queued: { tx: succeeded("queueWithdrawal", receipt) } };
+  }
+}
+
+export type ClearingRecovery =
+  /** The deployment has missed no deadline: withdraw with `withdrawFromClearing`. */
+  | { status: "operating" }
+  /** Faulted, and `epoch`, admitted before the fault, is still in its
+   * challenge window; recovery starts once it is final. `claimed` is the
+   * payout of the account's finalized withdrawal, claimed meanwhile. */
+  | { status: "waiting"; epoch: bigint; claimed: ClearingClaim[] }
+  /** What this call sent: the fault it raised, if it raised one, the
+   * payout of the account's finalized withdrawal, claimed to the
+   * destination it named, the account's last finalized balance, and each
+   * deposit no final epoch counted. `recover` pays a withdrawal still in
+   * flight to the destination it named and the rest to `destination`. A
+   * deferred payout waits in `unclaimedPayout` for `withdrawUnclaimed`.
+   * Every amount is in token base units. */
+  | {
+      status: "recovered";
+      faulted: Hex | null;
+      claimed: ClearingClaim[];
+      recovered: { amount: bigint; tx: Hex } | null;
+      refunded: { epoch: bigint; amount: bigint; tx: Hex }[];
+    };
+
+const revertOf = (error: unknown): string | undefined => {
+  if (!(error instanceof BaseError)) return undefined;
+  const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError);
+  return reverted instanceof ContractFunctionRevertedError ? (reverted.data?.errorName ?? "reverted") : undefined;
+};
+
+/** Take `signer`'s funds out of a Clearing deployment whose service has
+ * stopped. Once the service has missed a deadline, to admit an epoch it
+ * registered, a deposit, or the account's queued withdrawal, this faults
+ * the deployment, finalizes the epochs it admitted, starts recovery, and
+ * takes the payout of the account's finalized withdrawal, its last
+ * finalized balance and every deposit no final epoch counted, to
+ * `destination` (`from` itself unless given) or, for a withdrawal, to the
+ * destination it named. The payout and balance proofs come from
+ * `serviceUrl`, the clearing service or any of its validators, or the
+ * first of several that proves each. A proof none of them gives does not
+ * stop the steps that need none: they are taken, and then the error names
+ * what is left and what was sent. Each step already taken is skipped, so
+ * call it again after `waiting` or such an error. `from` pays the gas. */
+export async function recoverFromClearing(
+  opts: ClearingChain & {
+    signer: ClearingSigner;
+    serviceUrl: string | readonly string[];
+    destination?: Address;
+    fetch?: typeof globalThis.fetch;
+  },
+): Promise<ClearingRecovery> {
+  const serviceUrls = typeof opts.serviceUrl === "string" ? [opts.serviceUrl] : opts.serviceUrl;
+  if (serviceUrls.length === 0) throw new Error("recoverFromClearing needs a clearing service URL");
+  // A proof no service gives does not stop the steps that need none; the
+  // answer then names it, and what was sent.
+  let unclaimed: unknown;
+  let unproven: unknown;
+  const finish = (result: ClearingRecovery & { status: "waiting" | "recovered" }): ClearingRecovery => {
+    const missed = [unclaimed, unproven].filter((error) => error !== undefined);
+    if (missed.length === 0) return result;
+    const sent = [
+      result.status === "recovered" && result.faulted && `fault ${result.faulted}`,
+      ...result.claimed.map((c) => `claim ${c.tx}${c.deferred ? " (deferred: the destination calls withdrawUnclaimed)" : ""}`),
+      ...(result.status === "recovered"
+        ? [result.recovered && `recover ${result.recovered.tx}`, ...result.refunded.map((r) => `refundDeposit ${r.tx}`)]
+        : []),
+    ].filter(Boolean);
+    throw new Error(
+      `${missed.map((error) => (error instanceof Error ? error.message : String(error))).join("; ")}. ${
+        result.status === "waiting" ? `Epoch ${result.epoch} is still in its challenge window. ` : ""
+      }This call sent ${sent.length > 0 ? sent.join(", ") : "nothing"}: call recoverFromClearing again to take the rest`,
+      { cause: missed[0] },
+    );
+  };
+  const { pub, send } = chainClients(opts);
+  const fetcher = opts.fetch ?? globalThis.fetch;
+  const destination = opts.destination ?? opts.from.address;
+  const contract = { address: opts.settlement, abi: clearingAbi } as const;
+  const account = opts.signer.publicKey;
+  const key = accountKey(account);
+  const unit = await pub.readContract({ ...contract, functionName: "unit" });
+  let faulted: Hex | null = null;
+  if ((await pub.readContract({ ...contract, functionName: "fault" })) === 0) {
+    const admitted = await pub.readContract({ ...contract, functionName: "admittedCount" });
+    const faults = [
+      { functionName: "faultRegistration", args: [] },
+      { functionName: "faultWithdrawal", args: [account] },
+      { functionName: "faultDeposit", args: [admitted, account] },
+    ] as const;
+    for (const call of faults) {
+      try {
+        faulted = succeeded(call.functionName, await send({ ...contract, ...call }, 200_000n));
+        break;
+      } catch (error) {
+        // Each fault reverts `InvalidDeadline` until its deadline passes; any
+        // other refusal, running out of gas among them, is an error.
+        if (revertOf(error) !== "InvalidDeadline") throw error;
+      }
+    }
+    if (!faulted) return { status: "operating" };
+  }
+  // A withdrawal whose epoch finalized is paid by `claim`, not `recover`,
+  // and needs no recovery: it is claimed first, and again once this call
+  // finalizes the epoch that carries it.
+  const claimed: ClearingClaim[] = [];
+  const claimFinalized = async () => {
+    const [[, epochPlusOne, , , queuedTo], finalized] = await Promise.all([
+      pub.readContract({ ...contract, functionName: "withdrawals", args: [key] }),
+      pub.readContract({ ...contract, functionName: "finalizedCount" }),
+    ]);
+    unclaimed = undefined;
+    if (epochPlusOne === 0n || epochPlusOne > finalized) return;
+    // `recover` does not pay a finalized withdrawal, so a later call claims it.
+    const payout = await lookupPayout(serviceUrls, fetcher, epochPlusOne - 1n, account, queuedTo).catch((error: unknown) => {
+      unclaimed = error;
+    });
+    if (payout) await claimPayout({ pub, send, settlement: opts.settlement, unit }, payout, queuedTo, claimed);
+  };
+  await claimFinalized();
+  if (!(await pub.readContract({ ...contract, functionName: "recovering" }))) {
+    for (;;) {
+      const [finalized, admitted, invalidFrom] = await Promise.all([
+        pub.readContract({ ...contract, functionName: "finalizedCount" }),
+        pub.readContract({ ...contract, functionName: "admittedCount" }),
+        pub.readContract({ ...contract, functionName: "invalidFrom" }),
+      ]);
+      if (finalized >= admitted || finalized >= invalidFrom) break;
+      try {
+        succeeded("finalize", await send({ ...contract, functionName: "finalize", args: [] }, 2_000_000n));
+      } catch (error) {
+        if (revertOf(error) === "InvalidDeadline") return finish({ status: "waiting", epoch: finalized, claimed });
+        throw error;
+      }
+    }
+    try {
+      succeeded("beginRecovery", await send({ ...contract, functionName: "beginRecovery", args: [] }, 200_000n));
+    } catch (error) {
+      // Someone else started it between the read and the dry run.
+      if (revertOf(error) === undefined || !(await pub.readContract({ ...contract, functionName: "recovering" }))) throw error;
+    }
+  }
+  await claimFinalized();
+  const [deployment, state, finalized, admitted, done] = await Promise.all([
+    pub.readContract({ ...contract, functionName: "deployment" }),
+    pub.readContract({ ...contract, functionName: "finalizedState" }),
+    pub.readContract({ ...contract, functionName: "finalizedCount" }),
+    pub.readContract({ ...contract, functionName: "admittedCount" }),
+    pub.readContract({ ...contract, functionName: "recoveredAccounts", args: [key] }),
+  ]);
+  let recovered: { amount: bigint; tx: Hex } | null = null;
+  const balance = !done && finalized > 0n ? await provenBalance(state).catch((error: unknown) => void (unproven = error)) : undefined;
+  if (balance) {
+    if (BigInt(balance.amount) > 0n && balance.opening) {
+      const { amount, nextKey, ...proof } = balance.opening;
+      const signature = await opts.signer.sign("_METAL_CLEARING_RECOVERY", concatHex([deployment, state, destination]));
+      const receipt = await send(
+        {
+          ...contract,
+          functionName: "recover",
+          args: [account, destination, signature, { amount: BigInt(amount), nextKey, proof: clearingLogProof(proof) }],
+        },
+        2_000_000n,
+      );
+      recovered = { amount: BigInt(balance.amount) * unit, tx: succeeded("recover", receipt) };
+    }
+  }
+  const refunded: { epoch: bigint; amount: bigint; tx: Hex }[] = [];
+  for (let epoch = finalized; epoch <= admitted; epoch++) {
+    const amount = await pub.readContract({ ...contract, functionName: "depositAmounts", args: [epoch, key] });
+    if (amount === 0n) continue;
+    const signature = await opts.signer.sign(
+      "_METAL_CLEARING_DEPOSIT_REFUND",
+      concatHex([deployment, clearingUint64(epoch), clearingUint64(amount), destination]),
+    );
+    // About 760k on Metal, which charges 64 times Ethereum's gas for P-256 and modexp.
+    const receipt = await send({ ...contract, functionName: "refundDeposit", args: [epoch, account, destination, signature] }, 1_200_000n);
+    refunded.push({ epoch, amount: amount * unit, tx: succeeded("refundDeposit", receipt) });
+  }
+  return finish({ status: "recovered", faulted, claimed, recovered, refunded });
+
+  /** The account's balance as of `state`, from the first service that proves it there. */
+  async function provenBalance(state: Hex): Promise<ClearingBalance> {
+    const failures: string[] = [];
+    for (const serviceUrl of serviceUrls) {
+      try {
+        const balance = await clearingBalance(serviceUrl, account, fetcher);
+        if (balance.state.toLowerCase() === state.toLowerCase()) return balance;
+        failures.push(`${serviceUrl} proves balances against ${balance.state}`);
+      } catch (error) {
+        failures.push(`${serviceUrl}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    throw new Error(
+      `no clearing service named proves this account's balance at the contract's finalized state ${state}; a validator proves it once it has retained the last finalized epoch (${failures.join("; ")})`,
+    );
+  }
+}