@aztec/wallet-sdk 0.0.1-commit.b2a5d0dd1 → 0.0.1-commit.b3d3157a

package/dest/iframe/provider/iframe_wallet.js

@@ -8,9 +8,9 @@
  */ import { WalletSchema } from '@aztec/aztec.js/wallet';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 import { promiseWithResolvers } from '@aztec/foundation/promise';
-import { schemaHasMethod } from '@aztec/foundation/schemas';
+import { getSchemaReturnType, schemaHasMethod } from '@aztec/foundation/schemas';
 import { decrypt, encrypt } from '../../crypto.js';
-import { WalletMessageType } from '../../types.js';
+import { DEFAULT_HEARTBEAT_DEAD_AFTER_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, NOOP_LOGGER, WalletMessageType } from '../../types.js';
 /**
  * A wallet implementation that communicates with a web wallet loaded in an iframe
  * using encrypted postMessage.
@@ -36,7 +36,12 @@ import { WalletMessageType } from '../../types.js';
     disconnected;
     disconnectCallbacks;
     messageListener;
-    constructor(chainInfo, appId, walletId, sessionId, iframeWindow, walletOrigin, sharedKey){
+    heartbeatTimer;
+    lastInboundAt;
+    log;
+    heartbeatIntervalMs;
+    heartbeatDeadAfterMs;
+    constructor(chainInfo, appId, walletId, sessionId, iframeWindow, walletOrigin, sharedKey, logger, heartbeatOptions){
         this.chainInfo = chainInfo;
         this.appId = appId;
         this.walletId = walletId;
@@ -48,6 +53,11 @@ import { WalletMessageType } from '../../types.js';
         this.disconnected = false;
         this.disconnectCallbacks = [];
         this.messageListener = null;
+        this.heartbeatTimer = null;
+        this.lastInboundAt = 0;
+        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.
@@ -63,9 +73,11 @@ import { WalletMessageType } from '../../types.js';
    * @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(walletId, sessionId, iframeWindow, walletOrigin, sharedKey, chainInfo, appId) {
-        const wallet = new IframeWallet(chainInfo, appId, walletId, sessionId, iframeWindow, walletOrigin, sharedKey);
+   */ static create(walletId, sessionId, iframeWindow, walletOrigin, sharedKey, chainInfo, appId, logger, heartbeatOptions) {
+        const wallet = new IframeWallet(chainInfo, appId, walletId, sessionId, iframeWindow, walletOrigin, sharedKey, logger, heartbeatOptions);
         wallet.messageListener = (event)=>{
             if (event.origin !== walletOrigin) {
                 return;
@@ -74,9 +86,14 @@ import { WalletMessageType } from '../../types.js';
             if (!msg || typeof msg !== 'object') {
                 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);
-            } else if (msg.type === WalletMessageType.SESSION_DISCONNECTED && msg.sessionId === sessionId) {
+            } else if (msg.type === WalletMessageType.SESSION_DISCONNECTED) {
                 wallet.handleDisconnect();
             }
         };
@@ -91,7 +108,7 @@ import { WalletMessageType } from '../../types.js';
                             type: prop.toString(),
                             args
                         });
