@aztec/wallet-sdk 0.0.1-commit.96bb3f7 → 0.0.1-commit.bf2612ae

package/README.md

@@ -4,19 +4,18 @@ 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,
-  ConnectRequest,
   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';
 ```
 
 Cryptographic utilities for secure channel establishment are exported from `@aztec/wallet-sdk/crypto`:
@@ -25,434 +24,298 @@ 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,
+  hashToEmoji,
   importPublicKey,
 } from '@aztec/wallet-sdk/crypto';
 ```
 
-## Overview
-
-The Wallet SDK uses a **request-based discovery** model with **end-to-end encryption**:
-
-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** with its ECDH public key ONLY if it supports that specific network
-4. **dApp receives** only compatible wallets
-5. **dApp establishes secure channel** via ECDH key exchange (see [Secure Channel](#secure-channel))
-6. **All subsequent communication** is encrypted using AES-256-GCM
-
-### 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:**
+**For extension wallets**, pre-built connection handlers are available:
 
 ```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);
-//   }
-// });
+import {
+  BackgroundConnectionHandler,
+  ContentScriptConnectionHandler,
+} from '@aztec/wallet-sdk/extension/handlers';
 ```
 
-### 2. Discovery Message Format
-
-Discovery messages have this structure:
+## Overview
 
-```typescript
-{
-  type: 'aztec-wallet-discovery',
-  requestId: string,              // UUID for tracking this request
-  chainInfo: {
-    chainId: Fr,                  // Chain ID
-    version: Fr                   // Protocol version
-  }
-}
-```
+The Wallet SDK uses a **two-phase connection model** with **end-to-end encryption**:
 
-### 3. Check Network Support
+### Phase 1: Discovery
 
-Before responding, verify your wallet supports the requested network:
+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
 
-```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
+### Phase 2: Secure Channel Establishment
 
-function handleDiscovery(message: any) {
-  const { requestId, chainInfo } = message;
+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
 
-  // Parse and validate chain info
-  const { chainId, version } = ChainInfoSchema.parse(chainInfo);
+### Key Security Features
 
-  // Check if your wallet supports this network
-  const isSupported = checkNetworkSupport(chainId, version);
+- **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 (!isSupported) {
-    // Do NOT respond if you don't support this network
-    return;
-  }
+## Architecture for Extension Wallets
 
-  // Respond if supported
-  respondToDiscovery(requestId);
-}
 ```
-
-### 4. Respond to Discovery
-
-If your wallet supports the network, respond with your wallet information:
-
-**Extension wallet example:**
-
-```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
-
-// Your wallet should generate a key pair on initialization.
-// This keypair should be recreated each session
-let walletKeyPair: CryptoKeyPair;
-
-async function initializeWallet() {
-  // Generate ECDH key pair for secure channel establishment
-  walletKeyPair = await generateKeyPair();
-}
-
-async function respondToDiscovery(requestId: string) {
-  // Export the public key for sharing with dApps
-  const publicKey = await exportPublicKey(walletKeyPair.publicKey);
-
-  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
-      publicKey, // ECDH public key for secure channel (required)
-    },
-  };
-
-  // Send as JSON string via window.postMessage
-  window.postMessage(jsonStringify(response), '*');
-}
-
-// Using WebSocket:
-// websocket.send(jsonStringify(response));
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄──(discovery + port)────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (crypto+state)   │
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │              MessagePort                 │
+       └──────────(key exchange + encrypted)──────┘
 ```
 
-**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
-- The `publicKey` field is required for secure channel establishment
-
-## Secure Channel
+**Security model:**
 
-After discovery, the dApp establishes a secure encrypted channel with your wallet using ECDH key exchange and AES-256-GCM encryption. This ensures all wallet method calls and responses are encrypted end-to-end.
-
-### Security Model
-
-- **ECDH Key Exchange**: Uses P-256 (secp256r1) elliptic curve for key agreement
-- **AES-256-GCM Encryption**: All messages after channel establishment are encrypted
-- **Per-Session Keys**: Each connection derives a unique shared secret
-- **MessageChannel (Extension wallets)**: Uses a private MessagePort for communication, not visible to other page scripts
-
-### 1. Handle Connection Requests
+- 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 a dApp connects, it sends a `ConnectRequest` containing its ECDH public key:
+## Using Pre-built Connection Handlers
 
-```typescript
-interface ConnectRequest {
-  type: 'aztec-wallet-connect';
-  walletId: string; // Your wallet's ID
-  appId: string; // Application identifier
-  publicKey: ExportedPublicKey; // dApp's ECDH public key
-}
-```
+The SDK provides `BackgroundConnectionHandler` and `ContentScriptConnectionHandler` to handle the connection flow. These are the recommended way to build extension wallets.
 
-**Extension wallet example:**
+### Background Script Setup
 
 ```typescript
-import { decrypt, deriveSharedKey, encrypt, importPublicKey } from '@aztec/wallet-sdk/crypto';
-
-// Store connections by appId
-const connections = new Map<string, { sharedKey: CryptoKey }>();
-
-window.addEventListener('message', async event => {
-  if (event.source !== window) return;
-
-  const data = JSON.parse(event.data);
+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
+    }
+  },
 
-  if (data.type === 'aztec-wallet-connect') {
-    await handleConnect(data, event.ports[0]);
-  }
-});
+  // 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 handleConnect(request: ConnectRequest, port: MessagePort) {
-  // Import dApp's public key
-  const dappPublicKey = await importPublicKey(request.publicKey);
+  // Called when a session is terminated
+  onSessionTerminated: (requestId) => {
+    console.log('Session terminated:', requestId);
+  },
 
-  // Derive shared secret using our private key and dApp's public key
-  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);
+  },
+};
 
-  // Store the connection
-  connections.set(request.appId, { sharedKey });
+const handler = new BackgroundConnectionHandler(config, transport, callbacks);
 
-  // Set up encrypted message handler on the MessagePort
-  port.onmessage = async event => {
-    await handleEncryptedMessage(request.appId, event.data);
-  };
+// Initialize the handler to start listening
+handler.initialize();
 
-  port.start();
+// User approves connection from wallet UI
+function approveConnection(requestId: string) {
+  handler.approveDiscovery(requestId);
 }
-```
-
-### 2. Handle Encrypted Messages
-
-All wallet method calls arrive as encrypted payloads:
 
-```typescript
-interface EncryptedPayload {
-  iv: string; // Base64-encoded initialization vector
-  ciphertext: string; // Base64-encoded encrypted data
+// User denies connection
+function denyConnection(requestId: string) {
+  handler.rejectDiscovery(requestId);
 }
-```
-
-Decrypt incoming messages and encrypt responses:
 
-```typescript
-async function handleEncryptedMessage(appId: string, encrypted: EncryptedPayload) {
-  const connection = connections.get(appId);
-  if (!connection) {
-    console.error('Unknown connection');
-    return;
-  }
-
-  try {
-    // Decrypt the incoming message
-    const message = await decrypt<WalletMessage>(connection.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 response
-    const response: WalletResponse = {
-      messageId,
-      result,
-      walletId,
-    };
-
-    // Encrypt and send the response
-    const encryptedResponse = await encrypt(connection.sharedKey, response);
-    sendEncryptedResponse(appId, encryptedResponse);
-  } catch (error) {
-    // Send encrypted error response
-    const errorResponse: WalletResponse = {
-      messageId: message?.messageId ?? '',
-      error: { message: error.message },
-      walletId: message?.walletId ?? '',
-    };
-
-    const encryptedError = await encrypt(connection.sharedKey, errorResponse);
-    sendEncryptedResponse(appId, encryptedError);
-  }
+// Send response back to dApp
+async function sendWalletResponse(requestId: string, response: WalletResponse) {
+  await handler.sendResponse(requestId, response);
 }
-```
-
-### 3. Extension Wallet Architecture
-
-For browser extension wallets, the recommended architecture separates concerns:
 
+// Clean up on tab close/navigate
+browser.tabs.onRemoved.addListener((tabId) => {
+  handler.terminateForTab(tabId);
+});
 ```
-┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
-│   dApp      │◄────────────────────────►│  Content Script │◄────────────────────►│ Background Script│
-│ (web page)  │    (discovery only)      │  (message relay)│    (encrypted msgs)  │ (decrypt+process)│
-└─────────────┘                          └─────────────────┘                      └──────────────────┘
-       │                                            │
-       │         MessagePort (private channel)      │
-       └────────────────────────────────────────────┘
-                (encrypted wallet method calls)
-```
-
-**Security benefits:**
-
-- 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 the initial connection handshake uses `window.postMessage`
 
-## Message Format
-
-### Wallet Method Request
-
-After discovery, dApps will call wallet methods. These arrive as:
+### Content Script Setup
 
 ```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
+import {
+  ContentScriptConnectionHandler,
+  type ContentScriptTransport,
+} from '@aztec/wallet-sdk/extension/handlers';
 
-### Wallet Method Response
+const transport: ContentScriptTransport = {
+  sendToBackground: (message) => browser.runtime.sendMessage(message),
+  addBackgroundListener: (handler) => browser.runtime.onMessage.addListener(handler),
+};
 
-Your wallet must respond with:
+const handler = new ContentScriptConnectionHandler(transport);
 
-```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
-}
+// Start listening for discovery requests and background messages
+handler.start();
 ```
 
-## Parsing Messages
+## Testing Your Integration (dApp Side)
 
-### Using Zod Schemas
+The `WalletManager` supports two patterns for consuming discovered wallets.
 
-Use the provided Zod schemas to parse and validate incoming messages:
+### Async Iterator Pattern
 
 ```typescript
-import { ChainInfoSchema, WalletSchema } from '@aztec/wallet-sdk/manager';
-
-// Parse chain info
-const chainInfo = ChainInfoSchema.parse(message.chainInfo);
-
-// 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
-
-### Error Response Format
-
-Always send error responses with this structure:
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager } from '@aztec/wallet-sdk/manager';
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-```typescript
-{
-  messageId: string,               // Match the request
-  error: {
-    message: string,               // Error message
-    code?: string,                 // Optional error code
-    stack?: string                 // Optional stack trace
+const discovery = WalletManager.configure({
+  extensions: { enabled: true },
+}).getAvailableWallets({
+  chainInfo: {
+    chainId: new Fr(31337),
+    version: new Fr(1),
   },
-  walletId: string
-}
-```
-
-### Common Error Scenarios
+  appId: 'my-dapp',
+  timeout: 60000,
+});
 
