@multiplatform.one/web3 7.26.0 → 7.28.1

package/docs/bridge-protocol.md

@@ -77,7 +77,12 @@ The React Native host in this package is looser than this section asks:
 react-native-webview reports the sending frame's URL but not whether it is
 the top frame, so it accepts same-origin frames, and on an Android WebView
 without `WEB_MESSAGE_LISTENER` it sees the top frame's URL for every frame.
-The origin check in the delivery script still holds there.
+The origin check in the delivery script still holds there. Navigations are
+the same on Android: react-native-webview leaves `isTopFrame` out of
+`onShouldStartLoadWithRequest`, or hardcodes it to true on its fallback path
+(`TopShouldStartLoadWithRequestEvent.kt`), so every navigation Android asks
+about counts as the top frame and the sub-frame rule in section 5 never runs
+there. A sub-frame navigation to another web origin goes to the OS.
 
 **Android (Kotlin).** Receive page messages with
 `WebViewCompat.addWebMessageListener(webView, "ReactNativeWebView", setOf(pageOrigin), listener)`,
@@ -194,7 +199,8 @@ Event:
    it answers `-32601`.
 4. On a reload the page sends `ready` again. Requests in flight when the page
    went away never get an answer: fail them on the host (a reload, a crash,
-   `onRenderProcessGone` / `webViewWebContentProcessDidTerminate`).
+   `onRenderProcessGone` / `webViewWebContentProcessDidTerminate`), and
+   close anything showing the page, since the reloaded page starts closed.
 5. When the app returns to the foreground (typically back from a wallet app)
    the host sends `sys.resync` so the page re-reports account state.
 
@@ -233,10 +239,17 @@ tokens, and a foreign page would receive them. Android does not ask
 `shouldOverrideUrlLoading` about a POST (a form with `target=_top`), so also
 watch the top frame start loading (`onPageStarted` /
 `didStartProvisionalNavigation`): a document on another origin means the page
-is gone. Fail what is in flight and deliver nothing until the next
-`sys.ready`, then load the page's URL again (not a reload, which would reload
-the foreign document), twice at most until the page announces itself. Sub-frame loads are the page's business; allow them
-unless they are wallet links.
+is gone. Fail what is in flight, deliver nothing until the next
+`sys.ready`, and close anything showing the page: the page that comes back
+has none of its old state. Then load the page's URL again (not a reload,
+which would reload the foreign document). Count one reload per foreign
+document: until the page's own URL starts loading, a further foreign report
+is the same document (Android reports a pushState or a client redirect
+again). Twice at most until the page announces itself; after that stop
+loading it, drop the foreign document, fail every request at once with
+`-33002`, and try again only on a user action such as the app returning to
+the foreground. Sub-frame loads
+are the page's business; allow them unless they are wallet links.
 
 New windows (`window.open`, `target=_blank`; `onCreateWindow` /
 `createWebViewWith`) never open in the app: wallet links and `http`/`https`
@@ -274,6 +287,14 @@ redirect, whose `code` is the host's. MetaMask Connect needs only the
 
 `evm` errors are whatever the wallet's EIP-1193 provider threw, with its code.
 
+The host raises two more codes to its own callers when the page cannot
+answer. They never cross the wire.
+
+| code     | meaning                                                                                  |
+| -------- | ---------------------------------------------------------------------------------------- |
+| `-33001` | the page went away (a reload, a crash, a foreign document) before it answered; retry     |
+| `-33002` | the host stopped loading the page back (section 5); requests fail at once until it tries |
+
 ## 7. Namespaces
 
 ### `sys`
@@ -315,26 +336,32 @@ Events: `accountsChanged` (array of addresses), `chainChanged` (hex chain id),
 
 | method                | params                         | result                                        |
 | --------------------- | ------------------------------ | --------------------------------------------- |
