@aztec-labs/simulator 6.0.0-nightly.20260829

package/src/private/acvm_native.ts

@@ -0,0 +1,200 @@
+import type { ForeignCallHandler, WitnessMap } from '@aztec/noir-acvm_js';
+
+import { runInDirectory } from '@aztec-labs/foundation/fs';
+import { type Logger, type LoggerBindings, resolveLogger } from '@aztec-labs/foundation/log';
+import { Timer } from '@aztec-labs/foundation/timer';
+import type { FunctionArtifactWithContractName } from '@aztec-labs/stdlib/abi';
+import type { NoirCompiledCircuitWithName } from '@aztec-labs/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 { CircuitSimulator } from './circuit_simulator.js';
+
+export enum ACVM_RESULT {
+  SUCCESS,
+  FAILURE,
+}
+
+export type ACVMSuccess = {
+  status: ACVM_RESULT.SUCCESS;
+  duration: number;
+  witness: Map<number, string>;
+};
+
+export type ACVMFailure = {
+  status: ACVM_RESULT.FAILURE;
+  reason: string;
+};
+
+export type ACVMResult = ACVMSuccess | ACVMFailure;
+
+/**
+ * Parses a TOML format witness map string into a Map structure
+ * @param outputString - The witness map in TOML format
+ * @returns The parsed witness map
+ */
+function parseIntoWitnessMap(outputString: string) {
+  const lines = outputString.split('\n');
+  return new Map<number, string>(
+    lines
+      .filter((line: string) => line.length)
+      .map((line: string) => {
+        const pair = line.replaceAll(' ', '').split('=');
+        return [Number(pair[0]), pair[1].replaceAll('"', '')];
+      }),
+  );
+}
+
+/**
+ *
+ * @param inputWitness - The circuit's input witness
+ * @param bytecode - The circuit bytecode
+ * @param workingDirectory - A directory to use for temporary files by the ACVM
+ * @param pathToAcvm - The path to the ACVM binary
+ * @param outputFilename - If specified, the output will be stored as a file, encoded using Bincode
+ * @returns The completed partial witness outputted from the circuit
+ */
+export async function executeNativeCircuit(
+  inputWitness: WitnessMap,
+  bytecode: Buffer,
+  workingDirectory: string,
+  pathToAcvm: string,
+  outputFilename?: string,
+  loggerOrBindings?: Logger | LoggerBindings,
+): Promise<ACVMResult> {
+  const logger = resolveLogger('simulator:acvm-native', loggerOrBindings);
+  const bytecodeFilename = 'bytecode';
+  const witnessFilename = 'input_witness.toml';
+
+  // convert the witness map to TOML format
+  let witnessMap = '';
+  inputWitness.forEach((value: string, key: number) => {
+    witnessMap = witnessMap.concat(`${key} = '${value}'\n`);
+  });
+
+  try {
+    // Check that the directory exists
+    await fs.access(workingDirectory);
+  } catch {
+    return { status: ACVM_RESULT.FAILURE, reason: `Working directory ${workingDirectory} does not exist` };
+  }
+
+  try {
+    // Write the bytecode and input witness to the working directory
+    await fs.writeFile(`${workingDirectory}/${bytecodeFilename}`, bytecode);
+    await fs.writeFile(`${workingDirectory}/${witnessFilename}`, witnessMap);
+
+    // Execute the ACVM using the given args
+    const args = [
+      `execute`,
+      `--working-directory`,
+      `${workingDirectory}`,
+      `--bytecode`,
+      `${bytecodeFilename}`,
+      `--input-witness`,
+      `${witnessFilename}`,
+      '--print',
+      '--output-witness',
+      'output-witness',
+    ];
+
+    logger.debug(`Calling ACVM with ${args.join(' ')}`);
+
+    const processPromise = new Promise<string>((resolve, reject) => {
+      const outChunks: Buffer[] = [];
+      const errChunks: Buffer[] = [];
+      let outLen = 0;
+      let errLen = 0;
+      const acvm = proc.spawn(pathToAcvm, args);
+      acvm.stdout.on('data', (data: Buffer) => {
+        outChunks.push(data);
+        outLen += data.length;
+      });
+      acvm.stderr.on('data', (data: Buffer) => {
+        errChunks.push(data);
+        errLen += data.length;
+      });
+      acvm.on('close', code => {
+        if (code === 0) {
+          resolve(Buffer.concat(outChunks, outLen).toString('utf-8'));
+        } else {
+          const stderr = Buffer.concat(errChunks, errLen);
+          logger.error(`From ACVM: ${stderr.toString('utf-8')}`);
+          reject(stderr.toString('utf-8'));
+        }
+      });
+    });
+
+    const timer = new Timer();
+    const output = await processPromise;
+    const duration = timer.ms();
+    if (outputFilename) {
+      const outputWitnessFileName = `${workingDirectory}/output-witness.gz`;
+      await fs.copyFile(outputWitnessFileName, outputFilename);
+    }
+    // TODO: We shouldn't be parsing the witness from stdout, it's not very performant, and we end up with two ways of fetching the witness.
+    // We probably should implement the WitnessStack type, run the ACVM with msgpack serialization mode (env variable), and ungzip and parse the witness from
+    // the outputted gz witness file.
+    const witness = parseIntoWitnessMap(output);
+    return { status: ACVM_RESULT.SUCCESS, witness, duration };
+  } catch (error) {
+    return { status: ACVM_RESULT.FAILURE, reason: `${error}` };
+  }
+}
+
+export class NativeACVMSimulator implements CircuitSimulator {
+  private logger: Logger;
+
+  constructor(
+    private workingDirectory: string,
+    private pathToAcvm: string,
+    private witnessFilename?: string,
+    loggerOrBindings?: Logger | LoggerBindings,
+  ) {
+    this.logger = resolveLogger('simulator:acvm-native', loggerOrBindings);
+  }
+
+  async executeProtocolCircuit(
+    input: ACVMWitness,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler | undefined,
+  ): Promise<ACVMSuccess> {
+    // 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(artifact.bytecode, 'base64');
+      // Execute the circuit
+      const result = await executeNativeCircuit(
+        input,
+        decodedBytecode,
+        directory,
+        this.pathToAcvm,
+        this.witnessFilename,
+        this.logger,
+      );
+
+      if (result.status == ACVM_RESULT.FAILURE) {
+        throw new Error(`Failed to generate witness: ${result.reason}`);
+      }
+
+      return result;
+    };
+
+    return await runInDirectory(this.workingDirectory, operation, false, this.logger);
+  }
+
+  executeUserCircuit(
+    _input: ACVMWitness,
+    _artifact: FunctionArtifactWithContractName,
+    _callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
+    throw new Error('Not implemented');
+  }
+}

