@aztec/wallet-sdk 0.0.1-commit.d431d1c → 0.0.1-commit.d58ff9d0

package/README.md

@@ -10,6 +10,8 @@ All types and utilities needed for wallet integration are exported from `@aztec/
 import type {
   DiscoveryRequest,
   DiscoveryResponse,
+  KeyExchangeRequest,
+  KeyExchangeResponse,
   WalletInfo,
   WalletMessage,
   WalletResponse,
@@ -22,377 +24,423 @@ Cryptographic utilities for secure channel establishment are exported from `@azt
 import type { EncryptedPayload, ExportedPublicKey } from '@aztec/wallet-sdk/crypto';
 import {
   decrypt,
-  deriveSharedKey,
+  deriveSessionKeys,
   encrypt,
   exportPublicKey,
   generateKeyPair,
-  hashSharedSecret,
   hashToEmoji,
   importPublicKey,
 } from '@aztec/wallet-sdk/crypto';
 ```
 
-## Overview
+**For extension wallets**, pre-built connection handlers are available:
 
-The Wallet SDK uses a **unified discovery and connection** model with **end-to-end encryption**:
+```typescript
+import {
+  BackgroundConnectionHandler,
+  ContentScriptConnectionHandler,
+} from '@aztec/wallet-sdk/extension/handlers';
+```
 
-1. **dApp requests wallets** for a specific chain/version via `WalletManager.getAvailableWallets({ chainInfo })`
-2. **SDK broadcasts** a discovery message with chain information and the dApp's ECDH public key
-3. **Your wallet responds** with its ECDH public key and a MessagePort ONLY if it supports that network
-4. **Both parties derive** the same shared secret via ECDH key exchange
-5. **SDK receives** discovered wallets with secure channel already established (port + sharedKey)
-6. **All subsequent communication** is encrypted using AES-256-GCM over the private MessagePort
+## Overview
 
-### Key Features
+The Wallet SDK uses a **two-phase connection model** with **end-to-end encryption**:
 
-- **No separate connection step**: The secure channel is established during discovery
-- **MessagePort transferred immediately**: The discovery response includes a MessagePort for private communication
-- **Anti-MITM verification**: Both parties can display emoji verification codes derived from the shared secret
+### Phase 1: Discovery
 
-### Transport Mechanisms
+1. **dApp broadcasts** a discovery request with chain information (NO public keys)
+2. **Your wallet shows** a pending connection request to the user
+3. **User approves** the connection request
+4. **Your wallet responds** with basic wallet info and a MessagePort
 
-This guide uses **browser extension wallets** as the primary example, which communicate via `window.postMessage` for discovery and MessageChannel for secure communication. The same message protocol can be adapted for other transport mechanisms.
+### Phase 2: Secure Channel Establishment
 
-## Discovery Protocol
+5. **dApp initiates key exchange** by sending its ECDH public key over the MessagePort
+6. **Wallet generates** ephemeral key pair and derives session keys using HKDF
+7. **Both parties compute** the same verification hash independently
+8. **User verifies** the has matches on both sides. A util for conversion to an emoji grid is provided
+9. **User confirms** the connection in the dApp
+10. **All subsequent communication** is encrypted using AES-256-GCM
 
-### 1. Listen for Discovery Requests
+### Key Security Features
 
-**Extension wallet (content script):**
+- **User approval required**: Wallet never reveals itself without explicit user consent
+- **Ephemeral keys**: New key pairs generated for each session
+- **Anti-MITM verification**: 3x3 emoji grid (72 bits of security) for visual confirmation
 
-```typescript
-window.addEventListener('message', async (event) => {
-  if (event.source !== window) return;
-
-  let data: DiscoveryRequest;
-  try {
-    data = JSON.parse(event.data);
-  } catch {
-    return;
-  }
+## Architecture for Extension Wallets
 
-  if (data.type === 'aztec-wallet-discovery') {
-    await handleDiscoveryRequest(data);
-  }
-});
 ```
-
-### 2. Discovery Message Format
-
-Discovery messages have this structure:
-
-```typescript
-interface DiscoveryRequest {
-  type: 'aztec-wallet-discovery';
-  requestId: string;              // UUID for tracking this request
-  chainInfo: ChainInfo;           // Chain ID and protocol version
-  publicKey: ExportedPublicKey;   // dApp's ECDH public key for key exchange
-}
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄──(discovery + port)────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (crypto+state)   │
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │              MessagePort                 │
+       └──────────(key exchange + encrypted)──────┘
 ```
 
-### 3. Handle Discovery and Establish Secure Channel
+**Security model:**
+
+- The MessagePort is transferred via `window.postMessage` - other scripts on the page could intercept it
+- **Security comes from encryption**: After key exchange, all communication is AES-256-GCM encrypted
+- Content script never has access to private keys or session secrets
+- All cryptographic operations happen in the background script (service worker)
+- Anti-MITM verification (emoji grid) ensures both parties derived the same keys
 
-When your wallet receives a discovery request:
+## Using Pre-built Connection Handlers
 
-1. Check if you support the requested network
-2. Derive the shared secret from the dApp's public key
-3. Create a MessageChannel for secure communication
-4. Respond with your wallet info and transfer one end of the channel
+The SDK provides `BackgroundConnectionHandler` and `ContentScriptConnectionHandler` to handle the connection flow. These are the recommended way to build extension wallets.
 
-**Extension wallet (background script):**
+### Background Script Setup
 
 ```typescript
 import {
-  deriveSharedKey,
-  exportPublicKey,
-  generateKeyPair,
-  hashSharedSecret,
-  importPublicKey,
-} from '@aztec/wallet-sdk/crypto';
+  BackgroundConnectionHandler,
+  type BackgroundConnectionConfig,
+  type BackgroundConnectionCallbacks,
+  type BackgroundTransport,
+} from '@aztec/wallet-sdk/extension/handlers';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-// Generate key pair on wallet initialization (per session)
-let walletKeyPair = await generateKeyPair();
-let walletPublicKey = await exportPublicKey(walletKeyPair.publicKey);
+// Configuration for your wallet
+const config: BackgroundConnectionConfig = {
+  walletId: 'my-aztec-wallet',
+  walletName: 'My Aztec Wallet',
+  walletVersion: '1.0.0',
+  walletIcon: 'https://example.com/icon.png',
+};
+
+// Transport for browser extension APIs
+const transport: BackgroundTransport = {
+  sendToTab: (tabId, message) => browser.tabs.sendMessage(tabId, message),
+  addContentListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
+
+// Event callbacks (all optional)
+const callbacks: BackgroundConnectionCallbacks = {
+  // Called when a new discovery request is received
+  onPendingDiscovery: (discovery) => {
+    // Show pending connection in wallet UI
+    // Check if wallet supports this network (chainId AND version)
+    const supported = supportedNetworks.some(
+      n => n.chainId === discovery.chainInfo.chainId.toString() &&
+           n.version === discovery.chainInfo.version.toString()
+    );
+    if (supported) {
+      // Show the user so they can approve or reject
+    }
+  },
 
-// Store sessions by requestId
-const sessions = new Map<string, { sharedKey: CryptoKey; verificationHash: string; tabId: number }>();
+  // Called when key exchange completes and session is ready
+  onSessionEstablished: (session) => {
+    // Display verification emojis for user reference
+    console.log('Session emojis:', hashToEmoji(session.verificationHash));
+  },
 
-async function handleDiscovery(
-  request: DiscoveryRequest,
-  tabId: number
-): Promise<{ success: true; response: DiscoveryResponse }> {
-  // Check network support
-  if (!supportsNetwork(request.chainInfo)) {
-    throw new Error('Network not supported');
-  }
+  // Called when a session is terminated
+  onSessionTerminated: (requestId) => {
+    console.log('Session terminated:', requestId);
+  },
 
-  // Import dApp's public key and derive shared secret
-  const dAppPublicKey = await importPublicKey(request.publicKey);
-  const sharedKey = await deriveSharedKey(walletKeyPair.privateKey, dAppPublicKey);
+  // Called when a decrypted wallet message is received
+  onWalletMessage: (session, message) => {
+    // Forward to your wallet backend
+    wallet.postMessage(message);
+  },
+};
 
-  // Compute verification hash for anti-MITM verification
-  const verificationHash = await hashSharedSecret(sharedKey);
+const handler = new BackgroundConnectionHandler(config, transport, callbacks);
 
-  // Store the session with verificationHash (emoji computed lazily for display)
-  sessions.set(request.requestId, { sharedKey, verificationHash, tabId });
+// Initialize the handler to start listening
+handler.initialize();
 
-  const response: DiscoveryResponse = {
-    type: 'aztec-wallet-discovery-response',
-    requestId: request.requestId,
-    walletInfo: {
-      id: 'my-aztec-wallet',
-      name: 'My Aztec Wallet',
-      version: '1.0.0',
-      publicKey: walletPublicKey,
-    },
-  };
+// User approves connection from wallet UI
+function approveConnection(requestId: string) {
+  handler.approveDiscovery(requestId);
+}
 
-  return { success: true, response };
+// User denies connection
+function denyConnection(requestId: string) {
+  handler.rejectDiscovery(requestId);
 }
+
+// Send response back to dApp
+async function sendWalletResponse(requestId: string, response: WalletResponse) {
+  await handler.sendResponse(requestId, response);
+}
+
+// Clean up on tab close/navigate
+browser.tabs.onRemoved.addListener((tabId) => {
+  handler.terminateForTab(tabId);
+});
 ```
 
-**Content script (creates MessageChannel and sends response):**
+### Content Script Setup
 
 ```typescript
-async function handleDiscoveryRequest(request: DiscoveryRequest) {
-  // Forward to background script for key derivation
-  const result = await browser.runtime.sendMessage({
-    type: 'aztec-wallet-discovery',
-    content: request,
-  });
-
-  if (!result?.success) return;
-
-  // Create MessageChannel for secure communication
-  const channel = new MessageChannel();
-
-  // Set up relay from page to background
-  channel.port1.onmessage = (event) => {
-    browser.runtime.sendMessage({
-      type: 'secure-message',
-      requestId: request.requestId,
-      content: event.data,  // Encrypted payload
-    });
-  };
-  channel.port1.start();
+import {
+  ContentScriptConnectionHandler,
+  type ContentScriptTransport,
+} from '@aztec/wallet-sdk/extension/handlers';
 
-  // Send response with port2 to the page
-  window.postMessage(JSON.stringify(result.response), '*', [channel.port2]);
-}
+const transport: ContentScriptTransport = {
+  sendToBackground: (message) => browser.runtime.sendMessage(message),
+  addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
+
+const handler = new ContentScriptConnectionHandler(transport);
+
+// Start listening for discovery requests and background messages
+handler.start();
 ```
 
-### 4. Discovery Response Format
+## Testing Your Integration (dApp Side)
+
+The `WalletManager` supports two patterns for consuming discovered wallets.
+
+### Async Iterator Pattern
 
 ```typescript
-interface DiscoveryResponse {
-  type: 'aztec-wallet-discovery-response';
-  requestId: string;              // Must match the request
-  walletInfo: WalletInfo;         // Wallet info including public key
-}
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager } from '@aztec/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-interface WalletInfo {
-  id: string;                     // Unique wallet identifier
-  name: string;                   // Display name
-  icon?: string;                  // Optional icon URL
-  version: string;                // Wallet version
-  publicKey: ExportedPublicKey;   // ECDH public key for key exchange
-}
-```
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
+  },
+  appId: 'my-dapp',
+  timeout: 60000,
+});
 
-**Important:** The response is sent via `window.postMessage` with a MessagePort transferred as the third argument. The SDK receives the port and uses it for all subsequent encrypted communication.
+// Iterate over discovered wallets as they're approved
+for await (const provider of discovery.wallets) {
+  console.log(`Found: ${provider.name}`);
 
-## Secure Communication
+  // Establish secure channel (key exchange)
+  const pending = await provider.establishSecureChannel('my-dapp');
 
-### Architecture for Extension Wallets
+  // Display verification emojis to user
+  const emojis = hashToEmoji(pending.verificationHash);
+  console.log('Verify this matches your wallet:', emojis);
 
-```
-┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
-│   dApp      │◄───(discovery only)─────►│  Content Script │◄────────────────────►│ Background Script│
-│ (web page)  │                          │  (message relay)│                      │ (decrypt+process)│
-└─────────────┘                          └─────────────────┘                      └──────────────────┘
-       │                                          │
-       │         MessagePort (private channel)    │
-       └──────────(encrypted messages)────────────┘
+  // User confirms emojis match
+  const wallet = await pending.confirm();
+
+  // All calls are now encrypted
+  const accounts = await wallet.getAccounts();
+  console.log('Accounts:', accounts);
+}
+
+// Cancel discovery when done or on cleanup
+discovery.cancel();
 ```
 
-**Security benefits:**
+### Callback Pattern
 
-- Content script never has access to private keys or shared secrets
-- All cryptographic operations happen in the background script (service worker)
-- MessagePort provides a private channel not visible to other page scripts
-- Only discovery uses `window.postMessage`; all wallet calls are encrypted on the MessagePort
+```typescript
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager, type WalletProvider } from '@aztec/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-### Handle Encrypted Messages
+const discoveredProviders: WalletProvider[] = [];
 
