@aztec/wallet-sdk 5.0.0-private.20260319 → 5.0.0-rc.2

package/src/base-wallet/get_gas_limits.ts

@@ -0,0 +1,88 @@
+import { MAX_PROCESSABLE_L2_GAS, MAX_TX_DA_GAS } from '@aztec/constants';
+import { Gas, type GasUsed } from '@aztec/stdlib/gas';
+
+/**
+ * Returns suggested total and teardown gas limits for a simulated tx, clamped to the network's per-tx
+ * admission limits.
+ *
+ * The network only admits transactions that declare up to `maxTxGasLimits` per dimension (the
+ * node-advertised `txsLimits.gas`). Wallets pass the value read from their own node info, but since node info
+ * is remote input it is defensively clamped here to the per-tx protocol maxima so a value above them is never
+ * honored. If the simulated usage already exceeds the resulting admission limits the tx can never be included,
+ * so this throws a descriptive error instead of returning a limit the node would reject. Otherwise it pads the
+ * usage and clamps each dimension to the admission limit.
+ * @param gasUsed - The gas actually consumed during simulation.
+ * @param maxTxGasLimits - The maximum gas a single tx may declare on this network (the node-advertised `txsLimits.gas`).
+ * @param pad - Fraction to pad the suggested gas limits by (as a decimal, e.g. 0.1 for 10%). The effective
+ * padding shrinks to zero as usage approaches the network limit, since the network will not admit a higher
+ * declared limit regardless of the buffer.
+ */
+export function getGasLimits(
+  gasUsed: GasUsed,
+  maxTxGasLimits: Gas,
+  pad = 0.1,
+): {
+  /**
+   * Gas limit for the tx, excluding teardown gas
+   */
+  gasLimits: Gas;
+  /**
+   * Gas limit for the teardown phase
+   */
+  teardownGasLimits: Gas;
+} {
+  const { totalGas, teardownGas } = gasUsed;
+
+  // `maxTxGasLimits` is the node-advertised admission limit. Node info is remote input, so we defensively
+  // clamp to the per-tx protocol maxima so a value above them can never be honored.
+  const maxLimits = new Gas(
+    Math.min(maxTxGasLimits.daGas, MAX_TX_DA_GAS),
+    Math.min(maxTxGasLimits.l2Gas, MAX_PROCESSABLE_L2_GAS),
+  );
+
+  // The simulated usage must fit within the admission limits, otherwise the tx can never be included.
+  if (totalGas.daGas > maxLimits.daGas) {
+    throw new Error(
+      `Transaction consumes ${totalGas.daGas} DA gas but the network only admits transactions declaring up to ${maxLimits.daGas} DA gas`,
+    );
+  }
+  if (totalGas.l2Gas > maxLimits.l2Gas) {
+    throw new Error(
+      `Transaction consumes ${totalGas.l2Gas} L2 gas but the network only admits transactions declaring up to ${maxLimits.l2Gas} L2 gas`,
+    );
+  }
+
+  // Pad the limits by the buffer, then cap each dimension at the admission limit so the buffer cannot push a
+  // declared limit past what inbound validation accepts. Teardown is part of the total, so clamping it to the
+  // admission limit is safe.
+  return {
+    gasLimits: padGas(totalGas, pad, maxLimits),
+    teardownGasLimits: padGas(teardownGas, pad, maxLimits),
+  };
+}
+
+/** Pads each gas dimension, capping it at the network admission limit. */
+function padGas(gas: Gas, pad: number, cap: Gas): Gas {
+  const padded = gas.mul(1 + pad);
+  return new Gas(Math.min(padded.daGas, cap.daGas), Math.min(padded.l2Gas, cap.l2Gas));
+}
+
+/**
+ * Validates that caller-declared gas limits do not exceed the network's per-tx admission limits, throwing a
+ * descriptive error per dimension when they do. The node's inbound validation checks declared
+ * `gasSettings.gasLimits`, so we mirror that here to surface the rejection locally before the tx is sent.
+ * @param gasLimits - The gas limits the transaction will declare.
+ * @param maxTxGasLimits - The maximum gas a single tx may declare on this network (the node-advertised `txsLimits.gas`).
+ */
+export function assertGasLimitsWithinNetworkLimits(gasLimits: Gas, maxTxGasLimits: Gas): void {
+  if (gasLimits.daGas > maxTxGasLimits.daGas) {
+    throw new Error(
+      `Declared DA gas limit (${gasLimits.daGas}) exceeds the maximum this network allows per tx (${maxTxGasLimits.daGas})`,
+    );
+  }
+  if (gasLimits.l2Gas > maxTxGasLimits.l2Gas) {
+    throw new Error(
+      `Declared L2 gas limit (${gasLimits.l2Gas}) exceeds the maximum this network allows per tx (${maxTxGasLimits.l2Gas})`,
+    );
+  }
+}

package/src/base-wallet/index.ts