package/src/private/acvm_wasm.ts

@@ -0,0 +1,80 @@
+import initACVM, { type ExecutionError, type ForeignCallHandler, executeCircuit } from '@aztec/noir-acvm_js';
+import initAbi from '@aztec/noir-noirc_abi';
+
+import { type Logger, type LoggerBindings, resolveLogger } from '@aztec-labs/foundation/log';
+import { Timer } from '@aztec-labs/foundation/timer';
+import type { FunctionArtifactWithContractName } from '@aztec-labs/stdlib/abi';
+import type { NoirCompiledCircuitWithName } from '@aztec-labs/stdlib/noir';
+
+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 CircuitSimulator, enrichNoirError } from './circuit_simulator.js';
+
+let wasmInitPromise: Promise<unknown> | undefined;
+
+export class WASMSimulator implements CircuitSimulator {
+  protected log: Logger;
+
+  constructor(loggerOrBindings?: Logger | LoggerBindings) {
+    this.log = resolveLogger('wasm-simulator', loggerOrBindings);
+  }
+
+  async init(): Promise<void> {
+    // If these are available, then we are in the
+    // web environment. For the node environment, this
+    // is a no-op.
+    if (typeof initAbi === 'function') {
+      /** @ts-expect-error The node bundle doesn't include these default imports, so TS complains */
+      wasmInitPromise ??= Promise.all([initAbi(), initACVM()]);
+      await wasmInitPromise;
+    }
+  }
+
+  async executeProtocolCircuit(
+    input: ACVMWitness,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler,
+  ): Promise<ACVMSuccess> {
+    this.log.debug('init', { hash: artifact.hash });
+    await this.init();
+
+    // Decode the bytecode from base64 since the acvm does not know about base64 encoding
+    const decodedBytecode = Buffer.from(artifact.bytecode, 'base64');
+    //
+    // Execute the circuit
+    try {
+      const timer = new Timer();
+      const result = await executeCircuit(
+        decodedBytecode,
+        input,
+        callback, // handle calls to debug_log
+      );
+      this.log.debug('execution successful', { hash: artifact.hash });
+      return { witness: result, duration: timer.ms() } as ACVMSuccess;
+    } catch (err) {
+      // 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(artifact, err as ExecutionError);
+        this.log.debug('execution failed', {
+          hash: artifact.hash,
+          error: parsed,
+          message: parsed.message,
+        });
+        throw parsed;
+      }
+      this.log.debug('execution failed', { hash: artifact.hash, error: err });
+      throw new Error(`Circuit execution failed: ${err}`);
+    }
+  }
+
+  async executeUserCircuit(
+    input: ACVMWitness,
+    artifact: FunctionArtifactWithContractName,
+    callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
+    await this.init();
+    return acvm(artifact.bytecode, input, callback, this.log.createChild('acvm'));
+  }
+}

