@multiplatform.one/web3 7.26.0 → 7.28.0

package/src/core/lightDriver.spec.ts

@@ -0,0 +1,284 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createWallets,
+  describeConnectionDriver,
+  type DriverHarness,
+  type Wallets,
+} from "../../tests/core/driverContract";
+import { deferred } from "../../tests/core/testDriver";
+import { lightDriver, type LightWallet, type LightWalletAdapter } from "./lightDriver";
+
+const phantom = "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV";
+const solflare = "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin";
+const backpack = "DRpbCBMxVnDK7maPM5tGv6MvB3v1sRMC86PZ8okm21hy";
+const glow = "GLoWMgcn3VbyFKiC2FGMgfKxYSyTJS7uKFwKY2CSkq9X";
+
+const signature = (address: string, message: string) => `signed:${address}:${message}`;
+
+/** An adapter over one scripted wallet, the shape SolanaAdapter and friends have. */
+function scriptedAdapter(wallets: Wallets, id: string) {
+  const listeners = new Set<() => void>();
+  const adapter = {
+    address: null as string | null,
+    async connect() {
+      await wallets.answer(id, "prompt");
+      const wallet = wallets.get(id);
+      wallet.authorized = true;
+      wallet.open = true;
+      adapter.address = wallet.address;
+    },
+    async restore() {
+      const wallet = wallets.get(id);
+      if (!wallet.authorized) return false;
+      await wallets.answer(id, "restore");
+      wallet.open = true;
+      adapter.address = wallet.address;
+      return true;
+    },
+    async disconnect() {
+      wallets.get(id).open = false;
+      adapter.address = null;
+    },
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async signMessage(message: string) {
+      if (!adapter.address) throw new Error("not connected");
+      return signature(adapter.address, message);
+    },
+    emit() {
+      for (const listener of listeners) listener();
+    },
+    listeners,
+  } satisfies LightWalletAdapter & Record<string, unknown>;
+  return adapter;
+}
+
+const client = (wallet: LightWallet, account: { address: string; chainId?: string | number }) => ({
+  family: "solana" as const,
+  address: account.address,
+  chainId: account.chainId,
+  capabilities: ["signMessage" as const],
+  signMessage: (message: string) => wallet.adapter.signMessage(message),
+});
+
+function setup() {
+  const wallets = createWallets({ phantom, solflare, backpack });
+  const build = () => {
+    const adapters = {
+      phantom: scriptedAdapter(wallets, "phantom"),
+      solflare: scriptedAdapter(wallets, "solflare"),
+      backpack: scriptedAdapter(wallets, "backpack"),
+    };
+    const list: LightWallet[] = [
+      { id: "phantom", name: "Phantom", adapter: adapters.phantom },
+      { id: "solflare", name: "Solflare", adapter: adapters.solflare },
+      { id: "backpack", name: "Backpack", adapter: adapters.backpack },
+    ];
+    const driver = lightDriver({ wallets: () => list, chainId: "solana:mainnet", client });
+    return { adapters, driver, list };
+  };
+  const { adapters, driver, list } = build();
+  const harness: DriverHarness = {
+    driver,
+    wallets,
+    first: "phantom",
+    second: "solflare",
+    third: "backpack",
+    otherAddress: glow,
+    multiple: true,
+    normalize: (address) => address,
+    switchAccount(id, address) {
+      wallets.get(id).address = address;
+      const adapter = adapters[id as keyof typeof adapters];
+      adapter.address = address;
+      adapter.emit();
+    },
+    walletDisconnect(id) {
+      wallets.get(id).open = false;
+      const adapter = adapters[id as keyof typeof adapters];
+      adapter.address = null;
+      adapter.emit();
+    },
+    remount: () => build().driver,
+    verify: (address, message, signed) => signed === signature(address, message),
+  };
+  return { ...harness, adapters, list };
+}
+
+describeConnectionDriver("lightDriver", setup);
+
+describe("lightDriver", () => {
+  it("keeps the first adapter it saw for a wallet, however often discovery runs", async () => {
+    const wallets = createWallets({ phantom });
+    const discover = vi.fn((): LightWallet[] => [
+      { id: "phantom", name: "Phantom", adapter: scriptedAdapter(wallets, "phantom") },
+    ]);
+    const driver = lightDriver({ wallets: discover, client });
+    const account = await driver.connect("phantom");
+    driver.connectors();
+    driver.connectors();
+    expect(discover.mock.calls.length).toBeGreaterThan(1);
+    const signer = await driver.client?.(driver.getState());
+    expect(await signer?.signMessage("hi")).toBe(signature(account.address, "hi"));
+  });
+
+  it("lists a wallet that announces itself late, and tells watchConnectors", () => {
+    const wallets = createWallets({ phantom, solflare });
+    let list: LightWallet[] = [
+      { id: "phantom", name: "Phantom", adapter: scriptedAdapter(wallets, "phantom") },
+    ];
+    const announce = new Set<() => void>();
+    const driver = lightDriver({
+      wallets: () => list,
+      watchWallets: (listener) => {
+        announce.add(listener);
+        return () => announce.delete(listener);
+      },
+    });
+    const listener = vi.fn();
+    const unwatch = driver.watchConnectors?.(listener);
+    const before = driver.connectors();
+    expect(driver.connectors()).toBe(before);
+    list = [
+      ...list,
+      {
+        id: "solflare",
+        name: "Solflare",
+        icon: "data:icon",
+        adapter: scriptedAdapter(wallets, "solflare"),
+      },
+    ];
+    for (const announced of announce) announced();
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(driver.connectors()).toEqual([
+      { id: "phantom", name: "Phantom" },
+      { id: "solflare", name: "Solflare", icon: "data:icon" },
+    ]);
+    unwatch?.();
+    expect(announce.size).toBe(0);
+  });
+
+  it("without watchWallets has no watchConnectors, so the store reads the list each time", () => {
+    const { driver } = setup();
+    expect(driver.watchConnectors).toBeUndefined();
+  });
+
+  it("a wallet that cannot restore silently restores only while it still holds an address", async () => {
+    const wallets = createWallets({ phantom });
+    const { restore: _, ...adapter } = scriptedAdapter(wallets, "phantom");
+    const driver = lightDriver({
+      wallets: () => [{ id: "phantom", name: "Phantom", adapter }],
+    });
+    expect(await driver.reconnect("phantom")).toBeNull();
+    adapter.address = phantom;
+    expect(await driver.reconnect("phantom")).toEqual({ address: phantom });
+    expect(driver.getState()).toMatchObject({ status: "connected", connectorId: "phantom" });
+    expect(wallets.get("phantom").prompts).toBe(0);
+  });
+
+  it("a restore that fails rejects, so the store keeps the record for later", async () => {
+    const { driver, adapters } = setup();
+    vi.spyOn(adapters.phantom, "restore").mockRejectedValueOnce(new Error("wallet locked"));
+    await expect(driver.reconnect("phantom")).rejects.toThrow(/locked/);
+    expect(driver.getState()).toMatchObject({ status: "disconnected", account: null });
+  });
+
+  it("a connect that resolves with no address rejects and opens nothing", async () => {
+    const { driver, adapters } = setup();
+    vi.spyOn(adapters.phantom, "connect").mockResolvedValueOnce(undefined);
+    await expect(driver.connect("phantom")).rejects.toThrow(/no account/);
+    expect(driver.getState().account).toBeNull();
+    expect(adapters.phantom.listeners.size).toBe(0);
+  });
+
+  it("reports connecting and reconnecting while an attempt with nothing open is out", async () => {
+    const { driver, wallets } = setup();
+    const listener = vi.fn();
+    driver.subscribe(listener);
+    const gate = wallets.hold("phantom");
+    const connecting = driver.connect("phantom");
+    await vi.waitFor(() => expect(driver.getState().status).toBe("connecting"));
+    gate.approve();
+    await connecting;
+    await driver.disconnect();
+    wallets.get("phantom").authorized = true;
+    const held = wallets.hold("phantom");
+    const restoring = driver.reconnect("phantom");
+    await vi.waitFor(() => expect(driver.getState().status).toBe("reconnecting"));
+    held.approve();
+    await restoring;
+    expect(driver.getState().status).toBe("connected");
+    expect(listener.mock.calls.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it("listens to a wallet's events only while it is open", async () => {
+    const { driver, adapters } = setup();
+    await driver.connect("phantom");
+    expect(adapters.phantom.listeners.size).toBe(1);
+    await driver.disconnect("phantom");
+    expect(adapters.phantom.listeners.size).toBe(0);
+    await driver.connect("phantom");
+    adapters.phantom.address = null;
+    adapters.phantom.emit();
+    expect(adapters.phantom.listeners.size).toBe(0);
+  });
+
+  it("names each account's chain, by wallet when chainId is a function", async () => {
+    const wallets = createWallets({ phantom, solflare });
+    const driver = lightDriver({
+      wallets: () => [
+        { id: "phantom", name: "Phantom", adapter: scriptedAdapter(wallets, "phantom") },
+        { id: "solflare", name: "Solflare", adapter: scriptedAdapter(wallets, "solflare") },
+      ],
+      chainId: (wallet) => (wallet.id === "phantom" ? "solana:devnet" : undefined),
+    });
+    expect(await driver.connect("phantom")).toEqual({ address: phantom, chainId: "solana:devnet" });
+    expect(await driver.connect("solflare")).toEqual({ address: solflare });
+  });
+
+  it("keeps one state object while nothing changes, and a client only while connected", async () => {
+    const { driver } = setup();
+    expect(await driver.client?.(driver.getState())).toBeNull();
+    await driver.connect("phantom");
+    expect(driver.getState()).toBe(driver.getState());
+    const noClient = lightDriver({ wallets: () => [] });
+    expect(noClient.client?.(driver.getState()) ?? null).toBeNull();
+  });
+
+  it("closing everything asks every wallet, whatever one of them does", async () => {
+    const { driver, adapters, wallets } = setup();
+    await driver.connect("phantom");
+    await driver.connect("solflare");
+    vi.spyOn(adapters.phantom, "disconnect").mockReturnValueOnce(new Promise(() => {}));
+    void driver.disconnect();
+    expect(driver.getState().account).toBeNull();
+    await vi.waitFor(() => expect(wallets.get("solflare").open).toBe(false));
+  });
+
+  it("an adapter whose disconnect throws synchronously does not stop the others closing", async () => {
+    const { driver, adapters, wallets } = setup();
+    await driver.connect("phantom");
+    await driver.connect("solflare");
+    vi.spyOn(adapters.phantom, "disconnect").mockImplementationOnce(() => {
+      throw new Error("sync boom");
+    });
+    await expect(driver.disconnect()).rejects.toThrow(/sync boom/);
+    expect(wallets.get("solflare").open).toBe(false);
+  });
+
+  it("a disconnect that the wallet fails still lets go, then reports the failure", async () => {
+    const { driver, adapters, wallets } = setup();
+    await driver.connect("phantom");
+    const closing = deferred<void>();
+    vi.spyOn(adapters.phantom, "disconnect").mockReturnValueOnce(closing.promise);
+    const done = driver.disconnect();
+    expect(driver.getState()).toMatchObject({ status: "disconnected", account: null });
+    closing.reject(new Error("extension gone"));
+    await expect(done).rejects.toThrow(/extension gone/);
+    expect(wallets.get("phantom").open).toBe(true);
+  });
+});

package/src/core/lightDriver.ts

@@ -0,0 +1,235 @@
+import type { ChainClient } from "../clients/types";
+import type { ConnectionDriver, DriverAccount, DriverState, WalletConnector } from "./types";
+
+/**
+ * One wallet as the light driver drives it: an injected provider or a Wallet
+ * Standard wallet behind a small adapter. The mpo adapters (SolanaAdapter,
+ * SuiAdapter, BitcoinAdapter) fit as they are.
+ */
+export interface LightWalletAdapter {
+  /** The connected address, or null. */
+  readonly address: string | null;
+  /** Prompts the user and leaves `address` set. Rejects when they decline. */
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  /**
+   * Connects without prompting. Resolves false when the wallet no longer
+   * trusts the page; rejects when it cannot tell yet. Without it, a restore
+   * succeeds only while the adapter still holds an address.
+   */
+  restore?(): Promise<boolean>;
+  /** Wallet-side account switches and disconnects; the driver re-reads `address` on each. */
+  subscribe?(listener: () => void): () => void;
+  signMessage(message: string): Promise<string>;
+}
+
+export interface LightWallet {
+  readonly id: string;
+  readonly name: string;
+  readonly icon?: string;
+  readonly adapter: LightWalletAdapter;
+}
+
+export interface LightDriverOptions {
+  /**
+   * The wallets present now, read for every connector list. The first
+   * adapter seen for an id is the one the driver keeps, so discovery may
+   * build fresh adapters each time.
+   */
+  wallets: () => readonly LightWallet[];
+  /** Called when a wallet announces itself after the page loaded. */
+  watchWallets?: (listener: () => void) => () => void;
+  /** The chain an account is on: `solana:mainnet`, `sui:mainnet`, `bitcoin`. */
+  chainId?: string | number | ((wallet: LightWallet) => string | number | undefined);
+  /** The per-chain client for a connected wallet. */
+  client?: (
+    wallet: LightWallet,
+    account: DriverAccount,
+  ) => ChainClient | null | Promise<ChainClient | null>;
+}
+
+interface Open {
+  readonly wallet: LightWallet;
+  account: DriverAccount;
+  readonly unsubscribe: () => void;
+}
+
+const sameConnector = (a: WalletConnector, b: WalletConnector) =>
+  a.id === b.id && a.name === b.name && a.icon === b.icon;
+
+/**
+ * The connection driver for families that need no wallet SDK: connect,
+ * disconnect, wallet-side events and silent restore over a small adapter per
+ * wallet, several wallets open at once. The connection store remembers which
+ * one to restore. It imports no chain SDK, so a Solana-, Sui- or Bitcoin-only
+ * app ships neither wagmi nor viem.
+ */
+export function lightDriver(options: LightDriverOptions): ConnectionDriver {
+  const kept = new Map<string, LightWallet>();
+  const open = new Map<string, Open>();
+  const listeners = new Set<() => void>();
+  let current: string | null = null;
+  let connecting = 0;
+  let restoring = 0;
+  let snapshot: readonly WalletConnector[] = Object.freeze([]);
+  let state: DriverState = Object.freeze({
+    status: "disconnected",
+    connectorId: null,
+    account: null,
+  });
+
+  const present = (): LightWallet[] =>
+    options.wallets().map((wallet) => {
+      const known = kept.get(wallet.id);
+      if (known) return known;
+      kept.set(wallet.id, wallet);
+      return wallet;
+    });
+
+  const find = (id: string) => kept.get(id) ?? present().find((wallet) => wallet.id === id);
+
+  const chainOf = (wallet: LightWallet) =>
+    typeof options.chainId === "function" ? options.chainId(wallet) : options.chainId;
+
+  const accountOf = (wallet: LightWallet, address: string): DriverAccount => {
+    const chainId = chainOf(wallet);
+    return chainId === undefined ? { address } : { address, chainId };
+  };
+
+  const derive = (): DriverState => {
+    const active = current === null ? undefined : open.get(current);
+    if (active)
+      return { status: "connected", connectorId: active.wallet.id, account: active.account };
+    return {
+      status: restoring > 0 ? "reconnecting" : connecting > 0 ? "connecting" : "disconnected",
+      connectorId: null,
+      account: null,
+    };
+  };
+
+  const notify = () => {
+    const next = derive();
+    if (
+      next.status === state.status &&
+      next.connectorId === state.connectorId &&
+      next.account?.address === state.account?.address &&
+      next.account?.chainId === state.account?.chainId
+    ) {
+      return;
+    }
+    state = Object.freeze(next);
+    for (const listener of listeners) listener();
+  };
+
+  // `open` is kept in the order wallets were last current, so closing the
+  // current one falls back to the one current before it.
+  const close = (id: string) => {
+    const entry = open.get(id);
+    if (!entry) return;
+    entry.unsubscribe();
+    open.delete(id);
+    if (current === id) current = [...open.keys()].pop() ?? null;
+  };
+
+  const follow = (wallet: LightWallet) => () => {
+    const entry = open.get(wallet.id);
+    if (!entry) return;
+    const address = wallet.adapter.address;
+    if (address) entry.account = accountOf(wallet, address);
+    else close(wallet.id);
+    notify();
+  };
+
+  const hold = (wallet: LightWallet): DriverAccount => {
+    const address = wallet.adapter.address;
+    if (!address) throw new Error(`${wallet.name} returned no account`);
+    const existing = open.get(wallet.id);
+    open.delete(wallet.id);
+    open.set(wallet.id, {
+      wallet,
+      account: accountOf(wallet, address),
+      unsubscribe:
+        existing?.unsubscribe ?? wallet.adapter.subscribe?.(follow(wallet)) ?? (() => {}),
+    });
+    current = wallet.id;
+    notify();
+    return (open.get(wallet.id) as Open).account;
+  };
+
+  const driver: ConnectionDriver = {
+    connectors() {
+      const next = present().map((wallet) =>
+        wallet.icon === undefined
+          ? { id: wallet.id, name: wallet.name }
+          : { id: wallet.id, name: wallet.name, icon: wallet.icon },
+      );
+      const unchanged =
+        next.length === snapshot.length &&
+        next.every((connector, index) => {
+          const previous = snapshot[index];
+          return previous !== undefined && sameConnector(connector, previous);
+        });
+      if (!unchanged) snapshot = Object.freeze(next.map((connector) => Object.freeze(connector)));
+      return snapshot;
+    },
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async connect(connectorId) {
+      const wallet = find(connectorId);
+      if (!wallet) throw new Error(`no wallet ${connectorId} on this page`);
+      if (open.has(connectorId)) return hold(wallet);
+      connecting++;
+      notify();
+      try {
+        await wallet.adapter.connect();
+        return hold(wallet);
+      } finally {
+        connecting--;
+        notify();
+      }
+    },
+    async disconnect(connectorId) {
+      const closing = [...open.values()]
+        .map((entry) => entry.wallet)
+        .filter((wallet) => connectorId === undefined || wallet.id === connectorId);
+      for (const wallet of closing) close(wallet.id);
+      notify();
+      const results = await Promise.allSettled(
+        closing.map(async (wallet) => wallet.adapter.disconnect()),
+      );
+      const failed = results.find((result) => result.status === "rejected");
+      if (failed) throw failed.reason;
+    },
+    async reconnect(connectorId) {
+      const wallet = find(connectorId);
+      if (!wallet) throw new Error(`wallet ${connectorId} has not announced itself yet`);
+      if (open.has(connectorId)) return hold(wallet);
+      restoring++;
+      notify();
+      try {
+        const restored = wallet.adapter.restore
+          ? await wallet.adapter.restore()
+          : wallet.adapter.address !== null;
+        return restored && wallet.adapter.address ? hold(wallet) : null;
+      } finally {
+        restoring--;
+        notify();
+      }
+    },
+    client(driverState) {
+      if (!driverState.account || !driverState.connectorId || !options.client) return null;
+      const wallet = kept.get(driverState.connectorId);
+      return wallet ? options.client(wallet, driverState.account) : null;
+    },
+  };
+  if (options.watchWallets) {
+    const watch = options.watchWallets;
+    return { ...driver, watchConnectors: (listener) => watch(listener) };
+  }
+  return driver;
+}

package/src/core/react.ts

@@ -27,8 +27,26 @@ export function useConnectionStore(): ConnectionStore {
   return store;
 }
 
+/** The store under the nearest ConnectionProvider, or null where there is none. */
+export function useOptionalConnectionStore(): ConnectionStore | null {
+  return useContext(ConnectionStoreContext);
+}
+
 /** The active connection: status, family, connector, address, chainId and client. */
 export function useConnection(): ConnectionState {
   const store = useConnectionStore();
   return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }
+
+const unsubscribed = () => () => {};
+const absent = () => null;
+
+/** The active connection, or null where no ConnectionProvider is mounted. */
+export function useOptionalConnection(): ConnectionState | null {
+  const store = useOptionalConnectionStore();
+  return useSyncExternalStore(
+    store ? store.subscribe : unsubscribed,
+    store ? store.getState : absent,
+    store ? store.getState : absent,
+  );
+}