@metalntwx/metal-pay 0.3.0 → 0.3.2

package/src/clearing-custody.test.ts

@@ -1,4 +1,5 @@
 import { createServer, type Server } from "node:http";
+import { inspect } from "node:util";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import {
   decodeFunctionData,
@@ -22,16 +23,20 @@ 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`. */
-const contract = { token: ASSET as Hex, custody: [0n], depositReverts: false };
+ * 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 as a
- * revert; and the gas each dry run of a deposit was given. */
+ * 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>();
@@ -90,6 +95,11 @@ const rpc = createServer((req, res) => {
         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()") } }));
@@ -114,8 +124,9 @@ const rpc = createServer((req, res) => {
           reverted.add(hash);
         }
         try {
-          const claim = decodeFunctionData({ abi: clearingAbi, data: tx.data ?? "0x" });
-          if (claim.functionName === "claim") claimedPositions.add((claim.args[2] as { location: bigint }).location);
+          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);
@@ -154,11 +165,12 @@ beforeAll(async () => {
 });
 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: privateKeyToAccount(`0x${"45".repeat(32)}`),
+    from: depositor,
     settlement: `0x${"22".repeat(20)}`,
     asset: ASSET,
     account: `0x02${"11".repeat(32)}`,
@@ -190,6 +202,28 @@ describe("depositToClearing", () => {
     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;
@@ -226,6 +260,29 @@ describe("depositToClearing", () => {
     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)}`;
@@ -323,6 +380,19 @@ describe("clearingSpendable", () => {
     });
     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", () => {
@@ -337,7 +407,7 @@ describe("withdrawing and recovering", () => {
     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))).toMatchObject({ status: "sent", claimed: [] });
+    expect(await withdrawFromClearing(custody(fetch))).toEqual({ status: "empty" });
   });
 
   it("refuses a payout the service names to another destination, claiming nothing", async () => {
@@ -374,14 +444,22 @@ describe("withdrawing and recovering", () => {
     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))).toMatchObject({ status: "sent", claimed: [], queued: null });
+    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: "sent", claimed: [], queued: null });
+    expect(await withdrawFromClearing(custody(service({})))).toEqual({ status: "empty" });
     expect(sent).toHaveLength(0);
   });
 
@@ -516,6 +594,8 @@ describe("withdrawing and recovering", () => {
       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,
@@ -524,11 +604,160 @@ describe("withdrawing and recovering", () => {
     };
     refusing.queueWithdrawal = "InvalidBoundary";
     try {
-      await expect(withdrawFromClearing(custody(service({})))).rejects.toThrow(/an epoch finalized under it: call withdrawFromClearing again/);
+      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);
+  });
 });

package/src/clearing-custody.ts

