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

package/README.md

@@ -4,421 +4,443 @@ This guide explains how to integrate your wallet with the Aztec Wallet SDK, enab
 
 ## Available Types
 
-All types and utilities needed for wallet integration are exported from `@aztec/wallet-sdk/manager`:
+All types and utilities needed for wallet integration are exported from `@aztec/wallet-sdk/types`:
 
 ```typescript
 import type {
-  ChainInfo,
   DiscoveryRequest,
   DiscoveryResponse,
+  KeyExchangeRequest,
+  KeyExchangeResponse,
   WalletInfo,
   WalletMessage,
   WalletResponse,
-} from '@aztec/wallet-sdk/manager';
-import { ChainInfoSchema, WalletSchema, jsonStringify } from '@aztec/wallet-sdk/manager';
+} from '@aztec/wallet-sdk/types';
 ```
 
-## Overview
+Cryptographic utilities for secure channel establishment are exported from `@aztec/wallet-sdk/crypto`:
 
-The Wallet SDK uses a **request-based discovery** model:
+```typescript
+import type { EncryptedPayload, ExportedPublicKey } from '@aztec/wallet-sdk/crypto';
+import {
+  decrypt,
+  deriveSessionKeys,
+  encrypt,
+  exportPublicKey,
+  generateKeyPair,
+  hashToEmoji,
+  importPublicKey,
+} from '@aztec/wallet-sdk/crypto';
+```
 
-1. **dApp requests wallets** for a specific chain/version via `WalletManager.getAvailableWallets({ chainInfo })`
-2. **SDK broadcasts** a discovery message with chain information
-3. **Your wallet responds** ONLY if it supports that specific network
-4. **dApp receives** only compatible wallets
-5. **dApp calls wallet methods** which your wallet handles and responds to
+**For extension wallets**, pre-built connection handlers are available:
 
-### Transport Mechanisms
+```typescript
+import {
+  BackgroundConnectionHandler,
+  ContentScriptConnectionHandler,
+} from '@aztec/wallet-sdk/extension/handlers';
+```
 
-This guide uses **browser extension wallets** as the primary example, which communicate via `window.postMessage`. However, the same message protocol can be used with other transport mechanisms:
+## Overview
 
-- **Extension wallets**: Use `window.postMessage` (examples shown throughout this guide)
-- **Web wallets**: Could use WebSockets, HTTP, or other protocols (see comments in examples for hypothetical WebSocket usage)
-- **Mobile wallets**: Could use deep links, app-to-app communication, or custom protocols
+The Wallet SDK uses a **two-phase connection model** with **end-to-end encryption**:
 
-The message format remains the same regardless of transport - only the delivery mechanism changes.
+### Phase 1: Discovery
 
-## Discovery Protocol
+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
 
-### 1. Listen for Discovery Requests
+### Phase 2: Secure Channel Establishment
 
-**Extension wallet example:**
+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
 
-```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
-    return;
-  }
+### Key Security Features
 
-  const data = JSON.parse(event.data);
+- **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
 
-  if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
-  }
-});
+## Architecture for Extension Wallets
 
-// Using WebSocket:
-// websocket.on('message', (message) => {
-//   const data = JSON.parse(message);
-//   if (data.type === 'aztec-wallet-discovery') {
-//     handleDiscovery(data);
-//   }
-// });
+```
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄──(discovery + port)────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (crypto+state)   │
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │              MessagePort                 │
+       └──────────(key exchange + encrypted)──────┘
 ```
 
-### 2. Discovery Message Format
+**Security model:**
 
-Discovery messages have this structure:
+- 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
 
-```typescript
-{
-  type: 'aztec-wallet-discovery',
-  requestId: string,              // UUID for tracking this request
-  chainInfo: {
-    chainId: Fr,                  // Chain ID
-    version: Fr                   // Protocol version
-  }
-}
-```
+## Using Pre-built Connection Handlers
 
-### 3. Check Network Support
+The SDK provides `BackgroundConnectionHandler` and `ContentScriptConnectionHandler` to handle the connection flow. These are the recommended way to build extension wallets.
 
-Before responding, verify your wallet supports the requested network:
+### Background Script Setup
 
 ```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
-
-function handleDiscovery(message: any) {
-  const { requestId, chainInfo } = message;
+import {
+  BackgroundConnectionHandler,
+  type BackgroundConnectionConfig,
+  type BackgroundConnectionCallbacks,
+  type BackgroundTransport,
+} from '@aztec/wallet-sdk/extension/handlers';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
+
+// 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
+    }
+  },
 
