@aztec/simulator 0.0.0-test.0

package/src/public/avm/bytecode_utils.ts

@@ -0,0 +1,17 @@
+import { Opcode } from './serialization/instruction_serialization.js';
+
+const AVM_MAGIC_SUFFIX = Buffer.from([
+  Opcode.MOV_16, // opcode
+  0x00, // indirect
+  ...Buffer.from('18ca', 'hex'), // srcOffset
+  ...Buffer.from('18ca', 'hex'), // dstOffset
+]);
+
+export function markBytecodeAsAvm(bytecode: Buffer): Buffer {
+  return Buffer.concat([bytecode, AVM_MAGIC_SUFFIX]);
+}
+
+export function isAvmBytecode(bytecode: Buffer): boolean {
+  const magicSize = AVM_MAGIC_SUFFIX.length;
+  return bytecode.subarray(-magicSize).equals(AVM_MAGIC_SUFFIX);
+}

package/src/public/avm/errors.ts

@@ -0,0 +1,232 @@
+import type { Fr, Point } from '@aztec/foundation/fields';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { FailingFunction, NoirCallStack } from '@aztec/stdlib/errors';
+
+import { ExecutionError } from '../../common/errors.js';
+import type { AvmContext } from './avm_context.js';
+
+/**
+ * Avm-specific errors should derive from this
+ */
+export abstract class AvmExecutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AvmExecutionError';
+  }
+}
+
+export class NoBytecodeForContractError extends AvmExecutionError {
+  constructor(contractAddress: AztecAddress) {
+    super(`No bytecode found at: ${contractAddress}`);
+    this.name = 'NoBytecodeFoundInterpreterError';
+  }
+}
+
+export class ArithmeticError extends AvmExecutionError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ArithmeticError';
+  }
+}
+
+/**
+ * Error is thrown when the program counter goes to an invalid location.
+ * There is no instruction at the provided pc
+ */
+export class InvalidProgramCounterError extends AvmExecutionError {
+  constructor(pc: number, max: number) {
+    super(`Invalid program counter ${pc}, max is ${max}`);
+    this.name = 'InvalidProgramCounterError';
+  }
+}
+
+/**
+ * Error is thrown when the program counter points to a byte
+ * of an invalid opcode.
+ */
+export class InvalidOpcodeError extends AvmExecutionError {
+  constructor(str: string) {
+    super(str);
+    this.name = 'InvalidOpcodeError';
+  }
+}
+
+/**
+ * Error is thrown during parsing.
+ */
+export class AvmParsingError extends AvmExecutionError {
+  constructor(str: string) {
+    super(str);
+    this.name = 'AvmParsingError';
+  }
+}
+
+/**
+ * Error is thrown when the tag has an invalid value.
+ */
+export class InvalidTagValueError extends AvmExecutionError {
+  constructor(tagValue: number) {
+    super(`Tag value ${tagValue} is invalid.`);
+    this.name = 'InvalidTagValueError';
+  }
+}
+
+/**
+ * Error thrown during an instruction's execution (during its execute()).
+ */
+export class InstructionExecutionError extends AvmExecutionError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InstructionExecutionError';
+  }
+}
+
+/**
+ * Error thrown on failed AVM memory tag check.
+ */
+export class TagCheckError extends AvmExecutionError {
+  public static forOffset(offset: number, gotTag: string, expectedTag: string): TagCheckError {
+    return new TagCheckError(`Tag mismatch at offset ${offset}, got ${gotTag}, expected ${expectedTag}`);
+  }
+
+  public static forTag(gotTag: string, expectedTag: string): TagCheckError {
+    return new TagCheckError(`Tag mismatch, got ${gotTag}, expected ${expectedTag}`);
+  }
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'TagCheckError';
+  }
+}
+
+/**
+ * Error is thrown when a relative memory address resolved to an offset which
+ * is out of range, i.e, greater than maxUint32.
+ */
+export class RelativeAddressOutOfRangeError extends AvmExecutionError {
+  constructor(baseAddr: number, relOffset: number) {
+    super(`Address out of range. Base address ${baseAddr}, relative offset ${relOffset}`);
+    this.name = 'RelativeAddressOutOfRangeError';
+  }
+}
+
+/**
+ * Error is thrown when a memory slice contains addresses which are
+ * out of range, i.e, greater than maxUint32.
+ */
+export class MemorySliceOutOfRangeError extends AvmExecutionError {
+  constructor(baseAddr: number, size: number) {
+    super(`Memory slice is out of range. Base address ${baseAddr}, size ${size}`);
+    this.name = 'MemorySliceOutOfRangeError';
+  }
+}
+
+/** Error thrown when out of gas. */
+export class OutOfGasError extends AvmExecutionError {
+  constructor(dimensions: string[]) {
+    super(`Not enough ${dimensions.map(d => d.toUpperCase()).join(', ')} gas left`);
+    this.name = 'OutOfGasError';
+  }
+}
+
+/**
+ * Error is thrown when the supplied points length is not a multiple of 3. Specific for MSM opcode.
+ */
+export class MSMPointsLengthError extends AvmExecutionError {
+  constructor(pointsReadLength: number) {
+    super(`Points vector length should be a multiple of 3, was ${pointsReadLength}`);
+    this.name = 'MSMPointsLengthError';
+  }
+}
+
+/**
+ * Error is thrown when one of the supplied points does not lie on the Grumpkin curve. Specific for MSM opcode.
+ */
+export class MSMPointNotOnCurveError extends AvmExecutionError {
+  constructor(point: Point) {
+    super(`Point ${point.toString()} is not on the curve.`);
+    this.name = 'MSMPointNotOnCurveError';
+  }
+}
+
+/**
+ * Error is thrown when some inputs of ToRadixBE are not valid.
+ */
+export class InvalidToRadixInputsError extends AvmExecutionError {
+  constructor(errorString: string) {
+    super(errorString);
+    this.name = 'InvalidToRadixInputsError';
+  }
+}
+
+/**
+ * Error is thrown when a static call attempts to alter some state
+ */
+export class StaticCallAlterationError extends InstructionExecutionError {
+  constructor() {
+    super('Static call cannot update the state, emit L2->L1 messages or generate logs');
+    this.name = 'StaticCallAlterationError';
+  }
+}
+
+/**
+ * Meaningfully named alias for ExecutionError when used in the context of the AVM.
+ * Maintains a recursive structure reflecting the AVM's external callstack/errorstack, where
+ * options.cause is the error that caused this error (if this is not the root-cause itself).
+ */
+export class AvmRevertReason extends ExecutionError {
+  constructor(message: string, failingFunction: FailingFunction, noirCallStack: NoirCallStack, options?: ErrorOptions) {
+    super(message, failingFunction, noirCallStack, options);
+  }
+}
+
+async function createRevertReason(message: string, revertData: Fr[], context: AvmContext): Promise<AvmRevertReason> {
+  // We drop the returnPc information.
+  const internalCallStack = context.machineState.internalCallStack.map(entry => entry.callPc);
+
+  // If we are reverting due to the same error that we have been tracking, we use the nested error as the cause.
+  let nestedError = undefined;
+  const revertDataEquals = (a: Fr[], b: Fr[]) => a.length === b.length && a.every((v, i) => v.equals(b[i]));
+  if (
+    context.machineState.collectedRevertInfo &&
+    revertDataEquals(context.machineState.collectedRevertInfo.revertDataRepresentative, revertData)
+  ) {
+    nestedError = context.machineState.collectedRevertInfo.recursiveRevertReason;
+    message = context.machineState.collectedRevertInfo.recursiveRevertReason.message;
+  }
+
+  const fnName = await context.persistableState.getPublicFunctionDebugName(context.environment);
+
+  return new AvmRevertReason(
+    message,
+    /*failingFunction=*/ {
+      contractAddress: context.environment.address,
+      functionName: fnName,
+    },
+    /*noirCallStack=*/ [...internalCallStack, context.machineState.pc].map(pc => `0.${pc}`),
+    /*options=*/ { cause: nestedError },
+  );
+}
+
+/**
+ * Create a "revert reason" error for an exceptional halt.
+ *
+ * @param haltingError - the lower-level error causing the exceptional halt
+ * @param context - the context of the AVM execution used to extract the failingFunction and noirCallStack
+ */
+export async function revertReasonFromExceptionalHalt(
+  haltingError: AvmExecutionError,
+  context: AvmContext,
+): Promise<AvmRevertReason> {
+  return await createRevertReason(haltingError.message, [], context);
+}
+
+/**
+ * Create a "revert reason" error for an explicit revert (a root cause).
+ *
+ * @param revertData - output data of the explicit REVERT instruction
+ * @param context - the context of the AVM execution used to extract the failingFunction and noirCallStack
+ */
+export async function revertReasonFromExplicitRevert(revertData: Fr[], context: AvmContext): Promise<AvmRevertReason> {
+  return await createRevertReason('Assertion failed: ', revertData, context);
+}

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