+| `account`             | none                           | `{ "publicKey": base58 \| null }`             |
 | `connect`             | none                           | `{ "publicKey": base58 }`                     |
 | `disconnect`          | none                           | `null`                                        |
 | `signMessage`         | `{ "message": base64 }`        | `{ "signature": base64 }` (ed25519, 64 bytes) |
 | `signTransaction`     | `{ "transaction": base64 }`    | `{ "transaction": base64 }`                   |
 | `signAllTransactions` | `{ "transactions": [base64] }` | `{ "transactions": [base64] }`                |
 
-Transactions are serialized legacy or versioned transactions. Event:
-`accountChanged` with `{ "publicKey": base58 | null }`.
+`account` never prompts: it answers the connected wallet's key, or reconnects
+one that already trusts the page, or answers null. A page older than this
+method answers it with an error. Transactions are serialized legacy or
+versioned transactions. Event: `accountChanged` with
+`{ "publicKey": base58 | null }`.
 
 ### `sui`
 
-| method        | params                  | result                    |
-| ------------- | ----------------------- | ------------------------- |
-| `connect`     | none                    | `{ "address": "0x…" }`    |
-| `disconnect`  | none                    | `null`                    |
-| `signMessage` | `{ "message": string }` | `{ "signature": base64 }` |
+| method        | params                  | result                         |
+| ------------- | ----------------------- | ------------------------------ |
+| `account`     | none                    | `{ "address": "0x…" \| null }` |
+| `connect`     | none                    | `{ "address": "0x…" }`         |
+| `disconnect`  | none                    | `null`                         |
+| `signMessage` | `{ "message": string }` | `{ "signature": base64 }`      |
 
 `message` is UTF-8 text, signed as a Sui personal message. `signature` is
 Sui's serialized signature (flag, signature, public key), the form the
-Keycloak Sui verifier takes. `signMessage` connects first when needed. Event:
+Keycloak Sui verifier takes. `signMessage` connects first when needed, and
+`account` never prompts, as on `solana`. Event:
 `accountChanged` with `{ "address": string | null }`.
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/web3",
-  "version": "7.26.0",
+  "version": "7.28.1",
   "description": "Web3 wallet integration for multiplatform.one ecosystem with ConnectKit and wagmi",
   "keywords": [
     "connectkit",
@@ -54,6 +54,12 @@
       "require": "./dist/cjs/index.native.js",
       "default": "./dist/esm/index.native.js"
     },
+    "./web": {
+      "source": "./src/web.ts",
+      "types": "./types/web.d.ts",
+      "import": "./dist/esm/web.mjs",
+      "require": "./dist/cjs/web.cjs"
+    },
     "./bridge": {
       "source": "./src/bridge/core.ts",
       "react-native": "./src/bridge/core.ts",
@@ -107,10 +113,10 @@
   "dependencies": {
     "@aave/account": "^0.2.0",
     "@metamask/connect-evm": "^2.1.1",
-    "@multiplatform.one/connectkit": "7.26.0",
-    "@multiplatform.one/gpg": "7.26.0",
-    "@multiplatform.one/platform": "7.26.0",
-    "@multiplatform.one/theme": "7.26.0",
+    "@multiplatform.one/connectkit": "7.28.1",
+    "@multiplatform.one/gpg": "7.28.1",
+    "@multiplatform.one/platform": "7.28.1",
+    "@multiplatform.one/theme": "7.28.1",
     "@noble/curves": "^1.9.7",
     "@solana/kit": "^8.3.0",
     "@solana/wallet-adapter-base": "^0.9.27",
@@ -134,7 +140,7 @@
     "wagmi": "^3.7.1"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "7.26.0",
+    "@multiplatform.one/config": "7.28.1",
     "@tamagui/build": "2.7.6",
     "@tanstack/react-query": "^5.100.7",
     "@testing-library/jest-dom": "^6.9.1",
@@ -174,6 +180,7 @@
     "build:webview": "vite build --config webview/vite.config.ts && mv -f assets/index.html assets/webview.html && node scripts/verify-no-walletconnect.mjs assets/webview.html",
     "build:mock-wallet": "vite build --config webview-mock-wallet/vite.config.ts && mv -f assets/index.html assets/mock-wallet.html",
     "test:iife": "vite build --config keycloak-login/vite.config.ts && node scripts/verify-no-walletconnect.mjs dist/keycloak/login.iife.js && vitest run --config keycloak-login/vitest.config.mjs",
+    "test:web-entry": "vitest run --config web-entry/vitest.config.mjs",
     "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html"
   }
 }

