@aztec/simulator 0.0.0-test.0

package/src/private/providers/acvm_native.ts

@@ -0,0 +1,171 @@
+import { runInDirectory } from '@aztec/foundation/fs';
+import { createLogger } from '@aztec/foundation/log';
+import { Timer } from '@aztec/foundation/timer';
+import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+
+import type { WitnessMap } from '@noir-lang/types';
+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';
+
+const logger = createLogger('simulator:acvm-native');
+
+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,
+): Promise<ACVMResult> {
+  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 (error) {
+    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) => {
+      let outputWitness = Buffer.alloc(0);
+      let errorBuffer = Buffer.alloc(0);
+      const acvm = proc.spawn(pathToAcvm, args);
+      acvm.stdout.on('data', data => {
+        outputWitness = Buffer.concat([outputWitness, data]);
+      });
+      acvm.stderr.on('data', data => {
+        errorBuffer = Buffer.concat([errorBuffer, data]);
+      });
+      acvm.on('close', code => {
+        if (code === 0) {
+          resolve(outputWitness.toString('utf-8'));
+        } else {
+          logger.error(`From ACVM: ${errorBuffer.toString('utf-8')}`);
+          reject(errorBuffer.toString('utf-8'));
+        }
+      });
+    });
+
+    const duration = new Timer();
+    const output = await processPromise;
+    if (outputFilename) {
+      const outputWitnessFileName = `${workingDirectory}/output-witness.gz`;
+      await fs.copyFile(outputWitnessFileName, outputFilename);
+    }
+    const witness = parseIntoWitnessMap(output);
+    return { status: ACVM_RESULT.SUCCESS, witness, duration: duration.ms() };
+  } catch (error) {
+    return { status: ACVM_RESULT.FAILURE, reason: `${error}` };
+  }
+}
+
+export class NativeACVMSimulator implements SimulationProvider {
+  constructor(private workingDirectory: string, private pathToAcvm: string, private witnessFilename?: string) {}
+  async executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap> {
+    // Execute the circuit on those initial witness values
+
+    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');
+      // Execute the circuit
+      const result = await executeNativeCircuit(
+        input,
+        decodedBytecode,
+        directory,
+        this.pathToAcvm,
+        this.witnessFilename,
+      );
+
+      if (result.status == ACVM_RESULT.FAILURE) {
+        throw new Error(`Failed to generate witness: ${result.reason}`);
+      }
+
+      return result.witness;
+    };
+
+    return await runInDirectory(this.workingDirectory, operation, false, logger);
+  }
+
+  executeUserCircuit(
+    _acir: Buffer,
+    _initialWitness: ACVMWitness,
+    _callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
+    throw new Error('Not implemented');
+  }
+}

package/src/private/providers/acvm_wasm.ts