@@ -0,0 +1,105 @@
+import { Fr } from '@aztec/foundation/fields';
+import { encodeArguments } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { GasFees } from '@aztec/stdlib/gas';
+import type { MerkleTreeWriteOperations } from '@aztec/stdlib/interfaces/server';
+import { GlobalVariables } from '@aztec/stdlib/tx';
+import { NativeWorldStateService } from '@aztec/world-state';
+
+import { SideEffectTrace } from '../../../public/side_effect_trace.js';
+import type { AvmContractCallResult } from '../../avm/avm_contract_call_result.js';
+import {
+  getContractFunctionArtifact,
+  getFunctionSelector,
+  initContext,
+  initExecutionEnvironment,
+  resolveContractAssertionMessage,
+} from '../../avm/fixtures/index.js';
+import { AvmPersistableStateManager } from '../../avm/journal/journal.js';
+import { WorldStateDB } from '../../public_db_sources.js';
+import { AvmSimulator } from '../avm_simulator.js';
+import { BaseAvmSimulationTester } from './base_avm_simulation_tester.js';
+import { SimpleContractDataSource } from './simple_contract_data_source.js';
+
+const TIMESTAMP = new Fr(99833);
+const DEFAULT_GAS_FEES = new GasFees(2, 3);
+
+/**
+ * A test class that extends the BaseAvmSimulationTester to enable real-app testing of the core AvmSimulator.
+ * It provides an interface for simulating one top-level call at a time and maintains state between
+ * subsequent top-level calls.
+ */
+export class AvmSimulationTester extends BaseAvmSimulationTester {
+  constructor(
+    contractDataSource: SimpleContractDataSource,
+    merkleTrees: MerkleTreeWriteOperations,
+    private stateManager: AvmPersistableStateManager,
+  ) {
+    super(contractDataSource, merkleTrees);
+  }
+
+  static async create(): Promise<AvmSimulationTester> {
+    const contractDataSource = new SimpleContractDataSource();
+    const merkleTrees = await (await NativeWorldStateService.tmp()).fork();
+    const worldStateDB = new WorldStateDB(merkleTrees, contractDataSource);
+    const trace = new SideEffectTrace();
+    const firstNullifier = new Fr(420000);
+    // FIXME: merkle ops should work, but I'm seeing frequent (but inconsistent) bytecode retrieval
+    // failures on 2nd call to simulateCall with merkle ops on
+    const stateManager = AvmPersistableStateManager.create(
+      worldStateDB,
+      trace,
+      /*doMerkleOperations=*/ false,
+      firstNullifier,
+    );
+    return new AvmSimulationTester(contractDataSource, merkleTrees, stateManager);
+  }
+
+  /**
+   * Simulate a top-level contract call.
+   */
+  async simulateCall(
+    sender: AztecAddress,
+    address: AztecAddress,
+    fnName: string,
+    args: any[],
+    isStaticCall = false,
+  ): Promise<AvmContractCallResult> {
+    const contractArtifact = await this.contractDataSource.getContractArtifact(address);
+    if (!contractArtifact) {
+      throw new Error(`Contract not found at address: ${address}`);
+    }
+    const fnSelector = await getFunctionSelector(fnName, contractArtifact);
+    const fnAbi = getContractFunctionArtifact(fnName, contractArtifact);
+    const encodedArgs = encodeArguments(fnAbi!, args);
+    const calldata = [fnSelector.toField(), ...encodedArgs];
+
+    const globals = GlobalVariables.empty();
+    globals.timestamp = TIMESTAMP;
+    globals.gasFees = DEFAULT_GAS_FEES;
+
+    const environment = initExecutionEnvironment({
+      calldata,
+      globals,
+      address,
+      sender,
+      isStaticCall,
+    });
+    const persistableState = await this.stateManager.fork();
+    const context = initContext({ env: environment, persistableState });
+
+    // First we simulate (though it's not needed in this simple case).
+    const simulator = new AvmSimulator(context);
+    const result = await simulator.execute();
+    if (result.reverted) {
+      this.logger.error(`Error in ${fnName}:`);
+      this.logger.error(
+        resolveContractAssertionMessage(fnName, result.revertReason!, result.output, contractArtifact)!,
+      );
+    } else {
+      this.logger.info(`Simulation of function ${fnName} succeeded!`);
+      await this.stateManager.merge(persistableState);
+    }
+    return result;
+  }
+}

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