-All wallet method calls arrive as encrypted payloads on the MessagePort:
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
+  },
+  appId: 'my-dapp',
+  timeout: 60000,
+  // Callback fires as each wallet is discovered
+  onWalletDiscovered: (provider) => {
+    discoveredProviders.push(provider);
+    updateUI(); // Your UI update function
+  },
+});
 
-```typescript
-interface EncryptedPayload {
-  iv: string;         // Base64-encoded initialization vector
-  ciphertext: string; // Base64-encoded encrypted data
+// Wait for discovery to complete (or cancel early with discovery.cancel())
+await discovery.done;
+console.log('Discovery complete, found:', discoveredProviders.length);
+
+// Connect to a selected provider
+async function connectToWallet(provider: WalletProvider) {
+  const pending = await provider.establishSecureChannel('my-dapp');
+
+  // Show verification UI
+  const emojis = hashToEmoji(pending.verificationHash);
+  showVerificationDialog(emojis);
+
+  // User confirms
+  const wallet = await pending.confirm();
+  return wallet;
 }
 ```
 
-**Background script:**
+### React Hook Example
 
 ```typescript
-import { decrypt, encrypt } from '@aztec/wallet-sdk/crypto';
-
-async function handleSecureMessage(requestId: string, encrypted: EncryptedPayload) {
-  const session = sessions.get(requestId);
-  if (!session) return;
-
-  try {
-    // Decrypt the incoming message
-    const message = await decrypt<WalletMessage>(session.sharedKey, encrypted);
-    const { type, messageId, args, chainInfo, walletId } = message;
-
-    // Process the wallet method call
-    const wallet = await getWalletForChain(chainInfo);
-    const result = await wallet[type](...args);
-
-    // Create and encrypt response
-    const response: WalletResponse = { messageId, result, walletId };
-    const encryptedResponse = await encrypt(session.sharedKey, response);
-
-    // Send back through content script
-    browser.tabs.sendMessage(session.tabId, {
-      type: 'secure-response',
-      requestId,
-      content: encryptedResponse,
+function useWalletDiscovery(chainInfo: ChainInfo, appId: string) {
+  const [providers, setProviders] = useState<WalletProvider[]>([]);
+  const [isDiscovering, setIsDiscovering] = useState(true);
+  const discoveryRef = useRef<DiscoverySession | null>(null);
+
+  useEffect(() => {
+    setProviders([]);
+    setIsDiscovering(true);
+
+    const discovery = WalletManager.configure({
+      extensions: { enabled: true },
+    }).getAvailableWallets({
+      chainInfo,
+      appId,
+      timeout: 60000,
+      onWalletDiscovered: (provider) => {
+        setProviders(prev => [...prev, provider]);
+      },
     });
-  } catch (error) {
-    // Send encrypted error response
-    const errorResponse: WalletResponse = {
-      messageId: message?.messageId ?? '',
-      error: { message: error.message },
-      walletId: message?.walletId ?? '',
+
+    discoveryRef.current = discovery;
+
+    discovery.done.then(() => setIsDiscovering(false));
+
+    return () => {
+      discovery.cancel();
+      discoveryRef.current = null;
     };
-    const encryptedError = await encrypt(session.sharedKey, errorResponse);
-    // ... send error response
-  }
+  }, [chainInfo.chainId.toString(), chainInfo.version.toString(), appId]);
+
+  return { providers, isDiscovering, cancel: () => discoveryRef.current?.cancel() };
 }
 ```
 
