@multiplatform.one/web3 7.25.0 → 7.28.0

package/src/clients/evmRead.ts

@@ -0,0 +1,140 @@
+import {
+  createPublicClient,
+  erc20Abi,
+  http,
+  type Address,
+  type Chain,
+  type Hash,
+  type PublicClient,
+} from "viem";
+import { chainTransports, resolveChains, type Web3ChainConfig } from "../providers/walletConfig";
+import { ReadOnlyClientError, type ChainClient } from "./types";
+
+/** The ERC-20 reads, with the owner always named: a read-only client has no account. */
+export interface Erc20ReadActions {
+  balanceOf(token: Address, owner: Address): Promise<bigint>;
+  allowance(token: Address, spender: Address, owner: Address): Promise<bigint>;
+  decimals(token: Address): Promise<number>;
+}
+
+/**
+ * Reads one EVM chain with no wallet: prices, sale state, a quote or a balance
+ * for a visitor who has not connected, or a chain other than the connected
+ * one. Signing and sending reject with ReadOnlyClientError without a request.
+ */
+export interface EvmReadClient extends ChainClient<"evm"> {
+  readonly address: null;
+  readonly chainId: number;
+  readonly chain: Chain;
+  /** Reads, simulation, logs and receipts. */
+  readonly publicClient: PublicClient;
+  readonly readContract: PublicClient["readContract"];
+  readonly erc20: Erc20ReadActions;
+  /** The chain explorer's page for `hash`, when the chain names an explorer. */
+  explorerTxUrl(hash: Hash): string | undefined;
+  signMessage(message: string): Promise<never>;
+  sendTransaction(parameters: unknown): Promise<never>;
+  writeContract(parameters: unknown): Promise<never>;
+}
+
+export interface EvmReadClientConfig {
+  chain: Chain;
+  /** Reads go here. Defaults to an http client on `rpcUrl`, else the chain's default RPC. */
+  publicClient?: PublicClient;
+  /** Used only when `publicClient` is not given. */
+  rpcUrl?: string;
+}
+
+/** A read-only mpo EVM client for one chain. */
+export function evmReadClient(config: EvmReadClientConfig): EvmReadClient {
+  const { chain } = config;
+  const publicClient =
+    config.publicClient ??
+    (createPublicClient({ chain, transport: http(config.rpcUrl) }) as PublicClient);
+  if (publicClient.chain && publicClient.chain.id !== chain.id) {
+    throw new Error(
+      `evmReadClient: the public client reads chain ${publicClient.chain.id}, not chain ${chain.id}`,
+    );
+  }
+  const explorer = chain.blockExplorers?.default.url.replace(/\/+$/, "");
+  const refuse = (method: string) => async (): Promise<never> => {
+    throw new ReadOnlyClientError("evm", method);
+  };
+  return {
+    family: "evm",
+    address: null,
+    chainId: chain.id,
+    chain,
+    capabilities: [],
+    publicClient,
+    readContract: publicClient.readContract,
+    erc20: {
+      balanceOf: (token, owner) =>
+        publicClient.readContract({
+          address: token,
+          abi: erc20Abi,
+          functionName: "balanceOf",
+          args: [owner],
+        }),
+      allowance: (token, spender, owner) =>
+        publicClient.readContract({
+          address: token,
+          abi: erc20Abi,
+          functionName: "allowance",
+          args: [owner, spender],
+        }),
+      decimals: (token) =>
+        publicClient.readContract({ address: token, abi: erc20Abi, functionName: "decimals" }),
+    },
+    explorerTxUrl: (hash) => (explorer ? `${explorer}/tx/${hash}` : undefined),
+    signMessage: refuse("signMessage"),
+    sendTransaction: refuse("sendTransaction"),
+    writeContract: refuse("writeContract"),
+  };
+}
+
+export interface EvmReadClients {
+  /** The chains a WalletProvider with the same config offers, its default first. */
+  readonly chains: readonly [Chain, ...Chain[]];
+  /**
+   * The read client for `chainId`, or for the default chain. One per chain,
+   * made on first use. Throws for a chain the config does not offer.
+   */
+  get(chainId?: number): EvmReadClient;
+}
+
+/**
+ * Read clients for the chains of a Web3Config, outside React: the chain list
+ * WalletProvider resolves (testnet filter, localnet dev chain first) and the
+ * transports it reads them over. Inside a WalletProvider, useEvmReadClient
+ * reads through the provider's own wagmi clients instead.
+ */
+export function evmReadClients(config: Web3ChainConfig): EvmReadClients {
+  const chains = resolveChains(config);
+  const transports = chainTransports(chains);
+  const made = new Map<number, EvmReadClient>();
+  return {
+    chains,
+    get(chainId = chains[0].id) {
+      const cached = made.get(chainId);
+      if (cached) return cached;
+      const chain = chains.find((candidate) => candidate.id === chainId);
+      if (!chain) {
+        throw new Error(
+          `evmReadClients: chain ${chainId} is not configured; the config offers [${chains
+            .map((c) => c.id)
+            .join(", ")}]`,
+        );
+      }
+      const client = evmReadClient({
+        chain,
+        publicClient: createPublicClient({
+          chain,
+          transport: transports[chain.id],
+        }) as PublicClient,
+      });
+      made.set(chainId, client);
+      return client;
+    },
+  };
+}

