@multiplatform.one/web3 7.24.0 → 7.26.0

package/src/core/store.ts

@@ -0,0 +1,558 @@
+import type { ChainClient } from "../clients/types";
+import { createFamilyRegistry, type FamilyRegistry, type WalletFamily } from "./family";
+import type {
+  ConnectionDriver,
+  ConnectionState,
+  ConnectionStorage,
+  DriverAccount,
+  DriverConnectOptions,
+  DriverState,
+  SavedConnection,
+  WalletConnector,
+} from "./types";
+
+export const defaultConnectionStorageKey = "mpo.web3.connection";
+
+export interface ConnectionStoreOptions {
+  families: readonly WalletFamily[] | FamilyRegistry;
+  /**
+   * Where the last connection is remembered. Defaults to localStorage when the
+   * platform has one; null keeps nothing, so nothing is restored.
+   */
+  storage?: ConnectionStorage | null;
+  storageKey?: string;
+  /**
+   * How long, in milliseconds, a driver's disconnect may take before the store
+   * stops waiting for it. Defaults to 10 seconds. Infinity waits for as long
+   * as the driver takes; a negative value waits for nothing.
+   */
+  closeTimeout?: number;
+}
+
+export interface FamilyConnector {
+  readonly family: string;
+  readonly connector: WalletConnector;
+}
+
+/**
+ * Holds the one active wallet connection across every registered family.
+ * Only the active family's driver is listened to, so a second driver that
+ * reports an account (wagmi restoring on its own, say) changes nothing.
+ */
+export interface ConnectionStore {
+  getState(): ConnectionState;
+  subscribe(listener: () => void): () => void;
+  readonly registry: FamilyRegistry;
+  /**
+   * Every connectable family's connectors, merged in family order. The same
+   * array comes back until the list changes.
+   */
+  connectors(): readonly FamilyConnector[];
+  /** Called when any family's connector list changes. */
+  subscribeConnectors(listener: () => void): () => void;
+  /**
+   * Connects one family's connector, first closing any other connection.
+   * Remembers {family, connectorId} on success.
+   */
+  connect(
+    family: string,
+    connectorId: string,
+    options?: DriverConnectOptions,
+  ): Promise<ConnectionState>;
+  /** Closes the active connection and forgets it. */
+  disconnect(): Promise<void>;
+  /**
+   * Restores the remembered connection through its own driver only. Concurrent
+   * calls share one attempt; no other driver is asked. A disconnect from the
+   * wallet side keeps the record, so a later reconnect() can restore it.
+   */
+  reconnect(): Promise<ConnectionState>;
+  /**
+   * 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
+   * that moment stay open on their drivers for whatever takes over, such as a
+   * store remounted on the same drivers. A late result of an attempt cancelled
+   * before destroy() still closes its own connector unless another store holds
+   * it through the same driver object; a store on a fresh driver over the same
+   * wallet cannot be told apart from this one's leftover.
+   */
+  destroy(): void;
+}
+
+const disconnected: ConnectionState = Object.freeze({
+  status: "disconnected",
+  family: null,
+  connector: null,
+  address: null,
+  chainId: null,
+  client: null,
+});
+
+const superseded = () => new Error("wallet connect superseded");
+
+function browserStorage(): ConnectionStorage | null {
+  try {
+    const storage = (globalThis as { localStorage?: ConnectionStorage }).localStorage;
+    return storage && typeof storage.getItem === "function" ? storage : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseSaved(raw: string | null | undefined): SavedConnection | null {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw) as Partial<SavedConnection> | null;
+    return typeof value?.family === "string" && typeof value.connectorId === "string"
+      ? { family: value.family, connectorId: value.connectorId }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+const sameConnector = (a: WalletConnector, b: WalletConnector) =>
+  a.id === b.id && a.name === b.name && a.icon === b.icon && a.installed === b.installed;
+
+/** What each live store holds on a driver that several stores share. */
+const holdersByDriver = new WeakMap<ConnectionDriver, Set<() => readonly string[]>>();
+
+export function createConnectionStore(options: ConnectionStoreOptions): ConnectionStore {
+  const registry = Array.isArray(options.families)
+    ? createFamilyRegistry(options.families as readonly WalletFamily[])
+    : (options.families as FamilyRegistry);
+  const storage = options.storage === undefined ? browserStorage() : options.storage;
+  const key = options.storageKey ?? defaultConnectionStorageKey;
+  const requestedClose = options.closeTimeout ?? 10_000;
+  const closeTimeout = Number.isNaN(requestedClose) ? 10_000 : Math.max(0, requestedClose);
+  const drivers = new Map<string, ConnectionDriver>();
+  const holders = new Map<ConnectionDriver, () => readonly string[]>();
+  const listeners = new Set<() => void>();
+  const connectorListeners = new Set<() => void>();
+  const connectorWatches = new Map<ConnectionDriver, () => void>();
+  const closing = new Map<ConnectionDriver, Promise<void>>();
+  const inflight = new Map<ConnectionDriver, Map<string, number>>();
+  let state: ConnectionState = disconnected;
+  let active: { driver: ConnectionDriver; connectorId: string; unsubscribe: () => void } | null =
+    null;
+  let pending: { driver: ConnectionDriver; connectorId: string } | null = null;
+  let operation = 0;
+  let clientRequest = 0;
+  let restoring: Promise<ConnectionState> | null = null;
+  let connectorSnapshot: readonly FamilyConnector[] = Object.freeze([]);
+  let destroyed = false;
+  let keptAtDestroy: readonly ({ driver: ConnectionDriver; connectorId: string } | null)[] = [];
+
+  const set = (next: ConnectionState) => {
+    state = next;
+    for (const listener of listeners) listener();
+  };
+
+  const watchConnectors = (driver: ConnectionDriver) => {
+    if (connectorListeners.size === 0 || connectorWatches.has(driver) || !driver.watchConnectors) {
+      return;
+    }
+    connectorWatches.set(
+      driver,
+      driver.watchConnectors(() => {
+        for (const listener of connectorListeners) listener();
+      }),
+    );
+  };
+
+  const unwatchConnectors = () => {
+    for (const unwatch of connectorWatches.values()) unwatch();
+    connectorWatches.clear();
+  };
+
+  const hold = (driver: ConnectionDriver) => {
+    if (destroyed || holders.has(driver)) return;
+    const held = () =>
+      [active, pending].flatMap((entry) => (entry?.driver === driver ? [entry.connectorId] : []));
+    holders.set(driver, held);
+    let all = holdersByDriver.get(driver);
+    if (!all) {
+      all = new Set();
+      holdersByDriver.set(driver, all);
+    }
+    all.add(held);
+  };
+
+  const driverFor = (family: WalletFamily): ConnectionDriver => {
+    if (family.connectionless || !family.driver) {
+      throw new Error(`wallet family ${family.id} is connectionless; it signs without connecting`);
+    }
+    let driver = drivers.get(family.id);
+    if (!driver) {
+      driver = family.driver();
+      drivers.set(family.id, driver);
+      hold(driver);
+    }
+    watchConnectors(driver);
+    return driver;
+  };
+
+  const heldElsewhere = (driver: ConnectionDriver) =>
+    [...(holdersByDriver.get(driver) ?? [])]
+      .filter((held) => held !== holders.get(driver))
+      .flatMap((held) => held());
+
+  const connectorFor = (driver: ConnectionDriver, id: string): WalletConnector =>
+    driver.connectors().find((connector) => connector.id === id) ?? { id, name: id };
+
+  const save = async (value: SavedConnection | null) => {
+    if (!storage) return;
+    try {
+      if (value) await storage.setItem(key, JSON.stringify(value));
+      else await storage.removeItem(key);
+    } catch {
+      // A storage that refuses writes (private mode, quota) only costs the restore.
+    }
+  };
+
+  const load = async (): Promise<SavedConnection | null> => {
+    if (!storage) return null;
+    try {
+      return parseSaved(await storage.getItem(key));
+    } catch {
+      return null;
+    }
+  };
+
+  // Closes run one after another per driver, and a connect or restore on that
+  // driver waits for them: a late close would otherwise drop the new connection.
+  // Each is bounded by closeTimeout, so unless that is Infinity one wallet that
+  // never answers cannot wedge the queue; a close that times out can still land.
+  const closeDriver = (driver: ConnectionDriver, connectorId?: string) => {
+    const previous = closing.get(driver);
+    const run = (async () => {
+      await previous;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const closed = (async () => driver.disconnect(connectorId))().catch(() => {
+        // The wallet may already be gone; the store has let go of it either way.
+      });
+      if (closeTimeout === Number.POSITIVE_INFINITY) await closed;
+      else {
+        await Promise.race([
+          closed,
+          new Promise<void>((resolve) => {
+            timer = setTimeout(resolve, Math.min(closeTimeout, 2_147_483_647));
+          }),
+        ]);
+        clearTimeout(timer);
+      }
+    })();
+    closing.set(driver, run);
+    void run.then(() => {
+      if (closing.get(driver) === run) closing.delete(driver);
+    });
+    return run;
+  };
+
+  const release = () => {
+    active?.unsubscribe();
+    active = null;
+    clientRequest++;
+  };
+
+  const closeActive = async () => {
+    const previous = active;
+    release();
+    if (previous) await closeDriver(previous.driver);
+  };
+
+  /** A connection nobody uses any more: a superseded result, or one left by a failed attempt. */
+  const settleStale = async (
+    driver: ConnectionDriver,
+    connectorId: string,
+    account: DriverAccount | null,
+  ) => {
+    if (!account) return;
+    const inUse = [
+      ...(destroyed ? keptAtDestroy : [active, pending])
+        .filter((entry) => entry?.driver === driver)
+        .map((entry) => entry?.connectorId),
+      ...heldElsewhere(driver),
+    ];
+    if (inUse.includes(connectorId)) return;
+    // After destroy() the driver may serve a remounted store, so only this connector goes.
+    if (inUse.length === 0 && !destroyed) await closeDriver(driver);
+    else await closeDriver(driver, connectorId);
+  };
+
+  const closeOrphan = async (driver: ConnectionDriver, connectorId: string) => {
+    const left = driver.getState();
+    if (!left.account) return;
+    if (destroyed) {
+      if (left.connectorId === connectorId) {
+        await settleStale(driver, connectorId, left.account);
+      }
+    } else if (left.connectorId !== null) {
+      await settleStale(driver, left.connectorId, left.account);
+    } else if (
+      ![active, pending].some((entry) => entry?.driver === driver) &&
+      heldElsewhere(driver).length === 0
+    ) {
+      await closeDriver(driver);
+    }
+  };
+
+  /**
+   * Counts a connect or restore in flight on a driver. While one is, the
+   * driver reporting its connector is that attempt landing, not the user
+   * switching connectors, so the active connection does not follow it.
+   */
+  const track = (driver: ConnectionDriver, connectorId: string) => {
+    let counts = inflight.get(driver);
+    if (!counts) {
+      counts = new Map();
+      inflight.set(driver, counts);
+    }
+    counts.set(connectorId, (counts.get(connectorId) ?? 0) + 1);
+    return () => {
+      const left = (counts.get(connectorId) ?? 1) - 1;
+      if (left > 0) counts.set(connectorId, left);
+      else counts.delete(connectorId);
+    };
+  };
+
+  const clientFor = (driver: ConnectionDriver, driverState: DriverState): ChainClient | null => {
+    const request = ++clientRequest;
+    let result: ChainClient | null | Promise<ChainClient | null>;
+    try {
+      result = driver.client?.(driverState) ?? null;
+    } catch {
+      return null;
+    }
+    if (result === null || typeof (result as Promise<unknown>).then !== "function") {
+      return result as ChainClient | null;
+    }
+    (result as Promise<ChainClient | null>).then(
+      (client) => {
+        if (request === clientRequest && active?.driver === driver && client) {
+          set(Object.freeze({ ...state, client }));
+        }
+      },
+      () => {},
+    );
+    return null;
+  };
+
+  const activate = (
+    family: WalletFamily,
+    driver: ConnectionDriver,
+    connector: WalletConnector,
+    account: DriverAccount,
+  ) => {
+    release();
+    const onChange = () => {
+      if (active?.driver !== driver) return;
+      const driverState = driver.getState();
+      if (!driverState.account) {
+        if (driverState.status === "connecting" || driverState.status === "reconnecting") return;
+        release();
+        operation++;
+        set(disconnected);
+        return;
+      }
+      const connectorId = driverState.connectorId ?? active.connectorId;
+      if (connectorId !== active.connectorId && inflight.get(driver)?.get(connectorId)) return;
+      const chainId = driverState.account.chainId ?? null;
+      if (
+        connectorId === state.connector?.id &&
+        driverState.account.address === state.address &&
+        chainId === state.chainId
+      ) {
+        return;
+      }
+      const nextConnector =
+        connectorId === state.connector?.id && state.connector
+          ? state.connector
+          : connectorFor(driver, connectorId);
+      if (connectorId !== active.connectorId) {
+        active.connectorId = connectorId;
+        void save({ family: family.id, connectorId });
+      }
+      set(
+        Object.freeze({
+          status: "connected",
+          family: family.id,
+          connector: nextConnector,
+          address: driverState.account.address,
+          chainId,
+          client: clientFor(driver, { ...driverState, connectorId }),
+        }),
+      );
+    };
+    active = { driver, connectorId: connector.id, unsubscribe: driver.subscribe(onChange) };
+    set(
+      Object.freeze({
+        status: "connected",
+        family: family.id,
+        connector,
+        address: account.address,
+        chainId: account.chainId ?? null,
+        client: clientFor(driver, { status: "connected", connectorId: connector.id, account }),
+      }),
+    );
+  };
+
+  return {
+    registry,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    connectors() {
+      const next: FamilyConnector[] = [];
+      for (const family of registry.families) {
+        if (family.connectionless) continue;
+        for (const connector of driverFor(family).connectors()) {
+          next.push({ family: family.id, connector });
+        }
+      }
+      const unchanged =
+        next.length === connectorSnapshot.length &&
+        next.every((entry, index) => {
+          const previous = connectorSnapshot[index];
+          return (
+            previous !== undefined &&
+            entry.family === previous.family &&
+            sameConnector(entry.connector, previous.connector)
+          );
+        });
+      if (!unchanged) connectorSnapshot = Object.freeze(next.map((entry) => Object.freeze(entry)));
+      return connectorSnapshot;
+    },
+    subscribeConnectors(listener) {
+      connectorListeners.add(listener);
+      for (const family of registry.families) if (!family.connectionless) driverFor(family);
+      return () => {
+        connectorListeners.delete(listener);
+        if (connectorListeners.size === 0) unwatchConnectors();
+      };
+    },
+    async connect(familyName, connectorId, connectOptions) {
+      if (destroyed) throw new Error("this connection store was destroyed");
+      const family = registry.require(familyName);
+      const driver = driverFor(family);
+      const connector = connectorFor(driver, connectorId);
+      const current = ++operation;
+      restoring = null;
+      pending = { driver, connectorId };
+      const closingActive = closeActive();
+      set(Object.freeze({ ...disconnected, status: "connecting", family: family.id, connector }));
+      await closingActive;
+      if (current === operation) await save(null);
+      await closing.get(driver);
+      const untrack = track(driver, connectorId);
+      let account: DriverAccount;
+      let asked = false;
+      try {
+        try {
+          if (current !== operation) throw superseded();
+          asked = true;
+          account = await driver.connect(connectorId, 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);
+          throw error;
+        }
+        if (current !== operation) {
+          await settleStale(driver, connectorId, account);
+          throw superseded();
+        }
+      } finally {
+        untrack();
+      }
+      pending = null;
+      activate(family, driver, connector, account);
+      await save({ family: family.id, connectorId });
+      return state;
+    },
+    async disconnect() {
+      operation++;
+      restoring = null;
+      pending = null;
+      const closingActive = closeActive();
+      set(disconnected);
+      await save(null);
+      await closingActive;
+    },
+    reconnect() {
+      if (restoring) return restoring;
+      if (destroyed || state.status !== "disconnected") return Promise.resolve(state);
+      const current = ++operation;
+      const attempt = (async (): Promise<ConnectionState> => {
+        const saved = await load();
+        if (current !== operation || !saved) return state;
+        const family = registry.get(saved.family);
+        if (!family || family.connectionless || !family.driver) return state;
+        const driver = driverFor(family);
+        const connector = connectorFor(driver, saved.connectorId);
+        pending = { driver, connectorId: saved.connectorId };
+        set(
+          Object.freeze({ ...disconnected, status: "reconnecting", family: family.id, connector }),
+        );
+        await closing.get(driver);
+        const untrack = track(driver, saved.connectorId);
+        let account: DriverAccount | null;
+        try {
+          try {
+            if (current !== operation) return state;
+            account = await driver.reconnect(saved.connectorId);
+          } catch {
+            if (current === operation) {
+              pending = null;
+              set(disconnected);
+            }
+            await closeOrphan(driver, saved.connectorId);
+            return state;
+          }
+          if (current !== operation) {
+            await settleStale(driver, saved.connectorId, account);
+            return state;
+          }
+        } finally {
+          untrack();
+        }
+        pending = null;
+        if (!account) {
+          set(disconnected);
+          await save(null);
+          await closeOrphan(driver, saved.connectorId);
+          return state;
+        }
+        activate(family, driver, connector, account);
+        return state;
+      })();
+      restoring = attempt;
+      const settled = () => {
+        if (restoring === attempt) restoring = null;
+      };
+      void attempt.then(settled, settled);
+      return attempt;
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      keptAtDestroy = [active, pending];
+      for (const [driver, held] of holders) holdersByDriver.get(driver)?.delete(held);
+      operation++;
+      restoring = null;
+      pending = null;
+      release();
+      unwatchConnectors();
+      connectorListeners.clear();
+      listeners.clear();
+    },
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,96 @@
+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;
+}
+
+/**
+ * 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. 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/index.ts

@@ -3,6 +3,8 @@ export {
   WalletProvider,
   useWeb3Config,
   defaultChains,
+  useWalletBridge,
+  type WalletBridgeContextValue,
   type WalletProviderProps,
   type Web3Config,
 } from "./providers";
@@ -75,3 +77,7 @@ 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";