@aztec/wallet-sdk 0.0.1-commit.fcb71a6 → 0.0.1-commit.fffb133c

package/README.md

@@ -4,421 +4,318 @@ 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
-
-The Wallet SDK uses a **request-based discovery** model:
-
-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
-
-### Transport Mechanisms
-
-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:
-
-- **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 message format remains the same regardless of transport - only the delivery mechanism changes.
-
-## Discovery Protocol
-
-### 1. Listen for Discovery Requests
-
-**Extension wallet example:**
+Cryptographic utilities for secure channel establishment are exported from `@aztec/wallet-sdk/crypto`:
 
 ```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
-    return;
-  }
-
-  const data = JSON.parse(event.data);
-
-  if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
-  }
-});
-
-// Using WebSocket:
-// websocket.on('message', (message) => {
-//   const data = JSON.parse(message);
-//   if (data.type === 'aztec-wallet-discovery') {
-//     handleDiscovery(data);
-//   }
-// });
-```
-
-### 2. Discovery Message Format
-
-Discovery messages have this structure:
-
-```typescript
-{
-  type: 'aztec-wallet-discovery',
-  requestId: string,              // UUID for tracking this request
-  chainInfo: {
-    chainId: Fr,                  // Chain ID
-    version: Fr                   // Protocol version
-  }
-}
+import type { EncryptedPayload, ExportedPublicKey } from '@aztec/wallet-sdk/crypto';
+import {
+  decrypt,
+  deriveSessionKeys,
+  encrypt,
+  exportPublicKey,
+  generateKeyPair,
+  hashToEmoji,
+  importPublicKey,
+} from '@aztec/wallet-sdk/crypto';
 ```
 
-### 3. Check Network Support
-
-Before responding, verify your wallet supports the requested network:
+**For extension wallets**, pre-built connection handlers are available:
 
 ```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
-
-function handleDiscovery(message: any) {
-  const { requestId, chainInfo } = message;
-
-  // Parse and validate chain info
-  const { chainId, version } = ChainInfoSchema.parse(chainInfo);
-
-  // Check if your wallet supports this network
-  const isSupported = checkNetworkSupport(chainId, version);
-
-  if (!isSupported) {
-    // Do NOT respond if you don't support this network
-    return;
-  }
-
-  // Respond if supported
-  respondToDiscovery(requestId);
-}
+import {
+  BackgroundConnectionHandler,
+  ContentScriptConnectionHandler,
+} from '@aztec/wallet-sdk/extension/handlers';
 ```
 
-### 4. Respond to Discovery
+## Overview
 
-If your wallet supports the network, respond with your wallet information:
+The Wallet SDK uses a **two-phase connection model** with **end-to-end encryption**:
 
-**Extension wallet example:**
+### Phase 1: Discovery
 
-```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), '*');
-}
+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
 
-// Using WebSocket:
-// websocket.send(jsonStringify(response));
-```
+### Phase 2: Secure Channel Establishment
 
-**Important Notes:**
+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
 
-- 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
+### Key Security Features
 
-## Message Format
+- **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
 
-### Wallet Method Request
+## Architecture for Extension Wallets
 
-After discovery, dApps will call wallet methods. These arrive as:
-
-```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)
-}
 ```
-
-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
-
-### Wallet Method Response
-
-Your wallet must respond with:
-
-```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
-}
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄──(discovery + port)────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (crypto+state)   │
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │              MessagePort                 │
+       └──────────(key exchange + encrypted)──────┘
 ```
 
-## Handling Wallet Methods
+**Security model:**
 
-### 1. Set Up Message Listener
+- 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
 
-**Extension wallet example:**
+## Using Pre-built Connection Handlers
 
-```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
-    return;
-  }
-
-  let data;
-  try {
-    data = JSON.parse(event.data);
-  } catch {
-    return; // Not a valid JSON message
-  }
-
-  // Handle discovery
-  if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
-    return;
-  }
-
-  // Handle wallet methods
-  if (data.messageId && data.type && data.walletId === 'my-aztec-wallet') {
-    handleWalletMethod(data);
-  }
-});
-
-// 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);
-//   }
-// });
-```
+The SDK provides `BackgroundConnectionHandler` and `ContentScriptConnectionHandler` to handle the connection flow. These are the recommended way to build extension wallets.
 