package/src/clients/hooks.spec.tsx

@@ -6,6 +6,10 @@ import { getBase58Decoder } from "@solana/kit";
 import { createPublicClient, createWalletClient, custom } from "viem";
 import { mainnet } from "viem/chains";
 import { Web3ConfigContext, type Web3Config } from "../providers/walletConfig";
+import { testDriver } from "../../tests/core/testDriver";
+import { defineWalletFamily } from "../core/family";
+import { ConnectionProvider } from "../core/react";
+import { createConnectionStore } from "../core/store";
 
 const { mockUseAccount, mockUseWalletClient, mockUsePublicClient } = vi.hoisted(() => ({
   mockUseAccount: vi.fn(),
@@ -111,3 +115,57 @@ describe("useSuiClient / useBitcoinClient", () => {
     expect(renderHook(() => useBitcoinClient()).result.current?.chainId).toBe("bitcoin");
   });
 });
+
+describe("the family client hooks under a connection store", () => {
+  const message = { header: "wants you to sign in:", statement: null, chainId: null };
+
+  async function connected(family: "eth" | "sui" | "btc", address: string) {
+    const ecosystem = { eth: "evm", sui: "sui", btc: "bitcoin" }[family] as
+      | "evm"
+      | "sui"
+      | "bitcoin";
+    const driver = testDriver(ecosystem, [{ id: "wallet", name: "Wallet" }], {
+      wallet: { address, chainId: family === "eth" ? 1 : `${ecosystem}:mainnet` },
+    });
+    const store = createConnectionStore({
+      storage: null,
+      families: [defineWalletFamily({ id: family, label: family, message, driver: () => driver })],
+    });
+    await store.connect(family, "wallet");
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <ConnectionProvider store={store}>{children}</ConnectionProvider>
+    );
+    return { store, wrapper };
+  }
+
+  it("useSuiClient and useBitcoinClient read the store's connection, not wagmi's", async () => {
+    mockUseAccount.mockReturnValue({ connector: shim("bitcoin", "bc1q"), address: "bc1q" });
+    const { store, wrapper } = await connected("sui", "0xsui");
+    expect(renderHook(() => useSuiClient(), { wrapper }).result.current).toBe(
+      store.getState().client,
+    );
+    expect(renderHook(() => useBitcoinClient(), { wrapper }).result.current).toBeUndefined();
+  });
+
+  it("useEvmClient is the store's EVM client, and undefined while another family is active", async () => {
+    mockUseAccount.mockReturnValue({ connector: { id: "metaMask" }, chainId: 1 });
+    mockUseWalletClient.mockReturnValue({ data: walletClient });
+    const evm = await connected("eth", evmAddress);
+    expect(renderHook(() => useEvmClient(), { wrapper: evm.wrapper }).result.current).toBe(
+      evm.store.getState().client,
+    );
+    const sui = await connected("sui", "0xsui");
+    expect(
+      renderHook(() => useEvmClient(), { wrapper: sui.wrapper }).result.current,
+    ).toBeUndefined();
+  });
+
+  it("useEvmClient for a named chain still asks wagmi for that chain", async () => {
+    mockUseAccount.mockReturnValue({ connector: { id: "metaMask" }, chainId: 1 });
+    mockUseWalletClient.mockReturnValue({ data: walletClient });
+    const { wrapper } = await connected("eth", evmAddress);
+    const { result } = renderHook(() => useEvmClient({ chainId: 1 }), { wrapper });
+    expect(result.current?.family).toBe("evm");
+    expect(mockUseWalletClient).toHaveBeenCalledWith(expect.objectContaining({ chainId: 1 }));
+  });
+});

