@aztec/wallet-sdk 4.0.0-nightly.20260113 → 4.0.0-nightly.20260115

package/README.md

@@ -4,19 +4,16 @@ 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,
   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`:
@@ -29,57 +26,54 @@ import {
   encrypt,
   exportPublicKey,
   generateKeyPair,
+  hashSharedSecret,
+  hashToEmoji,
   importPublicKey,
 } from '@aztec/wallet-sdk/crypto';
 ```
 
 ## Overview
 
-The Wallet SDK uses a **request-based discovery** model with **end-to-end encryption**:
+The Wallet SDK uses a **unified discovery and connection** 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
+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
 
-### Transport Mechanisms
+### Key Features
 
-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:
+- **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
 
-- **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
+### Transport Mechanisms
 
-The message format remains the same regardless of transport - only the delivery mechanism changes.
+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.
 
 ## Discovery Protocol
 
 ### 1. Listen for Discovery Requests
 
-**Extension wallet example:**
+**Extension wallet (content script):**
 
 ```typescript
-window.addEventListener('message', event => {
-  if (event.source !== window) {
+window.addEventListener('message', async (event) => {
+  if (event.source !== window) return;
+
+  let data: DiscoveryRequest;
+  try {
+    data = JSON.parse(event.data);
+  } catch {
     return;
   }
 
-  const data = JSON.parse(event.data);
-
   if (data.type === 'aztec-wallet-discovery') {
-    handleDiscovery(data);
+    await handleDiscoveryRequest(data);
   }
 });
-
-// Using WebSocket:
-// websocket.on('message', (message) => {
-//   const data = JSON.parse(message);
-//   if (data.type === 'aztec-wallet-discovery') {
-//     handleDiscovery(data);
-//   }
-// });
 ```
 
 ### 2. Discovery Message Format
@@ -87,194 +81,185 @@ window.addEventListener('message', event => {
 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
-  }
+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
 }
 ```
 
-### 3. Check Network Support
-
-Before responding, verify your wallet supports the requested network:
+### 3. Handle Discovery and Establish Secure Channel
 
-```typescript
-import { ChainInfoSchema } from '@aztec/wallet-sdk/manager';
-
-function handleDiscovery(message: any) {
-  const { requestId, chainInfo } = message;
+When your wallet receives a discovery request:
 
-  // Parse and validate chain info
-  const { chainId, version } = ChainInfoSchema.parse(chainInfo);
+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
 
-  // Check if your wallet supports this network
-  const isSupported = checkNetworkSupport(chainId, version);
+**Extension wallet (background script):**
 
-  if (!isSupported) {
-    // Do NOT respond if you don't support this network
-    return;
-  }
-
-  // Respond if supported
-  respondToDiscovery(requestId);
-}
-```
-
-### 4. Respond to Discovery
+```typescript
+import {
+  deriveSharedKey,
+  exportPublicKey,
+  generateKeyPair,
+  hashSharedSecret,
+  importPublicKey,
+} from '@aztec/wallet-sdk/crypto';
 
-If your wallet supports the network, respond with your wallet information:
+// Generate key pair on wallet initialization (per session)
+let walletKeyPair = await generateKeyPair();
+let walletPublicKey = await exportPublicKey(walletKeyPair.publicKey);
 
-**Extension wallet example:**
+// Store sessions by requestId
+const sessions = new Map<string, { sharedKey: CryptoKey; verificationHash: string; tabId: number }>();
 
-```typescript
-import { jsonStringify } from '@aztec/wallet-sdk/manager';
+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');
+  }
 
-// Your wallet should generate a key pair on initialization.
-// This keypair should be recreated each session
-let walletKeyPair: CryptoKeyPair;
+  // Import dApp's public key and derive shared secret
+  const dAppPublicKey = await importPublicKey(request.publicKey);
+  const sharedKey = await deriveSharedKey(walletKeyPair.privateKey, dAppPublicKey);
 
-async function initializeWallet() {
-  // Generate ECDH key pair for secure channel establishment
-  walletKeyPair = await generateKeyPair();
-}
+  // Compute verification hash for anti-MITM verification
+  const verificationHash = await hashSharedSecret(sharedKey);
 
-async function respondToDiscovery(requestId: string) {
-  // Export the public key for sharing with dApps
-  const publicKey = await exportPublicKey(walletKeyPair.publicKey);
+  // Store the session with verificationHash (emoji computed lazily for display)
+  sessions.set(request.requestId, { sharedKey, verificationHash, tabId });
 
-  const response = {
+  const response: DiscoveryResponse = {
     type: 'aztec-wallet-discovery-response',
-    requestId,
+    requestId: request.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)
+      id: 'my-aztec-wallet',
+      name: 'My Aztec Wallet',
+      version: '1.0.0',
+      publicKey: walletPublicKey,
     },
   };
 
-  // Send as JSON string via window.postMessage
-  window.postMessage(jsonStringify(response), '*');
+  return { success: true, response };
 }
-
-// Using WebSocket:
-// websocket.send(jsonStringify(response));
 ```
 