-### 2. Route to Wallet Implementation
+### Background Script Setup
 
 ```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
-
-async function handleWalletMethod(message: any) {
-  const { type, messageId, args, chainInfo, appId, walletId } = message;
-
-  try {
-    // Parse and validate chain info
-    const parsedChainInfo = ChainInfoSchema.parse(chainInfo);
-
-    // Get the wallet instance for this chain
-    const wallet = await getWalletForChain(parsedChainInfo);
-
-    // Verify the method exists on the Wallet interface
-    if (typeof wallet[type] !== 'function') {
-      throw new Error(`Unknown wallet method: ${type}`);
+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
     }
+  },
 
-    // Call the wallet method
-    const result = await wallet[type](...args);
+  // Called when key exchange completes and session is ready
+  onSessionEstablished: (session) => {
+    // Display verification emojis for user reference
+    console.log('Session emojis:', hashToEmoji(session.verificationHash));
+  },
 
-    // Send success response
-    sendResponse(messageId, walletId, result);
-  } catch (error) {
-    // Send error response
-    sendError(messageId, walletId, error);
-  }
-}
-```
+  // Called when a session is terminated
+  onSessionTerminated: (requestId) => {
+    console.log('Session terminated:', requestId);
+  },
 
-### 3. Send Response
+  // Called when a decrypted wallet message is received
+  onWalletMessage: (session, message) => {
+    // Forward to your wallet backend
+    wallet.postMessage(message);
+  },
+};
 
-**Extension wallet example:**
+const handler = new BackgroundConnectionHandler(config, transport, callbacks);
 
-```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
+// Initialize the handler to start listening
+handler.initialize();
 
-function sendResponse(messageId: string, walletId: string, result: unknown) {
-  const response = {
-    messageId,
-    result,
-    walletId,
-  };
+// User approves connection from wallet UI
+function approveConnection(requestId: string) {
+  handler.approveDiscovery(requestId);
+}
 
-  // Send as JSON string
-  window.postMessage(jsonStringify(response), '*');
+// User denies connection
+function denyConnection(requestId: string) {
+  handler.rejectDiscovery(requestId);
 }
 
-function sendError(messageId: string, walletId: string, error: Error) {
-  const response = {
-    messageId,
-    error: {
-      message: error.message,
-      stack: error.stack,
-    },
-    walletId,
-  };
-
-  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({ messageId, result, walletId }));
+// Clean up on tab close/navigate
+browser.tabs.onRemoved.addListener((tabId) => {
+  handler.terminateForTab(tabId);
+});
 ```
 
-## Parsing Messages
-
-### Using Zod Schemas
-
-Use the provided Zod schemas to parse and validate incoming messages:
+### Content Script Setup
 
 ```typescript
-import { ChainInfoSchema, WalletSchema } from '@aztec/wallet-sdk/manager';
+import {
+  ContentScriptConnectionHandler,
+  type ContentScriptTransport,
+} from '@aztec/wallet-sdk/extension/handlers';
 
-// Parse chain info
-const chainInfo = ChainInfoSchema.parse(message.chainInfo);
+const transport: ContentScriptTransport = {
+  sendToBackground: (message) => browser.runtime.sendMessage(message),
+  addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
 
-// Validate result against expected schema for a method
-const accountsResult = await wallet.getAccounts(...args);
-// The SDK handles schema validation on the client side
-```
-
-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.
-
-## Error Handling
+const handler = new ContentScriptConnectionHandler(transport);
 
-### Error Response Format
+// Start listening for discovery requests and background messages
+handler.start();
+```
 
-Always send error responses with this structure:
+## Testing Your Integration (dApp Side)
 
-```typescript
-{
-  messageId: string,               // Match the request
-  error: {
-    message: string,               // Error message
-    code?: string,                 // Optional error code
-    stack?: string                 // Optional stack trace
-  },
-  walletId: string
-}
-```
+The `WalletManager` supports two patterns for consuming discovered wallets.
 
-### Common Error Scenarios
+### Async Iterator Pattern
 
 ```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager } from '@aztec/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-async function handleWalletMethod(message: any) {