package/src/clients/hooks.ts

@@ -1,51 +1,110 @@
 import { useMemo } from "react";
-import { useAccount, usePublicClient, useWalletClient } from "wagmi";
+import { useAccount, useChainId, useConfig, usePublicClient, useWalletClient } from "wagmi";
 import { isSyntheticChainId } from "../connectkit/connectors/syntheticChains";
+import { useOptionalConnection } from "../core/react";
 import { bitcoinClient, type BitcoinClient } from "./bitcoin";
 import { connectorAdapter } from "./adapter";
 import { evmClient, type EvmClient, type EvmWalletClient } from "./evm";
+import { evmReadClient, type EvmReadClient } from "./evmRead";
 import { suiClient, type SuiClient } from "./sui";
 import type { PublicClient } from "viem";
 
 /**
  * The connected EVM wallet as a viem WalletClient plus a PublicClient for reads,
  * wrapped in the mpo EVM client. Undefined until an EVM wallet is connected, and
- * while a non-EVM wallet holds the connection.
+ * while a non-EVM wallet holds the connection. Under a connection store
+ * (Web3Provider) it is the store's EVM client; for a named `chainId` it asks
+ * wagmi for a client on that chain.
  */
 export function useEvmClient(parameters: { chainId?: number } = {}): EvmClient | undefined {
+  const connection = useOptionalConnection();
+  const fromStore = connection !== null && parameters.chainId === undefined;
   const { connector, chainId: connectedChainId } = useAccount();
-  const evm = !!connector && !connectorAdapter(connector) && !isSyntheticChainId(connectedChainId);
+  const evm =
+    !!connector &&
+    !connectorAdapter(connector) &&
+    !isSyntheticChainId(connectedChainId) &&
+    (connection === null || connection.family === "eth");
   const { data: walletClient } = useWalletClient({
     chainId: parameters.chainId,
-    query: { enabled: evm },
+    query: { enabled: evm && !fromStore },
   });
   const publicClient = usePublicClient({ chainId: walletClient?.chain.id ?? parameters.chainId });
+  return useMemo(() => {
+    if (fromStore) {
+      return connection.family === "eth"
+        ? ((connection.client as EvmClient | null) ?? undefined)
+        : undefined;
+    }
+    return evm && walletClient && publicClient
+      ? evmClient({
+          walletClient: walletClient as unknown as EvmWalletClient,
+          publicClient: publicClient as PublicClient,
+        })
+      : undefined;
+  }, [fromStore, connection, evm, walletClient, publicClient]);
+}
+
+/**
+ * A read-only EVM client over WalletProvider's own public client for
+ * `chainId`. It needs no wallet, so a page can read a chain before one
+ * connects. With no `chainId` it follows wagmi's current chain: the connected
+ * EVM wallet's, else the last one used, and the default chain while a non-EVM
+ * wallet holds the connection. Pass `chainId` to read a contract on a fixed
+ * chain. Undefined for a chain the provider does not offer.
+ */
+export function useEvmReadClient(parameters: { chainId?: number } = {}): EvmReadClient | undefined {
+  const config = useConfig();
+  const currentChainId = useChainId();
+  // A Solana, Sui or Bitcoin wallet moves wagmi onto a synthetic chain that
+  // has no transport, where usePublicClient returns undefined.
+  const chainId =
+    parameters.chainId ??
+    (isSyntheticChainId(currentChainId)
+      ? config.chains.find((chain) => !isSyntheticChainId(chain.id))?.id
+      : undefined);
+  const publicClient = usePublicClient({ chainId });
   return useMemo(
     () =>
-      evm && walletClient && publicClient
-        ? evmClient({
-            walletClient: walletClient as unknown as EvmWalletClient,
-            publicClient: publicClient as PublicClient,
-          })
+      publicClient
+        ? evmReadClient({ chain: publicClient.chain, publicClient: publicClient as PublicClient })
         : undefined,
-    [evm, walletClient, publicClient],
+    [publicClient],
   );
 }
 
