@aztec/simulator 0.87.5 → 0.87.6

package/src/private/acvm/index.ts

@@ -1,5 +1,4 @@
 export { extractCallStack, type ACIRCallback, type ACIRExecutionResult } from './acvm.js';
 export * from './acvm_types.js';
 export * from './deserialize.js';
-export * from './oracle/index.js';
 export * from './serialize.js';

package/src/private/{providers/acvm_native.ts → acvm_native.ts}

@@ -9,9 +9,9 @@ import type { NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 import * as proc from 'child_process';
 import { promises as fs } from 'fs';
 
-import type { ACIRCallback, ACIRExecutionResult } from '../acvm/acvm.js';
-import type { ACVMWitness } from '../acvm/acvm_types.js';
-import type { SimulationProvider } from './simulation_provider.js';
+import type { ACIRCallback, ACIRExecutionResult } from './acvm/acvm.js';
+import type { ACVMWitness } from './acvm/acvm_types.js';
+import type { CircuitSimulator } from './circuit_simulator.js';
 
 const logger = createLogger('simulator:acvm-native');
 
@@ -137,7 +137,7 @@ export async function executeNativeCircuit(
   }
 }
 
-export class NativeACVMSimulator implements SimulationProvider {
+export class NativeACVMSimulator implements CircuitSimulator {
   constructor(
     private workingDirectory: string,
     private pathToAcvm: string,

package/src/private/{providers/acvm_wasm.ts → acvm_wasm.ts}

@@ -5,12 +5,12 @@ import initAbi from '@aztec/noir-noirc_abi';
 import type { FunctionArtifactWithContractName } from '@aztec/stdlib/abi';
 import type { NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 
-import { type ACIRCallback, type ACIRExecutionResult, acvm } from '../acvm/acvm.js';
-import type { ACVMWitness } from '../acvm/acvm_types.js';
+import { type ACIRCallback, type ACIRExecutionResult, acvm } from './acvm/acvm.js';
+import type { ACVMWitness } from './acvm/acvm_types.js';
 import type { ACVMSuccess } from './acvm_native.js';
-import { type SimulationProvider, enrichNoirError } from './simulation_provider.js';
+import { type CircuitSimulator, enrichNoirError } from './circuit_simulator.js';
 
-export class WASMSimulator implements SimulationProvider {
+export class WASMSimulator implements CircuitSimulator {
   constructor(protected log = createLogger('wasm-simulator')) {}
 
   async init(): Promise<void> {

package/src/private/{providers/acvm_wasm_with_blobs.ts → acvm_wasm_with_blobs.ts}

@@ -4,19 +4,19 @@ import type { WitnessMap } from '@aztec/noir-types';
 import type { FunctionArtifactWithContractName } from '@aztec/stdlib/abi';
 import type { NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 
-import type { ACIRCallback, ACIRExecutionResult } from '../acvm/acvm.js';
-import type { ACVMWitness } from '../acvm/acvm_types.js';
+import type { ACIRCallback, ACIRExecutionResult } from './acvm/acvm.js';
+import type { ACVMWitness } from './acvm/acvm_types.js';
 import type { ACVMSuccess } from './acvm_native.js';
-import { type SimulationProvider, enrichNoirError } from './simulation_provider.js';
+import { type CircuitSimulator, enrichNoirError } from './circuit_simulator.js';
 
 /**
- * A simulation provider that uses the WASM simulator with the ability to handle blobs via the foreign call handler.
+ * A circuit simulator that uses the WASM simulator with the ability to handle blobs via the foreign call handler.
  * This class is temporary while brillig cannot handle the blob math, and it is kept separate
  * because the zkg commitment library used in the blob code is not browser compatible.
  *
  * It is only used in the context of server-side code executing simulated protocol circuits.
  */
-export class WASMSimulatorWithBlobs implements SimulationProvider {
+export class WASMSimulatorWithBlobs implements CircuitSimulator {
   async executeProtocolCircuit(
     input: WitnessMap,
     artifact: NoirCompiledCircuitWithName,

package/src/private/circuit_recording/circuit_recorder.ts

@@ -0,0 +1,260 @@
+import { sha512 } from '@aztec/foundation/crypto';
+import { createLogger } from '@aztec/foundation/log';
+import { Timer } from '@aztec/foundation/timer';
+import type { ForeignCallHandler, ForeignCallInput, ForeignCallOutput } from '@aztec/noir-acvm_js';
+
+import type { ACIRCallback } from '../acvm/acvm.js';
+import type { ACVMWitness } from '../acvm/acvm_types.js';
+
+export type OracleCall = {
+  name: string;
+  inputs: unknown[];
+  outputs: unknown;
+  time: number;
+  // Due to the recursive nature of the simulator, we might have
+  // oracle calls performed after a foreign call (which is itself an oracle call)
+  // We keep track of the stack depth in this variable to ensure the recorded oracle
+  // calls are correctly associated with the right circuit.
+  // This is only use as a debugging tool
+  stackDepth: number;
+};
+
+export class CircuitRecording {
+  circuitName: string;
+  functionName: string;
+  bytecodeSHA512Hash: string;
+  timestamp: number;
+  inputs: Record<string, string>;
+  oracleCalls: OracleCall[];
+  error?: string;
+  parent?: CircuitRecording;
+
+  constructor(circuitName: string, functionName: string, bytecodeSHA512Hash: string, inputs: Record<string, string>) {
+    this.circuitName = circuitName;
+    this.functionName = functionName;
+    this.bytecodeSHA512Hash = bytecodeSHA512Hash;
+    this.timestamp = Date.now();
+    this.inputs = inputs;
+    this.oracleCalls = [];
+  }
+
+  setParent(recording?: CircuitRecording): void {
+    this.parent = recording;
+  }
+}
+
+/**
+ * Class responsible for recording circuit inputs necessary to replay the circuit. These inputs are the initial witness
+ * map and the oracle calls made during the circuit execution/witness generation.
+ *
+ * Example recording object:
+ * ```json
+ * {
+ *   "circuitName": "AMM",
+ *   "functionName": "add_liquidity",
+ *   "bytecodeSHA512Hash": "b46c640ed38f20eac5f61a5e41d8dd1e",
+ *   "timestamp": 1740691464360,
+ *   "inputs": {
+ *     "0": "0x1e89de1f0ad5204263733b7ddf65bec45b8f44714a4da85a46474dad677679ef",
+ *     "1": "0x00f4d59c0ff773427bb0fed5b422557ca4dc5655abe53d31fa9408cb3c5a672f",
+ *     "5": "0x000000000000000000000000000000000000000000000000000000000000000f"
+ *   },
+ *   "oracleCalls": [
+ *     {
+ *       "name": "loadCapsule",
+ *       "inputs": [
+ *         [
+ *           "0x102422483bad6abd385948435667e144ac4c272576e325e7563608876cd446fd"
+ *         ],
+ *         [
+ *           "0x000000000000000000000000000000000000000000000000000000000000004d"
+ *         ],
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000001"
+ *         ]
+ *       ],
+ *       "outputs": [
+ *         "0x0000000000000000000000000000000000000000000000000000000000000000",
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000000"
+ *         ]
+ *       ]
+ *     },
+ *     {
+ *       "name": "fetchTaggedLogs",
+ *       "inputs": []
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export class CircuitRecorder {
+  protected readonly logger = createLogger('simulator:acvm:recording');
+
+  protected recording?: CircuitRecording;
+
+  private stackDepth: number = 0;
+  private newCircuit: boolean = true;
+
+  protected constructor() {}
+
+  /**
+   * Initializes a new circuit recording session.
+   * @param recordDir - Directory to store the recording
+   * @param input - Circuit input witness
+   * @param circuitBytecode - Compiled circuit bytecode
+   * @param circuitName - Name of the circuit
+   * @param functionName - Name of the circuit function (defaults to 'main'). This is meaningful only for
+   * contracts as protocol circuits artifacts always contain a single entrypoint function called 'main'.
+   */
+  start(input: ACVMWitness, circuitBytecode: Buffer, circuitName: string, functionName: string): Promise<void> {
+    const parentRef = this.recording;
+    if (this.newCircuit) {
+      this.recording = new CircuitRecording(
+        circuitName,
+        functionName,
+        sha512(circuitBytecode).toString('hex'),
+        Object.fromEntries(input),
+      );
+    }
+    this.recording!.setParent(parentRef);
+
+    return Promise.resolve();
+  }
+
+  /**
+   * Wraps a callback to record all oracle/foreign calls.
+   * @param callback - The original callback to wrap, either a user circuit callback or protocol circuit callback.
+   * @returns A wrapped callback that records all oracle interactions.
+   */
+  wrapCallback(callback: ACIRCallback | ForeignCallHandler | undefined): ACIRCallback | ForeignCallHandler | undefined {
+    if (!callback) {
+      return undefined;
+    }
+    if (this.#isACIRCallback(callback)) {
+      return this.#wrapUserCircuitCallback(callback);
+    }
+    return this.#wrapProtocolCircuitCallback(callback);
+  }
+
+  /**
+   * Type guard to check if a callback is an ACIRCallback.
+   */
+  #isACIRCallback(callback: ACIRCallback | ForeignCallHandler): callback is ACIRCallback {
+    return typeof callback === 'object' && callback !== null && !('call' in callback);
+  }
+
+  /**
+   * Wraps a user circuit callback to record all oracle calls.
+   * @param callback - The original circuit callback.
+   * @returns A wrapped callback that records all oracle interactions which is to be provided to the ACVM.
+   */
+  #wrapUserCircuitCallback(callback: ACIRCallback): ACIRCallback {
+    const recordingCallback: ACIRCallback = {} as ACIRCallback;
+    const oracleMethods = Object.keys(callback);
+
+    for (const name of oracleMethods) {
+      const fn = callback[name as keyof ACIRCallback];
+      if (!fn || typeof fn !== 'function') {
+        throw new Error(`Oracle method ${name} not found when setting up recording callback`);
+      }
+
+      const isExternalCall = (name as keyof ACIRCallback) === 'callPrivateFunction';
+
+      recordingCallback[name as keyof ACIRCallback] = (...args: ForeignCallInput[]): ReturnType<typeof fn> => {
+        const timer = new Timer();
+        // If we're entering another circuit via `callPrivateFunction`, we increase the stack depth and set the
+        // newCircuit variable to ensure we are creating a new recording object.
+        if (isExternalCall) {
+          this.stackDepth++;
+          this.newCircuit = true;
+        }
+        const result = fn.call(callback, ...args);
+        if (result instanceof Promise) {
+          return result.then(async r => {
+            // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
+            // since we are going back to the "parent" circuit which can never be new
+            if (isExternalCall) {
+              this.stackDepth--;
+              this.newCircuit = false;
+              this.recording = this.recording!.parent;
+            }
+            await this.recordCall(name, args, r, timer.ms(), this.stackDepth);
+            return r;
+          }) as ReturnType<typeof fn>;
+        }
+        // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
+        // since we are going back to the "parent" circuit which can never be new
+        if (isExternalCall) {
+          this.stackDepth--;
+          this.newCircuit = false;
+          this.recording = this.recording!.parent;
+        }
+        void this.recordCall(name, args, result, timer.ms(), this.stackDepth);
+        return result;
+      };
+    }
+
+    return recordingCallback;
+  }
+
+  /**
+   * Wraps a protocol circuit callback to record all oracle calls.
+   * @param callback - The original oracle circuit callback.
+   * @returns A wrapped handler that records all oracle interactions which is to be provided to the ACVM.
+   */
+  #wrapProtocolCircuitCallback(callback: ForeignCallHandler): ForeignCallHandler {
+    return async (name: string, inputs: ForeignCallInput[]): Promise<ForeignCallOutput[]> => {
+      const timer = new Timer();
+      const result = await callback(name, inputs);
+      await this.recordCall(name, inputs, result, timer.ms(), 0);
+      return result;
+    };
+  }
+
+  /**
+   * Records a single oracle/foreign call with its inputs and outputs.
+   * @param name - Name of the call
+   * @param inputs - Input arguments
+   * @param outputs - Output results
+   */
+  recordCall(name: string, inputs: unknown[], outputs: unknown, time: number, stackDepth: number): Promise<OracleCall> {
+    const entry = {
+      name,
+      inputs,
+      outputs,
+      time,
+      stackDepth,
+    };
+    this.recording!.oracleCalls.push(entry);
+    return Promise.resolve(entry);
+  }
+
+  /**
+   * Finalizes the recording by resetting the state and returning the recording object.
+   */
+  finish(): Promise<CircuitRecording> {
+    const result = this.recording;
+    // If this is the top-level circuit recording, we reset the state for the next simulator call
+    if (!result!.parent) {
+      this.newCircuit = true;
+      this.recording = undefined;
+    }
+    return Promise.resolve(result!);
+  }
+
+  /**
+   * Finalizes the recording by resetting the state and returning the recording object with an attached error.
+   * @param error - The error that occurred during circuit execution
+   */
+  finishWithError(error: unknown): Promise<CircuitRecording> {
+    const result = this.recording;
+    // If this is the top-level circuit recording, we reset the state for the next simulator call
+    if (!result!.parent) {
+      this.newCircuit = true;
+      this.recording = undefined;
+    }
+    result!.error = JSON.stringify(error);
+    return Promise.resolve(result!);
+  }
+}

package/src/private/circuit_recording/file_circuit_recorder.ts

@@ -0,0 +1,158 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+import type { ACVMWitness } from '../acvm/acvm_types.js';
+import { CircuitRecorder, type CircuitRecording } from './circuit_recorder.js';
+
+export class FileCircuitRecorder extends CircuitRecorder {
+  declare recording?: CircuitRecording & { filePath: string; isFirstCall: boolean };
+
+  constructor(private readonly recordDir: string) {
+    super();
+  }
+
+  override async start(
+    input: ACVMWitness,
+    circuitBytecode: Buffer,
+    circuitName: string,
+    functionName: string = 'main',
+  ) {
+    await super.start(input, circuitBytecode, circuitName, functionName);
+
+    const recordingStringWithoutClosingBracket = JSON.stringify(
+      { ...this.recording, isFirstCall: undefined, parent: undefined, oracleCalls: undefined, filePath: undefined },
+      null,
+      2,
+    ).slice(0, -2);
+
+    try {
+      // Check if the recording directory exists and is a directory
+      const stats = await fs.stat(this.recordDir);
+      if (!stats.isDirectory()) {
+        throw new Error(`Recording path ${this.recordDir} exists but is not a directory`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        // The directory does not exist so we create it
+        await fs.mkdir(this.recordDir, { recursive: true });
+      } else {
+        throw err;
+      }
+    }
+
+    this.recording!.isFirstCall = true;
+    this.recording!.filePath = await FileCircuitRecorder.#computeFilePathAndStoreInitialRecording(
+      this.recordDir,
+      this.recording!.circuitName,
+      this.recording!.functionName,
+      recordingStringWithoutClosingBracket,
+    );
+  }
+
+  /**
+   * Computes a unique file path for the recording by trying different counter values.
+   * This is needed because multiple recordings of the same circuit could be happening simultaneously or an older
+   * recording might be present.
+   * @param recordDir - Directory to store the recording
+   * @param circuitName - Name of the circuit
+   * @param functionName - Name of the circuit function
+   * @param recordingContent - Initial recording content
+   * @returns A unique file path for the recording
+   */
+  static async #computeFilePathAndStoreInitialRecording(
+    recordDir: string,
+    circuitName: string,
+    functionName: string,
+    recordingContent: string,
+  ): Promise<string> {
+    let counter = 0;
+    while (true) {
+      try {
+        const filePath = getFilePath(recordDir, circuitName, functionName, counter);
+        // Write the initial recording content to the file
+        await fs.writeFile(filePath, recordingContent + ',\n  "oracleCalls": [\n', {
+          flag: 'wx', // wx flag fails if file exists
+        });
+        return filePath;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+          counter++;
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Records a single oracle/foreign call with its inputs and outputs.
+   * @param name - Name of the call
+   * @param inputs - Input arguments
+   * @param outputs - Output results
+   */
+  override async recordCall(name: string, inputs: unknown[], outputs: unknown, time: number, stackDepth: number) {
+    const entry = await super.recordCall(name, inputs, outputs, time, stackDepth);
+    try {
+      const prefix = this.recording!.isFirstCall ? '    ' : '    ,';
+      this.recording!.isFirstCall = false;
+      await fs.appendFile(this.recording!.filePath, prefix + JSON.stringify(entry) + '\n');
+    } catch (err) {
+      this.logger.error('Failed to log circuit call', { error: err });
+    }
+    return entry;
+  }
+
+  /**
+   * Finalizes the recording file by adding closing brackets. Without calling this method, the recording file is
+   * incomplete and it fails to parse.
+   */
+  override async finish(): Promise<CircuitRecording> {
+    // Finish sets the recording to undefined if we are at the topmost circuit,
+    // so we save the current file path before that
+    const filePath = this.recording!.filePath;
+    const result = await super.finish();
+    try {
+      await fs.appendFile(filePath, '  ]\n}\n');
+    } catch (err) {
+      this.logger.error('Failed to finalize recording file', { error: err });
+    }
+    return result!;
+  }
+
+  /**
+   * Finalizes the recording file by adding the error and closing brackets. Without calling this method or `finish`,
+   * the recording file is incomplete and it fails to parse.
+   * @param error - The error that occurred during circuit execution
+   */
+  override async finishWithError(error: unknown): Promise<CircuitRecording> {
+    // Finish sets the recording to undefined if we are at the topmost circuit,
+    // so we save the current file path before that
+    const filePath = this.recording!.filePath;
+    const result = await super.finishWithError(error);
+    try {
+      await fs.appendFile(filePath, '  ],\n');
+      await fs.appendFile(filePath, `  "error": ${JSON.stringify(error)}\n`);
+      await fs.appendFile(filePath, '}\n');
+    } catch (err) {
+      this.logger.error('Failed to finalize recording file with error', { error: err });
+    }
+    return result!;
+  }
+}
+
+/**
+ * Generates a file path for storing circuit recordings. The format of the filename is:
+ * `circuit_name_circuit_function_name_YYYY-MM-DD_N.json` where N is a counter to ensure unique filenames.
+ * @param recordDir - Base directory for recordings
+ * @param circuitName - Name of the circuit
+ * @param functionName - Name of the circuit function
+ * @param counter - Counter to ensure unique filenames. This is expected to be incremented in a loop until there is no
+ * existing file with the same name.
+ * @returns A file path for the recording.
+ */
+function getFilePath(recordDir: string, circuitName: string, functionName: string, counter: number): string {
+  const date = new Date();
+  const formattedDate = date.toISOString().split('T')[0];
+  const filename = `${circuitName}_${functionName}_${formattedDate}_${counter}.json`;
+  return path.join(recordDir, filename);
+}

package/src/private/circuit_recording/memory_circuit_recorder.ts

@@ -0,0 +1,11 @@
+import { CircuitRecorder } from './circuit_recorder.js';
+
+/*
+ * In memory circuit recorder uses the default implementation. This is kept
+ * while we decide the fate of the FileCircuitRecorder
+ */
+export class MemoryCircuitRecorder extends CircuitRecorder {
+  constructor() {
+    super();
+  }
+}

package/src/private/{providers/circuit_recording/simulation_provider_recorder_wrapper.ts → circuit_recording/simulator_recorder_wrapper.ts}

@@ -2,18 +2,21 @@ import type { ForeignCallHandler } from '@aztec/noir-protocol-circuits-types/typ
 import type { FunctionArtifactWithContractName } from '@aztec/stdlib/abi';
 import type { NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 
-import type { ACIRCallback, ACIRExecutionResult } from '../../acvm/acvm.js';
-import type { ACVMWitness } from '../../acvm/acvm_types.js';
+import type { ACIRCallback, ACIRCallbackStats, ACIRExecutionResult } from '../acvm/acvm.js';
+import type { ACVMWitness } from '../acvm/acvm_types.js';
 import type { ACVMSuccess } from '../acvm_native.js';
-import type { SimulationProvider } from '../simulation_provider.js';
-import { CircuitRecorder } from './circuit_recorder.js';
+import type { CircuitSimulator } from '../circuit_simulator.js';
+import type { CircuitRecorder } from './circuit_recorder.js';
 
 /**
- * Takes a simulation provider and wraps it in a circuit recorder. See CircuitRecorder for more details on how circuit
+ * Takes a circuit simulator and wraps it in a circuit recorder. See CircuitRecorder for more details on how circuit
  * recording works.
  */
-export class SimulationProviderRecorderWrapper implements SimulationProvider {
-  constructor(private simulator: SimulationProvider) {}
+export class SimulatorRecorderWrapper implements CircuitSimulator {
+  constructor(
+    private simulator: CircuitSimulator,
+    private recorder: CircuitRecorder,
+  ) {}
 
   executeProtocolCircuit(
     input: ACVMWitness,
@@ -47,7 +50,7 @@ export class SimulationProviderRecorderWrapper implements SimulationProvider {
     );
   }
 
-  async #simulate<C extends ACIRCallback | ForeignCallHandler | undefined, T>(
+  async #simulate<C extends ACIRCallback | ForeignCallHandler | undefined, T extends ACIRExecutionResult | ACVMSuccess>(
     simulateFn: (wrappedCallback: C) => Promise<T>,
     input: ACVMWitness,
     bytecode: Buffer,
@@ -55,28 +58,33 @@ export class SimulationProviderRecorderWrapper implements SimulationProvider {
     functionName: string,
     callback: C,
   ): Promise<T> {
-    const recordDir = process.env.CIRCUIT_RECORD_DIR;
-    if (!recordDir) {
-      // Recording is not enabled so we just execute the circuit
-      return simulateFn(callback);
-    }
-
     // Start recording circuit execution
-    const recorder = await CircuitRecorder.start(recordDir, input, bytecode, contractName, functionName);
+    await this.recorder.start(input, bytecode, contractName, functionName);
 
     // If callback was provided, we wrap it in a circuit recorder callback wrapper
-    const wrappedCallback = recorder.wrapCallback(callback);
+    const wrappedCallback = this.recorder.wrapCallback(callback);
     let result: T;
     try {
       result = await simulateFn(wrappedCallback as C);
     } catch (error) {
       // If an error occurs, we finalize the recording file with the error
-      await recorder.finishWithError(error);
+      await this.recorder.finishWithError(error);
       throw error;
     }
 
     // Witness generation is complete so we finish the circuit recorder
-    await recorder.finish();
+    const recording = await this.recorder.finish();
+
+    (result as ACIRExecutionResult).oracles = recording.oracleCalls?.reduce(
+      (acc, { time, name }) => {
+        if (!acc[name]) {
+          acc[name] = { times: [] };
+        }
+        acc[name].times.push(time);
+        return acc;
+      },
+      {} as Record<string, ACIRCallbackStats>,
+    );
 
     return result;
   }

package/src/private/{providers/simulation_provider.ts → circuit_simulator.ts}

@@ -4,14 +4,14 @@ import { parseDebugSymbols } from '@aztec/stdlib/abi';
 import type { FunctionArtifactWithContractName } from '@aztec/stdlib/abi';
 import type { NoirCompiledCircuit, NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 
-import { type ACIRCallback, type ACIRExecutionResult, extractCallStack } from '../acvm/acvm.js';
-import type { ACVMWitness } from '../acvm/acvm_types.js';
+import { type ACIRCallback, type ACIRExecutionResult, extractCallStack } from './acvm/acvm.js';
+import type { ACVMWitness } from './acvm/acvm_types.js';
 import type { ACVMSuccess } from './acvm_native.js';
 
 /**
  * Low level simulation interface
  */
-export interface SimulationProvider {
+export interface CircuitSimulator {
   /**
    * Execute a protocol circuit/generate a witness
    * @param input - The initial witness map defining all of the inputs to `circuit`.

package/src/private/{providers/factory.ts → factory.ts}

@@ -4,14 +4,14 @@ import { promises as fs } from 'fs';
 
 import { NativeACVMSimulator } from './acvm_native.js';
 import { WASMSimulator } from './acvm_wasm.js';
-import type { SimulationProvider } from './simulation_provider.js';
+import type { CircuitSimulator } from './circuit_simulator.js';
 
-export type SimulationProviderConfig = {
+export type SimulatorConfig = {
   acvmBinaryPath?: string;
   acvmWorkingDirectory?: string;
 };
 
-export function getSimulationProviderConfigFromEnv() {
+export function getSimulatorConfigFromEnv() {
   const { ACVM_BINARY_PATH, ACVM_WORKING_DIRECTORY } = process.env;
   return {
     acvmWorkingDirectory: ACVM_WORKING_DIRECTORY ? ACVM_WORKING_DIRECTORY : undefined,
@@ -19,10 +19,10 @@ export function getSimulationProviderConfigFromEnv() {
   };
 }
 
-export async function createSimulationProvider(
-  config: SimulationProviderConfig,
+export async function createSimulator(
+  config: SimulatorConfig,
   logger: Logger = createLogger('simulator'),
-): Promise<SimulationProvider> {
+): Promise<CircuitSimulator> {
   if (config.acvmBinaryPath && config.acvmWorkingDirectory) {
     try {
       await fs.access(config.acvmBinaryPath, fs.constants.R_OK);

package/src/public/avm/fixtures/base_avm_simulation_tester.ts

@@ -100,4 +100,9 @@ export abstract class BaseAvmSimulationTester {
     );
     await this.merkleTrees.sequentialInsert(MerkleTreeId.NULLIFIER_TREE, [contractAddressNullifier.toBuffer()]);
   }
+
+  async insertNullifier(contractThatEmitted: AztecAddress, nullifier: Fr) {
+    const siloedNullifier = await siloNullifier(contractThatEmitted, nullifier);
+    await this.merkleTrees.sequentialInsert(MerkleTreeId.NULLIFIER_TREE, [siloedNullifier.toBuffer()]);
+  }
 }