@@ -0,0 +1,63 @@
+import { createLogger } from '@aztec/foundation/log';
+import { foreignCallHandler } from '@aztec/noir-protocol-circuits-types/client';
+import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+
+import initACVM, { type ExecutionError, executeCircuit } from '@noir-lang/acvm_js';
+import initAbi from '@noir-lang/noirc_abi';
+import type { WitnessMap } from '@noir-lang/types';
+
+import { type ACIRCallback, acvm } from '../acvm/acvm.js';
+import type { ACVMWitness } from '../acvm/acvm_types.js';
+import { type SimulationProvider, parseErrorPayload } from './simulation_provider.js';
+
+export class WASMSimulator implements SimulationProvider {
+  constructor(protected log = createLogger('wasm-simulator')) {}
+
+  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 */
+      await Promise.all([initAbi(), initACVM()]);
+    }
+  }
+
+  async executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap> {
+    this.log.debug('init', { hash: compiledCircuit.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');
+    //
+    // Execute the circuit
+    try {
+      const _witnessMap = await executeCircuit(
+        decodedBytecode,
+        input,
+        foreignCallHandler, // handle calls to debug_log
+      );
+      this.log.debug('execution successful', { hash: compiledCircuit.hash });
+      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.
+      if (typeof err === 'object' && err !== null && 'rawAssertionPayload' in err) {
+        const parsed = parseErrorPayload(compiledCircuit.abi, err as ExecutionError);
+        this.log.debug('execution failed', {
+          hash: compiledCircuit.hash,
+          error: parsed,
+          message: parsed.message,
+        });
+        throw parsed;
+      }
+      this.log.debug('execution failed', { hash: compiledCircuit.hash, error: err });
+      throw new Error(`Circuit execution failed: ${err}`);
+    }
+  }
+
+  async executeUserCircuit(acir: Buffer, initialWitness: ACVMWitness, callback: ACIRCallback) {
+    await this.init();
+    return acvm(acir, initialWitness, callback);
+  }
+}

package/src/private/providers/acvm_wasm_with_blobs.ts

@@ -0,0 +1,50 @@
+import { foreignCallHandler } from '@aztec/noir-protocol-circuits-types/server';
+import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+
+import { type ExecutionError, executeCircuit } from '@noir-lang/acvm_js';
+import type { WitnessMap } from '@noir-lang/types';
+
+import type { ACIRCallback, ACIRExecutionResult } from '../acvm/acvm.js';
+import type { ACVMWitness } from '../acvm/acvm_types.js';
+import { type SimulationProvider, parseErrorPayload } from './simulation_provider.js';
+
+/**
+ * A simulation provider 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 {
+  async executeProtocolCircuit(input: WitnessMap, compiledCircuit: NoirCompiledCircuit): Promise<WitnessMap> {
+    // 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');
+    //
+    // Execute the circuit
+    try {
+      const _witnessMap = await executeCircuit(
+        decodedBytecode,
+        input,
+        foreignCallHandler, // 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.
+      if (typeof err === 'object' && err !== null && 'rawAssertionPayload' in err) {
+        throw parseErrorPayload(compiledCircuit.abi, err as ExecutionError);
+      }
+      throw new Error(`Circuit execution failed: ${err}`);
+    }
+  }
+
+  executeUserCircuit(
+    _acir: Buffer,
+    _initialWitness: ACVMWitness,
+    _callback: ACIRCallback,
+  ): Promise<ACIRExecutionResult> {
+    throw new Error('Not implemented');
+  }
+}

package/src/private/providers/factory.ts

@@ -0,0 +1,38 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+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';
+
+export type SimulationProviderConfig = {
+  acvmBinaryPath?: string;
+  acvmWorkingDirectory?: string;
+};
+
+export function getSimulationProviderConfigFromEnv() {
+  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 createSimulationProvider(
+  config: SimulationProviderConfig,
+  logger: Logger = createLogger('simulator'),
+): Promise<SimulationProvider> {
+  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}`);
+      return new NativeACVMSimulator(config.acvmWorkingDirectory, config.acvmBinaryPath);
+    } catch {
+      logger.warn(`Failed to access ACVM at ${config.acvmBinaryPath}, falling back to WASM`);
+    }
+  }
+  logger.info('Using WASM ACVM simulation');
+  return new WASMSimulator();
+}

package/src/private/providers/simulation_provider.ts

@@ -0,0 +1,45 @@
+import type { NoirCompiledCircuit } from '@aztec/stdlib/noir';
+
+import type { ExecutionError } from '@noir-lang/acvm_js';
+import { abiDecodeError } from '@noir-lang/noirc_abi';
+import type { Abi, WitnessMap } from '@noir-lang/types';
+
+import type { ACIRCallback, ACIRExecutionResult } from '../acvm/acvm.js';
+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>;
+}
+
+export type ErrorWithPayload = ExecutionError & { decodedAssertionPayload?: any };
+
+// Error handling 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 parseErrorPayload(abi: Abi, originalError: ExecutionError): Error {
+  const payload = originalError.rawAssertionPayload;
+  if (!payload) {
+    return originalError;
+  }
+  const enrichedError = originalError as ErrorWithPayload;
+
+  try {
+    // Decode the payload
+    const decodedPayload = abiDecodeError(abi, payload);
+
+    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 (_errorDecoding) {
+    // Ignore errors decoding the payload
+  }
+
+  return enrichedError;
+}

package/src/private/simulator.ts

@@ -0,0 +1,147 @@
+import { Fr } from '@aztec/foundation/fields';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import type { FunctionCall } from '@aztec/stdlib/abi';
+import { FunctionSelector, FunctionType } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { CallContext, PrivateExecutionResult, TxExecutionRequest } from '@aztec/stdlib/tx';
+
+import { createSimulationError } from '../common/errors.js';
+import type { ExecutionDataProvider } from './execution_data_provider.js';
+import { ExecutionNoteCache } from './execution_note_cache.js';
+import { HashedValuesCache } from './hashed_values_cache.js';
+import { executePrivateFunction, verifyCurrentClassId } from './private_execution.js';
+import { PrivateExecutionOracle } from './private_execution_oracle.js';
+import type { SimulationProvider } from './providers/simulation_provider.js';
+import { executeUnconstrainedFunction } from './unconstrained_execution.js';
+import { UnconstrainedExecutionOracle } from './unconstrained_execution_oracle.js';
+
+/**
+ * The ACIR simulator.
+ */
+export class AcirSimulator {
+  private log: Logger;
+
+  constructor(private executionDataProvider: ExecutionDataProvider, private simulationProvider: SimulationProvider) {
+    this.log = createLogger('simulator');
+  }
+
+  /**
+   * Runs a private function.
+   * @param request - The transaction request.
+   * @param entryPointArtifact - The artifact of the entry point function.
+   * @param contractAddress - The address of the contract (should match request.origin)
+   * @param msgSender - The address calling the function. This can be replaced to simulate a call from another contract or a specific account.
+   * @param scopes - The accounts whose notes we can access in this call. Currently optional and will default to all.
+   * @returns The result of the execution.
+   */
+  public async run(
+    request: TxExecutionRequest,
+    contractAddress: AztecAddress,
+    selector: FunctionSelector,
+    msgSender = AztecAddress.fromField(Fr.MAX_FIELD_VALUE),
+    scopes?: AztecAddress[],
+  ): Promise<PrivateExecutionResult> {
+    const header = await this.executionDataProvider.getBlockHeader();
+
+    await verifyCurrentClassId(contractAddress, this.executionDataProvider);
+    const entryPointArtifact = await this.executionDataProvider.getFunctionArtifact(contractAddress, selector);
+
+    if (entryPointArtifact.functionType !== FunctionType.PRIVATE) {
+      throw new Error(`Cannot run ${entryPointArtifact.functionType} function as private`);
+    }
+
+    if (request.origin !== contractAddress) {
+      this.log.warn(
+        `Request origin does not match contract address in simulation. Request origin: ${request.origin}, contract address: ${contractAddress}`,
+      );
+    }
+
+    // reserve the first side effect for the tx hash (inserted by the private kernel)
+    const startSideEffectCounter = 1;
+
+    const callContext = new CallContext(
+      msgSender,
+      contractAddress,
+      await FunctionSelector.fromNameAndParameters(entryPointArtifact.name, entryPointArtifact.parameters),
+      entryPointArtifact.isStatic,
+    );
+
+    const txRequestHash = await request.toTxRequest().hash();
+    const noteCache = new ExecutionNoteCache(txRequestHash);
+
+    const context = new PrivateExecutionOracle(
+      request.firstCallArgsHash,
+      request.txContext,
+      callContext,
+      header,
+      request.authWitnesses,
+      request.capsules,
+      HashedValuesCache.create(request.argsOfCalls),
+      noteCache,
+      this.executionDataProvider,
+      this.simulationProvider,
+      /*totalPublicArgsCount=*/ 0,
+      startSideEffectCounter,
+      undefined,
+      scopes,
+    );
+
+    try {
+      const executionResult = await executePrivateFunction(
+        this.simulationProvider,
+        context,
+        entryPointArtifact,
+        contractAddress,
+        request.functionSelector,
+      );
+      const { usedTxRequestHashForNonces } = noteCache.finish();
+      const firstNullifierHint = usedTxRequestHashForNonces ? Fr.ZERO : noteCache.getAllNullifiers()[0];
+      return new PrivateExecutionResult(executionResult, firstNullifierHint);
+    } catch (err) {
+      throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during private execution'));
+    }
+  }
+
+  /**
+   * Runs an unconstrained function.
+   * @param request - The transaction request.
+   * @param entryPointArtifact - The artifact of the entry point function.
+   * @param contractAddress - The address of the contract.
+   * @param scopes - The accounts whose notes we can access in this call. Currently optional and will default to all.
+   */
+  public async runUnconstrained(
+    request: FunctionCall,
+    contractAddress: AztecAddress,
+    selector: FunctionSelector,
+    scopes?: AztecAddress[],
+  ) {
+    await verifyCurrentClassId(contractAddress, this.executionDataProvider);
+    const entryPointArtifact = await this.executionDataProvider.getFunctionArtifact(contractAddress, selector);
+
+    if (entryPointArtifact.functionType !== FunctionType.UNCONSTRAINED) {
+      throw new Error(`Cannot run ${entryPointArtifact.functionType} function as unconstrained`);
+    }
+
+    const context = new UnconstrainedExecutionOracle(
+      contractAddress,
+      [],
+      [],
+      this.executionDataProvider,
+      undefined,
+      scopes,
+    );
+
+    try {
+      return await executeUnconstrainedFunction(
+        this.simulationProvider,
+        context,
+        entryPointArtifact,
+        contractAddress,
+        request.selector,
+        request.args,
+      );
+    } catch (err) {
+      throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during private execution'));
+    }
+  }
+}

package/src/private/unconstrained_execution.ts

@@ -0,0 +1,50 @@
+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 { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+import { ExecutionError, resolveAssertionMessageFromError } from '../common/errors.js';
+import { witnessMapToFields } from './acvm/deserialize.js';
+import { Oracle, extractCallStack, toACVMWitness } from './acvm/index.js';
+import type { SimulationProvider } from './providers/simulation_provider.js';
+import type { UnconstrainedExecutionOracle } from './unconstrained_execution_oracle.js';
+
+// docs:start:execute_unconstrained_function
+/**
+ * Execute an unconstrained function and return the decoded values.
+ */
+export async function executeUnconstrainedFunction(
+  simulatorProvider: SimulationProvider,
+  oracle: UnconstrainedExecutionOracle,
+  artifact: FunctionArtifact,
+  contractAddress: AztecAddress,
+  functionSelector: FunctionSelector,
+  args: Fr[],
+  log = createLogger('simulator:unconstrained_execution'),
+): Promise<AbiDecoded> {
+  log.verbose(`Executing unconstrained function ${artifact.name}`, {
+    contract: contractAddress,
+    selector: functionSelector,
+  });
+
+  const acir = artifact.bytecode;
+  const initialWitness = toACVMWitness(0, args);
+  const acirExecutionResult = await simulatorProvider
+    .executeUserCircuit(acir, initialWitness, new Oracle(oracle))
+    .catch((err: Error) => {
+      err.message = resolveAssertionMessageFromError(err, artifact);
+      throw new ExecutionError(
+        err.message,
+        {
+          contractAddress,
+          functionSelector,
+        },
+        extractCallStack(err, artifact.debug),
+        { cause: err },
+      );
+    });
+
+  const returnWitness = witnessMapToFields(acirExecutionResult.returnWitness);
+  return decodeFromAbi(artifact.returnTypes, returnWitness);
+}
+// docs:end:execute_unconstrained_function