-## Message Formats
+## Storage backends
+
+Your wallet and the PXE it embeds persist state through a pluggable key-value store (`@aztec/kv-store`). In the browser there are two backends:
+
+- **IndexedDB** (`@aztec/kv-store/deprecated/indexeddb`): the default in browser environments up to Aztec Alpha v4, now moved to a deprecated subpath. We plan to remove this backend, so new browser code should use the SQLite backend below.
+- **SQLite-OPFS** (`@aztec/kv-store/sqlite-opfs`): the default KV store backend from Aztec Alpha v5 on. It's backed by the durable Origin Private File System web standard, and it offers a number of advantages over IndexedDB: a sane transaction model (IDB transactions auto-close the moment the event loop yields, which constrains the store layer), support for encryption at rest, and better performance in the access patterns we exercise the most from both wallet and PXE.
+
+The backend is chosen by *which store you construct and hand to the wallet* there is no runtime flag or environment variable.
 
-### Wallet Method Request (Decrypted)
+> **Data migration is not supported between backends, by design.** The v4→v5 protocol upgrade discards all local state regardless, so switching to SQLite-OPFS simply means starting from a fresh store.
+
+### Quick start: embedded wallet with an encrypted SQLite store
+
+If you build on `@aztec/wallets`' `EmbeddedWallet`, open its two stores (PXE state + the wallet DB) with `openEncryptedEmbeddedStores`, then pass them in:
 
 ```typescript
-interface WalletMessage {
-  type: string;        // Wallet method name (e.g., 'getAccounts', 'sendTx')
-  messageId: string;   // UUID for tracking this request
-  args: unknown[];     // Method arguments
-  chainInfo: ChainInfo;
-  appId: string;       // Application identifier
-  walletId: string;    // Your wallet's ID
-}
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+import { openEncryptedEmbeddedStores } from '@aztec/wallets/embedded/store-encryption';
+import { createLogger } from '@aztec/foundation/log';
+
+const log = createLogger('wallet:storage');
+
+// Your wallet derives a 32-byte key (see "Key management" below).
+// IMPORTANT: return a *fresh* Uint8Array each call. Opening a store consumes (empties)
+// the key, so a reused array would be empty on the second open (see "important" below).
+const getEncryptionKey = async () => new Uint8Array(myDerivedKey);
+
+const { pxeStore, walletStore } = await openEncryptedEmbeddedStores(
+  {
+    pxe: { name: `pxe-${rollupAddress}`, poolDirectory: '/pxe' },
+    wallet: { name: `wallet-${rollupAddress}`, poolDirectory: '/wallet' },
+  },
+  getEncryptionKey,
+  log,
+);
+
+const wallet = await EmbeddedWallet.create(nodeUrl, {
+  pxe: { store: pxeStore },
+  walletDb: { store: walletStore },
+});
 ```
 
