@multiplatform.one/web3 7.31.1 → 7.32.0

package/src/connectkit/connectors/metaMaskConnectConnector.spec.ts

@@ -1,7 +1,7 @@
 import type { EventHandlers } from "@metamask/connect-evm";
 import type { Chain } from "viem";
-import { getAddress, SwitchChainError } from "viem";
-import { base, baseSepolia, mainnet, polygon, polygonAmoy } from "viem/chains";
+import { getAddress, SwitchChainError, UserRejectedRequestError } from "viem";
+import { base, baseSepolia, bscTestnet, mainnet, polygon, polygonAmoy, sepolia } from "viem/chains";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createConfig, http } from "wagmi";
 import { connect, reconnect, sendTransaction, signMessage, signTypedData } from "wagmi/actions";
@@ -9,9 +9,12 @@ import { connect, reconnect, sendTransaction, signMessage, signTypedData } from
 import {
   metaMaskConnect,
   metaMaskConnectChainIds,
+  metaMaskMayLackChain,
   metaMaskNetworks,
+  reopenMetaMask,
   resetMetaMaskConnectClient,
 } from "./metaMaskConnectConnector";
+import { wagmiDriver } from "../../wagmi/driver";
 import {
   BITCOIN_CHAIN_ID,
   SOLANA_CHAIN_ID,
@@ -39,9 +42,16 @@ vi.mock("@metamask/connect-evm", () => ({ createEVMClient }));
 const synthetic = [SOLANA_CHAIN_ID, SUI_CHAIN_ID, BITCOIN_CHAIN_ID];
 const hex = (id: number) => `0x${id.toString(16)}`;
 
-function build(chains: readonly Chain[]) {
+function build(
+  chains: readonly Chain[],
+  options: {
+    mobile?: boolean;
+    addChainFirst?: (chain: Chain) => boolean;
+    useDeeplink?: boolean;
+  } = {},
+) {
   const transports = Object.fromEntries(chains.map((chain) => [chain.id, http()]));
-  return metaMaskConnect({ dapp: { name: "test", url: "https://example.test" } })({
+  return metaMaskConnect({ dapp: { name: "test", url: "https://example.test" }, ...options })({
     chains: chains as [Chain, ...Chain[]],
     emitter: { uid: "metaMaskSDK", emit: vi.fn(), on: vi.fn(), once: vi.fn(), off: vi.fn() },
     transports,
@@ -397,6 +407,22 @@ describe("metaMaskConnect under wagmi", () => {
     }));
   });
 
+  it("connects through the connection driver on the chain the page names, asking MetaMask for it first", async () => {
+    const config = createConfig({
+      chains: [mainnet, base, baseSepolia],
+      connectors: [metaMaskConnect({ dapp: { name: "test", url: "https://example.test" } })],
+      transports: { [mainnet.id]: http(), [base.id]: http(), [baseSepolia.id]: http() },
+      multiInjectedProviderDiscovery: false,
+      storage: null,
+    });
+    client.getChainId.mockReturnValue(hex(baseSepolia.id));
+
+    const account = await wagmiDriver(config).connect("metaMaskSDK", { chainId: baseSepolia.id });
+
+    expect(client.connect.mock.calls[0]![0].chainIds[0]).toBe(hex(baseSepolia.id));
+    expect(account.chainId).toBe(baseSepolia.id);
+  });
+
   it("ignores a connect that carries no account", async () => {
     const config = wagmiConfig();
     const events = await clientEvents();
@@ -404,3 +430,229 @@ describe("metaMaskConnect under wagmi", () => {
     expect(config.state.status).toBe("disconnected");
   });
 });
+
+// What MetaMask Connect does on a phone, read from @metamask/connect-evm 2.1.1 and
+// @metamask/connect-multichain 1.2.0: a request the wallet answers goes over the
+// relay, and 10 ms later MetaMask Connect opens metamask://connect/mwp?id=<session>.
+// switchChain does that for wallet_switchEthereumChain, but for a chain MetaMask
+// lacks the wallet only answers "Unrecognized chain ID", and MetaMask Connect then
+// sends wallet_addEthereumChain with a second deeplink that no tap started.
+// Chrome on Android drops it, so the add waits in the relay and the switch never
+// settles (PROMA-121, reproduced on an Android 16 emulator with MetaMask 8.1.0).
+describe("metaMaskConnect switchChain on a phone", () => {
+  let request: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    resetMetaMaskConnectClient();
+    vi.clearAllMocks();
+    client.accounts = [];
+    request = vi.fn(async () => null);
+    client.getProvider.mockReturnValue({ request } as never);
+    client.getChainId.mockReturnValue("0x1");
+    client.connect.mockImplementation(async () => ({
+      accounts: ["0x0000000000000000000000000000000000000001"],
+      chainId: "0x1",
+    }));
+  });
+
+  afterEach(() => {
+    resetMetaMaskConnectClient();
+    client.getChainId.mockImplementation(() => "0x2105");
+    client.getProvider.mockImplementation(() => ({ request: vi.fn() }));
+    client.switchChain.mockImplementation(async () => undefined);
+    client.connect.mockImplementation(async () => ({
+      accounts: ["0x0000000000000000000000000000000000000001"],
+      chainId: "0x2105",
+    }));
+  });
+
+  const addCalls = () =>
+    request.mock.calls.filter(
+      ([call]) => (call as { method: string }).method === "wallet_addEthereumChain",
+    );
+
+  it("adds a testnet MetaMask does not ship in one wallet request, not a switch then an add", async () => {
+    const connector = build([baseSepolia, bscTestnet], { mobile: true });
+    await connector.connect();
+
+    await expect(connector.switchChain!({ chainId: baseSepolia.id })).resolves.toBe(baseSepolia);
+
+    expect(client.switchChain).not.toHaveBeenCalled();
+    expect(addCalls()).toHaveLength(1);
+    expect(addCalls()[0]![0]).toMatchObject({
+      params: [
+        {
+          chainId: hex(baseSepolia.id),
+          chainName: baseSepolia.name,
+          rpcUrls: [baseSepolia.rpcUrls.default.http[0]],
+        },
+      ],
+    });
+  });
+
+  it("switches to a chain MetaMask ships without a chain configuration, so no second request can follow", async () => {
+    const connector = build([base, sepolia], { mobile: true });
+    await connector.connect();
+
+    await connector.switchChain!({ chainId: base.id });
+    await connector.switchChain!({ chainId: sepolia.id });
+
+    expect(client.switchChain.mock.calls).toEqual([
+      [{ chainId: hex(base.id) }],
+      [{ chainId: hex(sepolia.id) }],
+    ]);
+    expect(addCalls()).toHaveLength(0);
+  });
+
+  it("fails a switch MetaMask cannot place with 4902, then adds the chain on the next switch", async () => {
+    const connector = build([base, polygonAmoy], { mobile: true, addChainFirst: () => false });
+    await connector.connect();
+    client.switchChain.mockRejectedValueOnce(
+      Object.assign(new Error('Unrecognized chain ID "0x13882".'), { code: 4902 }),
+    );
+
+    const failed = await connector.switchChain!({ chainId: polygonAmoy.id }).catch((e) => e);
+    expect(failed).toBeInstanceOf(SwitchChainError);
+    expect(failed.code).toBe(4902);
+    expect(String(failed.details)).toMatch(/Switch again from a tap/);
+    expect(client.switchChain).toHaveBeenCalledTimes(1);
+    expect((client.switchChain.mock.calls[0] as unknown[])[0]).not.toHaveProperty(
+      "chainConfiguration",
+    );
+
+    await connector.switchChain!({ chainId: polygonAmoy.id });
+    expect(client.switchChain).toHaveBeenCalledTimes(1);
+    expect(addCalls()).toHaveLength(1);
+  });
+
+  it("keeps a switch to a chain the session already permits in the page", async () => {
+    const connector = build([baseSepolia, bscTestnet], { mobile: true });
+    await connector.connect();
+    await connector.switchChain!({ chainId: baseSepolia.id });
+    await connector.switchChain!({ chainId: bscTestnet.id });
+    request.mockClear();
+
+    await connector.switchChain!({ chainId: baseSepolia.id });
+
+    expect(addCalls()).toHaveLength(0);
+    expect(client.switchChain).toHaveBeenCalledWith({ chainId: hex(baseSepolia.id) });
+  });
+
+  it("sends nothing when MetaMask is already on the chain", async () => {
+    client.getChainId.mockReturnValue(hex(baseSepolia.id));
+    const connector = build([baseSepolia], { mobile: true });
+
+    await expect(connector.switchChain!({ chainId: baseSepolia.id })).resolves.toBe(baseSepolia);
+
+    expect(client.switchChain).not.toHaveBeenCalled();
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  it("turns a rejection in MetaMask into UserRejectedRequestError, on either path", async () => {
+    const rejected = Object.assign(new Error("User rejected the request."), { code: 4001 });
+    const connector = build([base, baseSepolia], { mobile: true });
+    await connector.connect();
+
+    request.mockRejectedValueOnce(rejected);
+    await expect(connector.switchChain!({ chainId: baseSepolia.id })).rejects.toBeInstanceOf(
+      UserRejectedRequestError,
+    );
+    client.switchChain.mockRejectedValueOnce(rejected);
+    await expect(connector.switchChain!({ chainId: base.id })).rejects.toBeInstanceOf(
+      UserRejectedRequestError,
+    );
+  });
+
+  it("forgets what the session permitted when it disconnects", async () => {
+    const connector = build([baseSepolia], { mobile: true });
+    await connector.connect();
+    await connector.switchChain!({ chainId: baseSepolia.id });
+    await connector.disconnect();
+    await connector.connect();
+    request.mockClear();
+
+    await connector.switchChain!({ chainId: baseSepolia.id });
+
+    expect(addCalls()).toHaveLength(1);
+  });
+
+  it("keeps the desktop switch as MetaMask Connect does it, with the chain configuration", async () => {
+    const connector = build([baseSepolia], { mobile: false });
+    await connector.connect();
+
+    await connector.switchChain!({ chainId: baseSepolia.id });
+
+    expect(addCalls()).toHaveLength(0);
+    expect(client.switchChain).toHaveBeenCalledWith({
+      chainId: hex(baseSepolia.id),
+      chainConfiguration: expect.objectContaining({ chainId: hex(baseSepolia.id) }),
+    });
+  });
+});
+
+describe("metaMaskMayLackChain", () => {
+  it("is true for a testnet MetaMask does not ship and false for mainnets and its own testnets", () => {
+    expect(metaMaskMayLackChain(baseSepolia)).toBe(true);
+    expect(metaMaskMayLackChain(bscTestnet)).toBe(true);
+    expect(metaMaskMayLackChain(sepolia)).toBe(false);
+    expect(metaMaskMayLackChain(base)).toBe(false);
+    expect(metaMaskMayLackChain(mainnet)).toBe(false);
+  });
+});
+
+describe("reopenMetaMask", () => {
+  beforeEach(() => {
+    resetMetaMaskConnectClient();
+    vi.clearAllMocks();
+  });
+  afterEach(() => resetMetaMaskConnectClient());
+
+  const mobileOptions = () =>
+    (
+      createEVMClient.mock.calls[0]![0] as {
+        mobile: { preferredOpenLink?: (url: string, target?: string) => void };
+      }
+    ).mobile;
+
+  it("opens the last MetaMask link again, through the app's own opener", async () => {
+    const open = vi.fn();
+    const connector = metaMaskConnect({
+      dapp: { name: "test", url: "https://example.test" },
+      preferredOpenLink: open,
+    })({
+      chains: [baseSepolia],
+      emitter: { uid: "metaMaskSDK", emit: vi.fn(), on: vi.fn(), once: vi.fn(), off: vi.fn() },
+      transports: { [baseSepolia.id]: http() },
+    } as never);
+    await connector.setup?.();
+    expect(reopenMetaMask()).toBe(false);
+
+    mobileOptions().preferredOpenLink!("metamask://connect/mwp?id=abc", "_self");
+    open.mockClear();
+
+    expect(reopenMetaMask()).toBe(true);
+    expect(open).toHaveBeenCalledWith("metamask://connect/mwp?id=abc", "_self");
+  });
+
+  it("forgets the link when the session ends", async () => {
+    const connector = metaMaskConnect({
+      dapp: { name: "test", url: "https://example.test" },
+      preferredOpenLink: vi.fn(),
+    })({
+      chains: [baseSepolia],
+      emitter: { uid: "metaMaskSDK", emit: vi.fn(), on: vi.fn(), once: vi.fn(), off: vi.fn() },
+      transports: { [baseSepolia.id]: http() },
+    } as never);
+    await connector.setup?.();
+    mobileOptions().preferredOpenLink!("metamask://connect/mwp?id=abc");
+
+    await connector.disconnect();
+
+    expect(reopenMetaMask()).toBe(false);
+  });
+
+  it("leaves MetaMask Connect's universal-link opener alone when deeplinks are off", async () => {
+    await build([baseSepolia], { useDeeplink: false }).setup?.();
+    expect(mobileOptions()).toEqual({ useDeeplink: false });
+  });
+});

package/src/connectkit/connectors/metaMaskConnectConnector.ts

@@ -12,6 +12,7 @@
 // and ConnectWithInjector's display_uri listener all key off it, and so does
 // every consumer's persisted "recent connector".
 import type { EIP1193Provider, MetamaskConnectEVM } from "@metamask/connect-evm";
+import { isMobile } from "@multiplatform.one/connectkit";
 import { ChainNotConfiguredError, type CreateConnectorFn, createConnector } from "wagmi";
 import {
   type Address,
@@ -36,6 +37,18 @@ export type MetaMaskConnectParameters = {
   /** `metamask://` instead of the https://metamask.app.link universal link. */
   useDeeplink?: boolean;
   debug?: boolean;
+  /**
+   * MetaMask is the phone app, reached over the relay: every request it has to
+   * approve is a trip to the app that only a tap can start. Defaults to
+   * connectkit's `isMobile()`.
+   */
+  mobile?: boolean;
+  /**
+   * On a phone, whether a switch to `chain` asks MetaMask to add it
+   * (`wallet_addEthereumChain`, which adds the network and switches in one trip)
+   * rather than to switch to it. Defaults to `metaMaskMayLackChain`.
+   */
+  addChainFirst?: (chain: Chain) => boolean;
 };
 
 type ConnectorConfig = Parameters<CreateConnectorFn>[0];
@@ -149,6 +162,26 @@ function isUrl(value: string): boolean {
   }
 }
 
+// The testnets MetaMask 8 lists in its own network picker. An add request for
+// one of these shows "Update <network>" with a warning that the RPC URL is not a
+// known provider, so a switch asks for them instead.
+const metaMaskBuiltInTestnets = new Set([11155111, 59141, 10143, 6342, 6343]);
+
+/**
+ * Whether a phone's MetaMask may not have `chain` yet: a testnet it does not
+ * ship. A switch to a chain MetaMask lacks only answers "Unrecognized chain ID",
+ * and the add request that has to follow is a second trip to the app, which
+ * Chrome on Android drops when no tap started it.
+ */
+export function metaMaskMayLackChain(chain: Chain): boolean {
+  return chain.testnet === true && !metaMaskBuiltInTestnets.has(chain.id);
+}
+
+function isUnrecognizedChain(err: unknown): boolean {
+  const { code, message } = (err ?? {}) as { code?: number; message?: unknown };
+  return code === 4902 || (typeof message === "string" && message.includes("Unrecognized chain"));
+}
+
 /** The chain ids a connect asks MetaMask for, the requested one first (it becomes the active chain). */
 export function metaMaskConnectChainIds(networks: Record<Hex, string>, chainId?: number): Hex[] {
   const ids = Object.keys(networks) as Hex[];
@@ -164,6 +197,43 @@ export function metaMaskConnectChainIds(networks: Record<Hex, string>, chainId?:
 // build connectors that wagmi never uses, and one of those may be the newest.
 let client: Promise<MetamaskConnectEVM> | undefined;
 let owner: Emitter | undefined;
+// Chains the session is known to permit, where a switch stays in the page, and
+// chains MetaMask answered "Unrecognized chain ID" for, which a switch adds.
+const permittedChains = new Set<number>();
+const unrecognizedChains = new Set<number>();
+let lastDeeplink: { url: string; open: (url: string, target?: string) => void } | undefined;
+
+function forgetChains(): void {
+  permittedChains.clear();
+  unrecognizedChains.clear();
+  lastDeeplink = undefined;
+}
+
+/**
+ * Opens the MetaMask app again on the request it was last sent to. Call it
+ * synchronously from a tap, for an "Open MetaMask" button the page shows while
+ * a request waits: MetaMask can open before the request reaches it and show
+ * nothing, and a request sent after an await or a trip back opens nothing on
+ * Chrome for Android. Returns false when there is nothing to reopen.
+ */
+export function reopenMetaMask(): boolean {
+  if (!lastDeeplink) return false;
+  lastDeeplink.open(lastDeeplink.url, "_self");
+  return true;
+}
+
+function recordingOpenLink(
+  open: (url: string, target?: string) => void,
+): (url: string, target?: string) => void {
+  return (url, target) => {
+    lastDeeplink = { url, open };
+    open(url, target);
+  };
+}
+
+function navigate(url: string): void {
+  if (typeof window !== "undefined") window.location.href = url;
+}
 
 function getClient(
   parameters: MetaMaskConnectParameters,
@@ -184,18 +254,17 @@ function getClient(
       skipAutoAnnounce: true,
       debug: parameters.debug,
       ...(parameters.headless ? { ui: { headless: true } } : {}),
-      ...(parameters.preferredOpenLink || parameters.useDeeplink !== undefined
-        ? {
-            mobile: {
-              ...(parameters.preferredOpenLink
-                ? { preferredOpenLink: parameters.preferredOpenLink }
-                : {}),
-              ...(parameters.useDeeplink !== undefined
-                ? { useDeeplink: parameters.useDeeplink }
-                : {}),
-            },
-          }
-        : {}),
+      mobile: {
+        // MetaMask Connect's own opener does the same location change for a
+        // metamask:// link; going through one here keeps the link to reopen.
+        // With useDeeplink false it clicks a universal link instead, left as is.
+        ...(parameters.preferredOpenLink
+          ? { preferredOpenLink: recordingOpenLink(parameters.preferredOpenLink) }
+          : parameters.useDeeplink === false
+            ? {}
+            : { preferredOpenLink: recordingOpenLink(navigate) }),
+        ...(parameters.useDeeplink !== undefined ? { useDeeplink: parameters.useDeeplink } : {}),
+      },
       eventHandlers: {
         // A session approved outside connect(), in another tab say. wagmi drops
         // `change` for a connector it has no connection for, so only `connect`
@@ -208,11 +277,19 @@ function getClient(
             });
         },
         accountsChanged: (accounts) => {
-          if (accounts.length === 0) owner?.emit("disconnect");
-          else owner?.emit("change", { accounts: accounts.map((a) => getAddress(a)) });
+          if (accounts.length === 0) {
+            forgetChains();
+            owner?.emit("disconnect");
+          } else owner?.emit("change", { accounts: accounts.map((a) => getAddress(a)) });
+        },
+        chainChanged: (chainId) => {
+          permittedChains.add(Number(chainId));
+          owner?.emit("change", { chainId: Number(chainId) });
+        },
+        disconnect: () => {
+          forgetChains();
+          owner?.emit("disconnect");
         },
-        chainChanged: (chainId) => owner?.emit("change", { chainId: Number(chainId) }),
-        disconnect: () => owner?.emit("disconnect"),
         displayUri: (uri) => owner?.emit("message", { type: "display_uri", data: uri }),
       },
     }),
@@ -227,6 +304,7 @@ function getClient(
 export function resetMetaMaskConnectClient(): void {
   client = undefined;
   owner = undefined;
+  forgetChains();
 }
 
 function rethrow(err: unknown): never {
@@ -244,6 +322,8 @@ export function metaMaskConnect(parameters: MetaMaskConnectParameters) {
     const networks = metaMaskNetworks(config.chains, config.transports);
     const supportedNetworks = metaMaskSupportedNetworks(networks, config.transports);
     const fallbackChainId = Number(Object.keys(networks)[0] ?? 1);
+    const mobile = parameters.mobile ?? isMobile();
+    const addChainFirst = parameters.addChainFirst ?? metaMaskMayLackChain;
     const instance = () => getClient(parameters, supportedNetworks);
     let guarded: { provider: EIP1193Provider; wrapped: EIP1193Provider } | undefined;
     // Every call wagmi makes on the connector it uses claims the client's events;
@@ -280,12 +360,15 @@ export function metaMaskConnect(parameters: MetaMaskConnectParameters) {
             });
             accounts = result.accounts.map((a) => getAddress(a));
           }
-          return { accounts: accounts as never, chainId: chainIdOf(mm) };
+          const current = chainIdOf(mm);
+          permittedChains.add(current);
+          return { accounts: accounts as never, chainId: current };
         } catch (err) {
           rethrow(err);
         }
       },
       async disconnect() {
+        forgetChains();
         await (await claim()).disconnect();
       },
       async getAccounts() {
@@ -317,27 +400,56 @@ export function metaMaskConnect(parameters: MetaMaskConnectParameters) {
         const chain = config.chains.find((c) => c.id === chainId);
         if (!chain || !networks[numberToHex(chainId)])
           throw new SwitchChainError(new ChainNotConfiguredError());
+        const chainConfiguration = {
+          chainId: numberToHex(chainId),
+          chainName: addEthereumChainParameter?.chainName ?? chain.name,
+          nativeCurrency: addEthereumChainParameter?.nativeCurrency ?? chain.nativeCurrency,
+          rpcUrls: addEthereumChainParameter?.rpcUrls
+            ? [...addEthereumChainParameter.rpcUrls]
+            : [networks[numberToHex(chainId)]!],
+          ...(chain.blockExplorers?.default.url
+            ? { blockExplorerUrls: [chain.blockExplorers.default.url] }
+            : {}),
+        };
+        const mm = await claim();
+        if (mm.getChainId() === numberToHex(chainId)) return chain;
         try {
-          await (
-            await claim()
-          ).switchChain({
-            chainId: numberToHex(chainId),
-            chainConfiguration: {
-              chainId: numberToHex(chainId),
-              chainName: addEthereumChainParameter?.chainName ?? chain.name,
-              nativeCurrency: addEthereumChainParameter?.nativeCurrency ?? chain.nativeCurrency,
-              rpcUrls: addEthereumChainParameter?.rpcUrls
-                ? [...addEthereumChainParameter.rpcUrls]
-                : [networks[numberToHex(chainId)]],
-              ...(chain.blockExplorers?.default.url
-                ? { blockExplorerUrls: [chain.blockExplorers.default.url] }
-                : {}),
-            },
-          });
+          if (!mobile) {
+            await mm.switchChain({ chainId: numberToHex(chainId), chainConfiguration });
+          } else if (
+            !permittedChains.has(chainId) &&
+            (unrecognizedChains.has(chainId) || addChainFirst(chain))
+          ) {
+            // One trip that adds the network and permits it. MetaMask Connect
+            // takes the chain on once the wallet answers.
+            await mm.getProvider().request({
+              method: "wallet_addEthereumChain",
+              params: [chainConfiguration],
+            } as never);
+          } else {
+            // Without a configuration, so a chain MetaMask lacks fails here
+            // instead of MetaMask Connect sending the add request as a second
+            // trip, which no tap started and Chrome on Android drops.
+            await mm.switchChain({ chainId: numberToHex(chainId) });
+          }
+          permittedChains.add(chainId);
+          unrecognizedChains.delete(chainId);
           return chain;
         } catch (err) {
           if ((err as { code?: number })?.code === UserRejectedRequestError.code)
             throw new UserRejectedRequestError(err as Error);
+          if (mobile && isUnrecognizedChain(err)) {
+            unrecognizedChains.add(chainId);
+            throw new SwitchChainError(
+              Object.assign(
+                new Error(
+                  `MetaMask does not have ${chain.name} yet. Switch again from a tap to add it.`,
+                  { cause: err },
+                ),
+                { code: 4902 },
+              ),
+            );
+          }
           throw new SwitchChainError(err as Error);
         }
       },

package/src/connectkit/index.ts

@@ -6,6 +6,8 @@ export { default as getDefaultConnectors } from "./defaultConnectors";
 export { wallets } from "./wallets";
 export {
   metaMaskConnect,
+  metaMaskMayLackChain,
+  reopenMetaMask,
   type MetaMaskConnectParameters,
 } from "./connectors/metaMaskConnectConnector";
 

package/src/connectkit/openConnector/context.tsx

@@ -7,7 +7,7 @@ import React, {
   useRef,
   useSyncExternalStore,
 } from "react";
-import { useAccountEffect, type Connector } from "wagmi";
+import { ChainNotConfiguredError, useAccountEffect, useConfig, type Connector } from "wagmi";
 import {
   routes,
   useContext,
@@ -96,10 +96,12 @@ export const ConnectorLauncherProvider: React.FC<{ children: React.ReactNode }>
   const wallets = useWallets();
   const { connectAsync } = useConnect();
   const connectors = useConnectors();
+  const { chains } = useConfig();
 
   const depsRef = useRef<LauncherDeps>(null as unknown as LauncherDeps);
   depsRef.current = {
-    connect: (connector) => connectAsync({ connector }),
+    connect: (connector, chainId) =>
+      connectAsync(chainId === undefined ? { connector } : { connector, chainId }),
     showConnecting: (walletId) => {
       context.setConnector({ id: walletId });
       context.setRoute(routes.CONNECT);
@@ -111,8 +113,8 @@ export const ConnectorLauncherProvider: React.FC<{ children: React.ReactNode }>
     },
     onFailed: () => clearConnectIntent(),
   };
-  const latest = useRef({ wallets, connectors, options: context.options });
-  latest.current = { wallets, connectors, options: context.options };
+  const latest = useRef({ wallets, connectors, chains, options: context.options });
+  latest.current = { wallets, connectors, chains, options: context.options };
 
   const launcher = useMemo(() => createConnectorLauncher(() => depsRef.current), []);
   useEffect(() => () => launcher.cancel(), [launcher]);
@@ -133,7 +135,9 @@ export const ConnectorLauncherProvider: React.FC<{ children: React.ReactNode }>
 
   const openConnector = useCallback(
     (id: string, options: OpenConnectorOptions = {}) => {
-      const { wallets, connectors } = latest.current;
+      const { wallets, connectors, chains } = latest.current;
+      if (options.chainId !== undefined && !chains.some((chain) => chain.id === options.chainId))
+        throw new ChainNotConfiguredError();
       const wallet = resolveWallet(wallets, connectors, id);
       if (!wallet) {
         context.log(`openConnector: no connector ${id}, showing the wallet list.`);
@@ -145,6 +149,7 @@ export const ConnectorLauncherProvider: React.FC<{ children: React.ReactNode }>
       setConnectIntent();
       launcher.open(wallet.id, wallet.connector, {
         fallbackMs: options.fallbackMs ?? defaultOpenConnectorFallbackMs(),
+        ...(options.chainId === undefined ? {} : { chainId: options.chainId }),
       });
     },
     // context.log is stable enough for a debug line; the rest is read through refs.

package/src/connectkit/openConnector/launcher.spec.ts

@@ -68,7 +68,7 @@ describe("createConnectorLauncher", () => {
     launcher.open("metaMaskSDK", mm, { fallbackMs: 6000 });
 
     expect(deps.connect).toHaveBeenCalledTimes(1);
-    expect(deps.connect).toHaveBeenCalledWith(mm);
+    expect(deps.connect).toHaveBeenCalledWith(mm, undefined);
     expect(calls).toEqual(["connect:metaMaskSDK", "connecting:metaMaskSDK"]);
     expect(launcher.pending()?.walletId).toBe("metaMaskSDK");
   });
@@ -146,7 +146,7 @@ describe("createConnectorLauncher", () => {
     launcher.open("metaMaskSDK", mm, { fallbackMs: 6000 });
 
     expect(deps.connect).toHaveBeenCalledTimes(2);
-    expect(deps.connect).toHaveBeenLastCalledWith(mm);
+    expect(deps.connect).toHaveBeenLastCalledWith(mm, undefined);
     expect(launcher.pending()).toBe(first);
     expect(vi.getTimerCount()).toBe(1);
 
@@ -323,3 +323,25 @@ describe("createConnectorLauncher", () => {
     expect(deps.showList).not.toHaveBeenCalled();
   });
 });
+
+describe("createConnectorLauncher with a chainId", () => {
+  it("hands the chain to connect() inside the same synchronous call", () => {
+    const { launcher, deps } = setup();
+    const mm = fakeConnector("metaMaskSDK");
+
+    launcher.open("metaMaskSDK", mm, { fallbackMs: 0, chainId: 84532 });
+
+    expect(deps.connect).toHaveBeenCalledTimes(1);
+    expect(deps.connect).toHaveBeenCalledWith(mm, 84532);
+  });
+
+  it("re-issues a pending connect on the chain the new tap asks for", () => {
+    const { launcher, deps } = setup();
+    const mm = fakeConnector("metaMaskSDK");
+    launcher.open("metaMaskSDK", mm, { fallbackMs: 0, chainId: 84532 });
+
+    launcher.open("metaMaskSDK", mm, { fallbackMs: 0, chainId: 84532 });
+
+    expect(deps.connect).toHaveBeenNthCalledWith(2, mm, 84532);
+  });
+});