-                        return WalletSchema[prop.toString()].returnType().parseAsync(result);
+                        return getSchemaReturnType(WalletSchema[prop.toString()]).parseAsync(result);
                     };
                 } else {
                     return target[prop];
@@ -122,8 +139,11 @@ import { WalletMessageType } from '../../types.js';
                 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
+            });
         }
     }
     async postMessage(call) {
@@ -151,13 +171,62 @@ import { WalletMessageType } from '../../types.js';
             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.
+   */ startHeartbeat() {
+        if (this.heartbeatTimer !== null || this.disconnected) {
+            return;
+        }
+        this.lastInboundAt = Date.now();
+        this.heartbeatTimer = setInterval(()=>this.heartbeatTick(), this.heartbeatIntervalMs);
+    }
+    maybeStopHeartbeat() {
+        if (this.inFlight.size === 0 && this.heartbeatTimer !== null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    heartbeatTick() {
+        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
+            });
+        }
+    }
     handleDisconnect() {
         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/dest/types.d.ts

@@ -22,7 +22,14 @@ export declare enum WalletMessageType {
     /** Encrypted wallet response wrapper */
     SECURE_RESPONSE = "aztec-wallet-secure-response",
     /** Session disconnected notification */
-    SESSION_DISCONNECTED = "aztec-wallet-session-disconnected"
+    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"
 }
 /**
  * Information about an installed Aztec wallet.
@@ -132,4 +139,47 @@ export interface KeyExchangeResponse {
  * Callback invoked when a wallet connection is disconnected.
  */
 export type DisconnectCallback = () => void;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUV6RCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUVyRDs7O0dBR0c7QUFDSCxvQkFBWSxpQkFBaUI7SUFDM0Isa0RBQWtEO0lBQ2xELFNBQVMsMkJBQTJCO0lBQ3BDLHVDQUF1QztJQUN2QyxrQkFBa0Isb0NBQW9DO0lBQ3RELHNFQUFzRTtJQUN0RSxVQUFVLDRCQUE0QjtJQUN0QyxvREFBb0Q7SUFDcEQsb0JBQW9CLHNDQUFzQztJQUMxRCxxREFBcUQ7SUFDckQscUJBQXFCLHVDQUF1QztJQUM1RCwwQkFBMEI7SUFDMUIsWUFBWSx1QkFBdUI7SUFDbkMsdUNBQXVDO0lBQ3ZDLGNBQWMsZ0NBQWdDO0lBQzlDLHdDQUF3QztJQUN4QyxlQUFlLGlDQUFpQztJQUNoRCx3Q0FBd0M7SUFDeEMsb0JBQW9CLHNDQUFzQztDQUMzRDtBQUVEOzs7R0FHRztBQUNILE1BQU0sV0FBVyxVQUFVO0lBQ3pCLHVDQUF1QztJQUN2QyxFQUFFLEVBQUUsTUFBTSxDQUFDO0lBQ1gsaUNBQWlDO0lBQ2pDLElBQUksRUFBRSxNQUFNLENBQUM7SUFDYiwrQkFBK0I7SUFDL0IsSUFBSSxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQ2QscUJBQXFCO0lBQ3JCLE9BQU8sRUFBRSxNQUFNLENBQUM7Q0FDakI7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFdBQVcsbUJBQW9CLFNBQVEsVUFBVTtJQUNyRCxnRUFBZ0U7SUFDaEUsU0FBUyxFQUFFLGlCQUFpQixDQUFDO0lBQzdCOzs7O09BSUc7SUFDSCxnQkFBZ0IsQ0FBQyxFQUFFLE1BQU0sQ0FBQztDQUMzQjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGFBQWE7SUFDNUIsK0NBQStDO0lBQy9DLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsZ0NBQWdDO0lBQ2hDLElBQUksRUFBRSxNQUFNLENBQUM7SUFDYiwrQkFBK0I7SUFDL0IsSUFBSSxFQUFFLE9BQU8sRUFBRSxDQUFDO0lBQ2hCLHdCQUF3QjtJQUN4QixTQUFTLEVBQUUsU0FBUyxDQUFDO0lBQ3JCLHdDQUF3QztJQUN4QyxLQUFLLEVBQUUsTUFBTSxDQUFDO0lBQ2QsNENBQTRDO0lBQzVDLFFBQVEsRUFBRSxNQUFNLENBQUM7Q0FDbEI7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyxjQUFjO0lBQzdCLHNDQUFzQztJQUN0QyxTQUFTLEVBQUUsTUFBTSxDQUFDO0lBQ2xCLGtDQUFrQztJQUNsQyxNQUFNLENBQUMsRUFBRSxPQUFPLENBQUM7SUFDakIsNkJBQTZCO0lBQzdCLEtBQUssQ0FBQyxFQUFFLE9BQU8sQ0FBQztJQUNoQix1Q0FBdUM7SUFDdkMsUUFBUSxFQUFFLE1BQU0sQ0FBQztDQUNsQjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGdCQUFnQjtJQUMvQixpQ0FBaUM7SUFDakMsSUFBSSxFQUFFLGlCQUFpQixDQUFDLFNBQVMsQ0FBQztJQUNsQyxpQkFBaUI7SUFDakIsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQix3Q0FBd0M7SUFDeEMsS0FBSyxFQUFFLE1BQU0sQ0FBQztJQUNkLGlFQUFpRTtJQUNqRSxTQUFTLEVBQUUsU0FBUyxDQUFDO0NBQ3RCO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsaUJBQWlCO0lBQ2hDLDBDQUEwQztJQUMxQyxJQUFJLEVBQUUsaUJBQWlCLENBQUMsa0JBQWtCLENBQUM7SUFDM0MsZ0RBQWdEO0lBQ2hELFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsK0JBQStCO0lBQy9CLFVBQVUsRUFBRSxVQUFVLENBQUM7Q0FDeEI7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyxrQkFBa0I7SUFDakMsbUJBQW1CO0lBQ25CLElBQUksRUFBRSxpQkFBaUIsQ0FBQyxvQkFBb0IsQ0FBQztJQUM3QyxnREFBZ0Q7SUFDaEQsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQix3REFBd0Q7SUFDeEQsU0FBUyxFQUFFLGlCQUFpQixDQUFDO0NBQzlCO0FBRUQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsbUJBQW1CO0lBQ2xDLG1CQUFtQjtJQUNuQixJQUFJLEVBQUUsaUJBQWlCLENBQUMscUJBQXFCLENBQUM7SUFDOUMsZ0RBQWdEO0lBQ2hELFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsMERBQTBEO0lBQzFELFNBQVMsRUFBRSxpQkFBaUIsQ0FBQztDQUM5QjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxNQUFNLGtCQUFrQixHQUFHLE1BQU0sSUFBSSxDQUFDIn0=
+/**
+ * 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 declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+export declare const DEFAULT_HEARTBEAT_DEAD_AFTER_MS = 300000;
+/** 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 declare const NOOP_LOGGER: WalletSdkLogger;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUV6RCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUVyRDs7O0dBR0c7QUFDSCxvQkFBWSxpQkFBaUI7SUFDM0Isa0RBQWtEO0lBQ2xELFNBQVMsMkJBQTJCO0lBQ3BDLHVDQUF1QztJQUN2QyxrQkFBa0Isb0NBQW9DO0lBQ3RELHNFQUFzRTtJQUN0RSxVQUFVLDRCQUE0QjtJQUN0QyxvREFBb0Q7SUFDcEQsb0JBQW9CLHNDQUFzQztJQUMxRCxxREFBcUQ7SUFDckQscUJBQXFCLHVDQUF1QztJQUM1RCwwQkFBMEI7SUFDMUIsWUFBWSx1QkFBdUI7SUFDbkMsdUNBQXVDO0lBQ3ZDLGNBQWMsZ0NBQWdDO0lBQzlDLHdDQUF3QztJQUN4QyxlQUFlLGlDQUFpQztJQUNoRCx3Q0FBd0M7SUFDeEMsb0JBQW9CLHNDQUFzQztJQUMxRCxtRUFBbUU7SUFDbkUsSUFBSSxzQkFBc0I7SUFDMUI7OztPQUdHO0lBQ0gsSUFBSSxzQkFBc0I7Q0FDM0I7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFdBQVcsVUFBVTtJQUN6Qix1Q0FBdUM7SUFDdkMsRUFBRSxFQUFFLE1BQU0sQ0FBQztJQUNYLGlDQUFpQztJQUNqQyxJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsK0JBQStCO0lBQy9CLElBQUksQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNkLHFCQUFxQjtJQUNyQixPQUFPLEVBQUUsTUFBTSxDQUFDO0NBQ2pCO0FBRUQ7OztHQUdHO0FBQ0gsTUFBTSxXQUFXLG1CQUFvQixTQUFRLFVBQVU7SUFDckQsZ0VBQWdFO0lBQ2hFLFNBQVMsRUFBRSxpQkFBaUIsQ0FBQztJQUM3Qjs7OztPQUlHO0lBQ0gsZ0JBQWdCLENBQUMsRUFBRSxN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

package/dest/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dest/types.js

@@ -11,5 +11,30 @@
     /** Encrypted wallet message wrapper */ WalletMessageType["SECURE_MESSAGE"] = "aztec-wallet-secure-message";
     /** Encrypted wallet response wrapper */ WalletMessageType["SECURE_RESPONSE"] = "aztec-wallet-secure-response";
     /** Session disconnected notification */ WalletMessageType["SESSION_DISCONNECTED"] = "aztec-wallet-session-disconnected";
+    /** Liveness probe sent by the dApp while a request is in flight */ WalletMessageType["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.
+   */ WalletMessageType["PONG"] = "aztec-wallet-pong";
     return WalletMessageType;
 }({});
+/**
+ * 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;
+/**
+ * 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 = {
+    debug: ()=>{},
+    info: ()=>{},
+    warn: ()=>{},
+    error: ()=>{}
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aztec/wallet-sdk",
   "homepage": "https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/wallet-sdk",
-  "version": "0.0.1-commit.b2a5d0dd1",
+  "version": "0.0.1-commit.b3d3157a",
   "type": "module",
   "exports": {
     "./base-wallet": "./dest/base-wallet/index.js",
@@ -75,15 +75,15 @@
     ]
   },
   "dependencies": {
-    "@aztec/aztec.js": "0.0.1-commit.b2a5d0dd1",
-    "@aztec/constants": "0.0.1-commit.b2a5d0dd1",
-    "@aztec/entrypoints": "0.0.1-commit.b2a5d0dd1",
-    "@aztec/foundation": "0.0.1-commit.b2a5d0dd1",
-    "@aztec/pxe": "0.0.1-commit.b2a5d0dd1",
-    "@aztec/stdlib": "0.0.1-commit.b2a5d0dd1"
+    "@aztec/aztec.js": "0.0.1-commit.b3d3157a",
+    "@aztec/constants": "0.0.1-commit.b3d3157a",
+    "@aztec/entrypoints": "0.0.1-commit.b3d3157a",
+    "@aztec/foundation": "0.0.1-commit.b3d3157a",
+    "@aztec/pxe": "0.0.1-commit.b3d3157a",
+    "@aztec/stdlib": "0.0.1-commit.b3d3157a"
   },
   "devDependencies": {
-    "@aztec/noir-contracts.js": "0.0.1-commit.b2a5d0dd1",
+    "@aztec/noir-contracts.js": "0.0.1-commit.b3d3157a",
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.17",

package/src/base-wallet/base_wallet.ts

@@ -85,7 +85,7 @@ export type FeeOptions = {
 /** Options for `simulateViaEntrypoint`. */
 export type SimulateViaEntrypointOptions = Pick<
   SimulateOptions,
-  'from' | 'additionalScopes' | 'skipTxValidation' | 'skipFeeEnforcement'
+  'from' | 'additionalScopes' | 'skipTxValidation' | 'skipFeeEnforcement' | 'sendMessagesAs' | 'overrides'
 > & {
   /** Fee options for the entrypoint */
   feeOptions: FeeOptions;
@@ -131,6 +131,17 @@ export abstract class BaseWallet implements Wallet {
     return [...scopeSet].map(AztecAddress.fromString);
   }
 
+  /**
+   * Picks the sender address PXE should tag private messages with. Returns `undefined` when there is no signing
+   * account (`from === NO_FROM`) and no explicit override; in that case any private log emitted by the tx using
+   * the wallet-supplied default sender will fail the "Sender for tags is not set" assertion.
+   * @param from - Tx sender, or `NO_FROM`.
+   * @param sendMessagesAs - Explicit override.
+   */
+  protected senderForTagsFrom(from: AztecAddress | NoFrom, sendMessagesAs?: AztecAddress): AztecAddress | undefined {
+    return sendMessagesAs ?? (from === NO_FROM ? undefined : from);
+  }
+
   protected abstract getAccountFromAddress(address: AztecAddress): Promise<Account>;
 
   abstract getAccounts(): Promise<Aliased<AztecAddress>[]>;
@@ -337,6 +348,10 @@ export abstract class BaseWallet implements Wallet {
     return instance;
   }
 
+  registerContractClass(artifact: ContractArtifact): Promise<void> {
+    return this.pxe.registerContractClass(artifact);
+  }
+
   /**
    * Simulates calls through the standard PXE path (account entrypoint).
    * @param executionPayload - The execution payload to simulate.
@@ -353,6 +368,8 @@ export abstract class BaseWallet implements Wallet {
       skipTxValidation: opts.skipTxValidation,
       skipFeeEnforcement: opts.skipFeeEnforcement,
       scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+      senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs),
+      overrides: opts.overrides,
     });
     const appCallOffset = await this.computeAppCallOffset(opts.from, opts.feeOptions);
     return TxSimulationResultWithAppOffset.fromResultAndOffset(result, appCallOffset);
@@ -401,7 +418,7 @@ export abstract class BaseWallet implements Wallet {
     try {
       blockHeader = await this.pxe.getSyncedBlockHeader();
     } catch {
-      blockHeader = (await this.aztecNode.getBlockHeader())!;
+      blockHeader = (await this.aztecNode.getBlockData('latest'))!.header;
     }
 
     const simulationOrigin = opts.from === NO_FROM ? AztecAddress.ZERO : opts.from;
@@ -416,6 +433,7 @@ export abstract class BaseWallet implements Wallet {
             blockHeader,
             opts.skipFeeEnforcement ?? true,
             this.getContractName.bind(this),
+            opts.overrides,
           )
         : Promise.resolve([]),
       remainingCalls.length > 0
@@ -425,6 +443,8 @@ export abstract class BaseWallet implements Wallet {
             additionalScopes: opts.additionalScopes,
             skipTxValidation: opts.skipTxValidation,
             skipFeeEnforcement: opts.skipFeeEnforcement ?? true,
+            sendMessagesAs: opts.sendMessagesAs,
+            overrides: opts.overrides,
           })
         : Promise.resolve(null),
     ]);
@@ -444,6 +464,7 @@ export abstract class BaseWallet implements Wallet {
       profileMode: opts.profileMode,
       skipProofGeneration: opts.skipProofGeneration ?? true,
       scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+      senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs),
     });
   }
 
@@ -458,14 +479,17 @@ export abstract class BaseWallet implements Wallet {
       congestionEstimate: opts.fee?.congestionEstimate,
     });
     const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, feeOptions);
-    const provenTx = await this.pxe.proveTx(txRequest, this.scopesFrom(opts.from, opts.additionalScopes));
+    const provenTx = await this.pxe.proveTx(txRequest, {
+      scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+      senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs),
+    });
     const offchainOutput = extractOffchainOutput(
       provenTx.getOffchainEffects(),
       provenTx.publicInputs.constants.anchorBlockHeader.globalVariables.timestamp,
     );
     const tx = await provenTx.toTx();
     const txHash = tx.getTxHash();
-    if (await this.aztecNode.getTxEffect(txHash)) {
+    if ((await this.aztecNode.getTxReceipt(txHash)).isMined()) {
       throw new Error(`A settled tx with equal hash ${txHash.toString()} exists.`);
     }
     this.log.debug(`Sending transaction ${txHash}`);
@@ -484,7 +508,7 @@ export abstract class BaseWallet implements Wallet {
     const receipt = await waitForTx(this.aztecNode, txHash, waitOpts);
 
     // Display debug logs from public execution if present (served in test mode only)
-    if (receipt.debugLogs?.length) {
+    if (receipt.isMined() && receipt.debugLogs?.length) {
       await displayDebugLogs(receipt.debugLogs, this.getContractName.bind(this));
     }
 

package/src/base-wallet/utils.ts

@@ -25,6 +25,7 @@ import {
   PrivateCallExecutionResult,
   PrivateExecutionResult,
   PublicSimulationOutput,
+  type SimulationOverrides,
   Tx,
   TxContext,
   TxSimulationResult,
@@ -65,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(
@@ -76,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);
 
@@ -143,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;
@@ -166,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(
@@ -177,6 +183,7 @@ export async function simulateViaNode(
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean = true,
   getContractName: ContractNameResolver,
+  overrides?: SimulationOverrides,
 ): Promise<TxSimulationResult[]> {
   const batches: FunctionCall[][] = [];
 
@@ -196,6 +203,7 @@ export async function simulateViaNode(
       blockHeader,
       skipFeeEnforcement,
       getContractName,
+      overrides,
     );
     results.push(result);
   }

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;
 
 /**