-### Wallet Method Response
+If the supplied key cannot decrypt an existing store, `openEncryptedEmbeddedStores` throws `EmbeddedWalletEncryptionError` with `storeName: 'pxe' | 'wallet'`, which you can then surface as a "wrong password" error in your UI:
 
 ```typescript
-interface WalletResponse {
-  messageId: string;   // Must match the request
-  result?: unknown;    // Method result (if successful)
-  error?: unknown;     // Error (if failed)
-  walletId: string;    // Your wallet's ID
+import { EmbeddedWalletEncryptionError } from '@aztec/wallets/embedded/store-encryption';
+
+try {
+  await openEncryptedEmbeddedStores(/* ... */);
+} catch (err) {
+  if (err instanceof EmbeddedWalletEncryptionError) {
+    showWrongPasswordError(); // err.storeName tells you which store failed
+  } else {
+    throw err;
+  }
 }
 ```
 
-## Anti-MITM Verification
+### Important 
 
-Both the dApp and wallet independently compute a `verificationHash` from the shared secret. If both parties compute the same hash, they know there's no man-in-the-middle attack.
+1. **Opening a store consumes the key, it does not copy it.** So that raw key material does not linger in page memory, the SDK moves your key into the storage worker and detaches the buffer on your side. The `Uint8Array` you passed comes back empty, so the same array cannot be reused to open a second store. To open more than one store with the same key, hand each open a fresh copy (`new Uint8Array(key)`). `openEncryptedEmbeddedStores` does this for you by invoking your `getEncryptionKey` callback once per store.
+2. **Each coexisting store needs its own `poolDirectory`.** The OPFS SAH Pool holds an *exclusive* lock on its directory, so two stores sharing the default pool fail with "Access Handles cannot be created if there is another open Access Handle…". Give every store a distinct, stable `poolDirectory` (stable so the same files re-open next session).
 
