@metalntwx/metal-pay 0.2.0 → 0.3.1

package/src/clearing-custody.test.ts

@@ -0,0 +1,763 @@
+import { createServer, type Server } from "node:http";
+import { inspect } from "node:util";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  decodeFunctionData,
+  encodeAbiParameters,
+  encodeFunctionResult,
+  keccak256,
+  numberToHex,
+  parseTransaction,
+  recoverTransactionAddress,
+  toFunctionSelector,
+  type Hex,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { clearingAbi } from "./clearing-abi.js";
+import { createClearingSigner } from "./clearing-codec.js";
+import { CLEARING_MAX_AMOUNT, clearingSpendable, depositToClearing, recoverFromClearing, withdrawFromClearing } from "./clearing-custody.js";
+
+const ZERO32 = `0x${"00".repeat(32)}`;
+const ASSET = `0x${"33".repeat(20)}` as const;
+const sent: { hash: Hex; nonce: number; data: Hex; from: Hex }[] = [];
+let unreadable = 0;
+/** What the Clearing contract answers: its token, the custody it holds (one
+ * value per read, the last repeated), and whether a deposit's dry run reverts
+ * with `InvalidBoundary`; and what the depositor holds of the token (one value
+ * per read, the last repeated), past which its dry run reverts as the token
+ * does, with the reason "balance". */
+const contract = { token: ASSET as Hex, custody: [0n], depositReverts: false, held: [2n ** 128n] };
+/** How the node misbehaves: it takes a transaction and loses its answer,
+ * refuses it with an error, never mines, or mines the next deposit, or the
+ * next call of a Clearing function named in `revertNext`, as a revert; and
+ * the gas each dry run of a deposit was given. */
+const node = {
+  dropAnswer: false,
+  refuseWith: undefined as string | undefined,
+  neverMined: false,
+  revertNextDeposit: false,
+  revertNext: new Set<string>(),
+  dryRunGas: [] as (string | undefined)[],
+};
+const reverted = new Set<Hex>();
+const SETTLEMENT = `0x${"22".repeat(20)}` as const;
+/** The Clearing contract's views a withdrawal or recovery reads, by name, and
+ * the calls whose dry run reverts, with the error they revert with ("" for a
+ * revert with no reason, as running out of gas inside a call gives). */
+/** The contract's clearing unit: an 18-decimal token's, a millionth of it. */
+const UNIT = 10n ** 12n;
+const views: Record<string, (args: readonly unknown[]) => unknown> = { unit: () => UNIT };
+const refusing: Record<string, string> = {};
+/** The payout positions claimed, as the contract's bitmap records them. */
+const claimedPositions = new Set<bigint>();
+const word = (type: "address" | "uint64" | "uint256", value: unknown) => encodeAbiParameters([{ type }], [value as never]);
+const selector = (signature: string) => toFunctionSelector(signature);
+
+/** A chain that mines every transaction, where the first deposit's receipt cannot be read for a while. */
+const rpc = createServer((req, res) => {
+  let body = "";
+  req.on("data", (c) => (body += c));
+  req.on("end", async () => {
+    const { id, method, params } = JSON.parse(body);
+    const ok = (result: unknown) => res.end(JSON.stringify({ jsonrpc: "2.0", id, result }));
+    const fail = (code: number, message: string) => res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
+    res.setHeader("content-type", "application/json");
+    const mined = (hash: Hex) => sent.find((s) => s.hash === hash);
+    switch (method) {
+      case "eth_chainId":
+        return ok("0x539");
+      case "eth_blockNumber":
+        return ok(numberToHex(10 + sent.length));
+      case "eth_call": {
+        const data = String(params[0].data ?? params[0].input) as Hex;
+        const call = (() => {
+          try {
+            return decodeFunctionData({ abi: clearingAbi, data });
+          } catch {
+            return undefined;
+          }
+        })();
+        if (call && call.functionName in refusing) {
+          const reason = refusing[call.functionName];
+          return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: 3, message: "execution reverted", data: reason ? selector(`${reason}()`) : undefined } }));
+        }
+        if (call?.functionName === "claimedPayouts") {
+          const word = call.args[0] as bigint;
+          let bits = 0n;
+          for (const position of claimedPositions) if (position >> 8n === word) bits |= 1n << (position & 255n);
+          return ok(encodeFunctionResult({ abi: clearingAbi, functionName: "claimedPayouts", result: bits }));
+        }
+        if (call && views[call.functionName])
+          return ok(encodeFunctionResult({ abi: clearingAbi, functionName: call.functionName, result: views[call.functionName]!(call.args ?? []) } as never));
+        // A standing allowance.
+        if (data.startsWith(selector("allowance(address,address)"))) return ok(`0x${"ff".repeat(32)}`);
+        if (data.startsWith(selector("token()"))) return ok(word("address", contract.token));
+        if (data.startsWith(selector("activeCustody()")))
+          return ok(word("uint64", contract.custody.length > 1 ? contract.custody.shift() : contract.custody[0]));
+        if (data.startsWith(selector("claimReserve()"))) return ok(word("uint64", 0n));
+        const held = () => (contract.held.length > 1 ? contract.held.shift()! : contract.held[0]!);
+        if (data.startsWith(selector("balanceOf(address)")))
+          return ok(word("uint256", `0x${data.slice(-40)}`.toLowerCase() === depositor.address.toLowerCase() ? held() : 0n));
+        if (call?.functionName === "deposit" && (call.args[1] as bigint) * UNIT > held())
+          return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: 3, message: "execution reverted: balance", data: selector("Error(string)") + encodeAbiParameters([{ type: "string" }], ["balance"]).slice(2) } }));
+        if (data.startsWith(selector("deposit(bytes,uint64)"))) node.dryRunGas.push(params[0].gas);
+        if (data.startsWith(selector("deposit(bytes,uint64)")) && contract.depositReverts)
+          return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: 3, message: "execution reverted", data: selector("InvalidBoundary()") } }));
+        return ok("0x");
+      }
+      case "eth_getBlockByNumber":
+        return ok({
+          number: "0xa", hash: ZERO32, parentHash: ZERO32, timestamp: "0x1", baseFeePerGas: "0x7", gasLimit: "0x1", gasUsed: "0x0",
+          transactions: [], logsBloom: `0x${"00".repeat(256)}`, miner: `0x${"00".repeat(20)}`, extraData: "0x", difficulty: "0x0",
+          nonce: "0x0000000000000000", sha3Uncles: ZERO32, stateRoot: ZERO32, receiptsRoot: ZERO32, transactionsRoot: ZERO32, size: "0x1", uncles: [],
+        });
+      case "eth_getTransactionCount":
+        return ok(numberToHex(sent.length));
+      case "eth_sendRawTransaction": {
+        if (node.refuseWith) return fail(-32000, node.refuseWith);
+        const raw = params[0] as Hex;
+        const tx = parseTransaction(raw);
+        const hash = keccak256(raw);
+        sent.push({ hash, nonce: tx.nonce ?? 0, data: tx.data ?? "0x", from: await recoverTransactionAddress({ serializedTransaction: raw as never }) });
+        if (node.revertNextDeposit && (tx.data ?? "").startsWith(selector("deposit(bytes,uint64)"))) {
+          node.revertNextDeposit = false;
+          reverted.add(hash);
+        }
+        try {
+          const call = decodeFunctionData({ abi: clearingAbi, data: tx.data ?? "0x" });
+          if (node.revertNext.delete(call.functionName)) reverted.add(hash);
+          else if (call.functionName === "claim") claimedPositions.add((call.args[2] as { location: bigint }).location);
+        } catch {}
+        if (node.dropAnswer) return res.destroy();
+        return ok(hash);
+      }
+      case "eth_getTransactionByHash": {
+        const t = mined(params[0]);
+        if (!t) return ok(null);
+        return ok({
+          hash: t.hash, nonce: numberToHex(t.nonce), blockNumber: "0xb", blockHash: ZERO32, transactionIndex: "0x0", from: t.from,
+          to: `0x${"22".repeat(20)}`, input: t.data, value: "0x0", gas: "0x1", type: "0x2", maxFeePerGas: "0xf", maxPriorityFeePerGas: "0x1",
+          chainId: "0x539", v: "0x0", r: ZERO32, s: ZERO32,
+        });
+      }
+      case "eth_getTransactionReceipt": {
+        const t = mined(params[0]);
+        if (!t || node.neverMined) return ok(null);
+        if (t === sent[0] && unreadable < 2) {
+          unreadable++;
+          return fail(-32000, "upstream node unavailable");
+        }
+        return ok({
+          status: reverted.has(t.hash) ? "0x0" : "0x1", transactionHash: t.hash, blockNumber: "0xb", blockHash: ZERO32, from: t.from, to: `0x${"22".repeat(20)}`,
+          gasUsed: "0x1", cumulativeGasUsed: "0x1", effectiveGasPrice: "0x1", logs: [], logsBloom: `0x${"00".repeat(256)}`, type: "0x2",
+          transactionIndex: "0x0", contractAddress: null,
+        });
+      }
+      default:
+        return fail(-32601, `unhandled ${method}`);
+    }
+  });
+});
+
+let rpcUrl: string;
+beforeAll(async () => {
+  rpcUrl = await listen(rpc);
+});
+afterAll(() => new Promise<void>((resolve) => rpc.close(() => resolve())));
+
+const depositor = privateKeyToAccount(`0x${"45".repeat(32)}`);
+const deposit = (amount = 1000n * UNIT) =>
+  depositToClearing({
+    rpcUrl,
+    chainId: 1337,
+    from: depositor,
+    settlement: `0x${"22".repeat(20)}`,
+    asset: ASSET,
+    account: `0x02${"11".repeat(32)}`,
+    amount,
+    timeoutMs: 500,
+    pollMs: 10,
+  });
+
+describe("depositToClearing", () => {
+
+  it("reports a mined deposit done when reads of its receipt fail for a while", async () => {
+    const { depositTx } = await deposit();
+    expect(sent).toHaveLength(1);
+    expect(depositTx).toBe(sent[0]!.hash);
+  });
+
+  it("names the deposit it sent, and sends nothing more, when the node's answer to it is lost", async () => {
+    sent.length = 0;
+    node.dropAnswer = true;
+    try {
+      const refused = deposit();
+      await expect(refused).rejects.toThrow(/^deposit 0x[0-9a-f]{64} with nonce 0 /);
+      await expect(refused).rejects.toThrow(sent[0]!.hash);
+      // The node's own answer stays with it, for a refusal the hash cannot show.
+      await expect(refused).rejects.toHaveProperty("cause.name", "HttpRequestError");
+    } finally {
+      node.dropAnswer = false;
+    }
+    expect(sent).toHaveLength(1);
+  });
+
+  it("keeps the RPC URL, which can hold the endpoint's credential, out of the error and its cause", async () => {
+    sent.length = 0;
+    node.dropAnswer = true;
+    try {
+      const error = await depositToClearing({
+        rpcUrl: `${rpcUrl}/v2/k3y-0f-the-endpoint`,
+        chainId: 1337,
+        from: privateKeyToAccount(`0x${"45".repeat(32)}`),
+        settlement: SETTLEMENT,
+        asset: ASSET,
+        account: `0x02${"11".repeat(32)}`,
+        amount: 1000n * UNIT,
+      }).catch((e: unknown) => e);
+      expect(error).toHaveProperty("cause.name", "HttpRequestError");
+      expect(inspect(error, { depth: Infinity })).toContain("[RPC URL hidden]");
+      expect(inspect(error, { depth: Infinity })).not.toContain("k3y-0f-the-endpoint");
+      expect(inspect(error, { depth: Infinity })).not.toContain(rpcUrl);
+    } finally {
+      node.dropAnswer = false;
+    }
+  });
+
+  it("names a deposit whose receipt does not arrive, and does not send it again", async () => {
+    sent.length = 0;
+    node.neverMined = true;
+    try {
+      await expect(deposit()).rejects.toThrow(/^deposit 0x[0-9a-f]{64} with nonce 0 was sent and its outcome is unknown/);
+    } finally {
+      node.neverMined = false;
+    }
+    expect(sent).toHaveLength(1);
+  });
+
+  it("names a deposit the node refuses as refused, not in doubt", async () => {
+    node.refuseWith = "insufficient funds for gas * price + value";
+    try {
+      const error = await deposit().catch((e: unknown) => e);
+      expect(String(error)).toMatch(/refused deposit/);
+      expect(String(error)).not.toMatch(/outcome is unknown/);
+    } finally {
+      node.refuseWith = undefined;
+    }
+  });
+
+  it("dry-runs a deposit under the gas it is sent with", async () => {
+    sent.length = 0;
+    node.dryRunGas.length = 0;
+    await deposit();
+    expect(node.dryRunGas.at(-1)).toBe(numberToHex(1_000_000));
+  });
+
+  it("names a deposit that reverted when its next dry run passes, and sends it no more", async () => {
+    sent.length = 0;
+    node.revertNextDeposit = true;
+    await expect(deposit()).rejects.toThrow(/^deposit 0x[0-9a-f]{64} reverted/);
+    expect(sent).toHaveLength(1);
+  });
+
+  it("names what the sender holds and what the deposit needs, in *USDZ, when the token refuses the transfer for its balance", async () => {
+    // k12-backend's top-up: a deposit from a key that holds less than it.
+    sent.length = 0;
+    contract.held = [300_000n * UNIT];
+    try {
+      const from = depositor.address;
+      await expect(deposit(500_000n * UNIT)).rejects.toThrow(
+        `the deposit was refused, and nothing was deposited: ${from} holds 0.3 *USDZ and the deposit needs 0.5 *USDZ; fund it or deposit less`,
+      );
+      expect(sent).toHaveLength(0);
+      // Mined as a revert after its dry run passed, then refused for the balance read after it.
+      node.revertNextDeposit = true;
+      contract.held = [10n ** 18n, 300_000n * UNIT];
+      await expect(deposit(500_000n * UNIT)).rejects.toThrow(
+        new RegExp(`^deposit 0x[0-9a-f]{64} reverted: ${from} holds 0.3 \\*USDZ and the deposit needs 0.5 \\*USDZ; fund it or deposit less$`),
+      );
+      expect(sent).toHaveLength(1);
+    } finally {
+      contract.held = [2n ** 128n];
+      node.revertNextDeposit = false;
+    }
+  });
+
+  it("refuses a Clearing contract that holds another token, sending nothing", async () => {
+    sent.length = 0;
+    contract.token = `0x${"44".repeat(20)}`;
+    try {
+      await expect(deposit()).rejects.toThrow(/holds 0x4444444444444444444444444444444444444444/);
+    } finally {
+      contract.token = ASSET;
+    }
+    expect(sent).toHaveLength(0);
+  });
+
+  it("names the contract's limit on what it holds in all, before sending and when another deposit fills it first", async () => {
+    sent.length = 0;
+    contract.custody = [CLEARING_MAX_AMOUNT - 10n];
+    await expect(deposit()).rejects.toThrow(
+      `holds at most ${CLEARING_MAX_AMOUNT * UNIT} base units in all, and has room for ${10n * UNIT} more`,
+    );
+    expect(sent).toHaveLength(0);
+    // Room at first, then the dry run reverts because another deposit took it.
+    contract.custody = [0n, CLEARING_MAX_AMOUNT - 10n];
+    contract.depositReverts = true;
+    try {
+      await expect(deposit()).rejects.toThrow(`has room for ${10n * UNIT} more`);
+    } finally {
+      contract.custody = [0n];
+      contract.depositReverts = false;
+    }
+    expect(sent).toHaveLength(0);
+  });
+
+  it("deposits whole clearing units and refuses a fraction of one, sending nothing", async () => {
+    sent.length = 0;
+    await expect(deposit(UNIT + 1n)).rejects.toThrow(/whole number of clearing units/);
+    expect(sent).toHaveLength(0);
+    await deposit(5n * UNIT);
+    const sentDeposit = decodeFunctionData({ abi: clearingAbi, data: sent.at(-1)!.data });
+    expect(sentDeposit).toMatchObject({ functionName: "deposit", args: [expect.any(String), 5n] });
+  });
+});
+
+function listen(server: Server): Promise<string> {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") return reject(new Error("no port"));
+      resolve(`http://127.0.0.1:${address.port}`);
+    });
+  });
+}
+
+const DESTINATION = `0x${"77".repeat(20)}` as const;
+const signer = createClearingSigner(`0x${"56".repeat(32)}`);
+const proof = (location: number) => ({ location: String(location), leaves: "9", inactivePeaks: 0, digests: [] });
+/** The account's finalized balance, as the clearing service proves it. */
+let balance: unknown = { state: ZERO32, amount: "0", opening: null };
+/** The clearing service's answers, and the paths asked of it. */
+const asked: string[] = [];
+const service = (payouts: Record<string, unknown>) => async (input: URL | RequestInfo) => {
+  const path = new URL(String(input)).pathname;
+  asked.push(path);
+  if (path.startsWith("/payout/")) return Response.json(payouts[path] ?? null);
+  // The service proves balances only against a finalized epoch.
+  if (path.startsWith("/balance/"))
+    return views.finalizedCount?.([]) === 0n ? new Response("no finalized clearing balances", { status: 409 }) : Response.json(balance);
+  if (path === `/spendable/${signer.publicKey}`) return Response.json({ amount: "950" });
+  return new Response(null, { status: 404 });
+};
+const custody = (fetch: ReturnType<typeof service>) => ({
+  rpcUrl,
+  chainId: 1337,
+  from: privateKeyToAccount(`0x${"45".repeat(32)}`),
+  settlement: SETTLEMENT,
+  signer,
+  serviceUrl: "http://clearing.test",
+  fetch: fetch as typeof globalThis.fetch,
+});
+/** Several clearing services, by host. */
+const hosts =
+  (byHost: Record<string, ReturnType<typeof service>>) =>
+  (input: URL | RequestInfo) =>
+    byHost[new URL(String(input)).host]!(input);
+const unavailable = async () => Response.json({ error: "clearing request unavailable" }, { status: 409 });
+/** This account's withdrawal, queued to DESTINATION in epoch 2. */
+const withdrawalIn2 = () => [`0x${"ab".repeat(32)}`, 3n, 0n, 0n, DESTINATION, true];
+
+describe("clearingSpendable", () => {
+  it("answers in token base units, as deposits and prices count, though the service counts clearing units", async () => {
+    const spendable = await clearingSpendable({
+      rpcUrl,
+      settlement: SETTLEMENT,
+      serviceUrl: "http://clearing.test",
+      account: signer.publicKey,
+      fetch: service({}) as typeof globalThis.fetch,
+    });
+    expect(spendable).toBe(950n * UNIT);
+  });
+
+  it("names an RPC endpoint that does not answer as unreachable, hiding its URL", async () => {
+    const error = await clearingSpendable({
+      rpcUrl: "http://127.0.0.1:1/k3y-0f-the-endpoint",
+      settlement: SETTLEMENT,
+      serviceUrl: "http://clearing.test",
+      account: signer.publicKey,
+      fetch: service({}) as typeof globalThis.fetch,
+    }).catch((e: unknown) => e);
+    expect(String(error)).toMatch(/the RPC endpoint could not be reached/);
+    expect(String(error)).toMatch(/function:\s+unit\(\)/);
+    expect(inspect(error, { depth: Infinity })).not.toContain("k3y-0f-the-endpoint");
+  });
+});
+
+describe("withdrawing and recovering", () => {
+  it("claims only this account's payout, by one lookup, when another account's payout goes to the same destination, and not again", async () => {
+    sent.length = 0;
+    asked.length = 0;
+    claimedPositions.clear();
+    Object.assign(views, { fault: () => 0, withdrawals: withdrawalIn2, finalizedCount: () => 5n });
+    // Positions 6 and 7 both pay DESTINATION; 7 is this account's.
+    const fetch = service({ [`/payout/2/${signer.publicKey}`]: { destination: DESTINATION, amount: "150", proof: proof(7) } });
+    const first = await withdrawFromClearing(custody(fetch));
+    expect(first).toMatchObject({ status: "sent", claimed: [{ amount: 150n * UNIT }], queued: null });
+    expect(asked.filter((path) => path.startsWith("/payout/"))).toEqual([`/payout/2/${signer.publicKey}`]);
+    expect([...claimedPositions]).toEqual([7n]);
+    expect(await withdrawFromClearing(custody(fetch))).toEqual({ status: "empty" });
+  });
+
+  it("refuses a payout the service names to another destination, claiming nothing", async () => {
+    sent.length = 0;
+    claimedPositions.clear();
+    Object.assign(views, { fault: () => 0, withdrawals: withdrawalIn2, finalizedCount: () => 5n });
+    const fetch = service({ [`/payout/2/${signer.publicKey}`]: { destination: `0x${"88".repeat(20)}`, amount: "150", proof: proof(7) } });
+    await expect(withdrawFromClearing(custody(fetch))).rejects.toThrow(/not 0x7777777777777777777777777777777777777777/);
+    expect(sent).toHaveLength(0);
+  });
+
+  it("claims a finalized withdrawal while an epoch admitted before the fault is still in its challenge window", async () => {
+    sent.length = 0;
+    claimedPositions.clear();
+    Object.assign(views, {
+      fault: () => 1,
+      recovering: () => false,
+      withdrawals: withdrawalIn2,
+      finalizedCount: () => 5n,
+      admittedCount: () => 6n,
+      invalidFrom: () => 7n,
+    });
+    refusing.finalize = "InvalidDeadline";
+    try {
+      const fetch = service({ [`/payout/2/${signer.publicKey}`]: { destination: DESTINATION, amount: "150", proof: proof(7) } });
+      expect(await recoverFromClearing(custody(fetch))).toMatchObject({ status: "waiting", epoch: 5n, claimed: [{ amount: 150n * UNIT }] });
+    } finally {
+      delete refusing.finalize;
+    }
+  });
+
+  it("claims nothing for a payout of 0", async () => {
+    sent.length = 0;
+    claimedPositions.clear();
+    Object.assign(views, { fault: () => 0, withdrawals: withdrawalIn2, finalizedCount: () => 5n });
+    const fetch = service({ [`/payout/2/${signer.publicKey}`]: { destination: DESTINATION, amount: "0", proof: proof(7) } });
+    expect(await withdrawFromClearing(custody(fetch))).toEqual({ status: "empty" });
+    expect(sent).toHaveLength(0);
+  });
+
+  it("answers empty for a zero finalized balance and no withdrawal, sending nothing, every time", async () => {
+    sent.length = 0;
+    Object.assign(views, { fault: () => 0, withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false], finalizedCount: () => 5n });
+    expect(await withdrawFromClearing(custody(service({})))).toEqual({ status: "empty" });
+    expect(await withdrawFromClearing(custody(service({})))).toEqual({ status: "empty" });
+    expect(sent).toHaveLength(0);
+  });
+
+  it("queues nothing before the first epoch finalizes", async () => {
+    sent.length = 0;
+    Object.assign(views, { fault: () => 0, withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false], finalizedCount: () => 0n });
+    expect(await withdrawFromClearing(custody(service({})))).toEqual({ status: "empty" });
+    expect(sent).toHaveLength(0);
+  });
+
+  it("fails, rather than answering that the deployment operates, when a fault's dry run reverts for another reason than its deadline", async () => {
+    sent.length = 0;
+    Object.assign(views, { fault: () => 0, admittedCount: () => 5n });
+    Object.assign(refusing, { faultRegistration: "InvalidDeadline", faultWithdrawal: "", faultDeposit: "InvalidDeadline" });
+    try {
+      await expect(recoverFromClearing(custody(service({})))).rejects.toThrow(/faultWithdrawal/);
+    } finally {
+      for (const name of ["faultRegistration", "faultWithdrawal", "faultDeposit"]) delete refusing[name];
+    }
+    expect(sent).toHaveLength(0);
+  });
+
+  it("refunds the deposits of a deployment that faulted before any epoch finalized", async () => {
+    sent.length = 0;
+    Object.assign(views, {
+      fault: () => 1,
+      recovering: () => true,
+      withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false],
+      finalizedCount: () => 0n,
+      admittedCount: () => 0n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      finalizedState: () => ZERO32,
+      recoveredAccounts: () => false,
+      depositAmounts: ([epoch]: readonly unknown[]) => (epoch === 0n ? 40n : 0n),
+    });
+    expect(await recoverFromClearing(custody(service({})))).toMatchObject({ status: "recovered", recovered: null, refunded: [{ epoch: 0n, amount: 40n * UNIT }] });
+  });
+
+  it("takes the payout from the next service named when one has not retained its epoch", async () => {
+    sent.length = 0;
+    claimedPositions.clear();
+    Object.assign(views, {
+      fault: () => 1,
+      recovering: () => false,
+      withdrawals: withdrawalIn2,
+      finalizedCount: () => 5n,
+      admittedCount: () => 6n,
+      invalidFrom: () => 7n,
+    });
+    refusing.finalize = "InvalidDeadline";
+    try {
+      const fetch = hosts({
+        "a.test": unavailable,
+        "b.test": service({ [`/payout/2/${signer.publicKey}`]: { destination: DESTINATION, amount: "150", proof: proof(7) } }),
+      });
+      expect(await recoverFromClearing({ ...custody(fetch), serviceUrl: ["http://a.test", "http://b.test"] })).toMatchObject({
+        status: "waiting",
+        epoch: 5n,
+        claimed: [{ amount: 150n * UNIT }],
+      });
+    } finally {
+      delete refusing.finalize;
+    }
+  });
+
+  it("takes the balance from the next service named when one proves another state", async () => {
+    sent.length = 0;
+    Object.assign(views, {
+      fault: () => 1,
+      recovering: () => true,
+      withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false],
+      finalizedCount: () => 5n,
+      admittedCount: () => 5n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      finalizedState: () => ZERO32,
+      recoveredAccounts: () => false,
+      depositAmounts: () => 0n,
+    });
+    const proven = (state: string) => async () =>
+      Response.json({
+        state,
+        amount: "100",
+        opening: { ...proof(1), amount: "100", nextKey: ZERO32, chunk: ZERO32, opsRoot: ZERO32, pending: ZERO32, partialDigest: ZERO32 },
+      });
+    const fetch = hosts({ "a.test": proven(`0x${"11".repeat(32)}`), "b.test": proven(ZERO32) });
+    expect(await recoverFromClearing({ ...custody(fetch), serviceUrl: ["http://a.test", "http://b.test"] })).toMatchObject({
+      status: "recovered",
+      recovered: { amount: 100n * UNIT },
+    });
+  });
+
+  it("refunds and recovers when no service named has the payout, then names the payout left to claim", async () => {
+    sent.length = 0;
+    Object.assign(views, {
+      fault: () => 1,
+      recovering: () => true,
+      withdrawals: withdrawalIn2,
+      finalizedCount: () => 5n,
+      admittedCount: () => 5n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      finalizedState: () => ZERO32,
+      recoveredAccounts: () => false,
+      depositAmounts: ([epoch]: readonly unknown[]) => (epoch === 5n ? 40n : 0n),
+    });
+    const fetch = hosts({ "a.test": unavailable, "b.test": async (input) => (new URL(String(input)).pathname.startsWith("/payout/") ? unavailable() : service({})(input)) });
+    const error = await recoverFromClearing({ ...custody(fetch), serviceUrl: ["http://a.test", "http://b.test"] }).catch((e: unknown) => e);
+    expect(String(error)).toMatch(/epoch 2/);
+    expect(String(error)).toMatch(/http:\/\/a\.test.*409.*http:\/\/b\.test.*409/);
+    expect(String(error)).toMatch(/refundDeposit 0x[0-9a-f]{64}.*call recoverFromClearing again/);
+    expect(sent).toHaveLength(1);
+  });
+
+  it("names the claim it sent when no service named proves the balance", async () => {
+    sent.length = 0;
+    claimedPositions.clear();
+    Object.assign(views, {
+      fault: () => 1,
+      recovering: () => true,
+      withdrawals: withdrawalIn2,
+      finalizedCount: () => 5n,
+      admittedCount: () => 5n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      finalizedState: () => ZERO32,
+      recoveredAccounts: () => false,
+      depositAmounts: () => 0n,
+    });
+    const payouts = service({ [`/payout/2/${signer.publicKey}`]: { destination: DESTINATION, amount: "150", proof: proof(7) } });
+    const fetch = async (input: URL | RequestInfo) =>
+      new URL(String(input)).pathname.startsWith("/balance/") ? unavailable() : payouts(input);
+    const error = await recoverFromClearing(custody(fetch)).catch((e: unknown) => e);
+    expect(String(error)).toMatch(/balance.*This call sent claim 0x[0-9a-f]{64}: call recoverFromClearing again/);
+  });
+
+  it("asks for another call when an epoch finalizes while the withdrawal is queued", async () => {
+    sent.length = 0;
+    Object.assign(views, {
+      fault: () => 0,
+      withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false],
+      finalizedCount: () => 5n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      policy: () => [0n, 0n, 0n, 0n, 60n, 86_400n],
+      // The state the balance was proven against has since moved on.
+      finalizedState: () => `0x${"ee".repeat(32)}`,
+    });
+    balance = {
+      state: ZERO32,
+      amount: "100",
+      opening: { ...proof(1), amount: "100", nextKey: ZERO32, chunk: ZERO32, opsRoot: ZERO32, pending: ZERO32, partialDigest: ZERO32 },
+    };
+    refusing.queueWithdrawal = "InvalidBoundary";
+    try {
+      await expect(withdrawFromClearing(custody(service({})))).rejects.toThrow(
+        /^queueWithdrawal was refused because an epoch finalized under it, .*nothing was lost: make the same call again after the next epoch$/,
+      );
+      // Under the state it was proven against, the refusal is the contract's own, not a reason to call again.
+      views.finalizedState = () => ZERO32;
+      const error = await withdrawFromClearing(custody(service({}))).catch((e: Error) => e);
+      expect(String(error)).toMatch(/InvalidBoundary/);
+      expect(String(error)).not.toMatch(/finalized under it/);
+    } finally {
+      delete refusing.queueWithdrawal;
+      balance = { state: ZERO32, amount: "0", opening: null };
+    }
+    expect(sent).toHaveLength(0);
+  });
+
+  it("names a queued withdrawal mined as a revert because an epoch finalized under it as lost nothing, to call again after the next epoch", async () => {
+    sent.length = 0;
+    Object.assign(views, {
+      fault: () => 0,
+      withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false],
+      finalizedCount: () => 5n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      policy: () => [0n, 0n, 0n, 0n, 60n, 86_400n],
+      // The dry run passed; the state moved on before the withdrawal landed.
+      finalizedState: () => `0x${"ee".repeat(32)}`,
+    });
+    balance = {
+      state: ZERO32,
+      amount: "100",
+      opening: { ...proof(1), amount: "100", nextKey: ZERO32, chunk: ZERO32, opsRoot: ZERO32, pending: ZERO32, partialDigest: ZERO32 },
+    };
+    try {
+      node.revertNext.add("queueWithdrawal");
+      await expect(withdrawFromClearing(custody(service({})))).rejects.toThrow(
+        /^queueWithdrawal 0x[0-9a-f]{64} reverted because an epoch finalized under it, .*nothing was lost but its gas: make the same call again after the next epoch$/,
+      );
+      expect(sent).toHaveLength(1);
+      // Under the state it was proven against, the revert is not one to call again for.
+      views.finalizedState = () => ZERO32;
+      node.revertNext.add("queueWithdrawal");
+      const error = await withdrawFromClearing(custody(service({}))).catch((e: Error) => e);
+      expect(String(error)).toMatch(/queueWithdrawal reverted: 0x[0-9a-f]{64}/);
+      expect(String(error)).not.toMatch(/finalized under it/);
+    } finally {
+      node.revertNext.clear();
+      reverted.clear();
+      balance = { state: ZERO32, amount: "0", opening: null };
+    }
+  });
+
+  it("names a claim refused, or mined as a revert, because an epoch finalized under its proof as lost nothing, to call again after the next epoch", async () => {
+    const fetch = service({ [`/payout/2/${signer.publicKey}`]: { destination: DESTINATION, amount: "150", proof: proof(7) } });
+    // The payout is proven against a payouts log of 9 operations; the contract's has 10.
+    Object.assign(views, { fault: () => 0, withdrawals: withdrawalIn2, finalizedCount: () => 5n, finalizedPayouts: () => [ZERO32, 10n, 0n] });
+    try {
+      sent.length = 0;
+      claimedPositions.clear();
+      refusing.claim = "InvalidProof";
+      await expect(withdrawFromClearing(custody(fetch))).rejects.toThrow(
+        /^claim was refused because an epoch finalized under it, .*nothing was lost: make the same call again after the next epoch$/,
+      );
+      expect(sent).toHaveLength(0);
+      delete refusing.claim;
+      node.revertNext.add("claim");
+      await expect(withdrawFromClearing(custody(fetch))).rejects.toThrow(
+        /^claim 0x[0-9a-f]{64} reverted because an epoch finalized under it, .*nothing was lost but its gas: make the same call again after the next epoch$/,
+      );
+      expect(sent).toHaveLength(1);
+      // Against the contract's own payouts log, the refusal and the revert are not ones to call again for.
+      views.finalizedPayouts = () => [ZERO32, 9n, 0n];
+      refusing.claim = "InvalidProof";
+      expect(String(await withdrawFromClearing(custody(fetch)).catch((e: Error) => e))).not.toMatch(/finalized under it/);
+      delete refusing.claim;
+      node.revertNext.add("claim");
+      const error = await withdrawFromClearing(custody(fetch)).catch((e: Error) => e);
+      expect(String(error)).toMatch(/claim reverted: 0x[0-9a-f]{64}/);
+      expect(String(error)).not.toMatch(/finalized under it/);
+    } finally {
+      delete refusing.claim;
+      node.revertNext.clear();
+      reverted.clear();
+    }
+  });
+
+  it("queues a withdrawal from the finalized balance alone, through a fetch that serves only /balance and /payout, as a validator does", async () => {
+    sent.length = 0;
+    Object.assign(views, {
+      fault: () => 0,
+      withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false],
+      finalizedCount: () => 5n,
+      deployment: () => `0x${"cd".repeat(32)}`,
+      policy: () => [0n, 0n, 0n, 0n, 60n, 86_400n],
+      finalizedState: () => ZERO32,
+    });
+    balance = {
+      state: ZERO32,
+      amount: "100",
+      opening: { ...proof(1), amount: "100", nextKey: ZERO32, chunk: ZERO32, opsRoot: ZERO32, pending: ZERO32, partialDigest: ZERO32 },
+    };
+    const validatorOnly = async (input: URL | RequestInfo) => {
+      const path = new URL(String(input)).pathname;
+      return path.startsWith("/balance/") || path.startsWith("/payout/") ? service({})(input) : new Response(null, { status: 404 });
+    };
+    try {
+      expect(await withdrawFromClearing(custody(validatorOnly))).toMatchObject({ status: "sent", queued: { tx: expect.any(String) } });
+      expect(sent).toHaveLength(1);
+    } finally {
+      balance = { state: ZERO32, amount: "0", opening: null };
+    }
+  });
+
+  it("names a clearing service it cannot reach, for the balance or the payout, and a validator's URL as serviceUrl, never several URLs", async () => {
+    const down = (path: string, answer: () => Response) => async (input: URL | RequestInfo) =>
+      new URL(String(input)).pathname.startsWith(path) ? answer() : service({})(input);
+    const refused = () => new Response("busy", { status: 503 });
+    const gone = (): Response => {
+      throw new TypeError("fetch failed");
+    };
+    balance = { state: ZERO32, amount: "100", opening: null };
+    try {
+      for (const [views_, fetch] of [
+        [{ withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false] }, down("/balance/", refused)],
+        [{ withdrawals: () => [ZERO32, 0n, 0n, 0n, DESTINATION, false] }, down("/balance/", gone)],
+        [{ withdrawals: withdrawalIn2 }, down("/payout/", refused)],
+        [{ withdrawals: withdrawalIn2 }, down("/payout/", gone)],
+      ] as const) {
+        sent.length = 0;
+        Object.assign(views, { fault: () => 0, finalizedCount: () => 5n, ...views_ });
+        const error = await withdrawFromClearing(custody(fetch)).catch((e: Error) => e);
+        expect(String(error)).toMatch(/the clearing service could not be reached/);
+        expect(String(error)).toMatch(/pass a validator's URL from the facilitator's \/supported extra\.validatorUrls as serviceUrl/);
+        expect(String(error)).not.toMatch(/several|services named|list/);
+        expect(sent).toHaveLength(0);
+      }
+      // A service that answers, with no payout for the account, is not one that cannot be reached.
+      Object.assign(views, { withdrawals: withdrawalIn2 });
+      expect(String(await withdrawFromClearing(custody(service({}))).catch((e: Error) => e))).not.toMatch(/could not be reached/);
+    } finally {
+      balance = { state: ZERO32, amount: "0", opening: null };
+    }
+  });
+
+  it("points a withdrawal waiting on a service that has missed a deadline to recoverFromClearing, and waits while none is missed", async () => {
+    sent.length = 0;
+    Object.assign(views, { fault: () => 0, withdrawals: withdrawalIn2, finalizedCount: () => 1n, admittedCount: () => 3n, registered: () => true });
+    Object.assign(refusing, { faultRegistration: "InvalidDeadline", faultWithdrawal: "InvalidDeadline", faultDeposit: "InvalidDeadline" });
+    try {
+      expect(await withdrawFromClearing(custody(service({})))).toEqual({ status: "waiting", epoch: 2n });
+      // The service stopped: the withdrawal's deadline passed with its epoch unfinalized.
+      delete refusing.faultWithdrawal;
+      await expect(withdrawFromClearing(custody(service({})))).rejects.toThrow(/missed a deadline.*recoverFromClearing/);
+    } finally {
+      for (const name of ["faultRegistration", "faultWithdrawal", "faultDeposit"]) delete refusing[name];
+    }
+    expect(sent).toHaveLength(0);
+  });
+});