@aztec/simulator 0.0.0-test.0

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@aztec/simulator",
+  "version": "0.0.0-test.0",
+  "type": "module",
+  "exports": {
+    "./server": "./dest/server.js",
+    "./client": "./dest/client.js",
+    "./public/fixtures": "./dest/public/fixtures/index.js"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/index.ts"
+    ],
+    "name": "Simulator",
+    "tsconfig": "./tsconfig.json"
+  },
+  "scripts": {
+    "build": "yarn clean && tsc -b",
+    "build:dev": "tsc -b --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "formatting": "run -T prettier --check ./src && run -T eslint ./src",
+    "formatting:fix": "run -T eslint --fix ./src && run -T prettier -w ./src",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec/constants": "0.0.0-test.0",
+    "@aztec/foundation": "0.0.0-test.0",
+    "@aztec/noir-protocol-circuits-types": "0.0.0-test.0",
+    "@aztec/protocol-contracts": "0.0.0-test.0",
+    "@aztec/stdlib": "0.0.0-test.0",
+    "@aztec/telemetry-client": "0.0.0-test.0",
+    "@aztec/world-state": "0.0.0-test.0",
+    "levelup": "^5.1.1",
+    "lodash.clonedeep": "^4.5.0",
+    "lodash.merge": "^4.6.2",
+    "memdown": "^6.1.1",
+    "tslib": "^2.4.0",
+    "@aztec/noir-acvm_js": "0.0.0-test.0",
+    "@aztec/noir-noirc_abi": "0.0.0-test.0",
+    "@aztec/noir-types": "0.0.0-test.0"
+  },
+  "devDependencies": {
+    "@aztec/kv-store": "0.0.0-test.0",
+    "@aztec/merkle-tree": "0.0.0-test.0",
+    "@aztec/noir-contracts.js": "0.0.0-test.0",
+    "@jest/globals": "^29.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/levelup": "^5.1.3",
+    "@types/lodash.clonedeep": "^4.5.7",
+    "@types/lodash.merge": "^4.6.9",
+    "@types/memdown": "^3.0.2",
+    "@types/node": "^18.7.23",
+    "jest": "^29.5.0",
+    "jest-mock-extended": "^3.0.4",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4",
+    "viem": "2.22.8"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/client.ts

@@ -0,0 +1,4 @@
+export * from './private/index.js';
+export { WASMSimulator } from './private/providers/acvm_wasm.js';
+export { type SimulationProvider } from './private/providers/simulation_provider.js';
+export * from './common/index.js';

package/src/common/db_interfaces.ts

@@ -0,0 +1,94 @@
+import type { L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/constants';
+import type { Fr } from '@aztec/foundation/fields';
+import type { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { ContractInstanceWithAddress } from '@aztec/stdlib/contract';
+import type { NullifierMembershipWitness } from '@aztec/stdlib/trees';
+
+import type { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
+
+/**
+ * Database interface for providing access to public state.
+ */
+export interface PublicStateDB {
+  /**
+   * Reads a value from public storage, returning zero if none.
+   * @param contract - Owner of the storage.
+   * @param slot - Slot to read in the contract storage.
+   * @returns The current value in the storage slot.
+   */
+  storageRead(contract: AztecAddress, slot: Fr): Promise<Fr>;
+
+  /**
+   * Records a write to public storage.
+   * @param contract - Owner of the storage.
+   * @param slot - Slot to read in the contract storage.
+   * @param newValue - The new value to store.
+   */
+  storageWrite(contract: AztecAddress, slot: Fr, newValue: Fr): Promise<void>;
+}
+
+/**
+ * Database interface for providing access to public contract data.
+ */
+export interface PublicContractsDB {
+  /**
+   * Returns a publicly deployed contract instance.
+   * @param address - Address of the contract.
+   * @returns The contract instance or undefined if not found.
+   */
+  getContractInstance(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined>;
+
+  getDebugFunctionName(contractAddress: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+}
+
+/** Database interface for providing access to commitment tree, l1 to l2 message tree, and nullifier tree. */
+export interface CommitmentsDB {
+  /**
+   * Fetches a message from the db, given its key.
+   * @param contractAddress - Address of a contract by which the message was emitted.
+   * @param messageHash - Hash of the message.
+   * @param secret - Secret used to compute a nullifier.
+   * @dev Contract address and secret are only used to compute the nullifier to get non-nullified messages
+   * @returns The l1 to l2 membership witness (index of message in the tree and sibling path).
+   */
+  getL1ToL2MembershipWitness(
+    contractAddress: AztecAddress,
+    messageHash: Fr,
+    secret: Fr,
+  ): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>>;
+
+  /**
+   * @param leafIndex the leaf to look up
+   * @returns The l1 to l2 leaf value or undefined if not found.
+   */
+  getL1ToL2LeafValue(leafIndex: bigint): Promise<Fr | undefined>;
+
+  /**
+   * Gets the index of a commitment in the note hash tree.
+   * @param commitment - The commitment.
+   * @returns - The index of the commitment. Undefined if it does not exist in the tree.
+   */
+  getCommitmentIndex(commitment: Fr): Promise<bigint | undefined>;
+
+  /**
+   * Gets commitment in the note hash tree given a leaf index.
+   * @param leafIndex - the leaf to look up.
+   * @returns - The commitment at that index. Undefined if leaf index is not found.
+   */
+  getCommitmentValue(leafIndex: bigint): Promise<Fr | undefined>;
+
+  /**
+   * Gets the index of a nullifier in the nullifier tree.
+   * @param nullifier - The nullifier.
+   * @returns - The index of the nullifier. Undefined if it does not exist in the tree.
+   */
+  getNullifierIndex(nullifier: Fr): Promise<bigint | undefined>;
+
+  /**
+   * Returns a nullifier membership witness for the given nullifier or undefined if not found.
+   * REFACTOR: Same as getL1ToL2MembershipWitness, can be combined with aztec-node method that does almost the same thing.
+   * @param nullifier - Nullifier we're looking for.
+   */
+  getNullifierMembershipWitnessAtLatestBlock(nullifier: Fr): Promise<NullifierMembershipWitness | undefined>;
+}

package/src/common/debug_fn_name.ts

@@ -0,0 +1,18 @@
+import type { Fr } from '@aztec/foundation/fields';
+import { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+import type { WorldStateDB } from '../public/public_db_sources.js';
+
+export async function getPublicFunctionDebugName(
+  db: WorldStateDB,
+  contractAddress: AztecAddress,
+  calldata: Fr[],
+): Promise<string> {
+  // Public function is dispatched and therefore the target function is passed in the first argument.
+  const targetFunction =
+    calldata[0] !== undefined
+      ? await db.getDebugFunctionName(contractAddress, FunctionSelector.fromField(calldata[0]))
+      : `<calldata[0] undefined> (Contract Address: ${contractAddress})`;
+  return `${targetFunction}`;
+}

package/src/common/errors.ts

@@ -0,0 +1,183 @@
+import type { Fr } from '@aztec/foundation/fields';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import type { BrilligFunctionId, FunctionAbi, FunctionDebugMetadata, OpcodeLocation } from '@aztec/stdlib/abi';
+import {
+  type FailingFunction,
+  type NoirCallStack,
+  SimulationError,
+  type SourceCodeLocation,
+} from '@aztec/stdlib/errors';
+
+import type { RawAssertionPayload } from '@noir-lang/acvm_js';
+import { abiDecodeError } from '@noir-lang/noirc_abi';
+
+/**
+ * An error that occurred during the execution of a function.
+ * @param message - the error message
+ * @param failingFunction - the Aztec function that failed
+ * @param noirCallStack - the internal call stack of the function that failed (within the failing Aztec function)
+ * @param options - additional error options (an optional "cause" entry allows for a recursive error stack where
+ *                  an error's cause may be an ExecutionError itself)
+ */
+export class ExecutionError extends Error {
+  constructor(
+    message: string,
+    /**
+     * The function that failed.
+     */
+    public failingFunction: FailingFunction,
+    /**
+     * The noir call stack of the function that failed.
+     */
+    public noirCallStack?: NoirCallStack,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+/**
+ * Traverses the cause chain of an error.
+ * @param error - The error to start from.
+ * @param callback - A callback on every error, including the first one.
+ */
+export function traverseCauseChain(error: Error, callback: (error: Error) => void) {
+  let currentError: Error | undefined = error;
+  while (currentError) {
+    callback(currentError);
+    if (currentError.cause && currentError.cause instanceof Error) {
+      currentError = currentError.cause;
+    } else {
+      currentError = undefined;
+    }
+  }
+}
+
+/**
+ * Creates a simulation error from an error chain generated during the execution of a function.
+ * @param error - The error thrown during execution.
+ * @returns - A simulation error.
+ */
+export function createSimulationError(error: Error, revertData?: Fr[]): SimulationError {
+  let rootCause = error;
+  let noirCallStack: NoirCallStack | undefined = undefined;
+  const aztecCallStack: FailingFunction[] = [];
+
+  traverseCauseChain(error, cause => {
+    rootCause = cause;
+    if (cause instanceof ExecutionError) {
+      aztecCallStack.push(cause.failingFunction);
+      if (cause.noirCallStack) {
+        noirCallStack = cause.noirCallStack;
+      }
+    }
+  });
+
+  return new SimulationError(rootCause.message, aztecCallStack, revertData, noirCallStack, { cause: rootCause });
+}
+
+/**
+ * Extracts a brillig location from an opcode location.
+ * @param opcodeLocation - The opcode location to extract from. It should be in the format `acirLocation.brilligLocation` or `acirLocation`.
+ * @returns The brillig location if the opcode location contains one.
+ */
+function extractBrilligLocation(opcodeLocation: string): string | undefined {
+  const splitted = opcodeLocation.split('.');
+  if (splitted.length === 2) {
+    return splitted[1];
+  }
+  return undefined;
+}
+
+/**
+ * Extracts the call stack from the location of a failing opcode and the debug metadata.
+ * One opcode can point to multiple calls due to inlining.
+ */
+function getSourceCodeLocationsFromOpcodeLocation(
+  opcodeLocation: string,
+  debug: FunctionDebugMetadata,
+  brilligFunctionId?: BrilligFunctionId,
+): SourceCodeLocation[] {
+  const { debugSymbols, files } = debug;
+
+  let callStack = debugSymbols.locations[opcodeLocation] || [];
+  if (callStack.length === 0) {
+    const brilligLocation = extractBrilligLocation(opcodeLocation);
+    if (brilligFunctionId !== undefined && brilligLocation !== undefined) {
+      callStack = debugSymbols.brillig_locations[brilligFunctionId][brilligLocation] || [];
+    }
+  }
+  return callStack.map(call => {
+    const { file: fileId, span } = call;
+
+    const { path, source } = files[fileId];
+
+    const locationText = source.substring(span.start, span.end);
+    const precedingText = source.substring(0, span.start);
+    const previousLines = precedingText.split('\n');
+    // Lines and columns in stacks are one indexed.
+    const line = previousLines.length;
+    const column = previousLines[previousLines.length - 1].length + 1;
+
+    return {
+      filePath: path,
+      line,
+      column,
+      fileSource: source,
+      locationText,
+    };
+  });
+}
+
+/**
+ * Extracts the source code locations for an array of opcode locations
+ * @param opcodeLocations - The opcode locations that caused the error.
+ * @param debug - The debug metadata of the function.
+ * @returns The source code locations.
+ */
+export function resolveOpcodeLocations(
+  opcodeLocations: OpcodeLocation[],
+  debug: FunctionDebugMetadata,
+  brilligFunctionId?: BrilligFunctionId,
+): SourceCodeLocation[] {
+  return opcodeLocations.flatMap(opcodeLocation =>
+    getSourceCodeLocationsFromOpcodeLocation(opcodeLocation, debug, brilligFunctionId),
+  );
+}
+
+export function resolveAssertionMessage(errorPayload: RawAssertionPayload, abi: FunctionAbi): string | undefined {
+  const decoded = abiDecodeError(
+    { parameters: [], error_types: abi.errorTypes, return_type: null }, // eslint-disable-line camelcase
+    errorPayload,
+  );
+
+  if (typeof decoded === 'string') {
+    return decoded;
+  } else {
+    return jsonStringify(decoded);
+  }
+}
+
+export function resolveAssertionMessageFromRevertData(revertData: Fr[], abi: FunctionAbi): string | undefined {
+  if (revertData.length == 0) {
+    return undefined;
+  }
+
+  const [errorSelector, ...errorData] = revertData;
+
+  return resolveAssertionMessage(
+    {
+      selector: errorSelector.toBigInt().toString(),
+      data: errorData.map(f => f.toString()),
+    },
+    abi,
+  );
+}
+
+export function resolveAssertionMessageFromError(err: Error, abi: FunctionAbi): string {
+  if (typeof err === 'object' && err !== null && 'rawAssertionPayload' in err && err.rawAssertionPayload) {
+    return `Assertion failed: ${resolveAssertionMessage(err.rawAssertionPayload as RawAssertionPayload, abi)}`;
+  } else {
+    return err.message;
+  }
+}

package/src/common/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './stats/index.js';
+export * from './message_load_oracle_inputs.js';

package/src/common/message_load_oracle_inputs.ts

@@ -0,0 +1,15 @@
+import { Fr } from '@aztec/foundation/fields';
+import type { SiblingPath } from '@aztec/foundation/trees';
+
+export class MessageLoadOracleInputs<N extends number> {
+  constructor(
+    /** The index of the message commitment in the merkle tree. */
+    public index: bigint,
+    /** The path in the merkle tree to the message. */
+    public siblingPath: SiblingPath<N>,
+  ) {}
+
+  toFields(): Fr[] {
+    return [new Fr(this.index), ...this.siblingPath.toFields()];
+  }
+}

package/src/common/stats/index.ts

@@ -0,0 +1 @@
+export * from './stats.js';

package/src/common/stats/stats.ts

@@ -0,0 +1,20 @@
+import type { Logger } from '@aztec/foundation/log';
+import type { CircuitName, CircuitSimulationStats } from '@aztec/stdlib/stats';
+
+export function emitCircuitSimulationStats(
+  circuitName: CircuitName,
+  duration: number,
+  inputSize: number,
+  outputSize: number,
+  logger: Logger,
+) {
+  const stats: CircuitSimulationStats = {
+    eventName: 'circuit-simulation',
+    circuitName,
+    inputSize,
+    outputSize,
+    duration,
+  };
+
+  logger.debug('Circuit simulation stats', stats);
+}

package/src/private/acvm/acvm.ts

@@ -0,0 +1,127 @@
+import { createLogger } from '@aztec/foundation/log';
+import type { FunctionDebugMetadata } from '@aztec/stdlib/abi';
+import type { NoirCallStack } from '@aztec/stdlib/errors';
+
+import {
+  type ExecutionError,
+  type ForeignCallInput,
+  type ForeignCallOutput,
+  executeCircuitWithReturnWitness,
+} from '@noir-lang/acvm_js';
+
+import { resolveOpcodeLocations, traverseCauseChain } from '../../common/errors.js';
+import type { ACVMWitness } from './acvm_types.js';
+import type { ORACLE_NAMES } from './oracle/index.js';
+
+/**
+ * The callback interface for the ACIR.
+ */
+export type ACIRCallback = Record<
+  ORACLE_NAMES,
+  (
+    ...args: ForeignCallInput[]
+  ) =>
+    | void
+    | Promise<void>
+    | ForeignCallOutput
+    | ForeignCallOutput[]
+    | Promise<ForeignCallOutput>
+    | Promise<ForeignCallOutput[]>
+>;
+
+/**
+ * The result of executing an ACIR.
+ */
+export interface ACIRExecutionResult {
+  /**
+   * An execution result contains two witnesses.
+   * 1. The partial witness of the execution.
+   * 2. The return witness which contains the given public return values within the full witness.
+   */
+  partialWitness: ACVMWitness;
+  returnWitness: ACVMWitness;
+}
+
+/**
+ * The function call that executes an ACIR.
+ */
+export async function acvm(
+  acir: Buffer,
+  initialWitness: ACVMWitness,
+  callback: ACIRCallback,
+): Promise<ACIRExecutionResult> {
+  const logger = createLogger('simulator:acvm');
+
+  const solvedAndReturnWitness = await executeCircuitWithReturnWitness(
+    acir,
+    initialWitness,
+    async (name: string, args: ForeignCallInput[]) => {
+      try {
+        logger.debug(`Oracle callback ${name}`);
+        const oracleFunction = callback[name as ORACLE_NAMES];
+        if (!oracleFunction) {
+          throw new Error(`Oracle callback ${name} not found`);
+        }
+
+        const result = await oracleFunction.call(callback, ...args);
+
+        if (typeof result === 'undefined') {
+          return [];
+        } else if (result instanceof Array && !result.every(item => typeof item === 'string')) {
+          // We are dealing with a nested array which means that we do not need it wrap it in another array as to have
+          // the nested array structure it is already "wrapped".
+          return result;
+        } else {
+          return [result] as ForeignCallOutput[];
+        }
+      } catch (err) {
+        let typedError: Error;
+        if (err instanceof Error) {
+          typedError = err;
+        } else {
+          typedError = new Error(`Error in oracle callback ${err}`);
+        }
+        logger.error(`Error in oracle callback ${name}: ${typedError.message}`);
+        throw typedError;
+      }
+    },
+  ).catch((err: Error) => {
+    // Wasm callbacks act as a boundary for stack traces, so we capture it here and complete the error if it happens.
+    const stack = new Error().stack;
+
+    traverseCauseChain(err, cause => {
+      if (cause.stack) {
+        cause.stack += stack;
+      }
+    });
+
+    throw err;
+  });
+
+  return { partialWitness: solvedAndReturnWitness.solvedWitness, returnWitness: solvedAndReturnWitness.returnWitness };
+}
+
+/**
+ * Extracts the call stack from an thrown by the acvm.
+ * @param error - The error to extract from.
+ * @param debug - The debug metadata of the function called.
+ * @returns The call stack, if available.
+ */
+export function extractCallStack(
+  error: Error | ExecutionError,
+  debug?: FunctionDebugMetadata,
+): NoirCallStack | undefined {
+  if (!('callStack' in error) || !error.callStack) {
+    return undefined;
+  }
+  const { callStack, brilligFunctionId } = error;
+  if (!debug) {
+    return callStack;
+  }
+
+  try {
+    return resolveOpcodeLocations(callStack, debug, brilligFunctionId);
+  } catch (err) {
+    return callStack;
+  }
+}

package/src/private/acvm/acvm_types.ts

@@ -0,0 +1,11 @@
+import type { WitnessMap } from '@noir-lang/acvm_js';
+
+/**
+ * ACVMField
+ */
+export type ACVMField = string;
+
+/**
+ * The format for witnesses of the ACVM.
+ */
+export type ACVMWitness = WitnessMap;

package/src/private/acvm/deserialize.ts

@@ -0,0 +1,52 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import type { ACVMField, ACVMWitness } from './acvm_types.js';
+
+/**
+ * Converts an ACVM field to a Fr.
+ * @param field - The ACVM field to convert.
+ * @returns The Fr.
+ */
+export function fromACVMField(field: ACVMField): Fr {
+  return Fr.fromBuffer(Buffer.from(field.slice(2), 'hex'));
+}
+
+/**
+ * Converts a field to a number.
+ * @param fr - The field to convert.
+ * @returns The number.
+ * TODO(#4102): Nuke this once block number is big int.
+ */
+export function frToNumber(fr: Fr): number {
+  return Number(fr.value);
+}
+
+/**
+ * Converts a field to a boolean.
+ * @param fr - The field to convert.
+ */
+export function frToBoolean(fr: Fr): boolean {
+  return fr.toBigInt() === BigInt(1);
+}
+
+/**
+ * Converts a Noir BoundedVec of Fields into an Fr array. Note that BoundedVecs are structs, and therefore translated as
+ * two separate ACVMField values (an array and a single field).
+ *
+ * @param storage The array with the BoundedVec's storage (i.e. BoundedVec::storage())
+ * @param length The length of the BoundedVec (i.e. BoundedVec::len())
+ * @returns An array with the same content as the Noir version. Elements past the length are discarded.
+ */
+export function fromBoundedVec(storage: ACVMField[], length: ACVMField): Fr[] {
+  return storage.slice(0, frToNumber(fromACVMField(length))).map(fromACVMField);
+}
+
+/**
+ * Transforms a witness map to its field elements.
+ * @param witness - The witness to extract from.
+ * @returns The return values.
+ */
+export function witnessMapToFields(witness: ACVMWitness): Fr[] {
+  const sortedKeys = [...witness.keys()].sort((a, b) => a - b);
+  return sortedKeys.map(key => witness.get(key)!).map(fromACVMField);
+}

package/src/private/acvm/index.ts

@@ -0,0 +1,5 @@
+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/acvm/oracle/index.ts

@@ -0,0 +1,16 @@
+import type { Oracle } from './oracle.js';
+
+export * from './oracle.js';
+export * from './typed_oracle.js';
+
+/**
+ * A conditional type that takes a type `T` and returns a union of its method names.
+ */
+type MethodNames<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
+}[keyof T];
+
+/**
+ * Available oracle function names.
+ */
+export type ORACLE_NAMES = MethodNames<Oracle>;