@multiplatform.one/web3 7.26.0 → 7.28.1

package/src/bridge/nativeHost.spec.ts

@@ -1,23 +1,30 @@
 import { describe, expect, it } from "vitest";
 import { BridgeHost } from "./BridgeHost";
-import { buildInjectScript, createNativeBridge } from "./nativeHost";
+import { NativeBridgeErrorCode, buildInjectScript, createNativeBridge } from "./nativeHost";
 import { createPostMessageTransport } from "./postMessageTransport";
-import { BRIDGE_PROTOCOL_VERSION } from "./protocol";
+import { BRIDGE_PROTOCOL_VERSION, BridgeRequestError } from "./protocol";
+
+const pageUrl = "https://wallet.example.com/webview.html";
+const foreign = "https://evil.example/";
 
 /**
  * A fake page: `inject` runs the native side's script against a fake window
  * whose `__bridgeReceive` feeds a BridgeHost, and the host's replies come back
  * through `native.receive` with the page's URL.
  */
-function setup(pageUrl = "https://wallet.example.com/webview.html") {
+function setup(url = pageUrl) {
   const injected: string[] = [];
+  let pageLost = 0;
   const win: { location: { origin: string }; __bridgeReceive?: (raw: string) => void } = {
-    location: { origin: new URL(pageUrl).origin },
+    location: { origin: new URL(url).origin },
   };
-  let postedFrom = pageUrl;
+  let postedFrom = url;
   const native = createNativeBridge({
-    pageUrl,
+    pageUrl: url,
     allowDevHosts: true,
+    onPageLost() {
+      pageLost += 1;
+    },
     inject(script) {
       injected.push(script);
       new Function("window", script)(win);
@@ -31,12 +38,25 @@ function setup(pageUrl = "https://wallet.example.com/webview.html") {
     host,
     injected,
     win,
-    postFrom(url: string) {
-      postedFrom = url;
+    get pageLost() {
+      return pageLost;
+    },
+    postFrom(from: string) {
+      postedFrom = from;
     },
   };
 }
 
+/** Spend the remount budget: every remount lands (the page starts loading) and the page never says ready. */
+function strand(native: ReturnType<typeof createNativeBridge>) {
+  expect(native.navigated(foreign)).toBe(true);
+  expect(native.navigated(pageUrl)).toBe(false);
+  expect(native.navigated(foreign)).toBe(true);
+  expect(native.navigated(pageUrl)).toBe(false);
+  expect(native.navigated(foreign)).toBe(false);
+  expect(native.stranded).toBe(true);
+}
+
 describe("createNativeBridge", () => {
   it("refuses a page that is not hosted", () => {
     expect(() =>
@@ -104,7 +124,10 @@ describe("createNativeBridge", () => {
     expect(native.navigated("about:blank")).toBe(false);
     expect(native.peer).not.toBeNull();
     expect(native.navigated("https://evil.example/form")).toBe(true);
-    await expect(lost).rejects.toThrow(/went away/);
+    await expect(lost).rejects.toMatchObject({
+      code: NativeBridgeErrorCode.pageGone,
+      message: expect.stringMatching(/went away/),
+    });
     expect(native.peer).toBeNull();
     const before = injected.length;
     const next = native.client.request("evm", "eth_chainId");
@@ -119,7 +142,10 @@ describe("createNativeBridge", () => {
     host.ready();
     const lost = native.client.request("evm", "eth_requestAccounts");
     host.ready();
-    await expect(lost).rejects.toThrow(/reloaded/);
+    await expect(lost).rejects.toMatchObject({
+      code: NativeBridgeErrorCode.pageGone,
+      message: expect.stringMatching(/reloaded/),
+    });
   });
 
   it("pageGone fails what is in flight and queues until the next ready", async () => {
@@ -130,7 +156,7 @@ describe("createNativeBridge", () => {
     host.ready();
     const lost = native.client.request("evm", "eth_requestAccounts");
     native.pageGone();
-    await expect(lost).rejects.toThrow(/went away/);
+    await expect(lost).rejects.toMatchObject({ code: NativeBridgeErrorCode.pageGone });
     const before = injected.length;
     const next = native.client.request("evm", "eth_chainId");
     expect(injected).toHaveLength(before);
@@ -141,11 +167,109 @@ describe("createNativeBridge", () => {
   it("asks for the page back twice at most until it announces itself again", () => {
     const { native, host } = setup();
     host.ready();
-    expect(native.navigated("https://evil.example/")).toBe(true);
-    expect(native.navigated("https://evil.example/")).toBe(true);
-    expect(native.navigated("https://evil.example/")).toBe(false);
+    strand(native);
+    host.ready();
+    expect(native.stranded).toBe(false);
+    expect(native.navigated(foreign)).toBe(true);
+  });
+
+  it("a foreign pushState or client redirect before the remount lands costs one remount, not two", () => {
+    const { native, host } = setup();
+    host.ready();
+    expect(native.navigated(foreign)).toBe(true);
+    // Android's doUpdateVisitedHistory reports the foreign document again.
+    expect(native.navigated(`${foreign}next`)).toBe(false);
+    expect(native.navigated(pageUrl)).toBe(false);
+    expect(native.navigated(foreign)).toBe(true);
+    expect(native.navigated(foreign)).toBe(false);
+    expect(native.stranded).toBe(false);
+  });
+
+  it("past the remount cap, fails what is in flight and every new request at once, naming the page", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", () => "0x1");
     host.ready();
-    expect(native.navigated("https://evil.example/")).toBe(true);
+    expect(native.navigated(foreign)).toBe(true);
+    expect(native.navigated(pageUrl)).toBe(false);
+    expect(native.navigated(foreign)).toBe(true);
+    expect(native.navigated(pageUrl)).toBe(false);
+    const queued = native.client.request("evm", "eth_chainId");
+    expect(native.navigated(foreign)).toBe(false);
+    const stranded = {
+      name: "BridgeRequestError",
+      code: NativeBridgeErrorCode.pageStranded,
+      message: expect.stringContaining("https://wallet.example.com"),
+      data: { pageOrigin: "https://wallet.example.com" },
+    };
+    await expect(queued).rejects.toMatchObject(stranded);
+    const before = injected.length;
+    // Far longer than the test's own timeout: only an immediate rejection passes.
+    const next = native.client.request("evm", "eth_chainId", undefined, { timeoutMs: 600_000 });
+    await expect(next).rejects.toBeInstanceOf(BridgeRequestError);
+    await expect(next).rejects.toMatchObject(stranded);
+    expect(injected).toHaveLength(before);
+    expect(native.navigated(foreign)).toBe(false);
+  });
+
+  it("a page that comes back by itself clears the stranded state", async () => {
+    const { native, host } = setup();
+    host.register("evm", () => "0x1");
+    host.ready();
+    strand(native);
+    expect(native.navigated(pageUrl)).toBe(false);
+    host.ready();
+    expect(native.stranded).toBe(false);
+    await expect(native.client.request("evm", "eth_chainId")).resolves.toBe("0x1");
+  });
+
+  it("recover gives a stranded bridge a fresh budget and asks for the page back", async () => {
+    const { native, host } = setup();
+    host.register("evm", () => "0x1");
+    host.ready();
+    expect(native.recover()).toBe(false);
+    strand(native);
+    expect(native.recover()).toBe(true);
+    expect(native.stranded).toBe(false);
+    const next = native.client.request("evm", "eth_chainId");
+    // The stranded document may still report itself before the remount lands.
+    expect(native.navigated(foreign)).toBe(false);
+    expect(native.navigated(pageUrl)).toBe(false);
+    host.ready();
+    await expect(next).resolves.toBe("0x1");
+    expect(native.recover()).toBe(false);
+  });
+
+  it("recover also restarts a remount whose own load never showed up", () => {
+    const { native, host } = setup();
+    host.ready();
+    expect(native.navigated(foreign)).toBe(true);
+    // The remounted WebView's first report is foreign (the page URL redirected away).
+    expect(native.navigated(foreign)).toBe(false);
+    expect(native.stranded).toBe(false);
+    expect(native.recover()).toBe(true);
+    expect(native.navigated(pageUrl)).toBe(false);
+    expect(native.recover()).toBe(false);
+  });
+
+  it("reports every loss of the page so the host can release its sheet", () => {
+    const setupA = setup();
+    setupA.host.ready();
+    expect(setupA.pageLost).toBe(0);
+    expect(setupA.native.navigated(pageUrl)).toBe(false);
+    expect(setupA.pageLost).toBe(0);
+    setupA.native.navigated(foreign);
+    expect(setupA.pageLost).toBe(1);
+    setupA.native.navigated(pageUrl);
+    setupA.native.navigated(foreign);
+    setupA.native.navigated(pageUrl);
+    setupA.native.navigated(foreign);
+    expect(setupA.native.stranded).toBe(true);
+    expect(setupA.pageLost).toBe(3);
+
+    const setupB = setup();
+    setupB.host.ready();
+    setupB.native.pageGone();
+    expect(setupB.pageLost).toBe(1);
   });
 
   it("exposes the page origin", () => {

package/src/bridge/nativeHost.ts

@@ -1,7 +1,21 @@
 import { BridgeClient } from "./BridgeClient";
 import { hostedPageOrigin, parseOrigin } from "./hosting";
 import { createPostMessageTransport } from "./postMessageTransport";
-import { BRIDGE_PROTOCOL_VERSION, type BridgeReady } from "./protocol";
+import { BRIDGE_PROTOCOL_VERSION, BridgeRequestError, type BridgeReady } from "./protocol";
+
+/**
+ * Codes the native end raises itself when the page cannot answer. They never
+ * cross the wire, and sit outside JSON-RPC's reserved band so a wallet error
+ * passed through `evm` is unlikely to share one.
+ */
+export const NativeBridgeErrorCode = {
+  /** The page went away (reload, crash, a foreign document) before it answered. */
+  pageGone: -33001,
+  /** The host stopped loading the page back: requests fail at once until `recover()`. */
+  pageStranded: -33002,
+} as const;
+
+const MAX_REMOUNTS = 2;
 
 export interface NativeBridgeOptions {
   /** The hosted wallet page. Must pass `isHostedPageUrl`. */
@@ -14,6 +28,11 @@ export interface NativeBridgeOptions {
   timeoutMs?: number;
   /** Called once the page reports `sys.ready`. */
   onReady?(ready: BridgeReady): void;
+  /**
+   * Called when the page goes away or strands (not on a reload that sends
+   * `sys.ready` again): close anything showing it, it no longer holds that state.
+   */
+  onPageLost?(): void;
 }
 
 export interface NativeBridge {
@@ -22,22 +41,36 @@ export interface NativeBridge {
   readonly pageOrigin: string;
   /** What the page announced in `sys.ready`, or null before it has. */
   readonly peer: BridgeReady | null;
+  /** True once the page was lost past the remount cap; see `navigated`. */
+  readonly stranded: boolean;
   /**
    * Feed a WebView message in: `receive(e.nativeEvent.data, e.nativeEvent.url)`.
    * A message whose `fromUrl` is missing or on another origin is dropped.
    */
   receive(data: string, fromUrl: string): void;
   /**
-   * The top frame started loading `url` (react-native-webview's `onLoadStart`).
+   * The top frame is on `url` (react-native-webview's `onLoadStart`, which
+   * Android fires when history updates, after the document commits).
    * A document on another origin is not the page: what is in flight fails,
    * nothing more is delivered until the page announces itself again, and the
-   * answer is true so the host loads `pageUrl` back. Twice at most between two
-   * `sys.ready`s: a page that never comes back stays down instead of looping.
+   * answer is true so the host loads `pageUrl` back. Another foreign report
+   * before that load starts costs nothing: Android reports a foreign
+   * pushState or client redirect too. Twice at most between two `sys.ready`s;
+   * past that the bridge is stranded and fails every request at once with
+   * `pageStranded` instead of looping, until the page announces itself or
+   * the host calls `recover()`.
    */
   navigated(url: string): boolean;
+  /**
+   * On a user action (the app returning to the foreground): leave the
+   * stranded state, or a remount whose own page load never showed up, with a
+   * fresh remount budget. True when the host should now load `pageUrl` back.
+   */
+  recover(): boolean;
   /**
    * The page died (WebView content process gone) or is being reloaded: fail
-   * the requests in flight and queue new ones until the next `sys.ready`.
+   * the requests in flight and queue new ones until the next `sys.ready`
+   * (while stranded they fail at once instead).
    */
   pageGone(): void;
   dispose(): void;
@@ -66,17 +99,32 @@ export function createNativeBridge(options: NativeBridgeOptions): NativeBridge {
   const pageOrigin = hostedPageOrigin(options.pageUrl, { allowDevHosts: options.allowDevHosts });
   const queue: string[] = [];
   let peer: BridgeReady | null = null;
-  let reloads = 0;
+  let remounts = 0;
+  let remountPending = false;
+  let stranded = false;
+
+  const pageGoneError = (message: string) =>
+    new BridgeRequestError(NativeBridgeErrorCode.pageGone, message, { pageOrigin });
+  const strandedError = () =>
+    new BridgeRequestError(
+      NativeBridgeErrorCode.pageStranded,
+      `The wallet page ${pageOrigin} is gone and is no longer loaded back`,
+      { pageOrigin },
+    );
 
   const transport = createPostMessageTransport((raw) => {
-    if (peer) options.inject(buildInjectScript(raw, pageOrigin));
+    // The request is already pending in the client, so this rejects it at once.
+    if (stranded) client.rejectPending(strandedError());
+    else if (peer) options.inject(buildInjectScript(raw, pageOrigin));
     else queue.push(raw);
   });
   const offReady = transport.subscribe((message) => {
     if (message.ns !== "sys" || message.kind !== "event" || message.method !== "ready") return;
     // A second ready is a new document: whatever the old one was answering is lost.
-    if (peer) client.rejectPending(new Error("The wallet page reloaded"));
-    reloads = 0;
+    if (peer) client.rejectPending(pageGoneError("The wallet page reloaded"));
+    remounts = 0;
+    remountPending = false;
+    stranded = false;
     const params = message.params as Partial<BridgeReady> | undefined;
     peer = {
       protocol: typeof params?.protocol === "number" ? params.protocol : BRIDGE_PROTOCOL_VERSION,
@@ -87,11 +135,13 @@ export function createNativeBridge(options: NativeBridgeOptions): NativeBridge {
   });
   const client = new BridgeClient(transport, { timeoutMs: options.timeoutMs });
 
-  const pageGone = () => {
+  const lose = (error: Error) => {
     peer = null;
     queue.length = 0;
-    client.rejectPending(new Error("The wallet page went away"));
+    client.rejectPending(error);
+    options.onPageLost?.();
   };
+  const pageGone = () => lose(pageGoneError("The wallet page went away"));
 
   return {
     client,
@@ -99,16 +149,36 @@ export function createNativeBridge(options: NativeBridgeOptions): NativeBridge {
     get peer() {
       return peer;
     },
+    get stranded() {
+      return stranded;
+    },
     receive(data, fromUrl) {
       if (!fromUrl || parseOrigin(fromUrl)?.origin !== pageOrigin) return;
       transport.receive(data);
     },
     navigated(url) {
       if (url.trim().toLowerCase() === "about:blank") return false;
-      if (parseOrigin(url)?.origin === pageOrigin) return false;
+      if (parseOrigin(url)?.origin === pageOrigin) {
+        remountPending = false;
+        return false;
+      }
+      if (stranded || remountPending) return false;
+      if (remounts >= MAX_REMOUNTS) {
+        stranded = true;
+        lose(strandedError());
+        return false;
+      }
       pageGone();
-      reloads += 1;
-      return reloads <= 2;
+      remounts += 1;
+      remountPending = true;
+      return true;
+    },
+    recover() {
+      if (!stranded && !(remountPending && !peer)) return false;
+      stranded = false;
+      remounts = 0;
+      remountPending = true;
+      return true;
     },
     pageGone,
     dispose() {

package/src/bundler/metaMaskConnectTimeouts.spec.ts

@@ -330,6 +330,9 @@ describe("the bundler plugins", () => {
       optimizeDeps: {
         include: ["@metamask/connect-evm"],
         noDiscovery: true,
+        // optimizeDeps() scans the root's html entries whatever noDiscovery says,
+        // and that scan fails on workspace packages whose dist is not built yet.
+        entries: [],
         rolldownOptions: { plugins: extra },
       },
       plugins: [metaMaskConnectTimeouts()],

package/src/clients/adapter.ts

@@ -1,7 +1,11 @@
 import type { Ecosystem } from "@multiplatform.one/connectkit";
 import type { WalletAdapter } from "../connectkit/adapters/types";
 
-/** The wallet adapter a non-EVM shim connector carries (see walletAdapterConnector), or null. */
+/**
+ * The wallet adapter a non-EVM shim connector carries (see walletAdapterConnector), or null.
+ *
+ * @deprecated The wagmi shim for Solana, Sui and Bitcoin wallets, which goes in 8.0.0 when the connect modal reads the connection store (MPO-385). Use the `sol()`, `sui()` and `btc()` families and `useConnection()`.
+ */
 export function connectorAdapter(
   connector: unknown,
   ecosystem?: Exclude<Ecosystem, "evm">,

package/src/clients/connector.ts

@@ -16,6 +16,8 @@ export type NonEvmClient = SolanaMessageClient | SuiClient | BitcoinClient;
  * The signing client for a connected non-EVM wallet, built over the adapter
  * its shim connector carries. Sign-in uses it, so it stays free of
  * @solana/kit. Null for an EVM connector or one that is not connected.
+ *
+ * @deprecated The wagmi shim for Solana, Sui and Bitcoin wallets, which goes in 8.0.0 when the connect modal reads the connection store (MPO-385). Use the `sol()`, `sui()` and `btc()` families and `useConnection()`.
  */
 export function clientForConnector(
   connector: unknown,

package/src/clients/evm.spec.ts

@@ -319,6 +319,14 @@ describe("evmClient", () => {
     await expect(client.erc20.balanceOf(token)).resolves.toBe(5n * 10n ** 18n);
     await expect(client.erc20.allowance(token, spender)).resolves.toBe(4n);
     await expect(client.erc20.decimals(token)).resolves.toBe(18);
+    await expect(
+      client.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "allowance",
+        args: [account, spender],
+      }),
+    ).resolves.toBe(4n);
   });
 
   it("skips the approval when the allowance already covers the amount", async () => {

package/src/clients/evm.ts

@@ -284,6 +284,8 @@ export interface EvmClient extends ChainClient<"evm"> {
   readonly walletClient: EvmWalletClient;
   /** Reads, simulation and receipts. */
   readonly publicClient: PublicClient;
+  /** publicClient.readContract, so a read works on this client and on evmReadClient's alike. */
+  readonly readContract: PublicClient["readContract"];
   /** personal_sign; returns the 0x signature. */
   signMessage(message: string): Promise<Hex>;
   sendTransaction(parameters: EvmSendTransactionParameters): Promise<Hash>;
@@ -695,6 +697,7 @@ export function evmClient(config: EvmClientConfig): EvmClient {
     capabilities,
     walletClient,
     publicClient,
+    readContract: publicClient.readContract,
     signMessage: (message) => walletClient.signMessage({ account, message }),
     sendTransaction: (parameters) =>
       walletClient.sendTransaction({

package/src/clients/evmRead.spec.ts

@@ -0,0 +1,180 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createPublicClient,
+  custom,
+  decodeFunctionData,
+  encodeAbiParameters,
+  erc20Abi,
+  type Address,
+  type Chain,
+  type Hex,
+  type PublicClient,
+} from "viem";
+import { hardhat, mainnet, polygon, sepolia } from "viem/chains";
+import { classifyTxError } from "./evm";
+import { evmReadClient, evmReadClients } from "./evmRead";
+import { ReadOnlyClientError, UnsupportedClientMethodError } from "./types";
+
+const token = "0x2222222222222222222222222222222222222222" as Address;
+const owner = "0x1111111111111111111111111111111111111111" as Address;
+const spender = "0x3333333333333333333333333333333333333333" as Address;
+
+/** A node that answers eth_call for balanceOf, allowance and decimals, and records every method. */
+function node(chainId = 1) {
+  const methods: string[] = [];
+  const request = async ({ method, params }: { method: string; params?: unknown }) => {
+    methods.push(method);
+    if (method === "eth_chainId") return `0x${chainId.toString(16)}`;
+    if (method !== "eth_call") throw new Error(`unexpected ${method}`);
+    const [{ data }] = params as [{ data: Hex }];
+    const call = decodeFunctionData({ abi: erc20Abi, data });
+    if (call.functionName === "balanceOf") return encodeAbiParameters([{ type: "uint256" }], [42n]);
+    if (call.functionName === "allowance") return encodeAbiParameters([{ type: "uint256" }], [7n]);
+    if (call.functionName === "decimals") return encodeAbiParameters([{ type: "uint8" }], [6]);
+    throw new Error(`unexpected call ${call.functionName}`);
+  };
+  return { methods, request };
+}
+
+/** fetch stubbed as a JSON-RPC node, recording the URL of every request. */
+function stubFetch() {
+  const urls: string[] = [];
+  vi.stubGlobal("fetch", async (input: RequestInfo | URL, init?: RequestInit) => {
+    urls.push(new URL(input instanceof Request ? input.url : String(input)).href);
+    const { id } = JSON.parse(String(init?.body)) as { id: number };
+    const result = encodeAbiParameters([{ type: "uint256" }], [5n]);
+    return new Response(JSON.stringify({ jsonrpc: "2.0", id, result }), {
+      headers: { "content-type": "application/json" },
+    });
+  });
+  return urls;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("evmReadClient", () => {
+  const client = (chain: Chain = mainnet) => {
+    const rpc = node(chain.id);
+    const publicClient = createPublicClient({ chain, transport: custom(rpc) }) as PublicClient;
+    return { rpc, publicClient, client: evmReadClient({ chain, publicClient }) };
+  };
+
+  it("is an EVM client with no address and no signing capabilities", () => {
+    const { client: reader, publicClient } = client();
+    expect(reader.family).toBe("evm");
+    expect(reader.address).toBeNull();
+    expect(reader.chainId).toBe(1);
+    expect(reader.chain).toBe(mainnet);
+    expect(reader.capabilities).toEqual([]);
+    expect(reader.publicClient).toBe(publicClient);
+  });
+
+  it("reads a contract and ERC-20 state with no provider and no account", async () => {
+    const { client: reader, rpc } = client();
+    await expect(
+      reader.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [owner],
+      }),
+    ).resolves.toBe(42n);
+    await expect(reader.erc20.balanceOf(token, owner)).resolves.toBe(42n);
+    await expect(reader.erc20.allowance(token, spender, owner)).resolves.toBe(7n);
+    await expect(reader.erc20.decimals(token)).resolves.toBe(6);
+    expect(new Set(rpc.methods)).toEqual(new Set(["eth_call"]));
+  });
+
+  it.each(["signMessage", "sendTransaction", "writeContract"] as const)(
+    "rejects %s with ReadOnlyClientError before any request",
+    async (method) => {
+      const { client: reader, rpc } = client();
+      const call =
+        method === "signMessage"
+          ? reader.signMessage("hello")
+          : method === "sendTransaction"
+            ? reader.sendTransaction({ to: owner, value: 1n })
+            : reader.writeContract({
+                address: token,
+                abi: erc20Abi,
+                functionName: "transfer",
+                args: [owner, 1n],
+              });
+      const error = await call.then(
+        () => undefined,
+        (e: unknown) => e,
+      );
+      expect(error).toBeInstanceOf(ReadOnlyClientError);
+      expect(error).toBeInstanceOf(UnsupportedClientMethodError);
+      expect(error).toMatchObject({ name: "ReadOnlyClientError", family: "evm", method });
+      expect(classifyTxError(error)).toBe("failed");
+      expect(rpc.methods).toEqual([]);
+    },
+  );
+
+  it("links a transaction on the chain's explorer", () => {
+    const hash = `0x${"ab".repeat(32)}` as Hex;
+    expect(client().client.explorerTxUrl(hash)).toBe(`https://etherscan.io/tx/${hash}`);
+    expect(client(hardhat).client.explorerTxUrl(hash)).toBeUndefined();
+  });
+
+  it("refuses a public client on another chain", () => {
+    const publicClient = createPublicClient({
+      chain: polygon,
+      transport: custom(node(polygon.id)),
+    }) as PublicClient;
+    expect(() => evmReadClient({ chain: mainnet, publicClient })).toThrow(
+      "reads chain 137, not chain 1",
+    );
+  });
+
+  it("reads over rpcUrl, else the chain's default RPC", async () => {
+    const urls = stubFetch();
+    await evmReadClient({ chain: mainnet, rpcUrl: "https://rpc.example.com/eth" }).erc20.balanceOf(
+      token,
+      owner,
+    );
+    await evmReadClient({ chain: mainnet }).erc20.balanceOf(token, owner);
+    expect(urls).toEqual([
+      "https://rpc.example.com/eth",
+      new URL(mainnet.rpcUrls.default.http[0]).href,
+    ]);
+  });
+});
+
+describe("evmReadClients", () => {
+  it("offers the chains WalletProvider would, default first", () => {
+    const readers = evmReadClients({ chains: [mainnet, polygon, sepolia] });
+    expect(readers.chains.map((chain) => chain.id)).toEqual([mainnet.id, polygon.id]);
+    expect(readers.get().chainId).toBe(mainnet.id);
+    expect(readers.get(polygon.id).chainId).toBe(polygon.id);
+    expect(
+      evmReadClients({ chains: [mainnet, sepolia], enableTestnets: true }).chains.map((c) => c.id),
+    ).toEqual([mainnet.id, sepolia.id]);
+  });
+
+  it("keeps one client per chain", () => {
+    const readers = evmReadClients({ chains: [mainnet, polygon] });
+    expect(readers.get(polygon.id)).toBe(readers.get(polygon.id));
+    expect(readers.get()).toBe(readers.get(mainnet.id));
+  });
+
+  it("refuses a chain the config does not offer, naming the ones it does", () => {
+    const readers = evmReadClients({ chains: [mainnet, sepolia] });
+    expect(() => readers.get(sepolia.id)).toThrow(/11155111.*\[1\]/);
+  });
+
+  it("reads the localnet chain over localnetRpcUrl, as WalletProvider does", async () => {
+    const urls = stubFetch();
+    const readers = evmReadClients({
+      chains: [mainnet],
+      localnet: true,
+      localnetRpcUrl: "http://10.0.2.2:8545",
+    });
+    expect(readers.get().chainId).toBe(hardhat.id);
+    await expect(readers.get().erc20.balanceOf(token, owner)).resolves.toBe(5n);
+    expect(urls).toEqual(["http://10.0.2.2:8545/"]);
+  });
+});