package/src/bridge/base58.spec.ts

@@ -0,0 +1,18 @@
+import bs58 from "bs58";
+import { describe, expect, it } from "vitest";
+import { bytesToBase58 } from "./base58";
+
+describe("bytesToBase58", () => {
+  it("matches bs58 on keys, signatures, leading zeros and the empty input", () => {
+    const samples = [
+      new Uint8Array([]),
+      new Uint8Array([0]),
+      new Uint8Array([0, 0, 1, 2, 255]),
+      new Uint8Array(32).fill(255),
+      ...Array.from({ length: 50 }, (_, n) =>
+        crypto.getRandomValues(new Uint8Array(n % 2 ? 64 : 32)),
+      ),
+    ];
+    for (const bytes of samples) expect(bytesToBase58(bytes)).toBe(bs58.encode(bytes));
+  });
+});

package/src/bridge/base58.ts

@@ -0,0 +1,25 @@
+// Pure-JS base58 (the Bitcoin alphabet Solana uses) for the native side, where
+// bs58's ESM-only build does not load under Hermes.
+
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+export function bytesToBase58(bytes: Uint8Array): string {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros += 1;
+  const digits: number[] = [];
+  for (let i = zeros; i < bytes.length; i += 1) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j += 1) {
+      carry += digits[j] << 8;
+      digits[j] = carry % 58;
+      carry = Math.floor(carry / 58);
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = Math.floor(carry / 58);
+    }
+  }
+  let out = "1".repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i -= 1) out += ALPHABET[digits[i]];
+  return out;
+}

package/src/bridge/core.ts

@@ -11,6 +11,7 @@ export { bytesToBase64, base64ToBytes } from "./base64";
 export { SolanaBridge } from "./SolanaBridge";
 export { SuiBridge } from "./SuiBridge";
 export { GpgBridge, type GpgPendingRequest } from "./GpgBridge";