@@ -8,7 +8,6 @@ import {
   erc20Abi,
   FeeCapTooHighError,
   FeeCapTooLowError,
-  http,
   InsufficientFundsError,
   IntrinsicGasTooHighError,
   IntrinsicGasTooLowError,
@@ -29,6 +28,7 @@ import {
 import { getNodeError } from "viem/utils";
 import { clearingAbi } from "./clearing-abi.js";
 import { clearingUint64, clearingUnits } from "./clearing-codec.js";
+import { formatUsdz, rpcTransport, USDZ } from "./networks.js";
 import type { ClearingSigner } from "./clearing-client.js";
 
 export interface ClearingLogProof {
@@ -103,6 +103,9 @@ export async function clearingClose(
  * millionth of the token (its base unit at six decimals or fewer). */
 export const CLEARING_MAX_AMOUNT = 2n ** 64n - 1n;
 
+/** A clearing service that gave no answer, or a 5xx. */
+class ServiceUnreachable extends Error {}
+
 async function serviceGet<T>(
   serviceUrl: string,
   path: string,
@@ -110,9 +113,11 @@ async function serviceGet<T>(
 ): Promise<T> {
   const response = await fetcher(new URL(path, serviceUrl), {
     signal: AbortSignal.timeout(30_000),
+  }).catch((error: unknown) => {
+    throw new ServiceUnreachable(`clearing service gave no answer for ${path} (${error instanceof Error ? error.message : String(error)})`, { cause: error });
   });
   if (!response.ok)
-    throw new Error(`clearing service returned ${response.status} for ${path}`);
+    throw new (response.status >= 500 ? ServiceUnreachable : Error)(`clearing service returned ${response.status} for ${path}`);
   return (await response.json()) as T;
 }
 
@@ -126,7 +131,7 @@ export async function clearingSpendable(opts: {
   account: Hex;
   fetch?: typeof globalThis.fetch;
 }): Promise<bigint> {
-  const pub = createPublicClient({ transport: http(opts.rpcUrl) });
+  const pub = createPublicClient({ transport: rpcTransport(opts.rpcUrl) });
   const [{ amount }, unit] = await Promise.all([
     serviceGet<{ amount: string }>(
       opts.serviceUrl,
@@ -174,7 +179,7 @@ const REFUSALS = [
 /** 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 transport = rpcTransport(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
@@ -235,6 +240,16 @@ function succeeded(functionName: string, receipt: TransactionReceipt): Hex {
   return receipt.transactionHash;
 }
 
+/** A withdrawal's queue or claim refused, by its dry run or as a mined
+ * revert (`tx`), because an epoch finalized after the service proved it:
+ * the contract checks a proof against its finalized state alone. */
+function finalizedUnder(functionName: string, tx: Hex | undefined, cause?: unknown) {
+  return new Error(
+    `${tx ? `${functionName} ${tx} reverted` : `${functionName} was refused`} because an epoch finalized under it, so the service's proof is for the state before; nothing was lost${tx ? " but its gas" : ""}: make the same call again after the next epoch`,
+    cause === undefined ? {} : { cause },
+  );
+}
+
 /** 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
@@ -242,8 +257,10 @@ function succeeded(functionName: string, receipt: TransactionReceipt): Hex {
  * 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. */
+ * what the contract holds in all. A deposit the token refuses because
+ * `from` holds less fails naming what `from` holds and what the deposit
+ * needs. A deposit whose outcome is unknown is not sent again: the error
+ * names it. */
 export async function depositToClearing(
   opts: ClearingChain & {
     asset: Address;
@@ -300,6 +317,14 @@ export async function depositToClearing(
   const windowClosed = (error: unknown) =>
     error instanceof BaseError &&
     error.walk((e) => e instanceof ContractFunctionRevertedError && e.data?.errorName === "InvalidBoundary") !== null;
+  // The token refuses a transfer past what `from` holds with the reason
+  // "balance"; what it holds is read after the refusal.
+  const shortOf = async (error: unknown) => {
+    if (!(error instanceof BaseError && error.walk((e) => e instanceof ContractFunctionRevertedError && e.reason === "balance")))
+      return undefined;
+    const held = await pub.readContract({ address: opts.asset, abi: erc20Abi, functionName: "balanceOf", args: [opts.from.address] });
+    return `${opts.from.address} holds ${formatUsdz(held)} ${USDZ.symbol} and the deposit needs ${formatUsdz(opts.amount)} ${USDZ.symbol}; fund it or deposit less`;
+  };
   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
@@ -310,12 +335,17 @@ export async function depositToClearing(
       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))
+      if (!windowClosed(why)) {
+        const short = await shortOf(why);
         throw new Error(
-          `deposit ${receipt.transactionHash} reverted${why instanceof BaseError ? `: ${why.shortMessage}` : ", and its dry run now passes"}`,
+          `deposit ${receipt.transactionHash} reverted${short ? `: ${short}` : why instanceof BaseError ? `: ${why.shortMessage}` : ", and its dry run now passes"}`,
         );
+      }
     } catch (error) {
-      if (!windowClosed(error)) throw error;
+      if (!windowClosed(error)) {
+        const short = await shortOf(error);
+        throw short ? new Error(`the deposit was refused, and nothing was deposited: ${short}`, { cause: error }) : error;
+      }
     }
     await assertRoom();
     if (Date.now() >= deadline) throw new Error("the Clearing contract took no deposits before the timeout");
@@ -341,6 +371,7 @@ async function lookupPayout(
   destination: Address,
 ): Promise<ClearingPayout> {
   const failures: string[] = [];
+  const unreachable: ServiceUnreachable[] = [];
   for (const serviceUrl of serviceUrls) {
     try {
       const payout = await serviceGet<ClearingPayout | null>(serviceUrl, `/payout/${epoch}/${account}`, fetcher);
@@ -349,11 +380,14 @@ async function lookupPayout(
         failures.push(`${serviceUrl} names ${payout.destination}, not ${destination}, the destination the withdrawal named`);
       else return payout;
     } catch (error) {
+      if (error instanceof ServiceUnreachable) unreachable.push(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("; ")})`,
+    // None of them answered.
+    unreachable.length === serviceUrls.length ? { cause: unreachable[0] } : {},
   );
 }
 
@@ -370,10 +404,17 @@ async function claimPayout(
   const position = BigInt(payout.proof.location);
   const consumed = await pub.readContract({ ...contract, functionName: "claimedPayouts", args: [position >> 8n] });
   if (consumed & (1n << (position & 255n))) return;
+  // The proof is for the payouts log the service read as finalized; once a
+  // later epoch finalizes, the contract's log is longer and refuses it.
+  const moved = async () =>
+    (await pub.readContract({ ...contract, functionName: "finalizedPayouts" }))[1] !== BigInt(payout.proof.leaves);
   const receipt = await send(
     { ...contract, functionName: "claim", args: [destination, BigInt(payout.amount), clearingLogProof(payout.proof)] },
     1_000_000n,
-  );
+  ).catch(async (error: unknown) => {
+    throw revertOf(error) === "InvalidProof" && (await moved()) ? finalizedUnder("claim", undefined, error) : error;
+  });
+  if (receipt.status !== "success" && (await moved())) throw finalizedUnder("claim", receipt.transactionHash);
   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 });
@@ -381,12 +422,17 @@ async function claimPayout(
 
 export type ClearingWithdrawal =
   /** A withdrawal is queued and `epoch`, the one that carries it, has not
-   * finalized; nothing can be sent until it does. */
+   * finalized; nothing can be sent until it does. Once the service has
+   * missed a deadline, the call fails instead, naming `recoverFromClearing`. */
   | { status: "waiting"; epoch: bigint }
+  /** Nothing to withdraw: no payout to claim, and no finalized balance.
+   * What the account holds in an epoch not yet finalized can leave once
+   * it is. */
+  | { status: "empty" }
   /** 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
+   * queued for the account's finalized balance, or `null` when nothing
+   * finalized is left to queue. A
    * deferred payout is one the destination refused: it waits in the
    * contract's `unclaimedPayout` until the destination calls
    * `withdrawUnclaimed`. */
@@ -397,7 +443,9 @@ export type ClearingWithdrawal =
  * 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. */
+ * failure after a claim names the claims made before it. A queue or claim
+ * refused because an epoch finalized under its proof moved nothing: the
+ * error says to call again after the next epoch. */
 export async function withdrawFromClearing(
   opts: ClearingChain & {
     signer: ClearingSigner;
@@ -420,17 +468,38 @@ export async function withdrawFromClearing(
   ]);
   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" }),
     ]);
+    // A service that has missed a deadline may never finalize the epoch.
+    for (const call of faultCalls(admitted, opts.signer.publicKey)) {
+      const missed = await pub.simulateContract({ ...contract, ...call, account: opts.from.address }).then(
+        () => true,
+        (error: unknown) => {
+          if (revertOf(error) !== "InvalidDeadline") throw error;
+          return false;
+        },
+      );
+      if (missed)
+        throw new Error(
+          `the clearing service has missed a deadline (${call.functionName} would fault the deployment), so the withdrawal may never finalize: take the account's funds out with recoverFromClearing`,
+        );
+    }
+    if (epochPlusOne > 0n) return { status: "waiting", epoch: epochPlusOne - 1n };
+    // Not yet registered: the next registration carries it.
     return { status: "waiting", epoch: registered ? admitted + 1n : admitted };
   }
   const claimed: ClearingClaim[] = [];
   try {
-    return await claimThenQueue();
+    return await claimThenQueue().catch((error: unknown) => {
+      const gone = error instanceof ServiceUnreachable ? error : error instanceof Error && error.cause instanceof ServiceUnreachable ? error.cause : undefined;
+      if (!gone) throw error;
+      throw new Error(
+        `the clearing service could not be reached (${gone.message}): call withdrawFromClearing again once it answers; if it has stopped, pass a validator's URL from the facilitator's /supported extra.validatorUrls as serviceUrl`,
+        { cause: error },
+      );
+    });
   } catch (error) {
     if (claimed.length === 0) throw error;
     const made = claimed.map((c) => `${c.amount} in ${c.tx}`).join(", ");
@@ -445,10 +514,12 @@ export async function withdrawFromClearing(
         queuedTo,
         claimed,
       );
+    const unqueued = (): ClearingWithdrawal => (claimed.length > 0 ? { status: "sent", claimed, queued: null } : { status: "empty" });
     // The service proves balances only against a finalized epoch.
-    if (finalized === 0n) return { status: "sent", claimed, queued: null };
+    if (finalized === 0n) return unqueued();
     const balance = await clearingBalance(opts.serviceUrl, opts.signer.publicKey, fetcher);
-    if (BigInt(balance.amount) === 0n || !balance.opening) return { status: "sent", claimed, queued: null };
+    if (BigInt(balance.amount) === 0n) return unqueued();
+    if (!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" }),
@@ -458,12 +529,14 @@ export async function withdrawFromClearing(
     // 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 moved = async () =>
+      (await pub.readContract({ ...contract, functionName: "finalizedState" })).toLowerCase() !== close.withdrawal.state.toLowerCase();
     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 });
+      async (error: unknown) => {
+        throw revertOf(error) === "InvalidBoundary" && (await moved()) ? finalizedUnder("queueWithdrawal", undefined, error) : error;
       },
     );
+    if (receipt.status !== "success" && (await moved())) throw finalizedUnder("queueWithdrawal", receipt.transactionHash);
     return { status: "sent", claimed, queued: { tx: succeeded("queueWithdrawal", receipt) } };
   }
 }
@@ -490,6 +563,16 @@ export type ClearingRecovery =
       refunded: { epoch: bigint; amount: bigint; tx: Hex }[];
     };
 
+/** The calls that fault a deployment whose service has missed a deadline:
+ * to admit the epoch it registered, `account`'s queued withdrawal, or its
+ * deposit. Each reverts `InvalidDeadline` until its deadline passes. */
+const faultCalls = (admitted: bigint, account: Hex) =>
+  [
+    { functionName: "faultRegistration", args: [] },
+    { functionName: "faultWithdrawal", args: [account] },
+    { functionName: "faultDeposit", args: [admitted, account] },
+  ] as const;
+
 const revertOf = (error: unknown): string | undefined => {
   if (!(error instanceof BaseError)) return undefined;
   const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError);
@@ -550,12 +633,7 @@ export async function recoverFromClearing(
   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) {
+    for (const call of faultCalls(admitted, account)) {
       try {
         faulted = succeeded(call.functionName, await send({ ...contract, ...call }, 200_000n));
         break;