@multiplatform.one/web3 7.23.2 → 7.25.0

package/src/clients/evm.spec.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   createPublicClient,
   custom,
@@ -6,11 +6,19 @@ import {
   encodeAbiParameters,
   erc20Abi,
   toHex,
+  WaitForTransactionReceiptTimeoutError,
   type Address,
   type Hex,
 } from "viem";
 import { mainnet } from "viem/chains";
-import { evmClient } from "./evm";
+import {
+  classifyTxError,
+  evmClient,
+  ReceiptPendingError,
+  ReceiptWaitAbortedError,
+  TransactionReplacedError,
+  TransactionRevertedError,
+} from "./evm";
 
 const account = "0x1111111111111111111111111111111111111111" as Address;
 const token = "0x2222222222222222222222222222222222222222" as Address;
@@ -30,10 +38,49 @@ interface ChainState {
   usdt?: boolean;
   /** Hashes whose receipt comes back reverted. */
   reverted?: Set<Hex>;
+  /** Hashes still in the mempool: no receipt yet. */
+  pending?: Set<Hex>;
+  /** Mined transactions this client did not send, by hash. */
+  mined?: Map<Hex, { to: Address; value: Hex; nonce: Hex }>;
+  /** What eth_getBlockByNumber lists for block `takenAt`; other blocks are empty. */
+  blockTransactions?: Hex[];
+  /** eth_getTransactionCount from block `takenAt` on, one less before it; sent minus pending by default. */
+  nonceUsed?: number;
+  /** The block that took the nonce, the head by default. */
+  takenAt?: bigint;
+  /** Sent hashes the node no longer knows, as after a replacement it did not see. */
+  forgotten?: Set<Hex>;
+  block?: bigint;
+  /** The wallet answers eth_sendTransaction with EIP-1193 4001. */
+  userRejects?: boolean;
+  /** eth_getTransactionReceipt fails with an RPC error. */
+  receiptRpcDown?: boolean;
+  /** eth_getTransactionByHash answers once this settles. */
+  txLookupGate?: Promise<void>;
 }
 
 const revert = () => Object.assign(new Error("execution reverted"), { code: 3, data: "0x" as Hex });
 