-  // Parse and validate chain info
-  const { chainId, version } = ChainInfoSchema.parse(chainInfo);
+  // Called when key exchange completes and session is ready
+  onSessionEstablished: (session) => {
+    // Display verification emojis for user reference
+    console.log('Session emojis:', hashToEmoji(session.verificationHash));
+  },
 
-  // Check if your wallet supports this network
-  const isSupported = checkNetworkSupport(chainId, version);
+  // Called when a session is terminated
+  onSessionTerminated: (requestId) => {
+    console.log('Session terminated:', requestId);
+  },
 
-  if (!isSupported) {
-    // Do NOT respond if you don't support this network
-    return;
-  }
+  // Called when a decrypted wallet message is received
+  onWalletMessage: (session, message) => {
+    // Forward to your wallet backend
+    wallet.postMessage(message);
+  },
+};
 
-  // Respond if supported
-  respondToDiscovery(requestId);
-}
-```
+const handler = new BackgroundConnectionHandler(config, transport, callbacks);
 
-### 4. Respond to Discovery
+// Initialize the handler to start listening
+handler.initialize();
 
-If your wallet supports the network, respond with your wallet information:
+// User approves connection from wallet UI
+function approveConnection(requestId: string) {
+  handler.approveDiscovery(requestId);
+}
 
-**Extension wallet example:**
+// User denies connection
+function denyConnection(requestId: string) {
+  handler.rejectDiscovery(requestId);
+}
 
-```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
-
-function respondToDiscovery(requestId: string) {
-  const response = {
-    type: 'aztec-wallet-discovery-response',
-    requestId,
-    walletInfo: {
-      id: 'my-aztec-wallet', // Unique wallet identifier
-      name: 'My Aztec Wallet', // Display name
-      icon: 'https://example.com/icon.png', // Optional icon URL
-      version: '1.0.0', // Wallet version
-    },
-  };
-
-  // Send as JSON string via window.postMessage
-  window.postMessage(jsonStringify(response), '*');
+// Send response back to dApp
+async function sendWalletResponse(requestId: string, response: WalletResponse) {
+  await handler.sendResponse(requestId, response);
 }
 
-// Using WebSocket:
-// websocket.send(jsonStringify(response));
+// Clean up on tab close/navigate
+browser.tabs.onRemoved.addListener((tabId) => {
+  handler.terminateForTab(tabId);
+});
 ```
 
-**Important Notes:**
-
-- Both the SDK and wallets send messages as JSON strings (using `jsonStringify`)
-- Both the SDK and wallets must parse incoming JSON strings
-- Always use `jsonStringify` from `@aztec/foundation/json-rpc` for sending messages
-- Always parse incoming messages with `JSON.parse` and the proper schemas
+### Content Script Setup
 
-## Message Format
+```typescript
+import {
+  ContentScriptConnectionHandler,
+  type ContentScriptTransport,
+} from '@aztec/wallet-sdk/extension/handlers';
 
-### Wallet Method Request
+const transport: ContentScriptTransport = {
+  sendToBackground: (message) => browser.runtime.sendMessage(message),
+  addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
 
-After discovery, dApps will call wallet methods. These arrive as:
+const handler = new ContentScriptConnectionHandler(transport);
 
-```typescript
-{
-  type: string,                    // Wallet method name from the Wallet interface
-  messageId: string,               // UUID for tracking this request
-  args: unknown[],                 // Method arguments
-  chainInfo: {
-    chainId: Fr,                   // Same chain that was used in discovery
-    version: Fr
-  },
-  appId: string,                   // Application identifier
-  walletId: string                 // Your wallet's ID (from discovery response)
-}
+// Start listening for discovery requests and background messages
+handler.start();
 ```
 
-Example method calls:
-
-- `type: 'getAccounts'` - Get list of accounts
-- `type: 'getChainInfo'` - Get chain information
-- `type: 'sendTx'` - Send a transaction
-- `type: 'registerContract'` - Register a contract instance
+## Testing Your Integration (dApp Side)
 
-### Wallet Method Response
+The `WalletManager` supports two patterns for consuming discovered wallets.
 
-Your wallet must respond with:
+### Async Iterator Pattern
 
 ```typescript
-{
-  messageId: string,               // MUST match the request's messageId
-  result?: unknown,                // Method result (if successful)
-  error?: unknown,                 // Error (if failed)
-  walletId: string                 // Your wallet's ID
-}
-```
-
-## Handling Wallet Methods
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager } from '@aztec/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-### 1. Set Up Message Listener
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
+  },
+  appId: 'my-dapp',
+  timeout: 60000,
+});
 