-```typescript
-import { hashSharedSecret } from '@aztec/wallet-sdk/crypto';
+### No multi-tab access: assume one tab at a time
 
-// Compute verification hash from shared key
-const verificationHash = await hashSharedSecret(sharedKey);
+A store can be opened by **one browser tab at a time per origin**. If the user opens your wallet in a second tab of the same origin pointing at the same store, the second open contends for that lock.
 
-// Store verificationHash in session - this is the cryptographic proof
-sessions.set(requestId, { sharedKey, verificationHash, tabId });
-```
+Thanks to the lock, the data is never corrupted, but the second open fails or hangs rather than succeeding, and there is no graceful "already open elsewhere" signal yet.
 
-For user-friendly display, convert the hash to an emoji sequence:
+Until it does, design for a single active tab: detect a second instance (e.g. with the [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API) or a `BroadcastChannel`) and steer the user back to the existing tab, or open the store read-only there.
 
-```typescript
-import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
+If you need genuine concurrent multi-tab access, route all storage access through a single `SharedWorker` that you own and that holds the one connection.
 
-// Convert to emoji only when displaying to the user
-const emoji = hashToEmoji(verificationHash);  // e.g., "🔵🦋🎯🐼"
-```
+### Opting out of encryption
 
-The dApp displays the same emoji sequence. If they match, the connection is secure.
+If you do not need at-rest encryption (you rely on full-disk encryption, or the device is trusted), an *unencrypted* SQLite-OPFS store is still a better default than IndexedDB.
 
