@multiplatform.one/web3 7.26.0 → 7.28.0

package/src/core/store.ts

@@ -1,6 +1,7 @@
 import type { ChainClient } from "../clients/types";
 import { createFamilyRegistry, type FamilyRegistry, type WalletFamily } from "./family";
 import type {
+  ConnectOptions,
   ConnectionDriver,
   ConnectionState,
   ConnectionStorage,
@@ -52,13 +53,10 @@ export interface ConnectionStore {
   subscribeConnectors(listener: () => void): () => void;
   /**
    * Connects one family's connector, first closing any other connection.
-   * Remembers {family, connectorId} on success.
+   * Remembers {family, connectorId} on success. With `silent` it only takes a
+   * connection the wallet already granted, never prompting.
    */
-  connect(
-    family: string,
-    connectorId: string,
-    options?: DriverConnectOptions,
-  ): Promise<ConnectionState>;
+  connect(family: string, connectorId: string, options?: ConnectOptions): Promise<ConnectionState>;
   /** Closes the active connection and forgets it. */
   disconnect(): Promise<void>;
   /**
@@ -67,6 +65,13 @@ export interface ConnectionStore {
    * wallet side keeps the record, so a later reconnect() can restore it.
    */
   reconnect(): Promise<ConnectionState>;
+  /**
+   * The active connection's client. When the driver has not handed one over
+   * yet, or its last build failed, the driver is asked again and the store
+   * keeps what it gets. Null with nothing connected or a driver without
+   * clients; rejects with the driver's error.
+   */
+  client(): Promise<ChainClient | null>;
   /**
    * Stops listening to every driver and to this store's listeners, and refuses
    * later connects. It closes nothing: the connection and the attempt live at
@@ -90,6 +95,13 @@ const disconnected: ConnectionState = Object.freeze({
 
 const superseded = () => new Error("wallet connect superseded");
 
+/** The options a driver sees: the store's own `silent` stays with the store. */
+function driverOptions(options: ConnectOptions | undefined): DriverConnectOptions | undefined {
+  if (!options || !("silent" in options)) return options;
+  const { silent: _silent, ...rest } = options;
+  return rest;
+}
+
 function browserStorage(): ConnectionStorage | null {
   try {
     const storage = (globalThis as { localStorage?: ConnectionStorage }).localStorage;
@@ -455,15 +467,27 @@ export function createConnectionStore(options: ConnectionStoreOptions): Connecti
         try {
           if (current !== operation) throw superseded();
           asked = true;
-          account = await driver.connect(connectorId, connectOptions);
+          if (connectOptions?.silent) {
+            const granted = await driver.reconnect(connectorId);
+            if (!granted) {
+              throw new Error(`wallet ${family.id} ${connectorId} is not authorised on this page`);
+            }
+            account = granted;
+          } else {
+            account = await driver.connect(connectorId, driverOptions(connectOptions));
+          }
         } catch (error) {
           if (current === operation) {
             pending = null;
             set(disconnected);
           }
           // After destroy() the driver may serve another store; what it holds is
-          // this attempt's only if this attempt asked for it.
-          if (asked || !destroyed) await closeOrphan(driver, connectorId);
+          // this attempt's only if this attempt asked for it. A silent attempt
+          // opened nothing: what the driver holds is the connection it was
+          // handed, which stays with whoever opened it.
+          if (!connectOptions?.silent && (asked || !destroyed)) {
+            await closeOrphan(driver, connectorId);
+          }
           throw error;
         }
         if (current !== operation) {
@@ -541,6 +565,33 @@ export function createConnectionStore(options: ConnectionStoreOptions): Connecti
       void attempt.then(settled, settled);
       return attempt;
     },
+    async client() {
+      if (state.client) return state.client;
+      if (state.status !== "connected" || !active || !state.address) return null;
+      const { driver, connectorId } = active;
+      const asked = state;
+      const request = ++clientRequest;
+      const client =
+        (await driver.client?.({
+          status: "connected",
+          connectorId,
+          account: {
+            address: asked.address as string,
+            ...(asked.chainId === null ? {} : { chainId: asked.chainId }),
+          },
+        })) ?? null;
+      if (
+        client &&
+        request === clientRequest &&
+        active?.driver === driver &&
+        state.status === "connected" &&
+        state.address === asked.address &&
+        state.chainId === asked.chainId
+      ) {
+        set(Object.freeze({ ...state, client }));
+      }
+      return client;
+    },
     destroy() {
       if (destroyed) return;
       destroyed = true;

package/src/core/types.ts

@@ -31,6 +31,17 @@ export interface DriverConnectOptions {
   onDisplayUri?: (uri: string) => void;
 }
 
+/** What the connection store's `connect` takes. */
+export interface ConnectOptions extends DriverConnectOptions {
+  /**
+   * Take a connection the wallet has already granted, through the driver's
+   * silent `reconnect`, and never prompt. Rejects when the wallet has not
+   * granted it. A UI that opened the connection outside the store, such as
+   * the wagmi connect modal, hands it over this way.
+   */
+  silent?: boolean;
+}
+
 /**
  * The engine behind one wallet family's connections: wagmi for EVM, the light
  * driver for adapter-based families. The connection store drives it and holds
@@ -47,7 +58,10 @@ export interface ConnectionDriver {
   getState(): DriverState;
   /** Called on every state change: account, chain, connector, or a disconnect from the wallet side. */
   subscribe(listener: () => void): () => void;
-  /** Prompts the user. Rejects when they decline or the wallet fails. */
+  /**
+   * Prompts the user, unless the driver already holds that connector open,
+   * which resolves its account. Rejects when they decline or the wallet fails.
+   */
   connect(connectorId: string, options?: DriverConnectOptions): Promise<DriverAccount>;
   /**
    * Closes every connection the driver holds, or with a connectorId only that

package/src/families/btc.ts

@@ -0,0 +1,16 @@
+import { defineWalletFamily, type WalletFamily } from "../core/family";
+import { bitcoinDriver } from "../light/drivers";
+import { withHosting } from "./host";
+import { btcMessage } from "./messages";
+
+/** The Bitcoin family: UniSat, OKX or Phantom's Bitcoin wallet. */
+export function btc(): WalletFamily {
+  const family = defineWalletFamily({
+    id: "btc",
+    label: "Bitcoin",
+    aliases: ["bitcoin"],
+    message: btcMessage,
+    driver: () => bitcoinDriver(),
+  });
+  return withHosting(family, { ecosystem: "bitcoin", chainId: "bitcoin" });
+}

package/src/families/eth.ts

@@ -0,0 +1,35 @@
+import type { Config } from "@wagmi/core";
+import { defineWalletFamily, type WalletFamily } from "../core/family";
+import { wagmiDriver } from "../wagmi/driver";
+import { withHosting } from "./host";
+import { ethMessage } from "./messages";
+
+export interface EthFamilyOptions {
+  /**
+   * The wagmi config EVM wallets connect through. A Web3Provider uses it for
+   * its own WagmiProvider; left out, the provider builds one from its
+   * Web3Config, and a connection store made outside a provider has none.
+   */
+  config?: Config;
+}
+
+/** The EVM family: MetaMask, Coinbase Wallet and every EIP-6963 wallet, over wagmi and viem. */
+export function eth(options: EthFamilyOptions = {}): WalletFamily {
+  const { config } = options;
+  const family = defineWalletFamily({
+    id: "eth",
+    label: "Ethereum",
+    aliases: ["evm"],
+    message: ethMessage,
+    driver: () => {
+      if (!config) {
+        throw new Error(
+          "eth() needs a wagmi config outside a Web3Provider: eth({ config: createConfig(...) })",
+        );
+      }
+      return wagmiDriver(config);
+    },
+    bridge: { namespace: "evm" },
+  });
+  return withHosting(family, { ecosystem: "evm", ...(config ? { config } : {}) });
+}

package/src/families/families.spec.ts

@@ -0,0 +1,180 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { accountFor, keys, scriptedConnector, wagmiConfig } from "../../tests/core/wagmiWallets";
+import { createWallets } from "../../tests/core/driverContract";
+import { createConnectionStore } from "../core/store";
+import { createFamilyRegistry } from "../core/family";
+import { buildWalletMessage, type SignerFamily } from "../message/buildWalletMessage";
+import { btc, eth, gpg, sol, sui, walletFamilies } from "./index";
+
+const base = {
+  domain: "app.multiplatform.one",
+  uri: "https://app.multiplatform.one/login",
+  nonce: "ohY7vD2Kq9",
+  issuedAt: "2026-09-26T20:48:18.648Z",
+  address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
+};
+
+const outcome = (build: () => string) => {
+  try {
+    return { message: build() };
+  } catch {
+    return { threw: true };
+  }
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("the built-in families", () => {
+  const registry = createFamilyRegistry([eth(), sol(), sui(), btc(), gpg()]);
+  const names: SignerFamily[] = ["eth", "evm", "sol", "solana", "sui", "btc", "bitcoin", "gpg"];
+
+  it("sign the bytes buildWalletMessage builds, for every family, alias and option", () => {
+    let compared = 0;
+    for (const family of names) {
+      for (const statement of [undefined, null, "", "Custom statement."]) {
+        for (const chainId of [undefined, 137, "solana:devnet", 900001]) {
+          for (const version of [undefined, "2"]) {
+            const opts = { ...base, statement, chainId, version };
+            expect(outcome(() => registry.messages.build(family, opts))).toEqual(
+              outcome(() => buildWalletMessage(family, opts)),
+            );
+            compared++;
+          }
+        }
+      }
+    }
+    expect(compared).toBe(256);
+    for (const family of names) {
+      for (const opts of [
+        { ...base, address: undefined },
+        { ...base, statement: "two\nlines" },
+      ]) {
+        expect(outcome(() => registry.messages.build(family, opts))).toEqual(
+          outcome(() => buildWalletMessage(family, opts)),
+        );
+      }
+    }
+  });
+
+  it("are listed in registration order under their ids, and resolve the ecosystem names", () => {
+    expect(registry.families.map((family) => family.id)).toEqual([
+      "eth",
+      "sol",
+      "sui",
+      "btc",
+      "gpg",
+    ]);
+    expect(registry.require("evm").id).toBe("eth");
+    expect(registry.require("solana").id).toBe("sol");
+    expect(registry.require("bitcoin").id).toBe("btc");
+    expect(registry.families.map((family) => family.label)).toEqual([
+      "Ethereum",
+      "Solana",
+      "Sui",
+      "Bitcoin",
+      "GPG",
+    ]);
+  });
+
+  it("name the bridge namespace a native app reaches them on; sol and sui bring a bridge driver", () => {
+    expect(
+      [eth(), sol(), sui(), btc(), gpg()].map((family) => [
+        family.id,
+        family.bridge?.namespace ?? null,
+        typeof family.bridge?.driver,
+      ]),
+    ).toEqual([
+      ["eth", "evm", "undefined"],
+      ["sol", "solana", "function"],
+      ["sui", "sui", "function"],
+      ["btc", null, "undefined"],
+      ["gpg", "gpg", "undefined"],
+    ]);
+  });
+
+  it("gpg signs without connecting; the wallet families each have a driver", () => {
+    expect(gpg()).toMatchObject({ connectionless: true });
+    expect(gpg().driver).toBeUndefined();
+    for (const family of [eth(), sol(), sui(), btc()]) {
+      expect(family.connectionless).toBe(false);
+      expect(typeof family.driver).toBe("function");
+    }
+  });
+
+  it("eth connects through the wagmi config it is given", async () => {
+    const wallets = createWallets({ "wallet.one": accountFor(keys.one).address });
+    const config = wagmiConfig([
+      scriptedConnector(wallets, "wallet.one", {
+        [accountFor(keys.one).address]: accountFor(keys.one),
+      }),
+    ]);
+    const store = createConnectionStore({ families: [eth({ config })], storage: null });
+    expect(store.connectors().map((entry) => `${entry.family}:${entry.connector.id}`)).toEqual([
+      "eth:wallet.one",
+    ]);
+    const state = await store.connect("eth", "wallet.one");
+    expect(state).toMatchObject({
+      family: "eth",
+      address: accountFor(keys.one).address,
+      chainId: 1,
+    });
+  });
+
+  it("eth with no wagmi config says what it needs when a store outside Web3Provider asks", () => {
+    const store = createConnectionStore({ families: [eth()], storage: null });
+    expect(() => store.connectors()).toThrow(/eth\(\) needs a wagmi config/);
+  });
+
+  it("sol lists the injected Solana wallet on the cluster it is given", async () => {
+    const provider = {
+      isPhantom: true,
+      publicKey: null as { toString(): string } | null,
+      connect: vi.fn(async () => {
+        provider.publicKey = { toString: () => "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV" };
+        return { publicKey: provider.publicKey };
+      }),
+      disconnect: vi.fn(async () => {}),
+      signMessage: vi.fn(),
+    };
+    vi.stubGlobal("window", { phantom: { solana: provider } });
+    const store = createConnectionStore({
+      families: [sol({ chain: "solana:devnet" })],
+      storage: null,
+    });
+    expect(store.connectors().map((entry) => entry.connector.id)).toEqual([
+      "wallet:solana:phantom",
+    ]);
+    const state = await store.connect("sol", "wallet:solana:phantom");
+    expect(state).toMatchObject({
+      family: "sol",
+      address: "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
+      chainId: "solana:devnet",
+    });
+    expect(state.client).toMatchObject({ family: "solana", chainId: "solana:devnet" });
+  });
+});
+
+describe("walletFamilies", () => {
+  it("is every built-in family, GPG included, when given no names", () => {
+    expect(walletFamilies().map((family) => family.id)).toEqual([
+      "eth",
+      "sol",
+      "sui",
+      "btc",
+      "gpg",
+    ]);
+  });
+
+  it("builds the families Web3Config.families names, in the connect list's order", () => {
+    expect(walletFamilies(["solana", "evm"]).map((family) => family.id)).toEqual(["eth", "sol"]);
+    expect(walletFamilies(["btc", "sui"]).map((family) => family.id)).toEqual(["sui", "btc"]);
+  });
+
+  it("refuses gpg, an unknown family and an empty list, as Web3Config.families does", () => {
+    for (const names of [["gpg"], ["doge"], []]) {
+      expect(() => walletFamilies(names as never)).toThrow(/families/);
+    }
+  });
+});

package/src/families/gpg.ts

@@ -0,0 +1,13 @@
+import { defineWalletFamily, type WalletFamily } from "../core/family";
+import { gpgMessage } from "./messages";
+
+/** GPG sign-in: the user signs the message with their key in a terminal, with no wallet connection. */
+export function gpg(): WalletFamily {
+  return defineWalletFamily({
+    id: "gpg",
+    label: "GPG",
+    message: gpgMessage,
+    connectionless: true,
+    bridge: { namespace: "gpg" },
+  });
+}

package/src/families/host.ts

@@ -0,0 +1,34 @@
+import type { Config } from "@wagmi/core";
+import type { SolanaChain } from "../clients/solanaMessage";
+import type { WalletFamily } from "../core/family";
+
+/** The ecosystem a wagmi connector carries: `evm`, or a Solana, Sui or Bitcoin shim's. */
+export type HostedEcosystem = "evm" | "solana" | "sui" | "bitcoin";
+
+/**
+ * How a Web3Provider hosts a built-in family on its wagmi config while the
+ * ConnectKit modal still lists and connects every wallet through wagmi
+ * (MPO-385 step 5): the family's connections are wagmi's, so the modal and
+ * the connection store see one connection. It goes when the modal reads the
+ * store.
+ */
+export interface WagmiHosting {
+  readonly ecosystem: HostedEcosystem;
+  /** The chain id a connection reports, in place of the shim's synthetic one. */
+  readonly chainId?: string;
+  readonly solanaChain?: SolanaChain;
+  /** The wagmi config the app gave `eth()`, which the provider then uses. */
+  readonly config?: Config;
+}
+
+const hosting = new WeakMap<WalletFamily, WagmiHosting>();
+
+export function withHosting(family: WalletFamily, spec: WagmiHosting): WalletFamily {
+  hosting.set(family, Object.freeze({ ...spec }));
+  return family;
+}
+
+/** How a Web3Provider hosts this family on wagmi; undefined for GPG and a family of the app's own. */
+export function wagmiHosting(family: WalletFamily): WagmiHosting | undefined {
+  return hosting.get(family);
+}

package/src/families/index.ts

@@ -0,0 +1,32 @@
+// The built-in wallet families (MPO-385): what an app hands Web3Provider,
+// `families={[eth(), sol(), gpg()]}`. Each carries its sign-in message and its
+// connection driver; step 6 moves each into its own package.
+import type { WalletFamily } from "../core/family";
+import { resolveFamilies, type ConnectorFamily } from "../providers/walletConfig";
+import { btc } from "./btc";
+import { eth } from "./eth";
+import { gpg } from "./gpg";
+import { sol } from "./sol";
+import { sui } from "./sui";
+
+export { btc } from "./btc";
+export { eth, type EthFamilyOptions } from "./eth";
+export { gpg } from "./gpg";
+export { sol, type SolFamilyOptions } from "./sol";
+export { sui } from "./sui";
+
+/**
+ * The families `Web3Config.families` names, in the connect list's order, or
+ * with no names every built-in family, GPG included. Throws where
+ * `Web3Config.families` does: on `gpg`, an unknown name and an empty list.
+ */
+export function walletFamilies(names?: readonly ConnectorFamily[]): WalletFamily[] {
+  if (names === undefined) return [eth(), sol(), sui(), btc(), gpg()];
+  const { evm, ecosystems } = resolveFamilies({ families: names });
+  return [
+    ...(evm ? [eth()] : []),
+    ...(ecosystems.includes("solana") ? [sol()] : []),
+    ...(ecosystems.includes("sui") ? [sui()] : []),
+    ...(ecosystems.includes("bitcoin") ? [btc()] : []),
+  ];
+}

package/src/families/messages.ts

@@ -0,0 +1,39 @@
+import { getAddress } from "viem";
+import type { WalletMessageSpec } from "../core/message";
+
+// The five families' sign-in messages, byte for byte what buildWalletMessage
+// builds and the Keycloak verifiers parse. families.spec.ts holds them to it.
+
+export const ethMessage: WalletMessageSpec = {
+  header: "wants you to sign in with your Ethereum account:",
+  statement: "Sign in With Ethereum.",
+  chainId: "1",
+  numericChainId: true,
+  keepStatementLine: true,
+  normalizeAddress: (address) => getAddress(address),
+};
+
+export const solMessage: WalletMessageSpec = {
+  header: "wants you to sign in with your Solana account:",
+  statement: "Sign in With Solana.",
+  chainId: "solana:mainnet",
+};
+
+export const suiMessage: WalletMessageSpec = {
+  header: "wants you to sign in with your Sui account:",
+  statement: "Sign in With Sui.",
+  chainId: "sui:mainnet",
+};
+
+export const btcMessage: WalletMessageSpec = {
+  header: "wants you to sign in with your Bitcoin account:",
+  statement: "Sign in With Bitcoin.",
+  chainId: "bitcoin",
+};
+
+export const gpgMessage: WalletMessageSpec = {
+  header: "wants you to sign in with your GPG key.",
+  statement: null,
+  chainId: null,
+  address: false,
+};

package/src/families/sol.ts

@@ -0,0 +1,25 @@
+import { solanaBridgeDriver } from "../bridge/drivers";
+import type { SolanaChain } from "../clients/solanaMessage";
+import { defineWalletFamily, type WalletFamily } from "../core/family";
+import { solanaDriver } from "../light/drivers";
+import { withHosting } from "./host";
+import { solMessage } from "./messages";
+
+export interface SolFamilyOptions {
+  /** The cluster accounts are on. Defaults to `solana:mainnet`. */
+  chain?: SolanaChain;
+}
+
+/** The Solana family: the injected Solana wallet (Phantom, or any `window.solana`). */
+export function sol(options: SolFamilyOptions = {}): WalletFamily {
+  const chain = options.chain ?? "solana:mainnet";
+  const family = defineWalletFamily({
+    id: "sol",
+    label: "Solana",
+    aliases: ["solana"],
+    message: solMessage,
+    driver: () => solanaDriver({ chain }),
+    bridge: { namespace: "solana", driver: (bridge) => solanaBridgeDriver(bridge, { chain }) },
+  });
+  return withHosting(family, { ecosystem: "solana", chainId: chain, solanaChain: chain });
+}

package/src/families/sui.ts

@@ -0,0 +1,17 @@
+import { suiBridgeDriver } from "../bridge/drivers";
+import { defineWalletFamily, type WalletFamily } from "../core/family";
+import { suiDriver } from "../light/drivers";
+import { withHosting } from "./host";
+import { suiMessage } from "./messages";
+
+/** The Sui family: the first Wallet Standard Sui wallet on the page. */
+export function sui(): WalletFamily {
+  const family = defineWalletFamily({
+    id: "sui",
+    label: "Sui",
+    message: suiMessage,
+    driver: () => suiDriver(),
+    bridge: { namespace: "sui", driver: suiBridgeDriver },
+  });
+  return withHosting(family, { ecosystem: "sui", chainId: "sui:mainnet" });
+}

package/src/index.ts

@@ -1,12 +1,15 @@
 // Providers
 export {
   WalletProvider,
+  Web3Provider,
   useWeb3Config,
   defaultChains,
   useWalletBridge,
+  type ConnectorFamily,
   type WalletBridgeContextValue,
   type WalletProviderProps,
   type Web3Config,
+  type Web3ProviderProps,
 } from "./providers";
 
 // Hooks
@@ -61,7 +64,20 @@ export { LockContract, lockAbi, type LockContractProps } from "./examples";
 
 // Re-export useful types from viem/wagmi
 export type { Address, Chain } from "viem";
-export { mainnet, polygon, optimism, arbitrum, base, sepolia } from "wagmi/chains";
+export {
+  mainnet,
+  polygon,
+  optimism,
+  arbitrum,
+  base,
+  sepolia,
+  bsc,
+  baseSepolia,
+  bscTestnet,
+  polygonAmoy,
+  optimismSepolia,
+  arbitrumSepolia,
+} from "wagmi/chains";
 
 // Bridge (Hermes-safe; shared by web + the native WebView host)
 export * from "./bridge";
@@ -81,3 +97,24 @@ export * from "./clients";
 // Core contracts (MPO-385): the family registry, connection driver and store,
 // and the message registry. Chain-SDK free, so Hermes-safe on the native entry.
 export * from "./core";
+
+// The EVM connection driver (MPO-385): wagmi and viem behind the core's
+// ConnectionDriver, the engine the eth family runs on.
+export { wagmiDriver, type WagmiDriverOptions } from "./wagmi";
+
+// The light connection drivers (MPO-385) for families with no wallet SDK:
+// Solana, Sui and Bitcoin over their injected or Wallet Standard wallets.
+export { bitcoinDriver, solanaDriver, suiDriver, type SolanaDriverOptions } from "./light";
+
+// The built-in wallet families (MPO-385) an app hands Web3Provider:
+// `families={[eth(), sol(), gpg()]}`.
+export {
+  btc,
+  eth,
+  gpg,
+  sol,
+  sui,
+  walletFamilies,
+  type EthFamilyOptions,
+  type SolFamilyOptions,
+} from "./families";