-**Extension wallet example:**
+// Iterate over discovered wallets as they're approved
+for await (const provider of discovery.wallets) {
+  console.log(`Found: ${provider.name}`);
 
-```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
-    return;
-  }
+  // Establish secure channel (key exchange)
+  const pending = await provider.establishSecureChannel('my-dapp');
 
-  let data;
-  try {
-    data = JSON.parse(event.data);
-  } catch {
-    return; // Not a valid JSON message
-  }
+  // Display verification emojis to user
+  const emojis = hashToEmoji(pending.verificationHash);
+  console.log('Verify this matches your wallet:', emojis);
 
-  // Handle discovery
-  if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
-    return;
-  }
+  // User confirms emojis match
+  const wallet = await pending.confirm();
 
-  // Handle wallet methods
-  if (data.messageId && data.type && data.walletId === 'my-aztec-wallet') {
-    handleWalletMethod(data);
-  }
-});
+  // All calls are now encrypted
+  const accounts = await wallet.getAccounts();
+  console.log('Accounts:', accounts);
+}
 
-// Using WebSocket:
-// websocket.on('message', (message) => {
-//   const data = JSON.parse(message);
-//   if (data.type === 'aztec-wallet-discovery') {
-//     handleDiscovery(data);
-//   } else if (data.messageId && data.type) {
-//     handleWalletMethod(data);
-//   }
-// });
+// Cancel discovery when done or on cleanup
+discovery.cancel();
 ```
 
-### 2. Route to Wallet Implementation
+### Callback Pattern
 
 ```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager, type WalletProvider } from '@aztec/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-async function handleWalletMethod(message: any) {
-  const { type, messageId, args, chainInfo, appId, walletId } = message;
+const discoveredProviders: WalletProvider[] = [];
 
-  try {
-    // Parse and validate chain info
-    const parsedChainInfo = ChainInfoSchema.parse(chainInfo);
+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
+  },
+});
 
-    // Get the wallet instance for this chain
-    const wallet = await getWalletForChain(parsedChainInfo);
+// Wait for discovery to complete (or cancel early with discovery.cancel())
+await discovery.done;
+console.log('Discovery complete, found:', discoveredProviders.length);
 
-    // Verify the method exists on the Wallet interface
-    if (typeof wallet[type] !== 'function') {
-      throw new Error(`Unknown wallet method: ${type}`);
-    }
+// Connect to a selected provider
+async function connectToWallet(provider: WalletProvider) {
+  const pending = await provider.establishSecureChannel('my-dapp');
 
-    // Call the wallet method
-    const result = await wallet[type](...args);
+  // Show verification UI
+  const emojis = hashToEmoji(pending.verificationHash);
+  showVerificationDialog(emojis);
 
-    // Send success response
-    sendResponse(messageId, walletId, result);
-  } catch (error) {
-    // Send error response
-    sendError(messageId, walletId, error);
-  }
+  // User confirms
+  const wallet = await pending.confirm();
+  return wallet;
 }
 ```
 
-### 3. Send Response
-
-**Extension wallet example:**
+### React Hook Example
 
 ```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
+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]);
+      },
+    });
+
+    discoveryRef.current = discovery;
+
+    discovery.done.then(() => setIsDiscovering(false));
+
+    return () => {
+      discovery.cancel();
+      discoveryRef.current = null;
+    };
+  }, [chainInfo.chainId.toString(), chainInfo.version.toString(), appId]);
+
+  return { providers, isDiscovering, cancel: () => discoveryRef.current?.cancel() };
+}
+```
 
-function sendResponse(messageId: string, walletId: string, result: unknown) {
-  const response = {
-    messageId,
-    result,
-    walletId,
-  };
+## Storage backends
 
-  // Send as JSON string
-  window.postMessage(jsonStringify(response), '*');
-}
+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:
 
-function sendError(messageId: string, walletId: string, error: Error) {
-  const response = {
-    messageId,
-    error: {
-      message: error.message,
-      stack: error.stack,
-    },
-    walletId,
-  };
-
-  window.postMessage(jsonStringify(response), '*');
-}
+- **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.
 
-// Using WebSocket:
-// websocket.send(jsonStringify({ messageId, result, walletId }));
-```
+The backend is chosen by *which store you construct and hand to the wallet* there is no runtime flag or environment variable.
 
-## Parsing Messages
+> **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.
 
-### Using Zod Schemas
+### Quick start: embedded wallet with an encrypted SQLite store
 
-Use the provided Zod schemas to parse and validate incoming messages:
+If you build on `@aztec/wallets`' `EmbeddedWallet`, open its two stores (PXE state + the wallet DB) with `openEncryptedEmbeddedStores`, then pass them in:
 
 ```typescript
-import { ChainInfoSchema, WalletSchema } from '@aztec/wallet-sdk/manager';
-
-// Parse chain info
-const chainInfo = ChainInfoSchema.parse(message.chainInfo);
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+import { openEncryptedEmbeddedStores } from '@aztec/wallets/embedded/store-encryption';
+import { createLogger } from '@aztec/foundation/log';
 
-// Validate result against expected schema for a method
-const accountsResult = await wallet.getAccounts(...args);
-// The SDK handles schema validation on the client side
-```
+const log = createLogger('wallet:storage');
 
-The Wallet SDK automatically validates return values using `WalletSchema` on the client side, so your wallet implementation should return values that match the `Wallet` interface specification.
+// 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);
 
-## Error Handling
+const { pxeStore, walletStore } = await openEncryptedEmbeddedStores(
+  {
+    pxe: { name: `pxe-${rollupAddress}`, poolDirectory: '/pxe' },
+    wallet: { name: `wallet-${rollupAddress}`, poolDirectory: '/wallet' },
+  },
+  getEncryptionKey,
+  log,
+);
 
-### Error Response Format
+const wallet = await EmbeddedWallet.create(nodeUrl, {
+  pxe: { store: pxeStore },
+  walletDb: { store: walletStore },
+});
+```
 
-Always send error responses with this structure:
+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
-{
-  messageId: string,               // Match the request
-  error: {
-    message: string,               // Error message
-    code?: string,                 // Optional error code
-    stack?: string                 // Optional stack trace
-  },
-  walletId: string
+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;
+  }
 }
 ```
 
-### Common Error Scenarios
+### Important 
 
-```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+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).
 