-/** The connected Sui wallet (message signing only for now). */
+/**
+ * The connected Sui wallet (message signing only for now): the connection
+ * store's when one is mounted, else wagmi's shim connector's.
+ */
 export function useSuiClient(): SuiClient | undefined {
+  const connection = useOptionalConnection();
   const { connector, address } = useAccount();
   return useMemo(() => {
+    if (connection) {
+      return connection.family === "sui"
+        ? ((connection.client as SuiClient | null) ?? undefined)
+        : undefined;
+    }
     const adapter = connectorAdapter(connector, "sui");
     return adapter?.address ? suiClient(adapter) : undefined;
-  }, [connector, address]);
+  }, [connection, connector, address]);
 }
 
-/** The connected Bitcoin wallet (message signing only for now). */
+/**
+ * The connected Bitcoin wallet (message signing only for now): the
+ * connection store's when one is mounted, else wagmi's shim connector's.
+ */
 export function useBitcoinClient(): BitcoinClient | undefined {
+  const connection = useOptionalConnection();
   const { connector, address } = useAccount();
   return useMemo(() => {
+    if (connection) {
+      return connection.family === "btc"
+        ? ((connection.client as BitcoinClient | null) ?? undefined)
+        : undefined;
+    }
     const adapter = connectorAdapter(connector, "bitcoin");
     return adapter?.address ? bitcoinClient(adapter) : undefined;
-  }, [connector, address]);
+  }, [connection, connector, address]);
 }

package/src/clients/index.ts

