@aztec-labs/simulator 6.0.0-nightly.20260829

package/src/public/fixtures/custom_bytecode_tester.ts

@@ -0,0 +1,83 @@
+import { FunctionType, emptyContractArtifact, emptyFunctionArtifact } from '@aztec-labs/stdlib/abi';
+import type { PublicTxResult } from '@aztec-labs/stdlib/avm';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractInstanceWithAddress } from '@aztec-labs/stdlib/contract';
+
+import { PublicTxSimulationTester } from './public_tx_simulation_tester.js';
+
+/**
+ * Deploy a contract with the provided bytecode.
+ * @param bytecode - The bytecode buffer to use
+ * @param tester - The tester to use
+ * @param contractName - The name of the contract
+ * @param deployer - The deployer address
+ * @returns The deployed contract instance
+ */
+export async function deployCustomBytecode(
+  bytecode: Buffer,
+  tester: PublicTxSimulationTester,
+  contractName: string = 'CustomBytecodeContract',
+  deployer: AztecAddress = AztecAddress.fromNumberUnsafe(42),
+): Promise<ContractInstanceWithAddress> {
+  const contractArtifact = emptyContractArtifact();
+  contractArtifact.name = contractName;
+  contractArtifact.functions = [emptyFunctionArtifact()];
+  // We use name 'public_dispatch' since that is what is expected
+  // in a ContractArtifact. But function selectors are not required
+  // when executing since the custom bytecode likely has no dispatch.
+  contractArtifact.functions[0].name = 'public_dispatch';
+  contractArtifact.functions[0].functionType = FunctionType.PUBLIC;
+  contractArtifact.functions[0].bytecode = bytecode;
+
+  // return the contract instance
+  return await tester.registerAndDeployContract(
+    /*constructorArgs=*/ [],
+    deployer,
+    /*contractArtifact=*/ contractArtifact,
+  );
+}
+
+/**
+ * Execute a custom bytecode contract.
+ * @param contract - The contract instance to execute
+ * @param tester - The tester to use
+ * @param txLabel - The label of the transaction
+ * @param calldata - The calldata to use
+ * @returns The execution result
+ */
+export async function executeCustomBytecode(
+  contract: ContractInstanceWithAddress,
+  tester: PublicTxSimulationTester,
+  txLabel: string = 'CustomBytecodeTest',
+  calldata: any[] = [],
+): Promise<PublicTxResult> {
+  // EXECUTE! This means that if using AvmProvingTester subclass, it will PROVE the transaction!
+  return await tester.executeTxWithLabel(
+    /*txLabel=*/ txLabel,
+    /*sender=*/ contract.deployer,
+    /*setupCalls=*/ [],
+    /*appCalls=*/ [{ address: contract.address, args: calldata }],
+  );
+}
+
+/**
+ * Deploy and execute a custom bytecode contract.
+ * @param bytecode - The bytecode buffer to use
+ * @param tester - The tester to use
+ * @param txLabel - The label of the transaction
+ * @param contractName - The name of the contract
+ * @param deployer - The deployer address
+ * @param calldata - The calldata to use
+ * @returns The execution result
+ */
+export async function deployAndExecuteCustomBytecode(
+  bytecode: Buffer,
+  tester: PublicTxSimulationTester,
+  txLabel: string = 'CustomBytecodeTest',
+  contractName: string = 'CustomBytecodeContract',
+  deployer: AztecAddress = AztecAddress.fromNumberUnsafe(42),
+  calldata: any[] = [],
+): Promise<PublicTxResult> {
+  const testContract = await deployCustomBytecode(bytecode, tester, contractName, deployer);
+  return await executeCustomBytecode(testContract, tester, txLabel, calldata);
+}

package/src/public/fixtures/index.ts

