@aztec/wallet-sdk 0.0.1-commit.b6e433891 → 0.0.1-commit.b9865e97

package/src/base-wallet/base_wallet.ts

@@ -1,4 +1,5 @@
-import type { Account } from '@aztec/aztec.js/account';
+import type { Account, NoFrom } from '@aztec/aztec.js/account';
+import { NO_FROM } from '@aztec/aztec.js/account';
 import type { CallIntent, IntentInnerHash } from '@aztec/aztec.js/authorization';
 import {
   type InteractionWaitOptions,
@@ -8,32 +9,29 @@ import {
 } from '@aztec/aztec.js/contracts';
 import type { FeePaymentMethod } from '@aztec/aztec.js/fee';
 import { waitForTx } from '@aztec/aztec.js/node';
-import type {
-  Aliased,
-  AppCapabilities,
-  BatchResults,
-  BatchedMethod,
-  ExecuteUtilityOptions,
-  PrivateEvent,
-  PrivateEventFilter,
-  ProfileOptions,
-  SendOptions,
-  SimulateOptions,
-  Wallet,
-  WalletCapabilities,
-} from '@aztec/aztec.js/wallet';
 import {
-  GAS_ESTIMATION_DA_GAS_LIMIT,
-  GAS_ESTIMATION_L2_GAS_LIMIT,
-  GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT,
-  GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT,
-} from '@aztec/constants';
+  type Aliased,
+  type AppCapabilities,
+  type BatchResults,
+  type BatchedMethod,
+  ContractInitializationStatus,
+  type ExecuteUtilityOptions,
+  type PrivateEvent,
+  type PrivateEventFilter,
+  type ProfileOptions,
+  type SendOptions,
+  type SimulateOptions,
+  TxSimulationResultWithAppOffset,
+  type Wallet,
+  type WalletCapabilities,
+} from '@aztec/aztec.js/wallet';
 import { AccountFeePaymentMethodOptions, type DefaultAccountEntrypointOptions } from '@aztec/entrypoints/account';
+import { DefaultEntrypoint } from '@aztec/entrypoints/default';
 import type { ChainInfo } from '@aztec/entrypoints/interfaces';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import type { FieldsOf } from '@aztec/foundation/types';
-import { type AccessScopes, displayDebugLogs } from '@aztec/pxe/client/lazy';
+import { displayDebugLogs } from '@aztec/pxe/client/lazy';
 import type { PXE, PackedPrivateEvent } from '@aztec/pxe/server';
 import {
   type ContractArtifact,
@@ -45,21 +43,25 @@ import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
   type ContractInstanceWithAddress,
+  type NodeInfo,
   computePartialAddress,
   getContractClassFromArtifact,
 } from '@aztec/stdlib/contract';
 import { SimulationError } from '@aztec/stdlib/errors';
-import { Gas, GasSettings } from '@aztec/stdlib/gas';
-import { computeSiloedPrivateInitializationNullifier } from '@aztec/stdlib/hash';
+import { Gas, GasFees, GasSettings, ManaUsageEstimate } from '@aztec/stdlib/gas';
+import {
+  computeSiloedPrivateInitializationNullifier,
+  computeSiloedPublicInitializationNullifier,
+} from '@aztec/stdlib/hash';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 import {
   BlockHeader,
+  ExecutionPayload,
   type TxExecutionRequest,
   type TxProfileResult,
-  TxSimulationResult,
   type UtilityExecutionResult,
+  mergeExecutionPayloads,
 } from '@aztec/stdlib/tx';
-import { ExecutionPayload, mergeExecutionPayloads } from '@aztec/stdlib/tx';
 
 import { inspect } from 'util';
 
@@ -75,7 +77,7 @@ export type FeeOptions = {
    */
   walletFeePaymentMethod?: FeePaymentMethod;
   /** Configuration options for the account to properly handle the selected fee payment method */
-  accountFeePaymentMethodOptions: AccountFeePaymentMethodOptions;
+  accountFeePaymentMethodOptions?: AccountFeePaymentMethodOptions;
   /** The gas settings to use for the transaction */
   gasSettings: GasSettings;
 };
