@aztec/wallet-sdk 0.0.1-commit.fff30aa → 0.0.1-private.3d175340d2

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);

package/src/iframe/provider/iframe_wallet.ts

@@ -10,11 +10,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.
@@ -46,6 +56,11 @@ export class IframeWallet {
   private disconnected = false;
   private disconnectCallbacks: DisconnectCallback[] = [];
   private messageListener: ((e: MessageEvent) => void) | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private lastInboundAt = 0;
+  private log: WalletSdkLogger;
+  private heartbeatIntervalMs: number;
+  private heartbeatDeadAfterMs: number;
 
   private constructor(
     private chainInfo: ChainInfo,
@@ -55,7 +70,13 @@ export class IframeWallet {
     private iframeWindow: Window,
     private walletOrigin: string,
     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 proxied IframeWallet that implements the {@link Wallet} interface.
@@ -71,6 +92,8 @@ export class IframeWallet {
    * @param sharedKey - AES-256-GCM key derived from ECDH key exchange
    * @param chainInfo - Network information (chainId and version)
    * @param appId - Application identifier for the requesting dApp
+   * @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 proxied IframeWallet — call `.asWallet()` to get the typed `Wallet`
    */
   static create(
@@ -81,8 +104,20 @@ export class IframeWallet {
     sharedKey: CryptoKey,
     chainInfo: ChainInfo,
     appId: string,
+    logger?: WalletSdkLogger,
+    heartbeatOptions?: HeartbeatOptions,
   ): IframeWallet {
-    const wallet = new IframeWallet(chainInfo, appId, walletId, sessionId, iframeWindow, walletOrigin, sharedKey);
+    const wallet = new IframeWallet(
+      chainInfo,
+      appId,
+      walletId,
+      sessionId,
+      iframeWindow,
+      walletOrigin,
+      sharedKey,
+      logger,
+      heartbeatOptions,
+    );
 
     wallet.messageListener = (event: MessageEvent) => {
       if (event.origin !== walletOrigin) {
@@ -93,9 +128,16 @@ export class IframeWallet {
         return;
       }
 
-      if (msg.type === WalletMessageType.SECURE_RESPONSE && msg.sessionId === sessionId) {
+      if (msg.sessionId !== sessionId) {
+        return;
+      }
+
+      // Any inbound traffic on our session counts as proof of liveness.
+      wallet.lastInboundAt = Date.now();
+
+      if (msg.type === WalletMessageType.SECURE_RESPONSE) {
         void wallet.handleEncryptedResponse(msg.encrypted as EncryptedPayload);
-      } else if (msg.type === WalletMessageType.SESSION_DISCONNECTED && msg.sessionId === sessionId) {
+      } else if (msg.type === WalletMessageType.SESSION_DISCONNECTED) {
         wallet.handleDisconnect();
       }
     };
@@ -111,7 +153,7 @@ export class IframeWallet {
               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 IframeWallet];
@@ -148,8 +190,9 @@ export class IframeWallet {
         pending.resolve(result);
       }
       this.inFlight.delete(messageId);
-    } catch {
-      // Decryption errors are silently ignored (message not for us or corrupted)
+      this.maybeStopHeartbeat();
+    } catch (err) {
+      this.log.warn('Failed to decrypt wallet response', { err });
     }
   }
 
@@ -176,15 +219,66 @@ export class IframeWallet {
 
     const { promise, resolve, reject } = promiseWithResolvers<unknown>();
     this.inFlight.set(messageId, { promise, resolve, reject });
+    this.startHeartbeat();
     return promise;
   }
 
+  /**
+   * Start liveness probing while at least one request is in flight. PINGs are
+   * unencrypted control messages — older wallet handlers that don't understand
+   * them simply drop them, but any inbound traffic (PONG, encrypted response,
+   * disconnect notice) resets the idle timer, so a slow-but-alive legacy wallet
+   * never trips a false disconnect.
+   */
+  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('Iframe wallet channel unresponsive — declaring disconnect', {
+        idleMs,
+        inFlight: this.inFlight.size,
+      });
+      this.handleDisconnect();
+      return;
+    }
+
+    try {
+      this.iframeWindow.postMessage({ type: WalletMessageType.PING, sessionId: this.sessionId }, this.walletOrigin);
+    } catch (err) {
+      this.log.warn('Failed to send heartbeat PING', { err });
+    }
+  }
+
   private handleDisconnect(): void {
     if (this.disconnected) {
       return;
     }
     this.disconnected = true;
 
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
     if (this.messageListener) {
       window.removeEventListener('message', this.messageListener);
       this.messageListener = null;

package/src/types.ts

@@ -25,6 +25,13 @@ export enum WalletMessageType {
   SECURE_RESPONSE = 'aztec-wallet-secure-response',
   /** Session disconnected notification */
   SESSION_DISCONNECTED = 'aztec-wallet-session-disconnected',
+  /** Liveness probe sent by the dApp while a request is in flight */
+  PING = 'aztec-wallet-ping',
+  /** Liveness response from the wallet. Any inbound message (including a regular
+   * encrypted response) is treated as proof of liveness, so a missing PONG alone
+   * never trips disconnect — the dApp also resets its liveness timer on traffic.
+   */
+  PONG = 'aztec-wallet-pong',
 }
 
 /**
@@ -143,3 +150,55 @@ export interface KeyExchangeResponse {
  * Callback invoked when a wallet connection is disconnected.
  */
 export type DisconnectCallback = () => void;
+
+/**
+ * Default heartbeat tuning shared by both transports.
+ *
+ * - `intervalMs`: how often the dApp sends PING probes while a request is in flight.
+ * - `deadAfterMs`: how long the channel can stay silent (no PONG, no encrypted
+ *   response, no DISCONNECT) before the dApp declares the wallet unreachable
+ *   and rejects all in-flight requests. Generous enough that long-running
+ *   operations (proveTx, sendTx) on legacy wallets that don't reply to PING
+ *   still succeed — any inbound traffic resets the timer.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+export const DEFAULT_HEARTBEAT_DEAD_AFTER_MS = 300_000;
+
+/** Override knobs for the heartbeat — mostly useful for tests. */
+export interface HeartbeatOptions {
+  /** How often to send PING probes while a request is in flight (ms). */
+  intervalMs?: number;
+  /** Idle ceiling before declaring disconnect (ms). */
+  deadAfterMs?: number;
+}
+
+/**
+ * Minimal logger surface used by the wallet SDK.
+ *
+ * Defined locally so that wallet hosts (browser extensions, iframe wallet pages)
+ * can pass a simple `console`-backed logger without pulling in the full
+ * `@aztec/foundation` logging runtime, which is non-trivial to bundle in those
+ * contexts. Structurally compatible with `Logger` from `@aztec/foundation/log`,
+ * so dApp-side callers can pass that type directly.
+ */
+export interface WalletSdkLogger {
+  /** Diagnostic messages — typically discarded in production. */
+  debug: (message: string, data?: unknown) => void;
+  /** Informational messages — significant lifecycle events. */
+  info: (message: string, data?: unknown) => void;
+  /** Recoverable problems — channel decryption failure, missed heartbeats, etc. */
+  warn: (message: string, data?: unknown) => void;
+  /** Errors that prevent normal operation. */
+  error: (message: string, errOrData?: unknown, data?: unknown) => void;
+}
+
+/**
+ * No-op logger used as the default when callers don't provide one. Discards all
+ * messages — wallet hosts that want diagnostics should pass their own logger.
+ */
+export const NOOP_LOGGER: WalletSdkLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};