-  const { type, messageId, args, chainInfo, walletId } = message;
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
+  },
+  appId: 'my-dapp',
+  timeout: 60000,
+});
 
-  try {
-    // 1. Parse and validate chain info
-    const parsedChainInfo = ChainInfoSchema.parse(chainInfo);
+// Iterate over discovered wallets as they're approved
+for await (const provider of discovery.wallets) {
+  console.log(`Found: ${provider.name}`);
 
-    // 2. Check network support
-    if (!isNetworkSupported(parsedChainInfo)) {
-      throw new Error('Network not supported by wallet');
-    }
+  // Establish secure channel (key exchange)
+  const pending = await provider.establishSecureChannel('my-dapp');
 
-    // 3. Get wallet instance
-    const wallet = await getWalletForChain(parsedChainInfo);
+  // Display verification emojis to user
+  const emojis = hashToEmoji(pending.verificationHash);
+  console.log('Verify this matches your wallet:', emojis);
 
-    // 4. Validate method exists
-    if (typeof wallet[type] !== 'function') {
-      throw new Error(`Unknown wallet method: ${type}`);
-    }
+  // User confirms emojis match
+  const wallet = await pending.confirm();
 
-    // 5. Execute method
-    const result = await wallet[type](...args);
-    sendResponse(messageId, walletId, result);
-  } catch (error) {
-    sendError(messageId, walletId, error);
-  }
+  // All calls are now encrypted
+  const accounts = await wallet.getAccounts();
+  console.log('Accounts:', accounts);
 }
-```
 
-### User Rejection Handling
-
-If a user rejects an action:
-
-```typescript
-{
-  messageId: 'abc-123',
-  error: {
-    message: 'User rejected the request',
-    code: 'USER_REJECTED'
-  },
-  walletId: 'my-wallet'
-}
+// Cancel discovery when done or on cleanup
+discovery.cancel();
 ```
 
-## Testing Your Integration
-
-### WalletManager
-
-In a dApp using the Wallet SDK:
+### Callback Pattern
 
 ```typescript
-import { Fr } from '@aztec/foundation/curves/bn254';
-import { WalletManager } 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';
 
-const manager = WalletManager.configure({
-  extensions: { enabled: true },
-});
+const discoveredProviders: WalletProvider[] = [];
 
-// Discover wallets
-const wallets = await manager.getAvailableWallets({
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
   chainInfo: {
     chainId: new Fr(31337),
-    version: new Fr(0),
+    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
   },
-  timeout: 2000,
 });
 
-console.log('Discovered wallets:', wallets);
+// Wait for discovery to complete (or cancel early with discovery.cancel())
+await discovery.done;
+console.log('Discovery complete, found:', discoveredProviders.length);
 
-// Connect to your wallet
-const walletProvider = wallets.find(w => w.id === 'my-aztec-wallet');
-if (walletProvider) {
-  const wallet = await walletProvider.connect('test-app');
+// Connect to a selected provider
+async function connectToWallet(provider: WalletProvider) {
+  const pending = await provider.establishSecureChannel('my-dapp');
 
-  // Test wallet methods from the Wallet interface
-  const accounts = await wallet.getAccounts();
-  console.log('Accounts:', accounts);
+  // Show verification UI
+  const emojis = hashToEmoji(pending.verificationHash);
+  showVerificationDialog(emojis);
 
-  const chainInfo = await wallet.getChainInfo();
-  console.log('Chain info:', chainInfo);
+  // User confirms
+  const wallet = await pending.confirm();
+  return wallet;
 }
 ```
 
-## Reference Implementation
-
-For a complete reference implementation, see the demo wallet at:
+### React Hook Example
 
-- Repository: `~/repos/demo-wallet`
+```typescript
+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() };
+}
+```