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

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: () => {},
+};