package/src/private/acvm_wasm_with_blobs.ts

@@ -0,0 +1,55 @@
+import { type ExecutionError, type ForeignCallHandler, executeCircuit } from '@aztec/noir-acvm_js';
+import type { WitnessMap } from '@aztec/noir-types';
+
+import { Timer } from '@aztec-labs/foundation/timer';
+import type { FunctionArtifactWithContractName } from '@aztec-labs/stdlib/abi';
+import type { NoirCompiledCircuitWithName } from '@aztec-labs/stdlib/noir';
+
+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 CircuitSimulator, enrichNoirError } from './circuit_simulator.js';
+
+/**
+ * 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 CircuitSimulator {
+  async executeProtocolCircuit(
+    input: WitnessMap,
+    artifact: NoirCompiledCircuitWithName,
+    callback: ForeignCallHandler,
+  ): Promise<ACVMSuccess> {
+    // Decode the bytecode from base64 since the acvm does not know about base64 encoding
+    const decodedBytecode = Buffer.from(artifact.bytecode, 'base64');
+    //
+    // Execute the circuit
+    try {
+      const timer = new Timer();
+      const _witnessMap = await executeCircuit(
+        decodedBytecode,
+        input,
+        callback, // handle calls to debug_log and evaluate_blobs mock
+      );
+      return { witness: _witnessMap, duration: timer.ms() } as ACVMSuccess;
+    } catch (err) {
+      // 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(artifact, err as ExecutionError);
+      }
+      throw new Error(`Circuit execution failed: ${err}`);
+    }
+  }
+
+  executeUserCircuit(
+    _input: ACVMWitness,
+    _artifact: FunctionArtifactWithContractName,
+    _callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
+    throw new Error('Not implemented');
+  }
+}

package/src/private/circuit_simulator.ts

@@ -0,0 +1,91 @@
+import type { ExecutionError, ForeignCallHandler } from '@aztec/noir-acvm_js';
+import { abiDecodeError } from '@aztec/noir-noirc_abi';
+
+import { parseDebugSymbols } from '@aztec-labs/stdlib/abi';
+import type { FunctionArtifactWithContractName } from '@aztec-labs/stdlib/abi';
+import type { NoirCompiledCircuit, NoirCompiledCircuitWithName } from '@aztec-labs/stdlib/noir';
+
+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 CircuitSimulator {
+  /**
+   * 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<ACVMSuccess>;
+
+  /**
+   * 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[] };
+
+// Payload parsing taken from noir/noir-repo/tooling/noir_js/src/witness_generation.ts.
+// TODO: import this in isolation without having to import noir_js in its entirety.
+export function enrichNoirError(artifact: NoirCompiledCircuit, originalError: ExecutionError): DecodedError {
+  const enrichedError = originalError as DecodedError;
+
+  if (originalError.rawAssertionPayload) {
+    try {
+      // Decode the payload
+      const decodedPayload = abiDecodeError(artifact.abi, originalError.rawAssertionPayload);
+
+      if (typeof decodedPayload === 'string') {
+        // If it's a string, just add it to the error message
+        enrichedError.message = `Circuit execution failed: ${decodedPayload}`;
+      } else {
+        // If not, attach the payload to the original error
+        enrichedError.decodedAssertionPayload = decodedPayload;
+      }
+    } catch {
+      // Ignore errors decoding the payload
+    }
+  }
+
+  try {
+    // Decode the callstack
+    const callStack = extractCallStack(originalError, {
+      // TODO(https://github.com/AztecProtocol/aztec-packages/issues/5813)
+      // We only support handling debug info for the circuit entry point.
+      // So for now we simply index into the first debug info.
+      debugSymbols: parseDebugSymbols(artifact.debug_symbols)[0],
+      files: artifact.file_map,
+    });
+
+    enrichedError.noirCallStack = callStack?.map(errorLocation => {
+      if (typeof errorLocation === 'string') {
+        return `at opcode ${errorLocation}`;
+      } else {
+        return `at ${errorLocation.locationText} (${errorLocation.filePath}:${errorLocation.line}:${errorLocation.column})`;
+      }
+    });
+  } catch {
+    // Ignore errors resolving the callstack
+  }
+
+  return enrichedError;
+}

package/src/private/factory.ts

@@ -0,0 +1,40 @@
+import { type Logger, type LoggerBindings, resolveLogger } from '@aztec-labs/foundation/log';
+import { promises as fs } from 'fs';
+
+import { NativeACVMSimulator } from './acvm_native.js';
+import { WASMSimulator } from './acvm_wasm.js';
+import type { CircuitSimulator } from './circuit_simulator.js';
+
+export type SimulatorConfig = {
+  acvmBinaryPath?: string;
+  acvmWorkingDirectory?: string;
+};
+
+export function getSimulatorConfigFromEnv() {
+  const { ACVM_BINARY_PATH, ACVM_WORKING_DIRECTORY } = process.env;
+  return {
+    acvmWorkingDirectory: ACVM_WORKING_DIRECTORY ? ACVM_WORKING_DIRECTORY : undefined,
+    acvmBinaryPath: ACVM_BINARY_PATH ? ACVM_BINARY_PATH : undefined,
+  };
+}
+
+export async function createSimulator(
+  config: SimulatorConfig,
+  loggerOrBindings?: Logger | LoggerBindings,
+): Promise<CircuitSimulator> {
+  const logger = resolveLogger('simulator', loggerOrBindings);
+  if (config.acvmBinaryPath && config.acvmWorkingDirectory) {
+    try {
+      await fs.access(config.acvmBinaryPath, fs.constants.R_OK);
+      await fs.mkdir(config.acvmWorkingDirectory, { recursive: true });
+      logger.info(`Using native ACVM at ${config.acvmBinaryPath} and working directory ${config.acvmWorkingDirectory}`);
+      const acvmLogger = logger.createChild('acvm-native');
+      return new NativeACVMSimulator(config.acvmWorkingDirectory, config.acvmBinaryPath, undefined, acvmLogger);
+    } catch {
+      logger.warn(`Failed to access ACVM at ${config.acvmBinaryPath}, falling back to WASM`);
+    }
+  }
+  logger.info('Using WASM ACVM simulation');
+  const wasmLogger = logger.createChild('wasm');
+  return new WASMSimulator(wasmLogger);
+}