@@ -0,0 +1,13 @@
+export * from './public_tx_simulation_tester.js';
+export * from './public_processor_test_env.js';
+export * from './utils.js';
+export * from './simple_contract_data_source.js';
+export { TestExecutorMetrics } from '../test_executor_metrics.js';
+export { ammTest } from './amm_test.js';
+export { bulkTest, megaBulkTest } from './bulk_test.js';
+export { tokenTest } from './token_test.js';
+export {
+  deployCustomBytecode,
+  executeCustomBytecode,
+  deployAndExecuteCustomBytecode,
+} from './custom_bytecode_tester.js';

package/src/public/fixtures/public_processor_test_env.ts

@@ -0,0 +1,88 @@
+import { createLogger } from '@aztec-labs/foundation/log';
+import { TestDateProvider } from '@aztec-labs/foundation/timer';
+import { PublicSimulatorConfig } from '@aztec-labs/stdlib/avm';
+import { GasFees } from '@aztec-labs/stdlib/gas';
+import { GlobalVariables } from '@aztec-labs/stdlib/tx';
+import { getTelemetryClient } from '@aztec-labs/telemetry-client';
+import { NativeWorldStateService } from '@aztec-labs/world-state';
+
+import { AvmSimulatorPool } from '../avm_simulator_pool.js';
+import { PublicContractsDB } from '../public_db_sources.js';
+import { GuardedMerkleTreeOperations } from '../public_processor/guarded_merkle_tree.js';
+import { PublicProcessor } from '../public_processor/public_processor.js';
+import { PublicTxSimulator } from '../public_tx_simulator/public_tx_simulator.js';
+import { PublicTxSimulationTester } from './public_tx_simulation_tester.js';
+import { SimpleContractDataSource } from './simple_contract_data_source.js';
+
+/** Options for {@link PublicProcessorTestEnv.create}. */
+export interface PublicProcessorTestEnvOptions {
+  /** Global variables shared by the processor and the tester. Defaults to empty with nonzero gas fees. */
+  globals?: GlobalVariables;
+  /** Simulator config for the processor's PublicTxSimulator. */
+  config?: Partial<PublicSimulatorConfig>;
+}
+
+function defaultGlobals(): GlobalVariables {
+  const globals = GlobalVariables.empty();
+  globals.gasFees = new GasFees(2, 3);
+  return globals;
+}
+
+const defaultConfig = PublicSimulatorConfig.from({
+  skipFeeEnforcement: false,
+  collectDebugLogs: true,
+  collectHints: false,
+  collectStatistics: false,
+  collectCallMetadata: true,
+});
+
+/**
+ * Bundles the real-AVM wiring shared by public-processor app tests: a live WSDB world state, a CDB IPC
+ * server, a spawned AVM simulator, a {@link PublicProcessor} backed by all three, and a setup-only
+ * {@link PublicTxSimulationTester} sharing the same fork and contract data source for building txs and
+ * seeding balances. Own it with `await using`, or call {@link Symbol.asyncDispose} from `afterEach`.
+ */
+export class PublicProcessorTestEnv implements AsyncDisposable {
+  private constructor(
+    public readonly processor: PublicProcessor,
+    public readonly tester: PublicTxSimulationTester,
+    public readonly contractsDB: PublicContractsDB,
+    public readonly globals: GlobalVariables,
+    private readonly worldStateService: NativeWorldStateService,
+    private readonly avmSimulator: AvmSimulatorPool,
+  ) {}
+
+  static async create(opts: PublicProcessorTestEnvOptions = {}): Promise<PublicProcessorTestEnv> {
+    const globals = opts.globals ?? defaultGlobals();
+    const config = opts.config ? PublicSimulatorConfig.from({ ...defaultConfig, ...opts.config }) : defaultConfig;
+
+    const contractDataSource = new SimpleContractDataSource();
+    const worldStateService = await NativeWorldStateService.tmp();
+    const merkleTrees = await worldStateService.fork();
+    const contractsDB = new PublicContractsDB(contractDataSource);
+
+    const forkId = merkleTrees.getRevision().forkId;
+    const avmSimulator = await AvmSimulatorPool.spawn({ wsdbIpcPath: worldStateService.getIpcPath() });
+
+    const simulator = new PublicTxSimulator(avmSimulator, globals, contractsDB, forkId, config, undefined);
+    const processor = new PublicProcessor(
+      globals,
+      new GuardedMerkleTreeOperations(merkleTrees),
+      contractsDB,
+      simulator,
+      new TestDateProvider(),
+      getTelemetryClient(),
+      createLogger('simulator:public-processor'),
+    );
+
+    const tester = new PublicTxSimulationTester(merkleTrees, contractDataSource, globals);
+
+    return new PublicProcessorTestEnv(processor, tester, contractsDB, globals, worldStateService, avmSimulator);
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.avmSimulator[Symbol.asyncDispose]();
+    await this.tester.close();
+    await this.worldStateService.close();
+  }
+}