@@ -0,0 +1,109 @@
+import { DEPLOYER_CONTRACT_ADDRESS } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { computeFeePayerBalanceStorageSlot, getCanonicalFeeJuice } from '@aztec/protocol-contracts/fee-juice';
+import type { ContractArtifact } from '@aztec/stdlib/abi';
+import { PublicDataWrite } from '@aztec/stdlib/avm';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { ContractClassPublic, ContractInstanceWithAddress } from '@aztec/stdlib/contract';
+import { computePublicDataTreeLeafSlot, siloNullifier } from '@aztec/stdlib/hash';
+import type { MerkleTreeWriteOperations } from '@aztec/stdlib/interfaces/server';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+
+import { createContractClassAndInstance } from './index.js';
+import type { SimpleContractDataSource } from './simple_contract_data_source.js';
+
+/**
+ * An abstract test class that enables tests of real apps in the AVM without requiring e2e tests.
+ * It enables this by letting us (1) perform pseudo-contract-deployments (and registrations)
+ * that trigger merkle tree operations and (2) maintain a contract data source to store
+ * and retrieve contract classes and instances.
+ *
+ * This class is meant to be extended when writing tests for a specific simulation interface.
+ * For example, has been extended for testing of the core AvmSimulator, and again for the PublicTxSimulator,
+ * both of which benefit from such pseudo-deployments by populating merkle trees and a contract data source
+ * with contract information.
+ */
+export abstract class BaseAvmSimulationTester {
+  public logger = createLogger('avm-simulation-tester');
+
+  constructor(
+    public contractDataSource: SimpleContractDataSource,
+    public merkleTrees: MerkleTreeWriteOperations,
+    private initialFeePayerBalance = new Fr(10 ** 10),
+  ) {}
+
+  async setFeePayerBalance(feePayer: AztecAddress, balance = this.initialFeePayerBalance) {
+    const feeJuiceAddress = ProtocolContractAddress.FeeJuice;
+    const balanceSlot = await computeFeePayerBalanceStorageSlot(feePayer);
+    await this.setPublicStorage(feeJuiceAddress, balanceSlot, balance);
+  }
+
+  async setPublicStorage(address: AztecAddress, slot: Fr, value: Fr) {
+    const leafSlot = await computePublicDataTreeLeafSlot(address, slot);
+    // get existing preimage
+    const publicDataWrite = new PublicDataWrite(leafSlot, value);
+    await this.merkleTrees.batchInsert(MerkleTreeId.PUBLIC_DATA_TREE, [publicDataWrite.toBuffer()], 0);
+  }
+
+  /**
+   * Derive the contract class and instance with some seed.
+   * Add both to the contract data source along with the contract artifact.
+   */
+  async registerAndDeployContract(
+    constructorArgs: any[],
+    deployer: AztecAddress,
+    contractArtifact: ContractArtifact,
+    skipNullifierInsertion = false,
+    seed = 0,
+    originalContractClassId?: Fr, // if previously upgraded
+  ): Promise<ContractInstanceWithAddress> {
+    const { contractClass, contractInstance } = await createContractClassAndInstance(
+      constructorArgs,
+      deployer,
+      contractArtifact,
+      seed,
+      originalContractClassId,
+    );
+
+    await this.contractDataSource.addNewContract(contractArtifact, contractClass, contractInstance);
+
+    if (!skipNullifierInsertion) {
+      await this.insertContractAddressNullifier(contractInstance.address);
+    }
+    return contractInstance;
+  }
+
+  async registerFeeJuiceContract(): Promise<ContractInstanceWithAddress> {
+    const feeJuice = await getCanonicalFeeJuice();
+    const feeJuiceContractClassPublic = {
+      ...feeJuice.contractClass,
+      privateFunctions: [],
+      unconstrainedFunctions: [],
+    };
+    await this.contractDataSource.addNewContract(feeJuice.artifact, feeJuiceContractClassPublic, feeJuice.instance);
+    return feeJuice.instance;
+  }
+
+  addContractClass(contractClass: ContractClassPublic, contractArtifact: ContractArtifact): Promise<void> {
+    this.logger.debug(`Adding contract class with Id ${contractClass.id}`);
+    this.contractDataSource.addContractArtifact(contractClass.id, contractArtifact);
+    return this.contractDataSource.addContractClass(contractClass);
+  }
+
+  async addContractInstance(contractInstance: ContractInstanceWithAddress, skipNullifierInsertion = false) {
+    if (!skipNullifierInsertion) {
+      await this.insertContractAddressNullifier(contractInstance.address);
+    }
+    await this.contractDataSource.addContractInstance(contractInstance);
+  }
+
+  private async insertContractAddressNullifier(contractAddress: AztecAddress) {
+    const contractAddressNullifier = await siloNullifier(
+      AztecAddress.fromNumber(DEPLOYER_CONTRACT_ADDRESS),
+      contractAddress.toField(),
+    );
+    await this.merkleTrees.batchInsert(MerkleTreeId.NULLIFIER_TREE, [contractAddressNullifier.toBuffer()], 0);
+  }
+}