-**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
-
-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
-
-When a dApp connects, it sends a `ConnectRequest` containing its ECDH public key:
+**Content script (creates MessageChannel and sends response):**
 
 ```typescript
-interface ConnectRequest {
-  type: 'aztec-wallet-connect';
-  walletId: string; // Your wallet's ID
-  appId: string; // Application identifier
-  publicKey: ExportedPublicKey; // dApp's ECDH public key
+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();
+
+  // Send response with port2 to the page
+  window.postMessage(JSON.stringify(result.response), '*', [channel.port2]);
 }
 ```
 
-**Extension wallet example:**
+### 4. Discovery Response Format
 
 ```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;
+interface DiscoveryResponse {
+  type: 'aztec-wallet-discovery-response';
+  requestId: string;              // Must match the request
+  walletInfo: WalletInfo;         // Wallet info including public key
+}
 
-  const data = JSON.parse(event.data);
+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
+}
+```
 
-  if (data.type === 'aztec-wallet-connect') {
-    await handleConnect(data, event.ports[0]);
-  }
-});
+**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.
 
-async function handleConnect(request: ConnectRequest, port: MessagePort) {
-  // Import dApp's public key
-  const dappPublicKey = await importPublicKey(request.publicKey);
+## Secure Communication
 
-  // Derive shared secret using our private key and dApp's public key
-  const sharedKey = await deriveSharedKey(walletKeyPair.privateKey, dappPublicKey);
+### Architecture for Extension Wallets
 
-  // Store the connection
-  connections.set(request.appId, { sharedKey });
+```
+┌─────────────┐    window.postMessage    ┌─────────────────┐    browser.runtime   ┌──────────────────┐
+│   dApp      │◄───(discovery only)─────►│  Content Script │◄────────────────────►│ Background Script│
+│ (web page)  │                          │  (message relay)│                      │ (decrypt+process)│
+└─────────────┘                          └─────────────────┘                      └──────────────────┘
+       │                                          │
+       │         MessagePort (private channel)    │
+       └──────────(encrypted messages)────────────┘
+```
 
-  // Set up encrypted message handler on the MessagePort
-  port.onmessage = async event => {
-    await handleEncryptedMessage(request.appId, event.data);
-  };
+**Security benefits:**
 
-  port.start();
-}
-```
+- 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
 
-### 2. Handle Encrypted Messages
+### Handle Encrypted Messages
 
-All wallet method calls arrive as encrypted payloads:
+All wallet method calls arrive as encrypted payloads on the MessagePort:
 
 ```typescript
 interface EncryptedPayload {
-  iv: string; // Base64-encoded initialization vector
+  iv: string;         // Base64-encoded initialization vector
   ciphertext: string; // Base64-encoded encrypted data
 }
 ```
 
-Decrypt incoming messages and encrypt responses:
+**Background script:**
 
 ```typescript
-async function handleEncryptedMessage(appId: string, encrypted: EncryptedPayload) {
-  const connection = connections.get(appId);
-  if (!connection) {
-    console.error('Unknown connection');
-    return;
-  }
+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>(connection.sharedKey, encrypted);
-
+    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 response
-    const response: WalletResponse = {
-      messageId,
-      result,
-      walletId,
-    };
+    // Create and encrypt response
+    const response: WalletResponse = { messageId, result, walletId };
+    const encryptedResponse = await encrypt(session.sharedKey, response);
 
-    // Encrypt and send the response
-    const encryptedResponse = await encrypt(connection.sharedKey, response);
-    sendEncryptedResponse(appId, encryptedResponse);
+    // Send back through content script
+    browser.tabs.sendMessage(session.tabId, {
+      type: 'secure-response',
+      requestId,
+      content: encryptedResponse,
+    });
   } catch (error) {
     // Send encrypted error response
     const errorResponse: WalletResponse = {
@@ -282,151 +267,105 @@ async function handleEncryptedMessage(appId: string, encrypted: EncryptedPayload
       error: { message: error.message },
       walletId: message?.walletId ?? '',
     };
-
-    const encryptedError = await encrypt(connection.sharedKey, errorResponse);
-    sendEncryptedResponse(appId, encryptedError);
+    const encryptedError = await encrypt(session.sharedKey, errorResponse);
+    // ... send error response
   }
 }
 ```
 
-### 3. Extension Wallet Architecture
-
-For browser extension wallets, the recommended architecture separates concerns:
-
-```
-┌─────────────┐    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
+## Message Formats
 