package/src/public/fixtures/public_tx_simulation_tester.ts

@@ -0,0 +1,315 @@
+import { PUBLIC_TX_L2_GAS_OVERHEAD, TX_DA_GAS_OVERHEAD } from '@aztec-labs/constants';
+import { asyncMap } from '@aztec-labs/foundation/async-map';
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { type ContractArtifact, encodeArguments } from '@aztec-labs/stdlib/abi';
+import { PublicSimulatorConfig, type PublicTxResult } from '@aztec-labs/stdlib/avm';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { Gas, GasFees } from '@aztec-labs/stdlib/gas';
+import type { MerkleTreeWriteOperations } from '@aztec-labs/stdlib/interfaces/server';
+import { PublicCallRequest } from '@aztec-labs/stdlib/kernel';
+import { GlobalVariables, PublicCallRequestWithCalldata, type Tx } from '@aztec-labs/stdlib/tx';
+import { NativeWorldStateService } from '@aztec-labs/world-state';
+
+import { BaseAvmSimulationTester } from '../avm/testing/base_avm_simulation_tester.js';
+import {
+  DEFAULT_BLOCK_NUMBER,
+  DEFAULT_TIMESTAMP,
+  getContractFunctionAbi,
+  getFunctionSelector,
+} from '../avm/testing/utils.js';
+import { AvmSimulatorPool } from '../avm_simulator_pool.js';
+import { PublicContractsDB } from '../public_db_sources.js';
+import { MeasuredPublicTxSimulator } from '../public_tx_simulator/public_tx_simulator.js';
+import type { MeasuredPublicTxSimulatorInterface } from '../public_tx_simulator/public_tx_simulator_interface.js';
+import { TestExecutorMetrics } from '../test_executor_metrics.js';
+import { SimpleContractDataSource } from './simple_contract_data_source.js';
+import { type TestPrivateInsertions, createTxForPublicCalls } from './utils.js';
+
+const DEFAULT_GAS_FEES = new GasFees(2, 3);
+const TEARDOWN_DA_GAS_LIMIT = 98_304;
+const TEARDOWN_L2_GAS_LIMIT = 817_500;
+
+export type TestEnqueuedCall = {
+  sender?: AztecAddress;
+  address: AztecAddress;
+  fnName?: string;
+  args: any[];
+  isStaticCall?: boolean;
+  contractArtifact?: ContractArtifact;
+};
+
+const defaultConfig: PublicSimulatorConfig = PublicSimulatorConfig.from({
+  skipFeeEnforcement: false,
+  collectCallMetadata: true,
+  collectDebugLogs: true,
+  collectHints: false,
+  collectPublicInputs: false,
+  collectStatistics: false,
+});
+
+/**
+ * Factory type for creating a MeasuredPublicTxSimulatorInterface.
+ */
+export type MeasuredSimulatorFactory = (
+  merkleTree: MerkleTreeWriteOperations,
+  contractsDB: PublicContractsDB,
+  globals: GlobalVariables,
+  metrics: TestExecutorMetrics,
+  config: PublicSimulatorConfig,
+) => MeasuredPublicTxSimulatorInterface;
+
+/**
+ * A test class that extends the BaseAvmSimulationTester to enable real-app testing of the PublicTxSimulator.
+ * It provides an interface for simulating one transaction at a time and maintains state between subsequent
+ * transactions.
+ */
+export class PublicTxSimulationTester extends BaseAvmSimulationTester {
+  protected txCount: number = 0;
+  private simulator: MeasuredPublicTxSimulatorInterface | undefined;
+  private metricsPrefix?: string;
+  protected avmSimulator?: AvmSimulatorPool;
+
+  constructor(
+    merkleTree: MerkleTreeWriteOperations,
+    contractDataSource: SimpleContractDataSource,
+    globals: GlobalVariables = defaultGlobals(),
+    private metrics: TestExecutorMetrics = new TestExecutorMetrics(),
+    simulatorFactory?: MeasuredSimulatorFactory,
+    config: PublicSimulatorConfig = defaultConfig,
+  ) {
+    super(contractDataSource, merkleTree);
+
+    const contractsDB = new PublicContractsDB(contractDataSource);
+    if (simulatorFactory) {
+      this.simulator = simulatorFactory(merkleTree, contractsDB, globals, this.metrics, config);
+    } else {
+      // No simulator — this tester can only be used for setup (setFeePayerBalance, createTx, etc.)
+      // To simulate, use PublicTxSimulationTester.create() or pass a simulatorFactory.
+      this.simulator = undefined;
+    }
+  }
+
+  public static async create(
+    worldStateService: NativeWorldStateService, // make sure to close this later
+    globals: GlobalVariables = defaultGlobals(),
+    metrics: TestExecutorMetrics = new TestExecutorMetrics(),
+    config: PublicSimulatorConfig = defaultConfig,
+  ): Promise<PublicTxSimulationTester> {
+    const contractDataSource = new SimpleContractDataSource();
+    const merkleTree = await worldStateService.fork();
+
+    const avmSimulator = await AvmSimulatorPool.spawn({ wsdbIpcPath: worldStateService.getIpcPath() });
+    const simulatorFactory: MeasuredSimulatorFactory = (mt, cdb, g, m, c) =>
+      new MeasuredPublicTxSimulator(avmSimulator, g, cdb, mt.getRevision().forkId, m, c, undefined);
+
+    const tester = new PublicTxSimulationTester(
+      merkleTree,
+      contractDataSource,
+      globals,
+      metrics,
+      simulatorFactory,
+      config,
+    );
+    tester.avmSimulator = avmSimulator;
+    return tester;
+  }
+
+  public setMetricsPrefix(prefix: string) {
+    this.metricsPrefix = prefix;
+  }
+
+  public async createTx(
+    sender: AztecAddress,
+    setupCalls: TestEnqueuedCall[] = [],
+    appCalls: TestEnqueuedCall[] = [],
+    teardownCall?: TestEnqueuedCall,
+    feePayer: AztecAddress = sender,
+    /* need some unique first nullifier for note-nonce computations */
+    privateInsertions: TestPrivateInsertions = { nonRevertible: { nullifiers: [new Fr(420000 + this.txCount)] } },
+    gasLimits?: Gas,
+  ): Promise<Tx> {
+    const setupCallRequests = await asyncMap(setupCalls, call =>
+      this.#createPubicCallRequestForCall(call, call.sender ?? sender),
+    );
+    const appCallRequests = await asyncMap(appCalls, call =>
+      this.#createPubicCallRequestForCall(call, call.sender ?? sender),
+    );
+    const teardownCallRequest = teardownCall
+      ? await this.#createPubicCallRequestForCall(teardownCall, teardownCall.sender ?? sender)
+      : undefined;
+
+    this.txCount++;
+    return createTxForPublicCalls(
+      privateInsertions,
+      setupCallRequests,
+      appCallRequests,
+      teardownCallRequest,
+      feePayer,
+      /*gasUsedByPrivate*/ teardownCall
+        ? new Gas(TEARDOWN_DA_GAS_LIMIT + TX_DA_GAS_OVERHEAD, TEARDOWN_L2_GAS_LIMIT + PUBLIC_TX_L2_GAS_OVERHEAD)
+        : new Gas(TX_DA_GAS_OVERHEAD, PUBLIC_TX_L2_GAS_OVERHEAD),
+      defaultGlobals(),
+      gasLimits,
+    );
+  }
+
+  public async simulateTx(
+    sender: AztecAddress,
+    setupCalls: TestEnqueuedCall[] = [],
+    appCalls: TestEnqueuedCall[] = [],
+    teardownCall?: TestEnqueuedCall,
+    feePayer: AztecAddress = sender,
+    /* need some unique first nullifier for note-nonce computations */
+    privateInsertions?: TestPrivateInsertions,
+    txLabel: string = 'unlabeledTx',
+    gasLimits?: Gas,
+  ): Promise<PublicTxResult> {
+    const tx = await this.createTx(sender, setupCalls, appCalls, teardownCall, feePayer, privateInsertions, gasLimits);
+
+    await this.setFeePayerBalance(feePayer);
+
+    const txLabelWithCount = `${txLabel}/${this.txCount - 1}`;
+    const fullTxLabel = this.metricsPrefix ? `${this.metricsPrefix}/${txLabelWithCount}` : txLabelWithCount;
+
+    if (!this.simulator) {
+      throw new Error(
+        'No simulator configured. Pass a simulatorFactory to the constructor or use PublicTxSimulationTester.create()',
+      );
+    }
+    const avmResult = await this.simulator.simulate(tx, fullTxLabel);
+
+    // Something like this is often useful for debugging:
+    //if (avmResult.revertReason) {
+    //  // resolve / enrich revert reason
+    //  const lastAppCall = appCalls[appCalls.length - 1];
+
+    //  const contractArtifact =
+    //    lastAppCall.contractArtifact || (await this.contractDataSource.getContractArtifact(lastAppCall.address));
+    //  const fnAbi = getContractFunctionAbi(lastAppCall.fnName, contractArtifact!);
+    //  const revertReason = resolveAssertionMessageFromRevertData(avmResult.revertReason.revertData, fnAbi!);
+    //  this.logger.debug(`Revert reason: ${revertReason}`);
+    //}
+
+    return avmResult;
+  }
+
+  /**
+   * Just simulate the transaction and return the result.
+   *
+   * This wrapper around simulation allows for easy labeling of a TX
+   * which is especially useful when reporting benchmarks or metrics.
+   */
+  public async simulateTxWithLabel(
+    txLabel: string,
+    sender: AztecAddress,
+    setupCalls?: TestEnqueuedCall[],
+    appCalls?: TestEnqueuedCall[],
+    teardownCall?: TestEnqueuedCall,
+    feePayer?: AztecAddress,
+    privateInsertions?: TestPrivateInsertions,
+  ): Promise<PublicTxResult> {
+    return await this.simulateTx(sender, setupCalls, appCalls, teardownCall, feePayer, privateInsertions, txLabel);
+  }
+
+  /**
+   * Execute a transaction and return the result.
+   *
+   * This function can be (it is) overridden by a subclass (AvmProvingTester)
+   * to do more work (like prove and verify) while still reusing existing
+   * test fixtures (like amm_test). That is why it is not named "simulate*".
+   */
+  public async executeTxWithLabel(
+    txLabel: string,
+    sender: AztecAddress,
+    setupCalls?: TestEnqueuedCall[],
+    appCalls?: TestEnqueuedCall[],
+    teardownCall?: TestEnqueuedCall,
+    feePayer?: AztecAddress,
+    privateInsertions?: TestPrivateInsertions,
+  ): Promise<PublicTxResult> {
+    return await this.simulateTxWithLabel(
+      txLabel,
+      sender,
+      setupCalls,
+      appCalls,
+      teardownCall,
+      feePayer,
+      privateInsertions,
+    );
+  }
+
+  public prettyPrintMetrics() {
+    this.metrics.prettyPrint();
+  }
+
+  /** Clean up IPC resources (AVM simulator pool and merkle tree fork) created by create(). */
+  public async close(): Promise<void> {
+    await this.avmSimulator?.[Symbol.asyncDispose]();
+    // Close the merkle tree fork to release IPC resources before the wsdb process is killed.
+    if (this.merkleTrees?.close) {
+      await this.merkleTrees.close().catch(() => {});
+    }
+  }
+
+  /**
+   * Cancel the current simulation if one is in progress.
+   * This signals the underlying simulator to stop at the next safe point.
+   * Safe to call even if no simulation is in progress.
+   *
+   * @param waitTimeoutMs - If provided, wait up to this many ms for the simulation to actually stop.
+   */
+  public async cancel(waitTimeoutMs?: number): Promise<void> {
+    await this.simulator?.cancel?.(waitTimeoutMs);
+  }
+
+  /**
+   * Get the underlying simulator for advanced test scenarios.
+   * Use this when you need direct control over simulation (e.g., for testing cancellation).
+   */
+  public getSimulator(): MeasuredPublicTxSimulatorInterface | undefined {
+    return this.simulator;
+  }
+
+  async #createPubicCallRequestForCall(
+    call: TestEnqueuedCall,
+    sender: AztecAddress,
+  ): Promise<PublicCallRequestWithCalldata> {
+    const address = call.address;
+    const contractArtifact = call.contractArtifact || (await this.contractDataSource.getContractArtifact(address));
+    if (!contractArtifact) {
+      throw new Error(`Contract artifact not found for address: ${address}`);
+    }
+
+    let calldata: Fr[] = [];
+    if (!call.fnName) {
+      this.logger.debug(
+        `No function name specified for call to contract ${call.address.toString()}. Assuming this is a custom bytecode with no public_dispatch function.`,
+      );
+      this.logger.debug(`Not using ABI to encode arguments. Not prepending fn selector to calldata.`);
+      try {
+        calldata = call.args.map(arg => new Fr(arg));
+      } catch (error) {
+        this.logger.warn(`Tried assuming that all arguments are Field-like. Failed. Error: ${error}`);
+        throw error;
+      }
+    } else {
+      const fnSelector = await getFunctionSelector(call.fnName, contractArtifact);
+      const fnAbi = getContractFunctionAbi(call.fnName, contractArtifact)!;
+      const encodedArgs = encodeArguments(fnAbi, call.args);
+      calldata = [fnSelector.toField(), ...encodedArgs];
+    }
+    const isStaticCall = call.isStaticCall ?? false;
+    const request = await PublicCallRequest.fromCalldata(sender, address, isStaticCall, calldata);
+
+    return new PublicCallRequestWithCalldata(request, calldata);
+  }
+}
+
+export function defaultGlobals() {
+  const globals = GlobalVariables.empty();
+  globals.timestamp = DEFAULT_TIMESTAMP;
+  globals.gasFees = DEFAULT_GAS_FEES; // apply some nonzero default gas fees
+  globals.blockNumber = BlockNumber(DEFAULT_BLOCK_NUMBER);
+  return globals;
+}