+const rpcTransaction = (hash: Hex, tx: { to: Address; value: Hex; nonce: Hex; input?: Hex }) => ({
+  hash,
+  from: account,
+  to: tx.to,
+  value: tx.value,
+  input: tx.input ?? "0x",
+  nonce: tx.nonce,
+  gas: "0x5208",
+  maxFeePerGas: "0x2",
+  maxPriorityFeePerGas: "0x1",
+  type: "0x2",
+  chainId: "0x1",
+  blockHash: null,
+  blockNumber: null,
+  transactionIndex: null,
+  v: "0x0",
+  r: "0x1",
+  s: "0x1",
+});
+
 function mockProvider(state: ChainState) {
   const calls: Call[] = [];
   const sent: Hex[] = [];
@@ -46,6 +93,9 @@ function mockProvider(state: ChainState) {
         case "personal_sign":
           return "0xsigned";
         case "eth_sendTransaction": {
+          if (state.userRejects) {
+            throw Object.assign(new Error("User rejected the request."), { code: 4001 });
+          }
           const [{ data }] = params as [{ data?: Hex }];
           const hash = sent.length === 0 ? txHash : hashFor(sent.length + 1);
           sent.push(hash);
@@ -59,7 +109,16 @@ function mockProvider(state: ChainState) {
         }
         case "eth_getTransactionReceipt": {
           const [hash] = params as [Hex];
-          if (!sent.includes(hash)) return null;
+          if (state.receiptRpcDown) {
+            throw Object.assign(new Error("upstream unavailable"), { code: -32002 });
+          }
+          if (
+            !(sent.includes(hash) || state.mined?.has(hash)) ||
+            state.pending?.has(hash) ||
+            state.forgotten?.has(hash)
+          ) {
+            return null;
+          }
           return {
             transactionHash: hash,
             transactionIndex: "0x0",
@@ -80,7 +139,47 @@ function mockProvider(state: ChainState) {
         case "eth_estimateGas":
           return "0x5208";
         case "eth_blockNumber":
-          return "0x10";
+          return toHex(head());
+        case "eth_getTransactionCount": {
+          if (state.nonceUsed === undefined) return toHex(sent.length - (state.pending?.size ?? 0));
+          return toHex(
+            blockOf((params as [Address, string])[1]) < (state.takenAt ?? head())
+              ? state.nonceUsed - 1
+              : state.nonceUsed,
+          );
+        }
+        case "eth_getTransactionByHash": {
+          await state.txLookupGate;
+          const [hash] = params as [Hex];
+          if (state.forgotten?.has(hash)) return null;
+          if (state.mined?.has(hash)) return rpcTransaction(hash, state.mined.get(hash)!);
+          const call = calls.find(
+            (c) => c.method === "eth_sendTransaction" && sent[sendCalls().indexOf(c)] === hash,
+          );
+          if (!call) return null;
+          const tx = (call.params as [{ to: Address; value?: Hex; data?: Hex }])[0];
+          return rpcTransaction(hash, {
+            to: tx.to,
+            value: tx.value ?? "0x0",
+            input: tx.data,
+            nonce: toHex(sent.indexOf(hash)),
+          });
+        }
+        case "eth_getBlockByNumber": {
+          const number = blockOf((params as [string])[0]);
+          return {
+            number: toHex(number),
+            hash: `0x${"cd".repeat(32)}`,
+            parentHash: `0x${"ce".repeat(32)}`,
+            timestamp: "0x1",
+            transactions:
+              number === (state.takenAt ?? head())
+                ? (state.blockTransactions ?? []).map((hash) =>
+                    rpcTransaction(hash, state.mined!.get(hash)!),
+                  )
+                : [],
+          };
+        }
         case "eth_call": {
           const [{ data }] = params as [{ data: Hex }];
           const { functionName, args } = decodeFunctionData({ abi: erc20Abi, data });
@@ -104,6 +203,15 @@ function mockProvider(state: ChainState) {
       }
     },
   };
+  function sendCalls() {
+    return calls.filter((c) => c.method === "eth_sendTransaction");
+  }
+  function head() {
+    return state.block ?? 16n;
+  }
+  function blockOf(tag: string) {
+    return tag.startsWith("0x") ? BigInt(tag) : head();
+  }
   const sentTransaction = <T>() => {
     const call = calls.find((c) => c.method === "eth_sendTransaction");
     if (!call) throw new Error("no eth_sendTransaction");
@@ -118,7 +226,13 @@ function mockProvider(state: ChainState) {
       )
       .filter((d) => d.functionName === "approve")
       .map((d) => (d.args as [Address, bigint])[1]);
-  return { provider, calls, sent, sentTransaction, approvals };
+  const count = (method: string) => calls.filter((c) => c.method === method).length;
+  /** The block numbers eth_getBlockByNumber was asked for. */
+  const blocksFetched = () =>
+    calls
+      .filter((c) => c.method === "eth_getBlockByNumber")
+      .map((c) => BigInt((c.params as [Hex])[0]));
+  return { provider, calls, sent, sentTransaction, approvals, count, blocksFetched };
 }
 
 describe("evmClient", () => {
@@ -126,19 +240,22 @@ describe("evmClient", () => {
   let mock: ReturnType<typeof mockProvider>;
   let client: ReturnType<typeof evmClient>;
 
-  beforeEach(() => {
-    state = { allowance: 0n, balance: 5n * 10n ** 18n };
-    mock = mockProvider(state);
-    client = evmClient({
+  const makeClient = (pollingInterval: number) =>
+    evmClient({
       provider: mock.provider as never,
       account,
       chain: mainnet,
       publicClient: createPublicClient({
         chain: mainnet,
-        pollingInterval: 1,
+        pollingInterval,
         transport: custom(mock.provider),
       }),
     });
+
+  beforeEach(() => {
+    state = { allowance: 0n, balance: 5n * 10n ** 18n };
+    mock = mockProvider(state);
+    client = makeClient(1);
   });
 
   it("shares the common client shape", () => {
@@ -262,4 +379,521 @@ describe("evmClient", () => {
     expect(wrapped.address).toBe(account);
     expect(wrapped.chain.id).toBe(1);
   });
+
+  it("links a transaction to the chain's explorer", () => {
+    expect(client.explorerTxUrl(txHash)).toBe(`https://etherscan.io/tx/${txHash}`);
+  });
+
+  describe("receipts", () => {
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("confirms a mined transaction", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const receipt = await client.confirmTransaction(hash);
+      expect(receipt.status).toBe("success");
+      expect(receipt.transactionHash).toBe(hash);
+    });
+
+    it("gives up on a pending transaction as ReceiptPendingError, never a failure", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const error = await client.waitForTransactionReceipt(hash, { timeout: 50 }).catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(error).toMatchObject({
+        hash,
+        chainId: 1,
+        mayStillLand: true,
+        explorerUrl: `https://etherscan.io/tx/${hash}`,
+        nonce: 0,
+      });
+      expect(error.message).toMatch(/may still land/);
+      expect(classifyTxError(error)).toBe("pending");
+    });
+
+    it("waits past viem's 180 s default when no timeout is set", async () => {
+      vi.useFakeTimers();
+      const slow = makeClient(5_000);
+      const hash = await slow.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      let settled: string | undefined;
+      const wait = slow.confirmTransaction(hash).then(
+        (receipt) => (settled = receipt.status),
+        (error: Error) => (settled = error.name),
+      );
+      await vi.advanceTimersByTimeAsync(300_000);
+      expect(settled).toBeUndefined();
+      state.pending.clear();
+      state.block = 17n;
+      await vi.advanceTimersByTimeAsync(10_000);
+      await wait;
+      expect(settled).toBe("success");
+    });
+
+    it("rides out an RPC outage with no timeout, backing off up to 30 s between polls", async () => {
+      vi.useFakeTimers();
+      const polled = makeClient(500);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.receiptRpcDown = true;
+      let settled: string | undefined;
+      const wait = polled.confirmTransaction(hash).then(
+        (receipt) => (settled = receipt.status),
+        (error: Error) => (settled = error.name),
+      );
+      await vi.advanceTimersByTimeAsync(10 * 60_000);
+      expect(settled).toBeUndefined();
+      // 1200 polls at 500 ms without backoff; doubling to the 30 s cap is 20 at most, 40 at least.
+      const polls = mock.count("eth_getTransactionReceipt");
+      expect(polls).toBeGreaterThan(15);
+      expect(polls).toBeLessThan(50);
+      state.receiptRpcDown = false;
+      await vi.advanceTimersByTimeAsync(30_000);
+      await wait;
+      expect(settled).toBe("success");
+    });
+
+    it("gives up on an RPC outage only at the timeout, with the RPC's error as the cause", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.receiptRpcDown = true;
+      const error = await client.waitForTransactionReceipt(hash, { timeout: 50 }).catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(error.hash).toBe(hash);
+      expect(error.cause).toBeDefined();
+      expect(classifyTxError(error)).toBe("pending");
+    });
+
+    it("resolves a reverted receipt from waitForTransactionReceipt, as before", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.reverted = new Set([hash]);
+      await expect(client.waitForTransactionReceipt(hash)).resolves.toMatchObject({
+        status: "reverted",
+      });
+    });
+
+    it("rejects a reverted receipt from confirmTransaction as TransactionRevertedError", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.reverted = new Set([hash]);
+      const error = await client.confirmTransaction(hash).catch((e) => e);
+      expect(error).toBeInstanceOf(TransactionRevertedError);
+      expect(error).toMatchObject({ hash, chainId: 1, mayStillLand: false });
+      expect(error.receipt.status).toBe("reverted");
+      expect(classifyTxError(error)).toBe("reverted");
+    });
+
+    it("rejects a transaction the wallet cancelled instead of resolving the cancel's receipt", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const cancel = hashFor(99);
+      state.pending = new Set([hash]);
+      state.mined = new Map([[cancel, { to: account, value: "0x0", nonce: "0x0" }]]);
+      state.blockTransactions = [cancel];
+      state.nonceUsed = 1;
+      const error = await client.waitForTransactionReceipt(hash).catch((e) => e);
+      expect(error).toBeInstanceOf(TransactionReplacedError);
+      expect(error).toMatchObject({ hash, reason: "cancelled", mayStillLand: false });
+      expect(error.replacement.transactionHash).toBe(cancel);
+      expect(classifyTxError(error)).toBe("user-rejected");
+    });
+
+    it("settles concurrent waits, and a later one, on the same hash", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const hasty = client.waitForTransactionReceipt(hash, { timeout: 20 }).catch((e) => e);
+      const patient = client.confirmTransaction(hash);
+      expect(await hasty).toBeInstanceOf(ReceiptPendingError);
+      state.pending.clear();
+      state.block = 17n;
+      await expect(patient).resolves.toMatchObject({ status: "success" });
+      await expect(client.confirmTransaction(hash, { timeout: 1_000 })).resolves.toMatchObject({
+        transactionHash: hash,
+      });
+    });
+
+    it("sees a cancel the node saw before this wait began, given the nonce", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const cancel = hashFor(97);
+      state.forgotten = new Set([hash]);
+      state.mined = new Map([[cancel, { to: account, value: "0x0", nonce: "0x0" }]]);
+      state.blockTransactions = [cancel];
+      state.nonceUsed = 1;
+      const error = await client.confirmTransaction(hash, { nonce: 0 }).catch((e) => e);
+      expect(error).toBeInstanceOf(TransactionReplacedError);
+      expect(error).toMatchObject({ reason: "cancelled", mayStillLand: false });
+      expect(error.replacement.transactionHash).toBe(cancel);
+      expect(classifyTxError(error)).toBe("user-rejected");
+    });
+
+    it("calls a taken nonce it cannot compare pending, since it may be a speed-up", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const taker = hashFor(96);
+      state.forgotten = new Set([hash]);
+      state.mined = new Map([[taker, { to: spender, value: "0x1", nonce: "0x0" }]]);
+      state.blockTransactions = [taker];
+      state.nonceUsed = 1;
+      const error = await client.confirmTransaction(hash, { nonce: 0 }).catch((e) => e);
+      expect(error).toBeInstanceOf(TransactionReplacedError);
+      expect(error.reason).toBe("unmatched");
+      expect(error.replacement.transactionHash).toBe(taker);
+      expect(classifyTxError(error)).toBe("pending");
+    });
+
+    it("keeps waiting when the block that took the nonce does not list it, as after a reorg", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.forgotten = new Set([hash]);
+      state.nonceUsed = 1;
+      const error = await client
+        .confirmTransaction(hash, { nonce: 0, timeout: 50 })
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(classifyTxError(error)).toBe("pending");
+    });
+
+    it("finds a cancel 5000 blocks before a reload by binary search, fetching one block", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const cancel = hashFor(95);
+      state.forgotten = new Set([hash]);
+      state.mined = new Map([[cancel, { to: account, value: "0x0", nonce: "0x0" }]]);
+      state.blockTransactions = [cancel];
+      state.nonceUsed = 1;
+      state.block = 20_000n;
+      state.takenAt = 15_000n;
+      const error = await client.confirmTransaction(hash, { nonce: 0 }).catch((e) => e);
+      expect(error).toBeInstanceOf(TransactionReplacedError);
+      expect(error.reason).toBe("cancelled");
+      expect(error.replacement.transactionHash).toBe(cancel);
+      expect(classifyTxError(error)).toBe("user-rejected");
+      expect(mock.blocksFetched()).toEqual([15_000n]);
+      expect(mock.count("eth_getTransactionCount")).toBeLessThan(40);
+    });
+
+    it("resolves a speed-up mined while the tab slept 2000 blocks with the faster copy's receipt", async () => {
+      vi.useFakeTimers();
+      const polled = makeClient(4_000);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      const faster = hashFor(94);
+      state.pending = new Set([hash]);
+      state.nonceUsed = 0;
+      state.block = 1_000n;
+      let settled: string | undefined;
+      const wait = polled.confirmTransaction(hash).then(
+        (receipt) => (settled = receipt.transactionHash),
+        (error: Error) => (settled = error.name),
+      );
+      await vi.advanceTimersByTimeAsync(10);
+      expect(mock.count("eth_getTransactionCount")).toBe(1);
+      state.mined = new Map([[faster, { to: spender, value: "0x1", nonce: "0x0" }]]);
+      state.blockTransactions = [faster];
+      state.nonceUsed = 1;
+      state.block = 3_000n;
+      state.takenAt = 1_001n;
+      await vi.advanceTimersByTimeAsync(10_000);
+      await wait;
+      expect(settled).toBe(faster);
+      expect(mock.blocksFetched()).toEqual([1_001n]);
+    });
+
+    it("sleeps between polls while a speed-up it switched to has no receipt yet", async () => {
+      const polled = makeClient(20);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      const faster = hashFor(93);
+      state.pending = new Set([hash, faster]);
+      state.mined = new Map([[faster, { to: spender, value: "0x1", nonce: "0x0" }]]);
+      state.blockTransactions = [faster];
+      state.nonceUsed = 1;
+      const error = await polled.confirmTransaction(hash, { timeout: 200 }).catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(mock.count("eth_blockNumber")).toBeLessThan(20);
+    });
+
+    it("rejects at once with an AbortError when the signal is already aborted", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const before = mock.calls.length;
+      const error = await client
+        .confirmTransaction(hash, { signal: AbortSignal.abort("unmounted") })
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptWaitAbortedError);
+      expect(error).toMatchObject({ name: "AbortError", hash, chainId: 1, cause: "unmounted" });
+      expect(classifyTxError(error)).toBe("aborted");
+      expect(mock.calls.length).toBe(before);
+    });
+
+    it("stops polling when the signal aborts mid-wait", async () => {
+      const polled = makeClient(10);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const controller = new AbortController();
+      const wait = polled.confirmTransaction(hash, { signal: controller.signal }).catch((e) => e);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(mock.count("eth_getTransactionReceipt")).toBeGreaterThan(1);
+      controller.abort();
+      const error = await wait;
+      expect(error).toBeInstanceOf(ReceiptWaitAbortedError);
+      expect(error.nonce).toBe(0);
+      expect(classifyTxError(error)).toBe("aborted");
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      const polls = mock.count("eth_getTransactionReceipt");
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(mock.count("eth_getTransactionReceipt")).toBe(polls);
+    });
+
+    it("holds no abort listener past the poll or sleep it guards", async () => {
+      const polled = makeClient(1);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const controller = new AbortController();
+      const add = vi.spyOn(controller.signal, "addEventListener");
+      const remove = vi.spyOn(controller.signal, "removeEventListener");
+      const wait = polled.confirmTransaction(hash, { signal: controller.signal }).catch((e) => e);
+      while (mock.count("eth_getTransactionReceipt") < 50) {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+      expect(add.mock.calls.length).toBeGreaterThan(50);
+      expect(add.mock.calls.length - remove.mock.calls.length).toBeLessThanOrEqual(1);
+      controller.abort();
+      expect(await wait).toBeInstanceOf(ReceiptWaitAbortedError);
+    });
+
+    it("leaves no abort listener when the deadline lands mid-sleep", async () => {
+      const polled = makeClient(1_000);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const controller = new AbortController();
+      const add = vi.spyOn(controller.signal, "addEventListener");
+      const remove = vi.spyOn(controller.signal, "removeEventListener");
+      const error = await polled
+        .confirmTransaction(hash, { signal: controller.signal, timeout: 50 })
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(add.mock.calls.length).toBe(remove.mock.calls.length);
+    });
+
+    it("leaves no timer when the signal aborts mid-sleep under a long timeout", async () => {
+      vi.useFakeTimers();
+      const polled = makeClient(1_000);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const controller = new AbortController();
+      const wait = polled
+        .confirmTransaction(hash, { signal: controller.signal, timeout: 600_000 })
+        .catch((e) => e);
+      await vi.advanceTimersByTimeAsync(10);
+      controller.abort();
+      expect(await wait).toBeInstanceOf(ReceiptWaitAbortedError);
+      expect(vi.getTimerCount()).toBe(0);
+    });
+
+    it("keeps waiting under a timeout of Infinity or past 2^31 ms", async () => {
+      const polled = makeClient(10);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      const controller = new AbortController();
+      const settled: string[] = [];
+      const waits = [Infinity, 2 ** 31, 2 ** 32 + 5].map((timeout) =>
+        polled
+          .confirmTransaction(hash, { timeout, signal: controller.signal })
+          .catch((e: Error) => settled.push(`${timeout}: ${e.name}`)),
+      );
+      await new Promise((resolve) => setTimeout(resolve, 150));
+      expect(settled).toEqual([]);
+      controller.abort();
+      await Promise.all(waits);
+      expect(settled).toHaveLength(3);
+      expect(settled.every((line) => line.endsWith("AbortError"))).toBe(true);
+    });
+
+    it("hands onTrack nothing once the wait has been aborted", async () => {
+      const polled = makeClient(10);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.pending = new Set([hash]);
+      let release = () => {};
+      state.txLookupGate = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const onTrack = vi.fn();
+      const controller = new AbortController();
+      const wait = polled
+        .confirmTransaction(hash, { signal: controller.signal, onTrack })
+        .catch((e) => e);
+      while (mock.count("eth_getTransactionByHash") < 1) {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+      controller.abort();
+      expect(await wait).toBeInstanceOf(ReceiptWaitAbortedError);
+      release();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(onTrack).not.toHaveBeenCalled();
+    });
+
+    it("gives up at the timeout while an RPC call hangs", async () => {
+      const hung = evmClient({
+        provider: mock.provider as never,
+        account,
+        chain: mainnet,
+        publicClient: createPublicClient({
+          chain: mainnet,
+          pollingInterval: 10,
+          transport: custom({ request: () => new Promise(() => {}) }),
+        }),
+      });
+      const started = Date.now();
+      const error = await hung.waitForTransactionReceipt(txHash, { timeout: 100 }).catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(Date.now() - started).toBeLessThan(1_000);
+    });
+
+    it("hands onTrack the nonce once, then a speed-up's hash", async () => {
+      const polled = makeClient(10);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      const faster = hashFor(92);
+      state.pending = new Set([hash]);
+      const tracked: { hash: Hex; nonce: number }[] = [];
+      const wait = polled.confirmTransaction(hash, {
+        onTrack: (t) => {
+          tracked.push(t);
+          throw new Error("the app's bookkeeping broke");
+        },
+      });
+      while (mock.count("eth_getTransactionCount") < 3) {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+      expect(tracked).toEqual([{ hash, nonce: 0 }]);
+      state.mined = new Map([[faster, { to: spender, value: "0x1", nonce: "0x0" }]]);
+      state.blockTransactions = [faster];
+      state.nonceUsed = 1;
+      await expect(wait).resolves.toMatchObject({ transactionHash: faster });
+      expect(tracked).toEqual([
+        { hash, nonce: 0 },
+        { hash: faster, nonce: 0 },
+      ]);
+    });
+
+    it("aborts a wait backing off from an RPC outage without waiting out the backoff", async () => {
+      const polled = makeClient(5_000);
+      const hash = await polled.sendTransaction({ to: spender, value: 1n });
+      state.receiptRpcDown = true;
+      const controller = new AbortController();
+      const wait = polled.confirmTransaction(hash, { signal: controller.signal }).catch((e) => e);
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      const started = Date.now();
+      controller.abort();
+      expect(await wait).toBeInstanceOf(ReceiptWaitAbortedError);
+      expect(Date.now() - started).toBeLessThan(100);
+    });
+
+    it("keeps waiting on a hash the node forgot while its nonce is still free", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      state.forgotten = new Set([hash]);
+      state.nonceUsed = 0;
+      const error = await client
+        .confirmTransaction(hash, { nonce: 0, timeout: 50 })
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(classifyTxError(error)).toBe("pending");
+    });
+
+    it("resolves a sped-up transaction with the faster copy's receipt", async () => {
+      const hash = await client.sendTransaction({ to: spender, value: 1n });
+      const faster = hashFor(98);
+      state.pending = new Set([hash]);
+      state.mined = new Map([[faster, { to: spender, value: "0x1", nonce: "0x0" }]]);
+      state.blockTransactions = [faster];
+      state.nonceUsed = 1;
+      const receipt = await client.confirmTransaction(hash);
+      expect(receipt.transactionHash).toBe(faster);
+    });
+  });
+
+  describe("classifyTxError", () => {
+    it("classifies a wallet rejection of a send as user-rejected", async () => {
+      state.userRejects = true;
+      const error = await client.sendTransaction({ to: spender, value: 1n }).catch((e) => e);
+      expect(classifyTxError(error)).toBe("user-rejected");
+    });
+
+    it("classifies a wallet rejection of an ERC-20 transfer as user-rejected", async () => {
+      state.userRejects = true;
+      const error = await client.erc20.transfer({ token, to: spender, amount: 3n }).catch((e) => e);
+      expect(classifyTxError(error)).toBe("user-rejected");
+    });
+
+    it("classifies a raw EIP-1193 4001 as user-rejected", () => {
+      expect(classifyTxError({ code: 4001, message: "User rejected the request." })).toBe(
+        "user-rejected",
+      );
+    });
+
+    it("classifies a transfer the simulation reverts as reverted, before any send", async () => {
+      state.usdt = true;
+      state.allowance = 5n;
+      const error = await client.erc20.approve({ token, spender, amount: 9n }).catch((e) => e);
+      expect(classifyTxError(error)).toBe("reverted");
+      expect(mock.sent).toEqual([]);
+    });
+
+    it("classifies viem's own receipt timeout as pending", () => {
+      expect(classifyTxError(new WaitForTransactionReceiptTimeoutError({ hash: txHash }))).toBe(
+        "pending",
+      );
+    });
+
+    it("classifies only this module's aborts as aborted", () => {
+      const wait = new ReceiptWaitAbortedError(txHash, 1, 0, "unmounted");
+      expect(classifyTxError(wait)).toBe("aborted");
+      expect(classifyTxError(new Error("buy", { cause: wait }))).toBe("aborted");
+      const foreign = Object.assign(new Error("The operation was aborted."), {
+        name: "AbortError",
+      });
+      expect(classifyTxError(foreign)).toBe("failed");
+      expect(
+        classifyTxError(
+          new ReceiptPendingError(txHash, 1, { detail: "has no receipt", cause: foreign }),
+        ),
+      ).toBe("pending");
+    });
+
+    it("classifies anything else as failed", () => {
+      expect(classifyTxError(new Error("insufficient funds for gas"))).toBe("failed");
+      expect(classifyTxError(undefined)).toBe("failed");
+    });
+  });
+
+  describe("ensureAllowance", () => {
+    it("throws TransactionRevertedError when the approval reverts", async () => {
+      state.reverted = new Set([txHash]);
+      const error = await client.erc20
+        .ensureAllowance({ token, spender, amount: 50n })
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(TransactionRevertedError);
+      expect(error.hash).toBe(txHash);
+      expect(classifyTxError(error)).toBe("reverted");
+    });
+
+    it("throws ReceiptPendingError with the approval hash when it outlasts the timeout", async () => {
+      state.pending = new Set([txHash]);
+      const error = await client.erc20
+        .ensureAllowance({ token, spender, amount: 50n, timeout: 50 })
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(ReceiptPendingError);
+      expect(error.hash).toBe(txHash);
+      expect(error.message).toMatch(new RegExp(`^approve ${txHash}`));
+      expect(classifyTxError(error)).toBe("pending");
+    });
+
+    it("sends no approval once its signal has aborted", async () => {
+      const error = await client.erc20
+        .ensureAllowance({ token, spender, amount: 50n, signal: AbortSignal.abort() })
+        .catch((e) => e);
+      expect(error).toMatchObject({ name: "AbortError", mayStillLand: false });
+      expect(classifyTxError(error)).toBe("aborted");
+      expect(mock.sent).toEqual([]);
+    });
+
+    it("passes a wallet rejection of the approval through as user-rejected", async () => {
+      state.userRejects = true;
+      const error = await client.erc20
+        .ensureAllowance({ token, spender, amount: 50n })
+        .catch((e) => e);
+      expect(classifyTxError(error)).toBe("user-rejected");
+    });
+  });
 });