+export { solanaBridgeDriver, suiBridgeDriver, type SolanaBridgeDriverOptions } from "./drivers";
 export {
   AuthBridge,
   type AuthBridgeOptions,
@@ -28,6 +29,7 @@ export {
 export {
   buildInjectScript,
   createNativeBridge,
+  NativeBridgeErrorCode,
   type NativeBridge,
   type NativeBridgeOptions,
 } from "./nativeHost";

package/src/bridge/drivers.spec.ts

@@ -0,0 +1,283 @@
+import bs58 from "bs58";
+import { describe, expect, it } from "vitest";
+import {
+  createWallets,
+  describeConnectionDriver,
+  type DriverHarness,
+  type Wallets,
+} from "../../tests/core/driverContract";
+import { registerSolanaHandler, type SolanaByteSigner } from "../../webview/handlers/solana";
+import { registerSuiHandler, type SuiMessageSigner } from "../../webview/handlers/sui";
+import { createMockSolanaSigner } from "../../webview/wiring/mockSolanaSigner";
+import { createMockSuiSigner } from "../../webview/wiring/mockSuiSigner";
+import { solanaMessageClient } from "../clients/solanaMessage";
+import { suiClient } from "../clients/sui";
+import { lightDriver, type LightWallet } from "../core/lightDriver";
+import { verifySiwsSignature } from "../siws/verify";
+import { BridgeClient } from "./BridgeClient";
+import { BridgeHost } from "./BridgeHost";
+import {
+  solanaBridgeDriver,
+  solanaBridgeWallet,
+  suiBridgeDriver,
+  suiBridgeWallet,
+} from "./drivers";
+import { createMemoryTransportPair } from "./transport";
+
+const utf8 = (text: string) => new TextEncoder().encode(text);
+const signed = (address: string, message: string) => `signed:${address}:${message}`;
+
+/** The page side of one scripted wallet: what the hosted page's signer does for it. */
+function pageWallet(wallets: Wallets, id: string) {
+  let listener: ((address: string | null) => void) | null = null;
+  const wallet = () => wallets.get(id);
+  return {
+    current: () => (wallet().open ? wallet().address : null),
+    async connect() {
+      await wallets.answer(id, "prompt");
+      wallet().authorized = true;
+      wallet().open = true;
+      return wallet().address;
+    },
+    async restore() {
+      if (wallet().open) return wallet().address;
+      if (!wallet().authorized) return null;
+      await wallets.answer(id, "restore");
+      wallet().open = true;
+      return wallet().address;
+    },
+    async disconnect() {
+      wallet().open = false;
+    },
+    onAccountChanged(next: (address: string | null) => void) {
+      listener = next;
+      return () => {
+        listener = null;
+      };
+    },
+    emit: (address: string | null) => listener?.(address),
+  };
+}
+
+function solanaPage(wallets: Wallets, id: string, host: BridgeHost) {
+  const page = pageWallet(wallets, id);
+  const signer: SolanaByteSigner = {
+    getPublicKey: page.current,
+    connect: async () => ({ publicKey: await page.connect() }),
+    restore: page.restore,
+    disconnect: page.disconnect,
+    async signMessage(message) {
+      const address = page.current();
+      if (!address) throw new Error("not connected");
+      return utf8(signed(address, new TextDecoder().decode(message)));
+    },
+    signTransaction: async () => Promise.reject(new Error("unsupported")),
+    signAllTransactions: async () => Promise.reject(new Error("unsupported")),
+    onAccountChanged: page.onAccountChanged,
+  };
+  registerSolanaHandler(host, signer);
+  return page;
+}
+
+function suiPage(wallets: Wallets, id: string, host: BridgeHost) {
+  const page = pageWallet(wallets, id);
+  const signer: SuiMessageSigner = {
+    getAddress: page.current,
+    connect: async () => ({ address: await page.connect() }),
+    restore: page.restore,
+    disconnect: page.disconnect,
+    async signMessage(message) {
+      const address = page.current();
+      if (!address) throw new Error("not connected");
+      return signed(address, message);
+    },
+    onAccountChanged: page.onAccountChanged,
+  };
+  registerSuiHandler(host, signer);
+  return page;
+}
+
+/** A page per wallet, each on its own bridge, so one light driver drives three bridge wallets. */
+function harness(family: "solana" | "sui") {
+  const addresses =
+    family === "solana"
+      ? {
+          phantom: "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
+          solflare: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+          backpack: "DRpbCBMxVnDK7maPM5tGv6MvB3v1sRMC86PZ8okm21hy",
+        }
+      : {
+          phantom: `0x${"a1".repeat(32)}`,
+          solflare: `0x${"b2".repeat(32)}`,
+          backpack: `0x${"c3".repeat(32)}`,
+        };
+  const other =
+    family === "solana" ? "GLoWMgcn3VbyFKiC2FGMgfKxYSyTJS7uKFwKY2CSkq9X" : `0x${"d4".repeat(32)}`;
+  const wallets = createWallets(addresses);
+  const ids = Object.keys(addresses);
+  const pages = new Map<string, ReturnType<typeof pageWallet>>();
+  const clients = new Map<string, BridgeClient>();
+  for (const id of ids) {
+    const { a, b } = createMemoryTransportPair();
+    const host = new BridgeHost(b);
+    pages.set(id, family === "solana" ? solanaPage(wallets, id, host) : suiPage(wallets, id, host));
+    clients.set(id, new BridgeClient(a));
+  }
+  const build = () => {
+    const list: LightWallet[] = ids.map((id) =>
+      family === "solana"
+        ? solanaBridgeWallet(clients.get(id)!, { id, name: id })
+        : suiBridgeWallet(clients.get(id)!, { id, name: id }),
+    );
+    return lightDriver({
+      wallets: () => list,
+      chainId: family === "solana" ? "solana:mainnet" : "sui:mainnet",
+      client: (wallet) =>
+        family === "solana" ? solanaMessageClient(wallet.adapter) : suiClient(wallet.adapter),
+    });
+  };
+  const result: DriverHarness = {
+    driver: build(),
+    wallets,
+    first: "phantom",
+    second: "solflare",
+    third: "backpack",
+    otherAddress: other,
+    multiple: true,
+    normalize: (address) => address,
+    switchAccount(id, address) {
+      wallets.get(id).address = address;
+      pages.get(id)!.emit(address);
+    },
+    walletDisconnect(id) {
+      wallets.get(id).open = false;
+      pages.get(id)!.emit(null);
+    },
+    remount: build,
+    verify: (address, message, signature) =>
+      family === "solana"
+        ? signature === bs58.encode(utf8(signed(address, message)))
+        : signature === signed(address, message),
+  };
+  return result;
+}
+
+describeConnectionDriver("the Solana bridge wallet", () => harness("solana"));
+describeConnectionDriver("the Sui bridge wallet", () => harness("sui"));
+
+function page() {
+  const { a, b } = createMemoryTransportPair();
+  return { client: new BridgeClient(a), host: new BridgeHost(b) };
+}
+
+describe("solanaBridgeDriver", () => {
+  it("connects the page's Solana wallet and signs a message the SIWS verifier accepts", async () => {
+    const { client, host } = page();
+    registerSolanaHandler(host, createMockSolanaSigner());
+    const driver = solanaBridgeDriver(client, { chain: "solana:devnet" });
+    expect(driver.connectors()).toEqual([{ id: "webViewSolana", name: "Solana Wallet" }]);
+
+    const account = await driver.connect("webViewSolana");
+    expect(account.chainId).toBe("solana:devnet");
+    const solana = await driver.client!(driver.getState());
+    const message = "app.example.com wants you to sign in with your Solana account:\n…";
+    const signature = await solana!.signMessage(message);
+
+    expect(verifySiwsSignature(message, signature, account.address)).toBe(true);
+  });
+
+  it("a page with no account method cannot tell, so a restore rejects and the store keeps it", async () => {
+    const { client, host } = page();
+    registerSolanaHandler(host, createMockSolanaSigner());
+    const older = {
+      request: async (ns: string, method: string, params?: unknown) => {
+        if (method === "account") throw new Error("unknown solana method: account");
+        return client.request(ns as "solana", method, params);
+      },
+      on: client.on.bind(client),
+    };
+    await expect(solanaBridgeDriver(older).reconnect("webViewSolana")).rejects.toThrow(
+      /unknown solana method/,
+    );
+  });
+});
+
+describe("a page reload", () => {
+  it.each(["solana", "sui"] as const)(
+    "%s: the new page's account replaces the one the old page connected",
+    async (family) => {
+      const { client, host } = page();
+      const wallets = createWallets({
+        w:
+          family === "solana"
+            ? "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"
+            : `0x${"ab".repeat(32)}`,
+      });
+      (family === "solana" ? solanaPage : suiPage)(wallets, "w", host);
+      const driver = (family === "solana" ? solanaBridgeDriver : suiBridgeDriver)(client);
+      const id = family === "solana" ? "webViewSolana" : "webViewSui";
+      await driver.connect(id);
+      expect(driver.getState().status).toBe("connected");
+
+      // The WebView reloads: the new document holds no wallet session, the
+      // wallet will not restore it silently, and the page announces itself.
+      wallets.get("w").open = false;
+      wallets.get("w").authorized = false;
+      host.ready();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(driver.getState()).toMatchObject({ status: "disconnected", account: null });
+    },
+  );
+});
+
+describe("a slow account answer", () => {
+  it("does not touch a connection opened after it was asked, nor a newer account", async () => {
+    const { client, host } = page();
+    const X = `0x${"a1".repeat(32)}`;
+    const Y = `0x${"b2".repeat(32)}`;
+    const answers: ((value: unknown) => void)[] = [];
+    host.register("sui", async (method) => {
+      if (method === "connect") return { address: X };
+      if (method === "disconnect") return null;
+      if (method === "account") return new Promise((resolve) => answers.push(resolve));
+      throw new Error(method);
+    });
+    const driver = suiBridgeDriver(client);
+    await driver.connect("webViewSui");
+
+    // The page reloads and is slow to answer; the user reconnects meanwhile.
+    host.ready();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await driver.disconnect();
+    await driver.connect("webViewSui");
+    answers.shift()!({ address: null });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(driver.getState()).toMatchObject({ status: "connected", account: { address: X } });
+
+    // A newer accountChanged wins over an older account answer.
+    host.ready();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    host.emit("sui", "accountChanged", { address: Y });
+    answers.shift()!({ address: X });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(driver.getState()).toMatchObject({ account: { address: Y } });
+  });
+});
+
+describe("suiBridgeDriver", () => {
+  it("connects the page's Sui wallet and signs through it", async () => {
+    const { client, host } = page();
+    registerSuiHandler(host, createMockSuiSigner());
+    const driver = suiBridgeDriver(client);
+    expect(driver.connectors()).toEqual([{ id: "webViewSui", name: "Sui Wallet" }]);
+
+    const account = await driver.connect("webViewSui");
+    expect(account).toMatchObject({
+      address: expect.stringMatching(/^0x[0-9a-f]{64}$/),
+      chainId: "sui:mainnet",
+    });
+    const sui = await driver.client!(driver.getState());
+    await expect(sui!.signMessage("hello")).resolves.toMatch(/^[A-Za-z0-9+/]+=*$/);
+  });
+});

package/src/bridge/drivers.ts

@@ -0,0 +1,155 @@
+import { solanaMessageClient, type SolanaChain } from "../clients/solanaMessage";
+import { suiClient } from "../clients/sui";
+import type { BridgeRequester } from "../core/family";
+import { lightDriver, type LightWallet, type LightWalletAdapter } from "../core/lightDriver";
+import type { ConnectionDriver } from "../core/types";
+import { base64ToBytes, bytesToBase64 } from "./base64";
+import { bytesToBase58 } from "./base58";
+
+/** How one bridge namespace names its account and carries a signature. */
+interface BridgeWalletSpec {
+  readonly namespace: string;
+  /** The field `connect`, `account` and `accountChanged` carry the address in. */
+  readonly key: string;
+  sign(bridge: BridgeRequester, message: string): Promise<string>;
+}
+
+export interface BridgeWalletOptions {
+  readonly id: string;
+  readonly name: string;
+}
+
+/**
+ * The hosted page's wallet on one bridge namespace, as the light driver drives
+ * a wallet. It reads the account from `connect`, `account` and the page's
+ * `accountChanged` events, and asks `account` again when a reloaded page
+ * announces itself, since the new document may hold no session or another.
+ */
+function bridgeWallet(
+  bridge: BridgeRequester,
+  spec: BridgeWalletSpec,
+  { id, name }: BridgeWalletOptions,
+): LightWallet {
+  const read = (value: unknown): string | null => {
+    const address = (value as Record<string, unknown> | null | undefined)?.[spec.key];
+    return typeof address === "string" && address ? address : null;
+  };
+  const adapter: LightWalletAdapter & { address: string | null } = {
+    address: null,
+    async connect() {
+      const address = read(await bridge.request(spec.namespace, "connect"));
+      if (!address) throw new Error(`${name} connected no account`);
+      adapter.address = address;
+    },
+    async disconnect() {
+      adapter.address = null;
+      await bridge.request(spec.namespace, "disconnect");
+    },
+    // A page older than the account method answers it with an error, which
+    // the store reads as "cannot tell yet" and keeps the connection to restore.
+    async restore() {
+      adapter.address = read(await bridge.request(spec.namespace, "account"));
+      return adapter.address !== null;
+    },
+    subscribe(listener) {
+      // An answer to `account` counts only while this connection is open and
+      // nothing newer has said which account it is.
+      let live = true;
+      let latest = 0;
+      const off = bridge.on((ns, method, params) => {
+        if (ns === spec.namespace && method === "accountChanged") {
+          latest += 1;
+          adapter.address = read(params);
+          listener();
+        } else if (ns === "sys" && method === "ready") {
+          const asked = ++latest;
+          bridge.request(spec.namespace, "account").then(
+            (answer) => {
+              if (!live || asked !== latest) return;
+              adapter.address = read(answer);
+              listener();
+            },
+            // A page older than the account method: its own events have to say.
+            () => undefined,
+          );
+        }
+      });
+      return () => {
+        live = false;
+        off();
+      };
+    },
+    signMessage: (message) => spec.sign(bridge, message),
+  };
+  return { id, name, adapter };
+}
+
+const solana: BridgeWalletSpec = {
+  namespace: "solana",
+  key: "publicKey",
+  async sign(bridge, message) {
+    const answer = (await bridge.request("solana", "signMessage", {
+      message: bytesToBase64(new TextEncoder().encode(message)),
+    })) as { signature: string };
+    return bytesToBase58(base64ToBytes(answer.signature));
+  },
+};
+
+const sui: BridgeWalletSpec = {
+  namespace: "sui",
+  key: "address",
+  async sign(bridge, message) {
+    const answer = (await bridge.request("sui", "signMessage", { message })) as {
+      signature: string;
+    };
+    return answer.signature;
+  },
+};
+
+export interface SolanaBridgeDriverOptions {
+  /** The cluster accounts are on. Defaults to `solana:mainnet`. */
+  chain?: SolanaChain;
+}
+
+/**
+ * The hosted page's Solana wallet, driven from a React Native app across the
+ * bridge's `solana` namespace. Signatures come back base58, as on web.
+ */
+export function solanaBridgeDriver(
+  bridge: BridgeRequester,
+  options: SolanaBridgeDriverOptions = {},
+): ConnectionDriver {
+  const chain = options.chain ?? "solana:mainnet";
+  const wallets = [solanaBridgeWallet(bridge)];
+  return lightDriver({
+    wallets: () => wallets,
+    chainId: chain,
+    client: (wallet) => solanaMessageClient(wallet.adapter, chain),
+  });
+}
+
+/** The hosted page's Sui wallet across the bridge's `sui` namespace. */
+export function suiBridgeDriver(bridge: BridgeRequester): ConnectionDriver {
+  const wallets = [suiBridgeWallet(bridge)];
+  return lightDriver({
+    wallets: () => wallets,
+    chainId: "sui:mainnet",
+    client: (wallet) => suiClient(wallet.adapter),
+  });
+}
+
+/** One Solana wallet on the page, for a driver of several (tests, a page per wallet). */
+export function solanaBridgeWallet(
+  bridge: BridgeRequester,
+  options: BridgeWalletOptions = { id: "webViewSolana", name: "Solana Wallet" },
+): LightWallet {
+  return bridgeWallet(bridge, solana, options);
+}
+
+/** One Sui wallet on the page. */
+export function suiBridgeWallet(
+  bridge: BridgeRequester,
+  options: BridgeWalletOptions = { id: "webViewSui", name: "Sui Wallet" },
+): LightWallet {
+  return bridgeWallet(bridge, sui, options);
+}

package/src/bridge/index.spec.ts

@@ -6,5 +6,8 @@ describe("bridge barrel", () => {
     expect(typeof bridge.BridgeClient).toBe("function");
     expect(typeof bridge.createMemoryTransportPair).toBe("function");
     expect(typeof bridge.isBridgeMessage).toBe("function");
+    expect(bridge.NativeBridgeErrorCode.pageStranded).toBe(-33002);
+    expect(typeof bridge.solanaBridgeDriver).toBe("function");
+    expect(typeof bridge.suiBridgeDriver).toBe("function");
   });
 });