package/src/public/fixtures/simple_contract_data_source.ts

@@ -0,0 +1,122 @@
+import type { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { createLogger } from '@aztec-labs/foundation/log';
+import type { ContractArtifact, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractClassPublic, ContractDataSource, ContractInstanceWithAddress } from '@aztec-labs/stdlib/contract';
+
+import { getFunctionSelector } from '../avm/testing/utils.js';
+
+/**
+ * This class is used during public/avm testing to function as a database of
+ * contract contract classes and instances. Tests can populate it with classes
+ * and instances and then probe it via the ContractDataSource interface.
+ *
+ * This class does not include any real merkle trees & merkle operations.
+ */
+export class SimpleContractDataSource implements ContractDataSource {
+  public logger = createLogger('simple-contract-data-source');
+
+  // maps contract class ID to class
+  private contractClasses: Map<string, ContractClassPublic> = new Map();
+  // maps contract instance address to instance
+  private contractInstances: Map<string, ContractInstanceWithAddress> = new Map();
+  // maps contract instance address to address
+  private contractArtifacts: Map<string, ContractArtifact> = new Map();
+  // maps `${classID}:${fnSelector}` to name
+  private debugFunctionName: Map<string, string> = new Map();
+
+  /////////////////////////////////////////////////////////////
+  // Helper functions not in the contract data source interface
+  /**
+   * Derive the contract class and instance with some seed.
+   * Add both to the contract data source along with the contract artifact.
+   */
+  async addNewContract(
+    contractArtifact: ContractArtifact,
+    contractClass: ContractClassPublic,
+    contractInstance: ContractInstanceWithAddress,
+  ) {
+    await this.addContractArtifact(contractClass.id, contractArtifact);
+    await this.addContractClass(contractClass);
+    await this.addContractInstance(contractInstance);
+  }
+
+  async addContractArtifact(classId: Fr, artifact: ContractArtifact) {
+    this.contractArtifacts.set(classId.toString(), artifact);
+    const classIdStr = classId.toString();
+    const publicFns = artifact.nonDispatchPublicFunctions;
+    if (publicFns.length !== 0) {
+      for (const fn of publicFns) {
+        const actualFnName = `${fn.name}`;
+        const fnSelector = await getFunctionSelector(actualFnName, artifact);
+        const key = `${classIdStr}:${fnSelector.toString()}`;
+
+        const longFnName = `${artifact.name}.${actualFnName}`;
+        this.debugFunctionName.set(key, longFnName);
+      }
+    }
+  }
+
+  /////////////////////////////////////////////////////////////
+  // ContractDataSource function implementations
+  getBlockNumber(): Promise<BlockNumber> {
+    throw new Error('Method not implemented.');
+  }
+
+  getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
+    return Promise.resolve(this.contractClasses.get(id.toString()));
+  }
+
+  getBytecodeCommitment(_id: Fr): Promise<Fr | undefined> {
+    return Promise.resolve(undefined);
+  }
+
+  getContract(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined> {
+    return Promise.resolve(this.contractInstances.get(address.toString()));
+  }
+
+  getContractClassIds(): Promise<Fr[]> {
+    throw new Error('Method not implemented.');
+  }
+
+  async getContractArtifact(address: AztecAddress): Promise<ContractArtifact | undefined> {
+    const contractInstance = await this.getContract(address);
+    if (!contractInstance) {
+      this.logger.warn(`Contract not found at address: ${address}`);
+      return undefined;
+    }
+    this.logger.debug(`Retrieved contract artifact for address: ${address}`);
+    this.logger.debug(`Contract class ID: ${contractInstance.currentContractClassId}`);
+    return this.contractArtifacts.get(contractInstance!.currentContractClassId.toString());
+  }
+
+  async getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined> {
+    const contractInstance = await this.getContract(address);
+    if (!contractInstance) {
+      this.logger.warn(`Couldn't get fn name for debugging. Contract not in tester's ContractDataSource.`);
+      return undefined;
+    }
+    const key = `${contractInstance.currentContractClassId.toString()}:${selector.toString()}`;
+    const fnName = this.debugFunctionName.get(key);
+    if (!fnName) {
+      this.logger.warn(`Couldn't get fn name for debugging...`);
+      return undefined;
+    }
+    return fnName;
+  }
+
+  registerContractFunctionSignatures(_signatures: string[]): Promise<void> {
+    return Promise.resolve();
+  }
+
+  addContractClass(contractClass: ContractClassPublic): Promise<void> {
+    this.contractClasses.set(contractClass.id.toString(), contractClass);
+    return Promise.resolve();
+  }
+
+  addContractInstance(contractInstance: ContractInstanceWithAddress): Promise<void> {
+    this.contractInstances.set(contractInstance.address.toString(), contractInstance);
+    return Promise.resolve();
+  }
+}