@aztec/wallet-sdk 0.0.1-commit.9ef841308 → 0.0.1-commit.a5db02d

package/src/base-wallet/utils.ts

@@ -1,4 +1,5 @@
 import type { AztecNode } from '@aztec/aztec.js/node';
+import { TxSimulationResultWithAppOffset } from '@aztec/aztec.js/wallet';
 import { MAX_ENQUEUED_CALLS_PER_CALL } from '@aztec/constants';
 import type { ChainInfo } from '@aztec/entrypoints/interfaces';
 import { makeTuple } from '@aztec/foundation/array';
@@ -24,6 +25,7 @@ import {
   PrivateCallExecutionResult,
   PrivateExecutionResult,
   PublicSimulationOutput,
+  type SimulationOverrides,
   Tx,
   TxContext,
   TxSimulationResult,
@@ -64,6 +66,8 @@ export function extractOptimizablePublicStaticCalls(payload: ExecutionPayload):
  * @param gasSettings - Gas settings for the transaction.
  * @param blockHeader - Block header to use as anchor.
  * @param skipFeeEnforcement - Whether to skip fee enforcement during simulation.
+ * @param getContractName - Resolver for contract names (used for debug log display).
+ * @param overrides - Optional pre-simulation overrides applied to the ephemeral fork and contract DB.
  * @returns TxSimulationResult with public return values.
  */
 async function simulateBatchViaNode(
@@ -75,6 +79,7 @@ async function simulateBatchViaNode(
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean,
   getContractName: ContractNameResolver,
+  overrides?: SimulationOverrides,
 ): Promise<TxSimulationResult> {
   const txContext = new TxContext(chainInfo.chainId, chainInfo.version, gasSettings);
 
@@ -142,7 +147,7 @@ async function simulateBatchViaNode(
     publicFunctionCalldata: publicFunctionCalldata,
   });
 
-  const publicOutput = await node.simulatePublicCalls(tx, skipFeeEnforcement);
+  const publicOutput = await node.simulatePublicCalls(tx, skipFeeEnforcement, overrides);
 
   if (publicOutput.revertReason) {
     throw publicOutput.revertReason;
@@ -165,6 +170,8 @@ async function simulateBatchViaNode(
  * @param gasSettings - Gas settings for the transaction.
  * @param blockHeader - Block header to use as anchor.
  * @param skipFeeEnforcement - Whether to skip fee enforcement during simulation.
+ * @param getContractName - Resolver for contract names (used for debug log display).
+ * @param overrides - Optional pre-simulation overrides applied to the ephemeral fork and contract DB.
  * @returns Array of TxSimulationResult, one per batch.
  */
 export async function simulateViaNode(
@@ -176,6 +183,7 @@ export async function simulateViaNode(
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean = true,
   getContractName: ContractNameResolver,
+  overrides?: SimulationOverrides,
 ): Promise<TxSimulationResult[]> {
   const batches: FunctionCall[][] = [];
 
@@ -195,6 +203,7 @@ export async function simulateViaNode(
       blockHeader,
       skipFeeEnforcement,
       getContractName,
+      overrides,
     );
     results.push(result);
   }
@@ -214,13 +223,13 @@ export async function simulateViaNode(
  */
 export function buildMergedSimulationResult(
   optimizedResults: TxSimulationResult[],
-  normalResult: TxSimulationResult | null,
-): TxSimulationResult {
+  normalResult: TxSimulationResultWithAppOffset | null,
+): TxSimulationResultWithAppOffset {
   const optimizedReturnValues = optimizedResults.flatMap(r => r.publicOutput?.publicReturnValues ?? []);
   const normalReturnValues = normalResult?.publicOutput?.publicReturnValues ?? [];
   const allReturnValues = [...optimizedReturnValues, ...normalReturnValues];
 
-  const baseResult = normalResult ?? optimizedResults[0];
+  const baseResult: TxSimulationResult = normalResult ?? optimizedResults[0];
 
   const mergedPublicOutput: PublicSimulationOutput | undefined = baseResult.publicOutput
     ? {
@@ -229,10 +238,11 @@ export function buildMergedSimulationResult(
       }
     : undefined;
 
-  return new TxSimulationResult(
+  const merged = new TxSimulationResult(
     baseResult.privateExecutionResult,
     baseResult.publicInputs,
     mergedPublicOutput,
     normalResult?.stats,
   );
+  return TxSimulationResultWithAppOffset.fromResultAndOffset(merged, normalResult?.appCallOffset ?? 0);
 }

package/src/extension/handlers/background_connection_handler.ts

@@ -17,6 +17,7 @@ import {
   type WalletMessage,
   WalletMessageType,
   type WalletResponse,
+  type WalletSdkLogger,
 } from '../../types.js';
 import {
   type BackgroundMessage,
@@ -131,6 +132,8 @@ export interface BackgroundConnectionConfig {
   walletVersion: string;
   /** Optional wallet icon URL. */
   walletIcon?: string;
+  /** Logger used for diagnostics. */
+  logger: WalletSdkLogger;
 }
 
 /**
@@ -149,6 +152,7 @@ export interface BackgroundConnectionConfig {
  *     walletId: 'my-wallet',
  *     walletName: 'My Wallet',
  *     walletVersion: '1.0.0',
+ *     logger: console,
  *   },
  *   {
  *     sendToTab: (tabId, message) => browser.tabs.sendMessage(tabId, message),
@@ -167,12 +171,15 @@ export interface BackgroundConnectionConfig {
 export class BackgroundConnectionHandler {
   private pendingDiscoveries = new Map<string, PendingDiscovery>();
   private activeSessions = new Map<string, ActiveSession>();
+  private log: WalletSdkLogger;
 
   constructor(
     private config: BackgroundConnectionConfig,
     private transport: BackgroundTransport,
     private callbacks: BackgroundConnectionCallbacks = {},
-  ) {}
+  ) {
+    this.log = config.logger;
+  }
 
   initialize(): void {
     this.transport.addContentListener(this.handleMessage);
@@ -198,8 +205,8 @@ export class BackgroundConnectionHandler {
         break;
       case InternalMessageType.KEY_EXCHANGE_REQUEST:
         if (sessionId) {
-          this.handleKeyExchangeRequest(sessionId, content as KeyExchangeRequest).catch(() => {
-            // Key exchange failed - session won't be established
+          this.handleKeyExchangeRequest(sessionId, content as KeyExchangeRequest).catch(err => {
+            this.log.warn('Key exchange failed — session will not be established', { sessionId, err });
           });
         }
         break;
@@ -213,9 +220,31 @@ export class BackgroundConnectionHandler {
           void this.handleEncryptedMessage(sessionId, content as EncryptedPayload);
         }
         break;
+      case InternalMessageType.PING:
+        if (sessionId) {
+          this.handlePing(sessionId);
+        }
+        break;
     }
   };
 
+  /**
+   * Reply to a dApp PING with a PONG. Used as a liveness probe so the dApp can
+   * tell the difference between a slow request and a dead extension.
+   * @param sessionId - The session that sent the PING.
+   */
+  private handlePing(sessionId: string): void {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+    this.transport.sendToTab(session.tabId, {
+      origin: MessageOrigin.BACKGROUND,
+      type: InternalMessageType.PONG,
+      sessionId,
+    });
+  }
+
   getWalletInfo(): WalletInfo {
     return {
       id: this.config.walletId,
@@ -315,8 +344,8 @@ export class BackgroundConnectionHandler {
       });
 
       this.callbacks.onSessionEstablished?.(session);
-    } catch {
-      // Key exchange failed silently - session won't be established
+    } catch (err) {
+      this.log.warn('Key exchange failed — session will not be established', { sessionId, err });
     }
   }
 
@@ -329,8 +358,8 @@ export class BackgroundConnectionHandler {
     try {
       const message = await decrypt<WalletMessage>(session.sharedKey, encrypted);
       this.callbacks.onWalletMessage?.(session, message);
-    } catch {
-      // Decryption failed - ignore malformed message
+    } catch (err) {
+      this.log.warn('Failed to decrypt incoming wallet message', { sessionId, err });
     }
   }
 
@@ -348,8 +377,12 @@ export class BackgroundConnectionHandler {
         sessionId,
         content: encrypted,
       });
-    } catch {
-      // Encryption failed - response won't be sent
+    } catch (err) {
+      this.log.error('Failed to encrypt wallet response — response will not be sent', {
+        sessionId,
+        messageId: response.messageId,
+        err,
+      });
     }
   }
 

package/src/extension/handlers/content_script_connection_handler.ts

@@ -139,9 +139,20 @@ export class ContentScriptConnectionHandler {
       case InternalMessageType.SESSION_DISCONNECTED:
         this.handleSessionDisconnected(sessionId);
         break;
+      case InternalMessageType.PONG:
+        this.handlePong(sessionId);
+        break;
     }
   };
 
+  private handlePong(sessionId: string): void {
+    const connection = this.ports.get(sessionId);
+    if (!connection) {
+      return;
+    }
+    connection.port.postMessage({ type: WalletMessageType.PONG });
+  }
+
   private handleDiscoveryRequest(request: DiscoveryRequest): void {
     this.transport.sendToBackground({
       origin: MessageOrigin.CONTENT_SCRIPT,
@@ -178,6 +189,13 @@ export class ContentScriptConnectionHandler {
             content: data,
           });
           break;
+        case WalletMessageType.PING:
+          this.transport.sendToBackground({
+            origin: MessageOrigin.CONTENT_SCRIPT,
+            type: InternalMessageType.PING,
+            sessionId,
+          });
+          break;
         default:
           this.transport.sendToBackground({
             origin: MessageOrigin.CONTENT_SCRIPT,

package/src/extension/handlers/internal_message_types.ts

@@ -9,11 +9,13 @@ export const InternalMessageType = {
   KEY_EXCHANGE_REQUEST: 'key-exchange-request',
   SECURE_MESSAGE: 'secure-message',
   DISCONNECT_REQUEST: 'disconnect-request',
+  PING: 'ping',
   // Background → Content script
   DISCOVERY_APPROVED: 'discovery-approved',
   KEY_EXCHANGE_RESPONSE: 'key-exchange-response',
   SECURE_RESPONSE: 'secure-response',
   SESSION_DISCONNECTED: 'session-disconnected',
+  PONG: 'pong',
 } as const;
 
 /**

package/src/extension/provider/extension_wallet.ts

@@ -2,11 +2,21 @@ import type { ChainInfo } from '@aztec/aztec.js/account';
 import { type Wallet, WalletSchema } from '@aztec/aztec.js/wallet';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
-import { schemaHasMethod } from '@aztec/foundation/schemas';
+import { getSchemaReturnType, schemaHasMethod } from '@aztec/foundation/schemas';
 import type { FunctionsOf } from '@aztec/foundation/types';
 
 import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
-import { type DisconnectCallback, type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
+import {
+  DEFAULT_HEARTBEAT_DEAD_AFTER_MS,
+  DEFAULT_HEARTBEAT_INTERVAL_MS,
+  type DisconnectCallback,
+  type HeartbeatOptions,
+  NOOP_LOGGER,
+  type WalletMessage,
+  WalletMessageType,
+  type WalletResponse,
+  type WalletSdkLogger,
+} from '../../types.js';
 
 /**
  * Internal type representing a wallet method call before encryption.
@@ -55,6 +65,11 @@ export class ExtensionWallet {
   private inFlight = new Map<string, PromiseWithResolvers<unknown>>();
   private disconnected = false;
   private disconnectCallbacks: DisconnectCallback[] = [];
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private lastInboundAt = 0;
+  private log: WalletSdkLogger;
+  private heartbeatIntervalMs: number;
+  private heartbeatDeadAfterMs: number;
 
   /**
    * Private constructor - use {@link ExtensionWallet.create} to instantiate.
@@ -63,6 +78,8 @@ export class ExtensionWallet {
    * @param extensionId - The unique identifier of the target wallet extension
    * @param port - The MessagePort for private communication with the wallet
    * @param sharedKey - The derived AES-256-GCM shared key for encryption
+   * @param logger - Optional logger; defaults to a no-op logger
+   * @param heartbeatOptions - Optional heartbeat tuning (mostly useful for tests)
    */
   private constructor(
     private chainInfo: ChainInfo,
@@ -70,7 +87,13 @@ export class ExtensionWallet {
     private extensionId: string,
     private port: MessagePort,
     private sharedKey: CryptoKey,
-  ) {}
+    logger?: WalletSdkLogger,
+    heartbeatOptions?: HeartbeatOptions,
+  ) {
+    this.log = logger ?? NOOP_LOGGER;
+    this.heartbeatIntervalMs = heartbeatOptions?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.heartbeatDeadAfterMs = heartbeatOptions?.deadAfterMs ?? DEFAULT_HEARTBEAT_DEAD_AFTER_MS;
+  }
 
   /**
    * Creates a Wallet that communicates with a browser extension
@@ -81,6 +104,8 @@ export class ExtensionWallet {
    * @param sharedKey - The derived AES-256-GCM shared key for encryption
    * @param chainInfo - The chain information (chainId and version) for request context
    * @param appId - Application identifier used to identify the requesting dApp to the wallet
+   * @param logger - Optional logger; defaults to a no-op logger to keep extension/page bundles small
+   * @param heartbeatOptions - Optional override for heartbeat tuning (mostly useful for tests)
    * @returns A Wallet interface where all method calls are encrypted
    *
    * @example
@@ -104,13 +129,17 @@ export class ExtensionWallet {
     sharedKey: CryptoKey,
     chainInfo: ChainInfo,
     appId: string,
+    logger?: WalletSdkLogger,
+    heartbeatOptions?: HeartbeatOptions,
   ): ExtensionWallet {
-    const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey);
+    const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey, logger, heartbeatOptions);
 
     // Set up message handler for encrypted responses and unencrypted control messages
     wallet.port.onmessage = (event: MessageEvent) => {
       const data = event.data;
-      // Check for unencrypted disconnect notification
+      // Any inbound traffic counts as proof of liveness.
+      wallet.lastInboundAt = Date.now();
+
       if (data && typeof data === 'object' && 'type' in data && data.type === WalletMessageType.DISCONNECT) {
         wallet.handleDisconnect();
         return;
@@ -131,7 +160,7 @@ export class ExtensionWallet {
               type: prop.toString() as keyof FunctionsOf<Wallet>,
               args,
             });
-            return WalletSchema[prop.toString() as keyof typeof WalletSchema].returnType().parseAsync(result);
+            return getSchemaReturnType(WalletSchema[prop.toString() as keyof typeof WalletSchema]).parseAsync(result);
           };
         } else {
           return target[prop as keyof ExtensionWallet];
@@ -184,8 +213,10 @@ export class ExtensionWallet {
         resolve(result);
       }
       this.inFlight.delete(messageId);
-      // eslint-disable-next-line no-empty
-    } catch {}
+      this.maybeStopHeartbeat();
+    } catch (err) {
+      this.log.warn('Failed to decrypt wallet response', { err });
+    }
   }
 
   /**
@@ -223,9 +254,59 @@ export class ExtensionWallet {
 
     const { promise, resolve, reject } = promiseWithResolvers<unknown>();
     this.inFlight.set(messageId, { promise, resolve, reject });
+    this.startHeartbeat();
     return promise;
   }
 
+  /**
+   * Start the heartbeat probe loop while at least one request is in flight.
+   * Idempotent — calling while already running is a no-op.
+   *
+   * Heartbeat is opt-in via wire protocol: PINGs are unencrypted control messages
+   * (like DISCONNECT). Older wallets that do not understand PING simply drop it,
+   * which is safe — we only declare disconnect when **no** inbound traffic of any
+   * kind (PONG, encrypted response, DISCONNECT) arrives within the dead window.
+   * A wallet that is processing a slow request will reset the timer when it
+   * eventually responds, so this never causes false disconnects on legacy peers.
+   */
+  private startHeartbeat(): void {
+    if (this.heartbeatTimer !== null || this.disconnected) {
+      return;
+    }
+    this.lastInboundAt = Date.now();
+    this.heartbeatTimer = setInterval(() => this.heartbeatTick(), this.heartbeatIntervalMs);
+  }
+
+  private maybeStopHeartbeat(): void {
+    if (this.inFlight.size === 0 && this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private heartbeatTick(): void {
+    if (this.disconnected || this.inFlight.size === 0) {
+      this.maybeStopHeartbeat();
+      return;
+    }
+
+    const idleMs = Date.now() - this.lastInboundAt;
+    if (idleMs >= this.heartbeatDeadAfterMs) {
+      this.log.warn('Wallet channel unresponsive — declaring disconnect', {
+        idleMs,
+        inFlight: this.inFlight.size,
+      });
+      this.handleDisconnect();
+      return;
+    }
+
+    try {
+      this.port.postMessage({ type: WalletMessageType.PING });
+    } catch (err) {
+      this.log.warn('Failed to send heartbeat PING', { err });
+    }
+  }
+
   /**
    * Handles wallet disconnection.
    * Rejects all pending requests and notifies registered callbacks.
@@ -237,6 +318,11 @@ export class ExtensionWallet {
     }
     this.disconnected = true;
 
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
     if (this.port) {
       this.port.onmessage = null;
       this.port.close();

package/src/iframe/handlers/iframe_connection_handler.ts

@@ -14,11 +14,10 @@
  * so the dApp knows it can send a discovery request.
  */
 import type { ChainInfo } from '@aztec/aztec.js/account';
-import { createLogger } from '@aztec/aztec.js/log';
 import type { Wallet } from '@aztec/aztec.js/wallet';
 import { WalletSchema } from '@aztec/aztec.js/wallet';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
-import { parseWithOptionals, schemaHasMethod } from '@aztec/foundation/schemas';
+import { getSchemaParameters, parseWithOptionals, schemaHasMethod } from '@aztec/foundation/schemas';
 
 import {
   type EncryptedPayload,
@@ -29,7 +28,7 @@ import {
   generateKeyPair,
   importPublicKey,
 } from '../../crypto.js';
-import { type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
+import { type WalletMessage, WalletMessageType, type WalletResponse, type WalletSdkLogger } from '../../types.js';
 
 /**
  * A pending discovery request from a dApp (before user approval).
@@ -75,6 +74,8 @@ export interface IframeConnectionConfig {
   walletIcon?: string;
   /** Origins allowed to connect. If empty or undefined, all origins are allowed (dev mode). */
   allowedOrigins?: string[];
+  /** Logger used for diagnostics. */
+  logger: WalletSdkLogger;
 }
 
 /**
@@ -105,7 +106,7 @@ export interface IframeConnectionCallbacks {
  * @example
  * ```typescript
  * const handler = new IframeConnectionHandler(
- *   { walletId: 'my-wallet', walletName: 'My Wallet', walletVersion: '1.0.0' },
+ *   { walletId: 'my-wallet', walletName: 'My Wallet', walletVersion: '1.0.0', logger: console },
  *   {
  *     onPendingDiscovery: (session) => showApprovalUI(session),
  *     getWallet: (appId, chainInfo) => createWalletForApp(appId, chainInfo),
@@ -117,12 +118,14 @@ export interface IframeConnectionCallbacks {
 export class IframeConnectionHandler {
   private pendingSessions = new Map<string, PendingSession>();
   private activeSessions = new Map<string, ActiveSession>();
-  private log = createLogger('wallet:iframe-handler');
+  private log: WalletSdkLogger;
 
   constructor(
     private config: IframeConnectionConfig,
     private callbacks: IframeConnectionCallbacks,
-  ) {}
+  ) {
+    this.log = config.logger;
+  }
 
   start(): void {
     window.addEventListener('message', this.handleMessage);
@@ -203,7 +206,18 @@ export class IframeConnectionHandler {
       case WalletMessageType.DISCONNECT:
         this.terminateSession(msg.sessionId);
         break;
+      case WalletMessageType.PING:
+        this.handlePing(msg.sessionId);
+        break;
+    }
+  }
+
+  private handlePing(sessionId: string): void {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) {
+      return;
     }
+    this.postToOrigin(session.origin, { type: WalletMessageType.PONG, sessionId });
   }
 
   private handleDiscoveryRequest(msg: Record<string, unknown>, origin: string): void {
@@ -287,8 +301,7 @@ export class IframeConnectionHandler {
       if (!schemaHasMethod(WalletSchema, type)) {
         throw new Error(`Unknown wallet method: ${type}`);
       }
-      // Zod's AnyZodTuple rejects optional tuple items typed as `T | undefined`
-      const sanitizedArgs = await parseWithOptionals(args, WalletSchema[type].parameters() as any);
+      const sanitizedArgs = await parseWithOptionals(args, getSchemaParameters(WalletSchema[type]));
       result = await (wallet as Record<string, (...a: unknown[]) => Promise<unknown>>)[type](...sanitizedArgs);
     } catch (err: unknown) {
       error = err instanceof Error ? err.message : String(err);