@@ -83,19 +85,38 @@ 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;
-  /** Scopes to use for the simulation */
-  scopes: AccessScopes;
 };
+
+/** Options for `completeFeeOptions`. */
+export type CompleteFeeOptionsConfig = {
+  /** The address where the transaction is being sent from. */
+  from: AztecAddress | NoFrom;
+  /** The address paying for fees (if any fee payment method is embedded in the execution payload). */
+  feePayer?: AztecAddress;
+  /** User-provided partial gas settings. */
+  gasSettings?: Partial<FieldsOf<GasSettings>>;
+  /** If true, returns gas settings with high gas limits for estimation. If false, uses fallback limits. */
+  forEstimation?: boolean;
+  /**
+   * Assumed network congestion level for fee prediction. Controls how aggressively the wallet
+   * estimates future fees. Defaults to Limit (worst case) when not specified.
+   */
+  congestionEstimate?: ManaUsageEstimate;
+};
+
 /**
  * A base class for Wallet implementations
  */
 export abstract class BaseWallet implements Wallet {
   protected minFeePadding = 0.5;
   protected cancellableTransactions = false;
+  // A wallet is instantiated for a particular chain, so chain info never changes during its lifetime.
+  // We cache it here because getChainInfo is called frequently (every tx simulation, send, auth wit, etc.).
+  private nodeInfoPromise: Promise<NodeInfo> | undefined;
 
   // Protected because we want to force wallets to instantiate their own PXE.
   protected constructor(
@@ -104,12 +125,23 @@ export abstract class BaseWallet implements Wallet {
     protected log = createLogger('wallet-sdk:base_wallet'),
   ) {}
 
-  protected scopesFrom(from: AztecAddress, additionalScopes: AztecAddress[] = []): AztecAddress[] {
-    const allScopes = from.isZero() ? additionalScopes : [from, ...additionalScopes];
+  protected scopesFrom(from: AztecAddress | NoFrom, additionalScopes: AztecAddress[] = []): AztecAddress[] {
+    const allScopes = from === NO_FROM ? additionalScopes : [from, ...additionalScopes];
     const scopeSet = new Set(allScopes.map(address => address.toString()));
     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>[]>;
@@ -127,32 +159,42 @@ export abstract class BaseWallet implements Wallet {
   }
 
   async getChainInfo(): Promise<ChainInfo> {
-    const { l1ChainId, rollupVersion } = await this.aztecNode.getNodeInfo();
+    if (!this.nodeInfoPromise) {
+      this.nodeInfoPromise = this.aztecNode.getNodeInfo();
+    }
+    const { l1ChainId, rollupVersion } = await this.nodeInfoPromise;
     return { chainId: new Fr(l1ChainId), version: new Fr(rollupVersion) };
   }
 
   protected async createTxExecutionRequestFromPayloadAndFee(
     executionPayload: ExecutionPayload,
-    from: AztecAddress,
+    from: AztecAddress | NoFrom,
     feeOptions: FeeOptions,
   ): Promise<TxExecutionRequest> {
     const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
-    const executionOptions: DefaultAccountEntrypointOptions = {
-      txNonce: Fr.random(),
-      cancellable: this.cancellableTransactions,
-      feePaymentMethodOptions: feeOptions.accountFeePaymentMethodOptions,
-    };
     const finalExecutionPayload = feeExecutionPayload
       ? mergeExecutionPayloads([feeExecutionPayload, executionPayload])
       : executionPayload;
-    const fromAccount = await this.getAccountFromAddress(from);
     const chainInfo = await this.getChainInfo();
-    return fromAccount.createTxExecutionRequest(
-      finalExecutionPayload,
-      feeOptions.gasSettings,
-      chainInfo,
-      executionOptions,
-    );
+
+    if (from === NO_FROM) {
+      const entrypoint = new DefaultEntrypoint();
+      return entrypoint.createTxExecutionRequest(finalExecutionPayload, feeOptions.gasSettings, chainInfo);
+    } else {
+      const fromAccount = await this.getAccountFromAddress(from);
+      const executionOptions: DefaultAccountEntrypointOptions = {
+        txNonce: Fr.random(),
+        cancellable: this.cancellableTransactions,
+        // If from is an address, feeOptions include the way the account contract should handle the fee payment
+        feePaymentMethodOptions: feeOptions.accountFeePaymentMethodOptions!,
+      };
+      return fromAccount.createTxExecutionRequest(
+        finalExecutionPayload,
+        feeOptions.gasSettings,
+        chainInfo,
+        executionOptions,
+      );
+    }
   }
 
   public async createAuthWit(
@@ -201,31 +243,39 @@ export abstract class BaseWallet implements Wallet {
 
   /**
    * Completes partial user-provided fee options with wallet defaults.
-   * @param from - The address where the transaction is being sent from
-   * @param feePayer - The address paying for fees (if any fee payment method is embedded in the execution payload)
-   * @param gasSettings - User-provided partial gas settings
-   * @returns - Complete fee options that can be used to create a transaction execution request
+   * @param config - Fee completion config.
    */
-  protected async completeFeeOptions(
-    from: AztecAddress,
-    feePayer?: AztecAddress,
-    gasSettings?: Partial<FieldsOf<GasSettings>>,
-  ): Promise<FeeOptions> {
+  protected async completeFeeOptions(config: CompleteFeeOptionsConfig): Promise<FeeOptions> {
+    const { from, feePayer, gasSettings, forEstimation, congestionEstimate } = config;
     const maxFeesPerGas =
-      gasSettings?.maxFeesPerGas ?? (await this.aztecNode.getCurrentMinFees()).mul(1 + this.minFeePadding);
+      gasSettings?.maxFeesPerGas ?? (await this.getMinFees(congestionEstimate)).mul(1 + this.minFeePadding);
     let accountFeePaymentMethodOptions;
-    // The transaction does not include a fee payment method, so we set the flag
-    // for the account to use its fee juice balance
-    if (!feePayer) {
-      accountFeePaymentMethodOptions = AccountFeePaymentMethodOptions.PREEXISTING_FEE_JUICE;
-    } else {
-      // The transaction includes fee payment method, so we check if we are the fee payer for it
-      // (this can only happen if the embedded payment method is FeeJuiceWithClaim)
-      accountFeePaymentMethodOptions = from.equals(feePayer)
-        ? AccountFeePaymentMethodOptions.FEE_JUICE_WITH_CLAIM
-        : AccountFeePaymentMethodOptions.EXTERNAL;
+    // If from is an address, we need to determine the appropriate fee payment method options for the
+    // account contract entrypoint to use
+    if (from !== NO_FROM) {
+      if (!feePayer) {
+        // The transaction does not include a fee payment method, so we set the flag
+        // for the account to use its fee juice balance
+        accountFeePaymentMethodOptions = AccountFeePaymentMethodOptions.PREEXISTING_FEE_JUICE;
+      } else {
+        // The transaction includes fee payment method, so we check if we are the fee payer for it
+        // (this can only happen if the embedded payment method is FeeJuiceWithClaim)
+        accountFeePaymentMethodOptions = from.equals(feePayer)
+          ? AccountFeePaymentMethodOptions.FEE_JUICE_WITH_CLAIM
+          : AccountFeePaymentMethodOptions.EXTERNAL;
+      }
     }
-    const fullGasSettings: GasSettings = GasSettings.default({ ...gasSettings, maxFeesPerGas });
+    const gasSettingsOverrides = {
+      gasLimits: gasSettings?.gasLimits ? Gas.from(gasSettings.gasLimits) : undefined,
+      teardownGasLimits: gasSettings?.teardownGasLimits ? Gas.from(gasSettings.teardownGasLimits) : undefined,
+      maxFeesPerGas,
+      maxPriorityFeesPerGas: gasSettings?.maxPriorityFeesPerGas ?? GasFees.empty(),
+    };
+    // When estimating gas (simulation), use high limits so the simulation doesn't run out of gas.
+    // When sending for real, use protocol max limits that the network will actually accept.
+    const fullGasSettings = forEstimation
+      ? GasSettings.forEstimation(gasSettingsOverrides)
+      : GasSettings.fallback(gasSettingsOverrides);
     this.log.debug(`Using L2 gas settings`, fullGasSettings);
     return {
       gasSettings: fullGasSettings,
@@ -235,34 +285,25 @@ export abstract class BaseWallet implements Wallet {
   }
 
   /**
-   * Completes partial user-provided fee options with unreasonably high gas limits
-   * for gas estimation. Uses the same logic as completeFeeOptions but sets high limits
-   * to avoid running out of gas during estimation.
-   * @param from - The address where the transaction is being sent from
-   * @param feePayer - The address paying for fees (if any fee payment method is embedded in the execution payload)
-   * @param gasSettings - User-provided partial gas settings
+   * Returns the worst-case min fee across predicted future slots.
+   * Falls back to getCurrentMinFees if the node doesn't support getPredictedMinFees.
+   * @param estimate - The mana usage estimate to use for fee prediction. Defaults to Limit for conservative estimation.
    */
-  protected async completeFeeOptionsForEstimation(
-    from: AztecAddress,
-    feePayer?: AztecAddress,
-    gasSettings?: Partial<FieldsOf<GasSettings>>,
-  ) {
-    const defaultFeeOptions = await this.completeFeeOptions(from, feePayer, gasSettings);
-    const {
-      gasSettings: { maxFeesPerGas, maxPriorityFeesPerGas },
-    } = defaultFeeOptions;
-    // Use unrealistically high gas limits for estimation to avoid running out of gas.
-    // They will be tuned down after the simulation.
-    const gasSettingsForEstimation = new GasSettings(
-      new Gas(GAS_ESTIMATION_DA_GAS_LIMIT, GAS_ESTIMATION_L2_GAS_LIMIT),
-      new Gas(GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT, GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT),
-      maxFeesPerGas,
-      maxPriorityFeesPerGas,
-    );
-    return {
-      ...defaultFeeOptions,
-      gasSettings: gasSettingsForEstimation,
-    };
+  protected async getMinFees(estimate: ManaUsageEstimate = ManaUsageEstimate.Limit): Promise<GasFees> {
+    try {
+      const predicted = await this.aztecNode.getPredictedMinFees(estimate);
+      if (predicted.length === 0) {
+        return this.aztecNode.getCurrentMinFees();
+      }
+      return predicted.reduce((worst, fees) => (fees.feePerL2Gas > worst.feePerL2Gas ? fees : worst));
+    } catch (err: any) {
+      // Fallback for old nodes that don't support getPredictedMinFees.
+      // Only fall back on method-not-found errors (JSON-RPC code -32601); rethrow others.
+      if (err?.cause?.code === -32601 || err?.message?.includes('Method not found')) {
+        return this.aztecNode.getCurrentMinFees();
+      }
+      throw err;
+    }
   }
 
   registerSender(address: AztecAddress, _alias: string = ''): Promise<AztecAddress> {
@@ -307,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.
@@ -318,12 +363,30 @@ export abstract class BaseWallet implements Wallet {
       opts.from,
       opts.feeOptions,
     );
-    return this.pxe.simulateTx(txRequest, {
+    const result = await this.pxe.simulateTx(txRequest, {
       simulatePublic: true,
       skipTxValidation: opts.skipTxValidation,
       skipFeeEnforcement: opts.skipFeeEnforcement,
-      scopes: opts.scopes,
+      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);
+  }
+
+  /**
+   * Computes the index where the app's calls begin in the flattened array of calls (0 = entrypoint/root, 1..N = fee
+   * calls, N+1 = app).
+   * @param from - The sender address, or NO_FROM for the default entrypoint.
+   * @param feeOptions - Fee options containing the wallet fee payment method.
+   */
+  protected async computeAppCallOffset(from: AztecAddress | NoFrom, feeOptions: FeeOptions): Promise<number> {
+    if (from === NO_FROM) {
+      return 0;
+    }
+    const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
+    return (feeExecutionPayload?.calls.length ?? 0) + 1; // +1 for entrypoint
   }
 
   /**
@@ -334,10 +397,17 @@ export abstract class BaseWallet implements Wallet {
    * @param opts - Simulation options (from address, fee settings, etc.).
    * @returns The merged simulation result.
    */
-  async simulateTx(executionPayload: ExecutionPayload, opts: SimulateOptions): Promise<TxSimulationResult> {
-    const feeOptions = opts.fee?.estimateGas
-      ? await this.completeFeeOptionsForEstimation(opts.from, executionPayload.feePayer, opts.fee?.gasSettings)
-      : await this.completeFeeOptions(opts.from, executionPayload.feePayer, opts.fee?.gasSettings);
+  async simulateTx(
+    executionPayload: ExecutionPayload,
+    opts: SimulateOptions,
+  ): Promise<TxSimulationResultWithAppOffset> {
+    const feeOptions = await this.completeFeeOptions({
+      from: opts.from,
+      feePayer: executionPayload.feePayer,
+      gasSettings: opts.fee?.gasSettings,
+      forEstimation: true,
+      congestionEstimate: opts.fee?.congestionEstimate,
+    });
     const { optimizableCalls, remainingCalls } = extractOptimizablePublicStaticCalls(executionPayload);
     const remainingPayload = { ...executionPayload, calls: remainingCalls };
 
@@ -348,29 +418,33 @@ 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;
     const [optimizedResults, normalResult] = await Promise.all([
       optimizableCalls.length > 0
         ? simulateViaNode(
             this.aztecNode,
             optimizableCalls,
-            opts.from,
+            simulationOrigin,
             chainInfo,
             feeOptions.gasSettings,
             blockHeader,
             opts.skipFeeEnforcement ?? true,
             this.getContractName.bind(this),
+            opts.overrides,
           )
         : Promise.resolve([]),
       remainingCalls.length > 0
         ? this.simulateViaEntrypoint(remainingPayload, {
             from: opts.from,
             feeOptions,
-            scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+            additionalScopes: opts.additionalScopes,
             skipTxValidation: opts.skipTxValidation,
             skipFeeEnforcement: opts.skipFeeEnforcement ?? true,
+            sendMessagesAs: opts.sendMessagesAs,
+            overrides: opts.overrides,
           })
         : Promise.resolve(null),
     ]);
@@ -379,12 +453,18 @@ export abstract class BaseWallet implements Wallet {
   }
 
   async profileTx(executionPayload: ExecutionPayload, opts: ProfileOptions): Promise<TxProfileResult> {
-    const feeOptions = await this.completeFeeOptions(opts.from, executionPayload.feePayer, opts.fee?.gasSettings);
+    const feeOptions = await this.completeFeeOptions({
+      from: opts.from,
+      feePayer: executionPayload.feePayer,
+      gasSettings: opts.fee?.gasSettings,
+      congestionEstimate: opts.fee?.congestionEstimate,
+    });
     const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, feeOptions);
     return this.pxe.profileTx(txRequest, {
       profileMode: opts.profileMode,
       skipProofGeneration: opts.skipProofGeneration ?? true,
       scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+      senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs),
     });
   }
 
@@ -392,16 +472,24 @@ export abstract class BaseWallet implements Wallet {
     executionPayload: ExecutionPayload,
     opts: SendOptions<W>,
   ): Promise<SendReturn<W>> {
-    const feeOptions = await this.completeFeeOptions(opts.from, executionPayload.feePayer, opts.fee?.gasSettings);
+    const feeOptions = await this.completeFeeOptions({
+      from: opts.from,
+      feePayer: executionPayload.feePayer,
+      gasSettings: opts.fee?.gasSettings,
+      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}`);
@@ -420,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));
     }
 
@@ -455,7 +543,7 @@ export abstract class BaseWallet implements Wallet {
   }
 
   executeUtility(call: FunctionCall, opts: ExecuteUtilityOptions): Promise<UtilityExecutionResult> {
-    return this.pxe.executeUtility(call, { authwits: opts.authWitnesses, scopes: [opts.scope] });
+    return this.pxe.executeUtility(call, { authwits: opts.authWitnesses, scopes: opts.scopes });
   }
 
   async getPrivateEvents<T>(
@@ -480,26 +568,29 @@ export abstract class BaseWallet implements Wallet {
 
   /**
    * Returns metadata about a contract, including whether it has been initialized, published, and updated.
-   *
-   * `isContractInitialized` requires the contract instance to be registered in the PXE (for `init_hash`). When the
-   * instance is not available, `isContractInitialized` is `undefined` since it cannot be determined.
    * @param address - The contract address to query.
    */
   async getContractMetadata(address: AztecAddress) {
     const instance = await this.pxe.getContractInstance(address);
     const publiclyRegisteredContractPromise = this.aztecNode.getContract(address);
-    // We check only the private initialization nullifier. It is emitted by both private and public initializers and
-    // includes init_hash, preventing observers from determining initialization status from the address alone. Without
-    // the instance (and thus init_hash), we can't compute it, so we return undefined.
-    //
-    // We skip the public initialization nullifier because it's not always emitted (contracts without public external
-    // functions that require initialization checks won't emit it). If the private one exists, the public one was
-    // created in the same tx and will also be present.
-    let isContractInitialized: boolean | undefined = undefined;
+
+    let initializationStatus: ContractInitializationStatus;
     if (instance) {
+      // We have the instance, so we can compute the private initialization nullifier (which includes init_hash and is
+      // emitted by both private and public initializers) and get a definitive INITIALIZED/UNINITIALIZED answer.
       const initNullifier = await computeSiloedPrivateInitializationNullifier(address, instance.initializationHash);
       const witness = await this.aztecNode.getNullifierMembershipWitness('latest', initNullifier);
-      isContractInitialized = !!witness;
+      initializationStatus = witness
+        ? ContractInitializationStatus.INITIALIZED
+        : ContractInitializationStatus.UNINITIALIZED;
+    } else {
+      // Without the instance we lack the init_hash needed for the private nullifier. We fall back to checking the
+      // public initialization nullifier (computed from address alone). Not all contracts emit it (only those with
+      // public functions that require initialization checks), so its absence doesn't mean the contract is
+      // uninitialized.
+      const publicNullifier = await computeSiloedPublicInitializationNullifier(address);
+      const witness = await this.aztecNode.getNullifierMembershipWitness('latest', publicNullifier);
+      initializationStatus = witness ? ContractInitializationStatus.INITIALIZED : ContractInitializationStatus.UNKNOWN;
     }
     const publiclyRegisteredContract = await publiclyRegisteredContractPromise;
     const isContractUpdated =
@@ -507,7 +598,7 @@ export abstract class BaseWallet implements Wallet {
       !publiclyRegisteredContract.currentContractClassId.equals(publiclyRegisteredContract.originalContractClassId);
     return {
       instance: instance ?? undefined,
-      isContractInitialized,
+      initializationStatus,
       isContractPublished: !!publiclyRegisteredContract,
       isContractUpdated: !!isContractUpdated,
       updatedContractClassId: isContractUpdated ? publiclyRegisteredContract.currentContractClassId : undefined,

package/src/base-wallet/index.ts

@@ -1,2 +1,7 @@
-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';

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