@aztec/simulator 0.81.0 → 0.82.0

package/src/private/providers/acvm_native.ts

@@ -1,8 +1,10 @@
 import { runInDirectory } from '@aztec/foundation/fs';
 import { createLogger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
-import type { WitnessMap } from '@aztec/noir-types';
-import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+import type { WitnessMap } from '@aztec/noir-acvm_js';
+import type { ForeignCallHandler } from '@aztec/noir-protocol-circuits-types/types';
+import type { FunctionArtifactWithContractName } from '@aztec/stdlib/abi';
+import type { NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 
 import * as proc from 'child_process';
 import { promises as fs } from 'fs';
@@ -136,12 +138,21 @@ export async function executeNativeCircuit(
 
 export class NativeACVMSimulator implements SimulationProvider {
   constructor(private workingDirectory: string, private pathToAcvm: string, private witnessFilename?: string) {}
-  async executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap> {
+
+  async executeProtocolCircuit(
+    input: ACVMWitness,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler | undefined,
+  ): Promise<ACVMWitness> {
     // Execute the circuit on those initial witness values
 
+    if (callback) {
+      throw new Error('Native ACVM simulator does not support foreign calls. Ignoring callback.');
+    }
+
     const operation = async (directory: string) => {
       // Decode the bytecode from base64 since the acvm does not know about base64 encoding
-      const decodedBytecode = Buffer.from(compiledCircuit.bytecode, 'base64');
+      const decodedBytecode = Buffer.from(artifact.bytecode, 'base64');
       // Execute the circuit
       const result = await executeNativeCircuit(
         input,
@@ -162,8 +173,8 @@ export class NativeACVMSimulator implements SimulationProvider {
   }
 
   executeUserCircuit(
-    _acir: Buffer,
-    _initialWitness: ACVMWitness,
+    _input: ACVMWitness,
+    _artifact: FunctionArtifactWithContractName,
     _callback: ACIRCallback,
   ): Promise<ACIRExecutionResult> {
     throw new Error('Not implemented');

package/src/private/providers/acvm_wasm.ts

@@ -1,11 +1,10 @@
 import { createLogger } from '@aztec/foundation/log';
-import initACVM, { type ExecutionError, executeCircuit } from '@aztec/noir-acvm_js';
+import initACVM, { type ExecutionError, type ForeignCallHandler, executeCircuit } from '@aztec/noir-acvm_js';
 import initAbi from '@aztec/noir-noirc_abi';
-import { foreignCallHandler } from '@aztec/noir-protocol-circuits-types/client';
-import type { WitnessMap } from '@aztec/noir-types';
-import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+import type { FunctionArtifactWithContractName } from '@aztec/stdlib/abi';
+import type { NoirCompiledCircuitWithName } from '@aztec/stdlib/noir';
 
-import { type ACIRCallback, acvm } from '../acvm/acvm.js';
+import { type ACIRCallback, type ACIRExecutionResult, acvm } from '../acvm/acvm.js';
 import type { ACVMWitness } from '../acvm/acvm_types.js';
 import { type SimulationProvider, enrichNoirError } from './simulation_provider.js';
 
@@ -22,41 +21,49 @@ export class WASMSimulator implements SimulationProvider {
     }
   }
 
-  async executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap> {
-    this.log.debug('init', { hash: compiledCircuit.hash });
+  async executeProtocolCircuit(
+    input: ACVMWitness,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler,
+  ): Promise<ACVMWitness> {
+    this.log.debug('init', { hash: artifact.hash });
     await this.init();
-    // Execute the circuit on those initial witness values
-    //
+
     // Decode the bytecode from base64 since the acvm does not know about base64 encoding
-    const decodedBytecode = Buffer.from(compiledCircuit.bytecode, 'base64');
+    const decodedBytecode = Buffer.from(artifact.bytecode, 'base64');
     //
     // Execute the circuit
     try {
-      const _witnessMap = await executeCircuit(
+      const result = await executeCircuit(
         decodedBytecode,
         input,
-        foreignCallHandler, // handle calls to debug_log
+        callback, // handle calls to debug_log
       );
-      this.log.debug('execution successful', { hash: compiledCircuit.hash });
-      return _witnessMap;
+      this.log.debug('execution successful', { hash: artifact.hash });
+      return result;
     } catch (err) {
-      // Typescript types catched errors as unknown or any, so we need to narrow its type to check if it has raw assertion payload.
+      // Typescript types caught errors as unknown or any, so we need to narrow its type to check if it has raw
+      // assertion payload.
       if (typeof err === 'object' && err !== null && 'rawAssertionPayload' in err) {
-        const parsed = enrichNoirError(compiledCircuit, err as ExecutionError);
+        const parsed = enrichNoirError(artifact, err as ExecutionError);
         this.log.debug('execution failed', {
-          hash: compiledCircuit.hash,
+          hash: artifact.hash,
           error: parsed,
           message: parsed.message,
         });
         throw parsed;
       }
-      this.log.debug('execution failed', { hash: compiledCircuit.hash, error: err });
+      this.log.debug('execution failed', { hash: artifact.hash, error: err });
       throw new Error(`Circuit execution failed: ${err}`);
     }
   }
 
-  async executeUserCircuit(acir: Buffer, initialWitness: ACVMWitness, callback: ACIRCallback) {
+  async executeUserCircuit(
+    input: ACVMWitness,
+    artifact: FunctionArtifactWithContractName,
+    callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
     await this.init();
-    return acvm(acir, initialWitness, callback);
+    return acvm(artifact.bytecode, input, callback);
   }
 }

package/src/private/providers/acvm_wasm_with_blobs.ts

@@ -1,7 +1,7 @@
-import { type ExecutionError, executeCircuit } from '@aztec/noir-acvm_js';
-import { foreignCallHandler } from '@aztec/noir-protocol-circuits-types/server';
+import { type ExecutionError, type ForeignCallHandler, executeCircuit } from '@aztec/noir-acvm_js';
 import type { WitnessMap } from '@aztec/noir-types';
-import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+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';
@@ -15,33 +15,36 @@ import { type SimulationProvider, enrichNoirError } from './simulation_provider.
  * It is only used in the context of server-side code executing simulated protocol circuits.
  */
 export class WASMSimulatorWithBlobs implements SimulationProvider {
-  async executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap> {
-    // Execute the circuit on those initial witness values
-    //
+  async executeProtocolCircuit(
+    input: WitnessMap,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler,
+  ): Promise<WitnessMap> {
     // Decode the bytecode from base64 since the acvm does not know about base64 encoding
-    const decodedBytecode = Buffer.from(compiledCircuit.bytecode, 'base64');
+    const decodedBytecode = Buffer.from(artifact.bytecode, 'base64');
     //
     // Execute the circuit
     try {
       const _witnessMap = await executeCircuit(
         decodedBytecode,
         input,
-        foreignCallHandler, // handle calls to debug_log and evaluate_blobs mock
+        callback, // handle calls to debug_log and evaluate_blobs mock
       );
 
       return _witnessMap;
     } catch (err) {
-      // Typescript types catched errors as unknown or any, so we need to narrow its type to check if it has raw assertion payload.
+      // Typescript types caught errors as unknown or any, so we need to narrow its type to check if it has raw
+      // assertion payload.
       if (typeof err === 'object' && err !== null && 'rawAssertionPayload' in err) {
-        throw enrichNoirError(compiledCircuit, err as ExecutionError);
+        throw enrichNoirError(artifact, err as ExecutionError);
       }
       throw new Error(`Circuit execution failed: ${err}`);
     }
   }
 
   executeUserCircuit(
-    _acir: Buffer,
-    _initialWitness: ACVMWitness,
+    _input: ACVMWitness,
+    _artifact: FunctionArtifactWithContractName,
     _callback: ACIRCallback,
   ): Promise<ACIRExecutionResult> {
     throw new Error('Not implemented');

package/src/private/providers/circuit_recording/circuit_recorder.ts

@@ -0,0 +1,283 @@
+import { createLogger } from '@aztec/foundation/log';
+import type { ForeignCallHandler, ForeignCallInput, ForeignCallOutput } from '@aztec/noir-acvm_js';
+
+import { createHash } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+
+import type { ACIRCallback } from '../../acvm/acvm.js';
+import type { ACVMWitness } from '../../acvm/acvm_types.js';
+import { Oracle } from '../../acvm/oracle/oracle.js';
+
+/**
+ * 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.
+ *
+ * The recording is stored in a JSON file called `circuit_name_circuit_function_name_YYYY-MM-DD_N.json` where N is
+ * a counter to ensure unique filenames. The file is stored in the `recordDir` directory provided as a parameter to
+ * CircuitRecorder.start().
+ *
+ * Example recording file:
+ * ```json
+ * {
+ *   "circuitName": "AMM",
+ *   "functionName": "add_liquidity",
+ *   "bytecodeMd5Hash": "b46c640ed38f20eac5f61a5e41d8dd1e",
+ *   "timestamp": 1740691464360,
+ *   "inputs": {
+ *     "0": "0x1e89de1f0ad5204263733b7ddf65bec45b8f44714a4da85a46474dad677679ef",
+ *     "1": "0x00f4d59c0ff773427bb0fed5b422557ca4dc5655abe53d31fa9408cb3c5a672f",
+ *     "5": "0x000000000000000000000000000000000000000000000000000000000000000f"
+ *   },
+ *   "oracleCalls": [
+ *     {
+ *       "name": "loadCapsule",
+ *       "inputs": [
+ *         [
+ *           "0x102422483bad6abd385948435667e144ac4c272576e325e7563608876cd446fd"
+ *         ],
+ *         [
+ *           "0x000000000000000000000000000000000000000000000000000000000000004d"
+ *         ],
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000001"
+ *         ]
+ *       ],
+ *       "outputs": [
+ *         "0x0000000000000000000000000000000000000000000000000000000000000000",
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000000"
+ *         ]
+ *       ]
+ *     },
+ *     {
+ *       "name": "syncNotes",
+ *       "inputs": []
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export class CircuitRecorder {
+  private readonly logger = createLogger('simulator:acvm:recording');
+  private isFirstCall = true;
+
+  private constructor(private readonly filePath: string) {}
+
+  /**
+   * 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'.
+   * @returns A new CircuitRecorder instance
+   */
+  static async start(
+    recordDir: string,
+    input: ACVMWitness,
+    circuitBytecode: Buffer,
+    circuitName: string,
+    functionName: string = 'main',
+  ): Promise<CircuitRecorder> {
+    const recording = {
+      circuitName: circuitName,
+      functionName: functionName,
+      bytecodeMd5Hash: createHash('md5').update(circuitBytecode).digest('hex'),
+      timestamp: Date.now(),
+      inputs: Object.fromEntries(input),
+    };
+
+    const recordingStringWithoutClosingBracket = JSON.stringify(recording, null, 2).slice(0, -2);
+
+    try {
+      // Check if the recording directory exists and is a directory
+      const stats = await fs.stat(recordDir);
+      if (!stats.isDirectory()) {
+        throw new Error(`Recording path ${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(recordDir, { recursive: true });
+      } else {
+        throw err;
+      }
+    }
+
+    const filePath = await CircuitRecorder.#computeFilePathAndStoreInitialRecording(
+      recordDir,
+      circuitName,
+      functionName,
+      recordingStringWithoutClosingBracket,
+    );
+    return new CircuitRecorder(filePath);
+  }
+
+  /**
+   * 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;
+      }
+    }
+  }
+
+  /**
+   * 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.getOwnPropertyNames(Oracle.prototype).filter(name => name !== 'constructor');
+
+    for (const name of oracleMethods) {
+      const fn = callback[name as keyof ACIRCallback];
+      if (!fn) {
+        throw new Error(`Oracle method ${name} not found when setting up recording callback`);
+      }
+
+      recordingCallback[name as keyof ACIRCallback] = (...args: ForeignCallInput[]): ReturnType<typeof fn> => {
+        const result = fn.call(callback, ...args);
+        if (result instanceof Promise) {
+          return result.then(async r => {
+            await this.#recordCall(name, args, r);
+            return r;
+          }) as ReturnType<typeof fn>;
+        }
+        void this.#recordCall(name, args, result);
+        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 result = await callback(name, inputs);
+      await this.#recordCall(name, inputs, result);
+      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
+   */
+  async #recordCall(name: string, inputs: unknown[], outputs: unknown) {
+    try {
+      const entry = {
+        name,
+        inputs,
+        outputs,
+      };
+      const prefix = this.isFirstCall ? '    ' : '    ,';
+      this.isFirstCall = false;
+      await fs.appendFile(this.filePath, prefix + JSON.stringify(entry) + '\n');
+    } catch (err) {
+      this.logger.error('Failed to log circuit call', { error: err });
+    }
+  }
+
+  /**
+   * Finalizes the recording file by adding closing brackets. Without calling this method, the recording file is
+   * incomplete and it fails to parse.
+   */
+  async finish(): Promise<void> {
+    try {
+      await fs.appendFile(this.filePath, '  ]\n}\n');
+    } catch (err) {
+      this.logger.error('Failed to finalize recording file', { error: err });
+    }
+  }
+
+  /**
+   * 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
+   */
+  async finishWithError(error: unknown): Promise<void> {
+    try {
+      await fs.appendFile(this.filePath, '  ],\n');
+      await fs.appendFile(this.filePath, `  "error": ${JSON.stringify(error)}\n`);
+      await fs.appendFile(this.filePath, '}\n');
+    } catch (err) {
+      this.logger.error('Failed to finalize recording file with error', { error: err });
+    }
+  }
+}
+
+/**
+ * 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/providers/circuit_recording/simulation_provider_recorder_wrapper.ts

@@ -0,0 +1,82 @@
+import type { ForeignCallHandler } from '@aztec/noir-protocol-circuits-types/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 { SimulationProvider } from '../simulation_provider.js';
+import { CircuitRecorder } from './circuit_recorder.js';
+
+/**
+ * Takes a simulation provider 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) {}
+
+  executeProtocolCircuit(
+    input: ACVMWitness,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler | undefined,
+  ): Promise<ACVMWitness> {
+    const bytecode = Buffer.from(artifact.bytecode, 'base64');
+
+    return this.#simulate<ForeignCallHandler | undefined, ACVMWitness>(
+      wrappedCallback => this.simulator.executeProtocolCircuit(input, artifact, wrappedCallback),
+      input,
+      bytecode,
+      artifact.name,
+      'main',
+      callback,
+    );
+  }
+
+  executeUserCircuit(
+    input: ACVMWitness,
+    artifact: FunctionArtifactWithContractName,
+    callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
+    return this.#simulate<ACIRCallback, ACIRExecutionResult>(
+      wrappedCallback => this.simulator.executeUserCircuit(input, artifact, wrappedCallback),
+      input,
+      artifact.bytecode,
+      artifact.contractName,
+      artifact.name,
+      callback,
+    );
+  }
+
+  async #simulate<C extends ACIRCallback | ForeignCallHandler | undefined, T>(
+    simulateFn: (wrappedCallback: C) => Promise<T>,
+    input: ACVMWitness,
+    bytecode: Buffer,
+    contractName: string,
+    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);
+
+    // If callback was provided, we wrap it in a circuit recorder callback wrapper
+    const wrappedCallback = 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);
+      throw error;
+    }
+
+    // Witness generation is complete so we finish the circuit recorder
+    await recorder.finish();
+
+    return result;
+  }
+}

package/src/private/providers/simulation_provider.ts

@@ -1,8 +1,8 @@
-import type { ExecutionError } from '@aztec/noir-acvm_js';
+import type { ExecutionError, ForeignCallHandler } from '@aztec/noir-acvm_js';
 import { abiDecodeError } from '@aztec/noir-noirc_abi';
-import type { WitnessMap } from '@aztec/noir-types';
 import { parseDebugSymbols } from '@aztec/stdlib/abi';
-import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+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';
@@ -11,8 +11,33 @@ import type { ACVMWitness } from '../acvm/acvm_types.js';
  * Low level simulation interface
  */
 export interface SimulationProvider {
-  executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap>;
-  executeUserCircuit(acir: Buffer, initialWitness: ACVMWitness, callback: ACIRCallback): Promise<ACIRExecutionResult>;
+  /**
+   * Execute a protocol circuit/generate a witness
+   * @param input - The initial witness map defining all of the inputs to `circuit`.
+   * @param artifact - ACIR circuit bytecode and its metadata.
+   * @param callback - A callback to process any foreign calls from the circuit. Can be undefined as for native
+   * ACVM simulator we don't process foreign calls.
+   * @returns The solved witness calculated by executing the circuit on the provided inputs.
+   */
+  executeProtocolCircuit(
+    input: ACVMWitness,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler | undefined,
+  ): Promise<ACVMWitness>;
+
+  /**
+   * Execute a user circuit (smart contract function)/generate a witness
+   * @param input - The initial witness map defining all of the inputs to `circuit`.
+   * @param artifact - Contract function ACIR circuit bytecode and its metadata.
+   * @param callback - A callback to process any foreign calls from the circuit.
+   * @returns The solved witness calculated by executing the circuit on the provided inputs, as well as the return
+   * witness indices as specified by the circuit.
+   */
+  executeUserCircuit(
+    input: ACVMWitness,
+    artifact: FunctionArtifactWithContractName,
+    callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult>;
 }
 
 export type DecodedError = ExecutionError & { decodedAssertionPayload?: any; noirCallStack?: string[] };

package/src/private/simulator.ts

@@ -1,7 +1,8 @@
 import { Fr } from '@aztec/foundation/fields';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import type { FunctionCall } from '@aztec/stdlib/abi';
+import type { AbiDecoded, FunctionCall } from '@aztec/stdlib/abi';
 import { FunctionSelector, FunctionType } from '@aztec/stdlib/abi';
+import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { CallContext, PrivateExecutionResult, TxExecutionRequest } from '@aztec/stdlib/tx';
 
@@ -113,8 +114,9 @@ export class AcirSimulator {
     request: FunctionCall,
     contractAddress: AztecAddress,
     selector: FunctionSelector,
+    authwits: AuthWitness[],
     scopes?: AztecAddress[],
-  ) {
+  ): Promise<AbiDecoded> {
     await verifyCurrentClassId(contractAddress, this.executionDataProvider);
     const entryPointArtifact = await this.executionDataProvider.getFunctionArtifact(contractAddress, selector);
 
@@ -124,7 +126,7 @@ export class AcirSimulator {
 
     const context = new UnconstrainedExecutionOracle(
       contractAddress,
-      [],
+      authwits,
       [],
       this.executionDataProvider,
       undefined,

package/src/private/unconstrained_execution.ts

@@ -1,6 +1,11 @@
 import type { Fr } from '@aztec/foundation/fields';
 import { createLogger } from '@aztec/foundation/log';
-import { type AbiDecoded, type FunctionArtifact, type FunctionSelector, decodeFromAbi } from '@aztec/stdlib/abi';
+import {
+  type AbiDecoded,
+  type FunctionArtifactWithContractName,
+  type FunctionSelector,
+  decodeFromAbi,
+} from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
 import { ExecutionError, resolveAssertionMessageFromError } from '../common/errors.js';
@@ -16,7 +21,7 @@ import type { UnconstrainedExecutionOracle } from './unconstrained_execution_ora
 export async function executeUnconstrainedFunction(
   simulatorProvider: SimulationProvider,
   oracle: UnconstrainedExecutionOracle,
-  artifact: FunctionArtifact,
+  artifact: FunctionArtifactWithContractName,
   contractAddress: AztecAddress,
   functionSelector: FunctionSelector,
   args: Fr[],
@@ -27,10 +32,9 @@ export async function executeUnconstrainedFunction(
     selector: functionSelector,
   });
 
-  const acir = artifact.bytecode;
   const initialWitness = toACVMWitness(0, args);
   const acirExecutionResult = await simulatorProvider
-    .executeUserCircuit(acir, initialWitness, new Oracle(oracle))
+    .executeUserCircuit(initialWitness, artifact, new Oracle(oracle))
     .catch((err: Error) => {
       err.message = resolveAssertionMessageFromError(err, artifact);
       throw new ExecutionError(