@aztec/wallet-sdk 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5a9928

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 } 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,9 +1,12 @@
 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';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { Tuple } from '@aztec/foundation/serialize';
+import type { ContractNameResolver } from '@aztec/pxe/client/lazy';
+import { displayDebugLogs } from '@aztec/pxe/client/lazy';
 import { generateSimulatedProvingResult } from '@aztec/pxe/simulator';
 import { type FunctionCall, FunctionSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -22,6 +25,7 @@ import {
   PrivateCallExecutionResult,
   PrivateExecutionResult,
   PublicSimulationOutput,
+  type SimulationOverrides,
   Tx,
   TxContext,
   TxSimulationResult,
@@ -62,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(
@@ -72,6 +78,8 @@ async function simulateBatchViaNode(
   gasSettings: GasSettings,
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean,
+  getContractName: ContractNameResolver,
+  overrides?: SimulationOverrides,
 ): Promise<TxSimulationResult> {
   const txContext = new TxContext(chainInfo.chainId, chainInfo.version, gasSettings);
 
@@ -126,6 +134,7 @@ async function simulateBatchViaNode(
   const provingResult = await generateSimulatedProvingResult(
     privateResult,
     (_contractAddress: AztecAddress, _functionSelector: FunctionSelector) => Promise.resolve(''),
+    node,
     1, // minRevertibleSideEffectCounter
   );
 
@@ -138,12 +147,15 @@ 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;
   }
 
+  // Display debug logs from the public simulation.
+  await displayDebugLogs(publicOutput.debugLogs, getContractName);
+
   return new TxSimulationResult(privateResult, provingResult.publicInputs, publicOutput, undefined);
 }
 
@@ -158,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(
@@ -168,6 +182,8 @@ export async function simulateViaNode(
   gasSettings: GasSettings,
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean = true,
+  getContractName: ContractNameResolver,
+  overrides?: SimulationOverrides,
 ): Promise<TxSimulationResult[]> {
   const batches: FunctionCall[][] = [];
 
@@ -186,6 +202,8 @@ export async function simulateViaNode(
       gasSettings,
       blockHeader,
       skipFeeEnforcement,
+      getContractName,
+      overrides,
     );
     results.push(result);
   }
@@ -205,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
     ? {
@@ -220,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;
 
 /**