-## Session Management
+The `createStore` convenience helper always uses the default OPFS pool directory and does not currently let you change it, so it only works for a single store per tab. The embedded wallet runs two stores (PXE + walletDB), so open them directly from `AztecSQLiteOPFSStore` with a distinct `poolDirectory` each:
 
-Sessions should be cleaned up when:
+```typescript
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+import { AztecSQLiteOPFSStore } from '@aztec/kv-store/sqlite-opfs';
+import { createLogger } from '@aztec/foundation/log';
 
-- **Tab closes**: Browser tabs API `onRemoved` event
-- **Tab navigates**: Browser tabs API `onUpdated` event with `status === 'loading'`
+const log = createLogger('wallet:storage');
 
-```typescript
-// Clean up when tab closes
-browser.tabs.onRemoved.addListener((tabId) => {
-  for (const [requestId, session] of sessions) {
-    if (session.tabId === tabId) {
-      sessions.delete(requestId);
-    }
-  }
-});
+// No key; just name, ephemeral=false, and a distinct poolDirectory per store.
+const pxeStore = await AztecSQLiteOPFSStore.open(log, `pxe-${rollupAddress}`, false, '/pxe');
+const walletStore = await AztecSQLiteOPFSStore.open(log, `wallet-${rollupAddress}`, false, '/wallet');
 