@@ -5,6 +5,7 @@
 // native signs Solana through the WebView bridge, so @solana/kit must never
 // enter that bundle, and sign-in (solanaMessageClient) does not need it.
 export {
+  ReadOnlyClientError,
   UnsupportedClientMethodError,
   type ChainClient,
   type ClientCapability,
@@ -27,6 +28,15 @@ export {
   type EvmWriteContractParameters,
   type TxErrorKind,
 } from "./evm";
+export {
+  evmReadClient,
+  evmReadClients,
+  type Erc20ReadActions,
+  type EvmReadClient,
+  type EvmReadClientConfig,
+  type EvmReadClients,
+} from "./evmRead";
+export type { Web3ChainConfig } from "../providers/walletConfig";
 export { suiClient, type SuiClient } from "./sui";
 export { bitcoinClient, type BitcoinClient } from "./bitcoin";
 export {
@@ -45,4 +55,4 @@ export {
   type SolanaCluster,
   type SolanaMessageClient,
 } from "./solanaMessage";
-export { useBitcoinClient, useEvmClient, useSuiClient } from "./hooks";
+export { useBitcoinClient, useEvmClient, useEvmReadClient, useSuiClient } from "./hooks";

package/src/clients/types.ts

@@ -19,7 +19,10 @@ export type ClientCapability =
  */
 export interface ChainClient<F extends ClientFamily = ClientFamily> {
   readonly family: F;
-  /** Chain-native address. Null for GPG, whose identity arrives with the signature. */
+  /**
+   * Chain-native address. Null for GPG, whose identity arrives with the
+   * signature, and for a read-only client, which has no account.
+   */
   readonly address: string | null;
   /** EVM numeric chain id, or a CAIP-2 style id (`solana:mainnet`, `sui:mainnet`, `bitcoin`). */
   readonly chainId?: number | string;
@@ -38,3 +41,14 @@ export class UnsupportedClientMethodError extends Error {
     this.name = "UnsupportedClientMethodError";
   }
 }
+
+/**
+ * A signing or sending method called on a read-only client, such as
+ * evmReadClient's. Nothing reached a wallet and nothing was sent.
+ */
+export class ReadOnlyClientError extends UnsupportedClientMethodError {
+  constructor(family: ClientFamily, method: string) {
+    super(family, method, "read-only client, connect a wallet to sign or send");
+    this.name = "ReadOnlyClientError";
+  }
+}

package/src/clients/useEvmReadClient.spec.tsx

@@ -0,0 +1,93 @@
+// @vitest-environment happy-dom
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { WagmiProvider, createConfig, createStorage } from "wagmi";
+import { connect, disconnect } from "wagmi/actions";
+import { mock } from "wagmi/connectors";
+import { mainnet, polygon } from "wagmi/chains";
+import { solanaChain } from "../connectkit/connectors/syntheticChains";
+import { chainTransports } from "../providers/walletConfig";
+import { useEvmReadClient } from "./hooks";
+
+const account = "0x1111111111111111111111111111111111111111";
+
+/**
+ * The wagmi config WalletProvider builds: its chains, then the synthetic
+ * non-EVM chains getDefaultConfig appends, with transports for the real ones
+ * only.
+ */
+function walletProviderConfig() {
+  const map = new Map<string, string>();
+  return createConfig({
+    chains: [mainnet, polygon, solanaChain],
+    connectors: [mock({ accounts: [account], features: {} })],
+    transports: chainTransports([mainnet, polygon]),
+    storage: createStorage({
+      storage: {
+        getItem: (key) => map.get(key) ?? null,
+        setItem: (key, value) => void map.set(key, value),
+        removeItem: (key) => void map.delete(key),
+      },
+    }),
+  });
+}
+
+const rendered: { unmount(): void }[] = [];
+afterEach(() => {
+  for (const r of rendered.splice(0)) r.unmount();
+});
+
+function render(config: ReturnType<typeof walletProviderConfig>, chainId?: number) {
+  const queryClient = new QueryClient();
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <WagmiProvider config={config}>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </WagmiProvider>
+  );
+  const hook = renderHook(() => useEvmReadClient(chainId ? { chainId } : {}), { wrapper });
+  rendered.push(hook);
+  return hook;
+}
+
+describe("useEvmReadClient in a WalletProvider's wagmi config", () => {
+  it("reads the default chain before any wallet connects", () => {
+    const { result } = render(walletProviderConfig());
+    expect(result.current?.chainId).toBe(mainnet.id);
+    expect(result.current?.address).toBeNull();
+    expect(result.current?.publicClient.chain?.id).toBe(mainnet.id);
+  });
+
+  it("follows the connected EVM wallet's chain, and keeps the chain it names", async () => {
+    const config = walletProviderConfig();
+    const current = render(config);
+    const named = render(config, mainnet.id);
+    await act(() => connect(config, { connector: config.connectors[0], chainId: polygon.id }));
+    expect(current.result.current?.chainId).toBe(polygon.id);
+    expect(named.result.current?.chainId).toBe(mainnet.id);
+    await act(() => disconnect(config));
+    expect(current.result.current?.chainId).toBe(polygon.id);
+  });
+
+  it("reads the default chain while a non-EVM wallet holds a synthetic chain", () => {
+    const config = walletProviderConfig();
+    const { result } = render(config);
+    act(() => config.setState((state) => ({ ...state, chainId: solanaChain.id })));
+    expect(result.current?.chainId).toBe(mainnet.id);
+    expect(render(config, polygon.id).result.current?.chainId).toBe(polygon.id);
+  });
+
+  it("is undefined for a chain the config does not offer, or one with no RPC", () => {
+    const config = walletProviderConfig();
+    expect(render(config, 999).result.current).toBeUndefined();
+    expect(render(config, solanaChain.id).result.current).toBeUndefined();
+  });
+
+  it("keeps one client while the chain stays put", () => {
+    const { result, rerender } = render(walletProviderConfig());
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/src/connectkit/adapters/BitcoinAdapter.ts

@@ -19,7 +19,10 @@ import type { SignInMessageOptions, WalletAdapter, WalletAddress } from "./types
 
 interface UnisatProvider {
   requestAccounts(): Promise<string[]>;
+  getAccounts?(): Promise<string[]>;
   signMessage(message: string, type?: "ecdsa" | "bip322-simple"): Promise<string>;
+  on?(event: "accountsChanged", listener: (accounts: string[]) => void): void;
+  removeListener?(event: "accountsChanged", listener: (accounts: string[]) => void): void;
 }
 
 interface PhantomBtcAccount {
@@ -30,8 +33,18 @@ interface PhantomBtcAccount {
 interface PhantomBtcProvider {
   requestAccounts(): Promise<PhantomBtcAccount[]>;
   signMessage(address: string, message: Uint8Array): Promise<{ signature: Uint8Array }>;
+  on?(event: "accountsChanged", listener: (accounts: PhantomBtcAccount[]) => void): void;
+  off?(event: "accountsChanged", listener: (accounts: PhantomBtcAccount[]) => void): void;
+  removeListener?(
+    event: "accountsChanged",
+    listener: (accounts: PhantomBtcAccount[]) => void,
+  ): void;
 }
 
+/** BIP-322 P2WPKH only: the native-segwit "payment" account (bc1q…). */
+const paymentAccount = (accounts: readonly PhantomBtcAccount[] | undefined) =>
+  accounts?.find((a) => a.purpose === "payment" || a.addressType === "p2wpkh") ?? accounts?.[0];
+
 function bytesToBase64(bytes: Uint8Array): string {
   let s = "";
   for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
@@ -65,10 +78,7 @@ export class BitcoinAdapter implements WalletAdapter {
     }
     if (w.phantom?.bitcoin) {
       const phantom = w.phantom.bitcoin;
-      const accounts = await phantom.requestAccounts();
-      // BIP-322 P2WPKH only: pick the native-segwit "payment" account (bc1q…).
-      const payment =
-        accounts.find((a) => a.purpose === "payment" || a.addressType === "p2wpkh") ?? accounts[0];
+      const payment = paymentAccount(await phantom.requestAccounts());
       if (!payment) throw new Error("Bitcoin wallet returned no accounts");
       this.kind = "phantom";
       this.phantom = phantom;
@@ -79,6 +89,56 @@ export class BitcoinAdapter implements WalletAdapter {
     throw new Error("No Bitcoin wallet found. Install a Bitcoin wallet (Unisat, OKX, Phantom).");
   }
 
+  /**
+   * Reconnects without a prompt through UniSat's or OKX's `getAccounts`.
+   * Resolves false when the wallet no longer trusts the page, and for
+   * Phantom, whose Bitcoin provider has no silent path. Throws when no
+   * Bitcoin wallet is injected yet.
+   */
+  async restore(): Promise<boolean> {
+    const w = window as unknown as {
+      unisat?: UnisatProvider;
+      okxwallet?: { bitcoin?: UnisatProvider };
+      phantom?: { bitcoin?: PhantomBtcProvider };
+    };
+    const unisat = w.unisat ?? w.okxwallet?.bitcoin;
+    if (unisat) {
+      const accounts = (await unisat.getAccounts?.()) ?? [];
+      if (!accounts.length) return false;
+      this.kind = "unisat";
+      this.unisat = unisat;
+      this.address = accounts[0];
+      this.isConnected = true;
+      return true;
+    }
+    if (w.phantom?.bitcoin) return false;
+    throw new Error("No Bitcoin wallet found yet.");
+  }
+
+  /** The wallet's account switches; an empty list means it disconnected. */
+  subscribe(listener: () => void): () => void {
+    const update = (address: string | null) => {
+      this.address = address;
+      this.isConnected = address !== null;
+      listener();
+    };
+    const unisat = this.kind === "unisat" ? this.unisat : null;
+    if (unisat?.on) {
+      const onAccounts = (accounts: string[]) => update(accounts[0] ?? null);
+      unisat.on("accountsChanged", onAccounts);
+      return () => unisat.removeListener?.("accountsChanged", onAccounts);
+    }
+    const phantom = this.kind === "phantom" ? this.phantom : null;
+    if (phantom?.on) {
+      const onAccounts = (accounts: PhantomBtcAccount[]) =>
+        update(paymentAccount(accounts)?.address ?? null);
+      phantom.on("accountsChanged", onAccounts);
+      return () =>
+        (phantom.off ?? phantom.removeListener)?.call(phantom, "accountsChanged", onAccounts);
+    }
+    return () => {};
+  }
+
   async disconnect(): Promise<void> {
     this.kind = null;
     this.unisat = null;

package/src/connectkit/adapters/SolanaAdapter.ts

@@ -37,12 +37,17 @@ function base58encode(bytes: Uint8Array): string {
   return str;
 }
 
+type SolanaListener = (publicKey?: { toString(): string } | null) => void;
+
 interface InjectedSolana {
   isPhantom?: boolean;
   publicKey?: { toString(): string } | null;
   connect(opts?: { onlyIfTrusted?: boolean }): Promise<{ publicKey: { toString(): string } }>;
   disconnect(): Promise<void>;
   signMessage(message: Uint8Array, display?: "utf8" | "hex"): Promise<{ signature: Uint8Array }>;
+  on?(event: "accountChanged" | "disconnect", listener: SolanaListener): void;
+  off?(event: "accountChanged" | "disconnect", listener: SolanaListener): void;
+  removeListener?(event: "accountChanged" | "disconnect", listener: SolanaListener): void;
 }
 
 function getInjectedProvider(): InjectedSolana {
@@ -72,6 +77,50 @@ export class SolanaAdapter implements WalletAdapter {
     this.isConnected = true;
   }
 
+  /**
+   * Reconnects without a prompt (`onlyIfTrusted`). Resolves false when the
+   * wallet refuses because it no longer trusts the page (4001); throws on
+   * any other failure, and when no wallet is injected yet.
+   */
+  async restore(): Promise<boolean> {
+    const provider = getInjectedProvider();
+    try {
+      const { publicKey } = await provider.connect({ onlyIfTrusted: true });
+      this.address = publicKey.toString();
+      this.isConnected = true;
+      return true;
+    } catch (error) {
+      if ((error as { code?: unknown } | null)?.code === 4001) return false;
+      throw error;
+    }
+  }
+
+  /**
+   * The wallet's account switches and disconnects. Phantom reports a null
+   * account when the user switches to one this page has not connected, so the
+   * page must connect again; the adapter treats it as a disconnect.
+   */
+  subscribe(listener: () => void): () => void {
+    const provider = getInjectedProvider();
+    const onAccount: SolanaListener = (publicKey) => {
+      this.address = publicKey ? publicKey.toString() : null;
+      this.isConnected = this.address !== null;
+      listener();
+    };
+    const onDisconnect: SolanaListener = () => {
+      this.address = null;
+      this.isConnected = false;
+      listener();
+    };
+    provider.on?.("accountChanged", onAccount);
+    provider.on?.("disconnect", onDisconnect);
+    return () => {
+      const off = (provider.off ?? provider.removeListener)?.bind(provider);
+      off?.("accountChanged", onAccount);
+      off?.("disconnect", onDisconnect);
+    };
+  }
+
   async disconnect(): Promise<void> {
     try {
       await getInjectedProvider().disconnect();