@@ -1,2 +1,8 @@
-export { BaseWallet, type FeeOptions, type SimulateViaEntrypointOptions } from './base_wallet.js';
+export {
+  BaseWallet,
+  type CompleteFeeOptionsConfig,
+  type FeeOptions,
+  type SimulateViaEntrypointOptions,
+} from './base_wallet.js';
 export { simulateViaNode, buildMergedSimulationResult, extractOptimizablePublicStaticCalls } from './utils.js';
+export { getGasLimits, assertGasLimitsWithinNetworkLimits } from './get_gas_limits.js';

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/crypto.ts

@@ -497,3 +497,107 @@ export function hashToEmoji(hash: string, count: number = DEFAULT_EMOJI_GRID_SIZ
   }
   return emojis.join('');
 }
+
+// ─── Passphrase-based encryption (PBKDF2 + AES-256-GCM) ───────────────────
+
+/** Default PBKDF2 iteration count. High to compensate for short PINs (~1-2s on modern hardware). */
+const DEFAULT_PBKDF2_ITERATIONS = 2_000_000;
+const PBKDF2_SALT_BYTES = 16;
+const PBKDF2_IV_BYTES = 12;
+
+/**
+ * Derives an AES-256-GCM key from a passphrase using PBKDF2-SHA256.
+ *
+ * @param passphrase - The user-provided passphrase or PIN
+ * @param salt - Random salt bytes
+ * @param iterations - PBKDF2 iteration count (default: 2,000,000)
+ * @returns An AES-256-GCM CryptoKey
+ */
+export async function deriveKeyFromPassphrase(
+  passphrase: string,
+  salt: Uint8Array,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, [
+    'deriveKey',
+  ]);
+  return crypto.subtle.deriveKey(
+    { name: 'PBKDF2', salt: salt as BufferSource, iterations, hash: 'SHA-256' },
+    keyMaterial,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+/**
+ * Encrypts arbitrary bytes with a passphrase using PBKDF2 + AES-256-GCM.
+ *
+ * Output layout: `[salt (16)] [iv (12)] [ciphertext (...)]`
+ *
+ * @param plaintext - Data to encrypt
+ * @param passphrase - User passphrase or PIN
+ * @param iterations - PBKDF2 iteration count (default: 2,000,000)
+ * @returns A Uint8Array containing salt + iv + ciphertext
+ */
+export async function encryptWithPassphrase(
+  plaintext: Uint8Array,
+  passphrase: string,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<Uint8Array> {
+  const salt = crypto.getRandomValues(new Uint8Array(PBKDF2_SALT_BYTES));
+  const iv = crypto.getRandomValues(new Uint8Array(PBKDF2_IV_BYTES));
+  const key = await deriveKeyFromPassphrase(passphrase, salt, iterations);
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext as BufferSource),
+  );
+  const result = new Uint8Array(PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES + ciphertext.length);
+  result.set(salt, 0);
+  result.set(iv, PBKDF2_SALT_BYTES);
+  result.set(ciphertext, PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  return result;
+}
+
+/**
+ * Decrypts data produced by {@link encryptWithPassphrase}.
+ *
+ * @param data - The encrypted blob (salt + iv + ciphertext)
+ * @param passphrase - The passphrase used during encryption
+ * @param iterations - PBKDF2 iteration count (must match encryption)
+ * @returns The decrypted plaintext bytes
+ * @throws On wrong passphrase (AES-GCM auth tag mismatch)
+ */
+export async function decryptWithPassphrase(
+  data: Uint8Array,
+  passphrase: string,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<Uint8Array> {
+  const salt = data.slice(0, PBKDF2_SALT_BYTES);
+  const iv = data.slice(PBKDF2_SALT_BYTES, PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  const ciphertext = data.slice(PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  const key = await deriveKeyFromPassphrase(passphrase, salt, iterations);
+  return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext as BufferSource));
+}
+
+/**
+ * Converts a Uint8Array to a base64 string.
+ */
+export function uint8ToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Converts a base64 string to a Uint8Array.
+ */
+export function base64ToUint8(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

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 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.
@@ -19,11 +29,6 @@ type WalletMethodCall = {
   args: unknown[];
 };
 
-/**
- * Callback type for wallet disconnect events.
- */
-export type DisconnectCallback = () => void;
-
 /**
  * A wallet implementation that communicates with browser extension wallets
  * using an encrypted MessageChannel.
@@ -60,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.
@@ -68,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,
@@ -75,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
@@ -86,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
@@ -109,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;
@@ -136,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];
@@ -189,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 });
+    }
   }
 
   /**
@@ -228,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.
@@ -242,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/extension/provider/index.ts

@@ -1,4 +1,4 @@
-export { ExtensionWallet, type DisconnectCallback } from './extension_wallet.js';
+export { ExtensionWallet } from './extension_wallet.js';
 export {
   ExtensionProvider,
   type DiscoveredWallet,