-// Clean up when tab navigates
-browser.tabs.onUpdated.addListener((tabId, changeInfo) => {
-  if (changeInfo.status === 'loading') {
-    for (const [requestId, session] of sessions) {
-      if (session.tabId === tabId) {
-        sessions.delete(requestId);
-      }
-    }
-  }
+const wallet = await EmbeddedWallet.create(nodeUrl, {
+  pxe: { store: pxeStore },
+  walletDb: { store: walletStore },
 });
 ```
 
-## Testing Your Integration
+### Building your own wallet (lower-level API)
 
-### Using WalletManager
+If you are not using `EmbeddedWallet`, construct stores directly from `@aztec/kv-store/sqlite-opfs` and pass them wherever a store is accepted (e.g. `PXECreationOptions.store`):
 
 ```typescript
-import { Fr } from '@aztec/foundation/fields';
-import { WalletManager, hashToEmoji } from '@aztec/wallet-sdk/manager';
+import { openEncryptedStore, createStore, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
 
-const manager = WalletManager.configure({
-  extensions: { enabled: true },
-});
+// Encrypted, persistent:
+const store = await openEncryptedStore(new Uint8Array(myDerivedKey), 'my-store', '/my-pool');
 
-// Discover wallets (secure channel established automatically)
-const wallets = await manager.getAvailableWallets({
-  chainInfo: {
-    chainId: new Fr(31337),
-    version: new Fr(0),
-  },
-  timeout: 2000,
-});
+// Or unencrypted:
+const plain = await createStore('my-store', { dataStoreMapSizeKb: 2e10 });
+```
 
-// Each wallet provider has verification info
-for (const provider of wallets) {
-  const emoji = hashToEmoji(provider.metadata.verificationHash);
-  console.log(`${provider.name}: ${emoji}`);
-}
+Note: `dataStoreMapSizeKb` is an LMDB-specific ceiling (the maximum memory-map size). SQLite-OPFS grows its file dynamically and ignores the value, but it is a required field of the shared `DataStoreConfig` type, so you must still pass something (any number is fine). We will fix this implementation leak in coming versions.
 
-// Connect and use
-const walletProvider = wallets.find(w => w.id === 'my-aztec-wallet');
-if (walletProvider) {
-  const wallet = await walletProvider.connect('my-app-id');
+Note: `openEncryptedStore` throws `SqliteEncryptionError` (with a typed `code`, e.g. `'decrypt_failed'`) on a bad key.
 
-  // All calls are automatically encrypted
-  const accounts = await wallet.getAccounts();
-  console.log('Accounts:', accounts);
-}
-```
+### Using SQLite-OPFS in a browser extension (MV3)
+
+SQLite-OPFS needs OPFS, a Web Worker, and cross-origin isolation (SharedArrayBuffer). In a Chrome MV3 extension:
 
-## Reference Implementation
+- **Run it in an offscreen document, not the background service worker.** The service worker is ephemeral and does not reliably provide OPFS/SharedArrayBuffer; an offscreen document does, and it is where your PXE and stores should live.
+- **No COOP/COEP header setup is needed inside the extension.** Extension pages are cross-origin-isolated by default. (A plain web page hosting the wallet *does* need those headers.)
 
-For a complete reference implementation, see the demo wallet at:
+### Key management is your responsibility
 
-- Repository: `~/repos/demo-wallet`
+The store encrypts data at rest given a 32-byte key, but deriving and safeguarding that key is the wallet's job. A common pattern is to derive the key from a user password with a memory-hard KDF (e.g. Argon2id) and hold it only in memory while the wallet is unlocked. Adapt this to your own security model.