@multiplatform.one/web3 7.25.0 → 7.28.0

package/src/core/types.ts

@@ -0,0 +1,110 @@
+import type { ChainClient } from "../clients/types";
+
+/** Where a connection is: none, being opened by the user, being restored silently, or open. */
+export type ConnectionStatus = "disconnected" | "connecting" | "reconnecting" | "connected";
+
+/** One wallet a driver can connect, as the connect list shows it. */
+export interface WalletConnector {
+  readonly id: string;
+  readonly name: string;
+  readonly icon?: string;
+  /** The wallet is present here now: an injected extension, an installed app. */
+  readonly installed?: boolean;
+}
+
+/** The account a driver connected. */
+export interface DriverAccount {
+  /** Chain-native address. */
+  readonly address: string;
+  /** EVM numeric chain id, or a CAIP-2 style id (`solana:mainnet`). */
+  readonly chainId?: number | string;
+}
+
+export interface DriverState {
+  readonly status: ConnectionStatus;
+  readonly connectorId: string | null;
+  readonly account: DriverAccount | null;
+}
+
+export interface DriverConnectOptions {
+  /** Called with a pairing URI when the connector hands off to another app or device. */
+  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
+ * the one active connection; a driver never decides which family is active.
+ */
+export interface ConnectionDriver {
+  /** The connectors this driver can drive, in list order. */
+  connectors(): readonly WalletConnector[];
+  /**
+   * Called when the connector list changes: an EIP-6963 or Wallet Standard
+   * wallet announcing itself late. Without it the list is read once per call.
+   */
+  watchConnectors?(listener: () => void): () => void;
+  getState(): DriverState;
+  /** Called on every state change: account, chain, connector, or a disconnect from the wallet side. */
+  subscribe(listener: () => void): () => void;
+  /**
+   * 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
+   * connector's, doing nothing when it is not open.
+   */
+  disconnect(connectorId?: string): Promise<void>;
+  /**
+   * Restores a connector the user authorised before, without prompting.
+   * Resolves null only when the wallet says it is no longer authorised, which
+   * makes the store forget it. A connector that is not available yet (an
+   * EIP-6963 wallet still to announce itself) rejects instead, and the store
+   * keeps it for the next restore.
+   */
+  reconnect(connectorId: string): Promise<DriverAccount | null>;
+  /**
+   * The per-chain client for the current account, or null. The store asks
+   * again only when the connector, address or chain changes.
+   */
+  client?(state: DriverState): ChainClient | null | Promise<ChainClient | null>;
+}
+
+/** What `useConnection()` returns: the single active connection across every family. */
+export interface ConnectionState {
+  readonly status: ConnectionStatus;
+  readonly family: string | null;
+  readonly connector: WalletConnector | null;
+  readonly address: string | null;
+  readonly chainId: number | string | null;
+  readonly client: ChainClient | null;
+}
+
+/**
+ * Where the store remembers the last connection. localStorage, wagmi's storage
+ * and React Native AsyncStorage all fit.
+ */
+export interface ConnectionStorage {
+  getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+/** The persisted record: which family and connector to restore, nothing else. */
+export interface SavedConnection {
+  readonly family: string;
+  readonly connectorId: string;
+}

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";
@@ -77,3 +93,28 @@ export * from "./clients";
 // verify pulls @noble/curves + bs58 (ESM-only) which Hermes rejects in the RN
 // bundle ("import statement requires module mode"). It's server/web-side only —
 // import it directly from "@multiplatform.one/web3/siws" (or the source path).
+
+// 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";