-After discovery, dApps will call wallet methods. These arrive as:
+### Wallet Method Request (Decrypted)
 
 ```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)
+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
 }
 ```
 
-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
+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
 }
 ```
 
-## Parsing Messages
+## Anti-MITM Verification
 
-### Using Zod Schemas
-
-Use the provided Zod schemas to parse and validate incoming messages:
+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.
 
 ```typescript
-import { ChainInfoSchema, WalletSchema } from '@aztec/wallet-sdk/manager';
+import { hashSharedSecret } from '@aztec/wallet-sdk/crypto';
 
-// Parse chain info
-const chainInfo = ChainInfoSchema.parse(message.chainInfo);
+// Compute verification hash from shared key
+const verificationHash = await hashSharedSecret(sharedKey);
 
-// Validate result against expected schema for a method
-const accountsResult = await wallet.getAccounts(...args);
-// The SDK handles schema validation on the client side
+// Store verificationHash in session - this is the cryptographic proof
+sessions.set(requestId, { sharedKey, verificationHash, tabId });
 ```
 
-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:
+For user-friendly display, convert the hash to an emoji sequence:
 
 ```typescript
-{
-  messageId: string,               // Match the request
-  error: {
-    message: string,               // Error message
-    code?: string,                 // Optional error code
-    stack?: string                 // Optional stack trace
-  },
-  walletId: string
-}
-```
+import { hashToEmoji } from '@aztec/wallet-sdk/crypto';
 
-### Common Error Scenarios
+// Convert to emoji only when displaying to the user
+const emoji = hashToEmoji(verificationHash);  // e.g., "🔵🦋🎯🐼"
+```
 
-Common errors to handle within the encrypted message handler:
+The dApp displays the same emoji sequence. If they match, the connection is secure.
 
-- **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
+## Session Management
 
-### User Rejection Handling
+Sessions should be cleaned up when:
 
-If a user rejects an action:
+- **Tab closes**: Browser tabs API `onRemoved` event
+- **Tab navigates**: Browser tabs API `onUpdated` event with `status === 'loading'`
 
 ```typescript
-{
-  messageId: 'abc-123',
-  error: {
-    message: 'User rejected the request',
-    code: 'USER_REJECTED'
-  },
-  walletId: 'my-wallet'
-}
+// Clean up when tab closes
+browser.tabs.onRemoved.addListener((tabId) => {
+  for (const [requestId, session] of sessions) {
+    if (session.tabId === tabId) {
+      sessions.delete(requestId);
+    }
+  }
+});
+
+// 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);
+      }
+    }
+  }
+});
 ```
 
 ## Testing Your Integration
 
-### WalletManager
-
-In a dApp using the Wallet SDK:
+### Using WalletManager
 
 ```typescript
-import { Fr } from '@aztec/foundation/curves/bn254';
-import { WalletManager } from '@aztec/wallet-sdk/manager';
+import { Fr } from '@aztec/foundation/fields';
+import { WalletManager, hashToEmoji } from '@aztec/wallet-sdk/manager';
 
 const manager = WalletManager.configure({
   extensions: { enabled: true },
 });
 
-// Discover wallets
+// Discover wallets (secure channel established automatically)
 const wallets = await manager.getAvailableWallets({
   chainInfo: {
     chainId: new Fr(31337),
@@ -435,19 +374,20 @@ const wallets = await manager.getAvailableWallets({
   timeout: 2000,
 });
 
-console.log('Discovered wallets:', wallets);
+// Each wallet provider has verification info
+for (const provider of wallets) {
+  const emoji = hashToEmoji(provider.metadata.verificationHash);
+  console.log(`${provider.name}: ${emoji}`);
+}
 
-// Connect to your wallet
+// Connect and use
 const walletProvider = wallets.find(w => w.id === 'my-aztec-wallet');
 if (walletProvider) {
-  const wallet = await walletProvider.connect('test-app');
+  const wallet = await walletProvider.connect('my-app-id');
 
-  // Test wallet methods from the Wallet interface
+  // All calls are automatically encrypted
   const accounts = await wallet.getAccounts();
   console.log('Accounts:', accounts);
-
-  const chainInfo = await wallet.getChainInfo();
-  console.log('Chain info:', chainInfo);
 }
 ```