-async function handleWalletMethod(message: any) {
-  const { type, messageId, args, chainInfo, walletId } = message;
+### No multi-tab access: assume one tab at a time
 
-  try {
-    // 1. Parse and validate chain info
-    const parsedChainInfo = ChainInfoSchema.parse(chainInfo);
+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.
 
-    // 2. Check network support
-    if (!isNetworkSupported(parsedChainInfo)) {
-      throw new Error('Network not supported by wallet');
-    }
+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.
 
-    // 3. Get wallet instance
-    const wallet = await getWalletForChain(parsedChainInfo);
+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.
 
-    // 4. Validate method exists
-    if (typeof wallet[type] !== 'function') {
-      throw new Error(`Unknown wallet method: ${type}`);
-    }
+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.
 
-    // 5. Execute method
-    const result = await wallet[type](...args);
-    sendResponse(messageId, walletId, result);
-  } catch (error) {
-    sendError(messageId, walletId, error);
-  }
-}
-```
+### Opting out of encryption
 
-### User Rejection Handling
+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.
 
-If a user rejects an action:
+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:
 
 ```typescript
-{
-  messageId: 'abc-123',
-  error: {
-    message: 'User rejected the request',
-    code: 'USER_REJECTED'
-  },
-  walletId: 'my-wallet'
-}
-```
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+import { AztecSQLiteOPFSStore } from '@aztec/kv-store/sqlite-opfs';
+import { createLogger } from '@aztec/foundation/log';
+
+const log = createLogger('wallet:storage');
+
+// 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');
 
-## Testing Your Integration
+const wallet = await EmbeddedWallet.create(nodeUrl, {
+  pxe: { store: pxeStore },
+  walletDb: { store: walletStore },
+});
+```
 
-### WalletManager
+### Building your own wallet (lower-level API)
 
-In a dApp using the Wallet SDK:
+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 } 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
-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 });
+```
 
-console.log('Discovered wallets:', wallets);
+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 to your wallet
-const walletProvider = wallets.find(w => w.id === 'my-aztec-wallet');
-if (walletProvider) {
-  const wallet = await walletProvider.connect('test-app');
+Note: `openEncryptedStore` throws `SqliteEncryptionError` (with a typed `code`, e.g. `'decrypt_failed'`) on a bad key.
 
-  // Test wallet methods from the Wallet interface
-  const accounts = await wallet.getAccounts();
-  console.log('Accounts:', accounts);
+### Using SQLite-OPFS in a browser extension (MV3)
 
-  const chainInfo = await wallet.getChainInfo();
-  console.log('Chain info:', chainInfo);
-}
-```
+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.