-Common errors to handle within the encrypted message handler:
+// Iterate over discovered wallets as they're approved
+for await (const provider of discovery.wallets) {
+  console.log(`Found: ${provider.name}`);
 
-- **Network not supported**: Chain info doesn't match wallet's supported networks
-- **Unknown method**: The requested wallet method doesn't exist
-- **Invalid arguments**: Method arguments fail validation
-- **User rejection**: User declined the transaction or action
+  // Establish secure channel (key exchange)
+  const pending = await provider.establishSecureChannel('my-dapp');
 
-### User Rejection Handling
+  // Display verification emojis to user
+  const emojis = hashToEmoji(pending.verificationHash);
+  console.log('Verify this matches your wallet:', emojis);
 
-If a user rejects an action:
+  // User confirms emojis match
+  const wallet = await pending.confirm();
 
-```typescript
-{
-  messageId: 'abc-123',
-  error: {
-    message: 'User rejected the request',
-    code: 'USER_REJECTED'
-  },
-  walletId: 'my-wallet'
+  // All calls are now encrypted
+  const accounts = await wallet.getAccounts();
+  console.log('Accounts:', accounts);
 }
-```
 
-## Testing Your Integration
-
-### WalletManager
+// Cancel discovery when done or on cleanup
+discovery.cancel();
+```
 
-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
+### React Hook Example
 
-For a complete reference implementation, see the demo wallet at:
+```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]);
 
-- Repository: `~/repos/demo-wallet`
+  return { providers, isDiscovering, cancel: () => discoveryRef.current?.cancel() };
+}
+```