@aztec/simulator 0.22.0 → 0.24.0

package/src/avm/avm_execution_environment.ts

@@ -0,0 +1,98 @@
+import { FunctionSelector, GlobalVariables } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * Contains variables that remain constant during AVM execution
+ * These variables are provided by the public kernel circuit
+ */
+// TODO(https://github.com/AztecProtocol/aztec-packages/issues/3992): gas not implemented
+export class AvmExecutionEnvironment {
+  constructor(
+    public readonly address: AztecAddress,
+
+    public readonly storageAddress: AztecAddress,
+
+    public readonly origin: AztecAddress,
+
+    public readonly sender: AztecAddress,
+
+    public readonly portal: EthAddress,
+
+    public readonly feePerL1Gas: Fr,
+
+    public readonly feePerL2Gas: Fr,
+
+    public readonly feePerDaGas: Fr,
+
+    public readonly contractCallDepth: Fr,
+
+    public readonly globals: GlobalVariables,
+
+    public readonly isStaticCall: boolean,
+
+    public readonly isDelegateCall: boolean,
+
+    public readonly calldata: Fr[],
+
+    public readonly temporaryFunctionSelector: FunctionSelector,
+  ) {}
+
+  public deriveEnvironmentForNestedCall(address: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+    return new AvmExecutionEnvironment(
+      /*address=*/ address,
+      /*storageAddress=*/ address,
+      this.origin,
+      this.sender,
+      this.portal,
+      this.feePerL1Gas,
+      this.feePerL2Gas,
+      this.feePerDaGas,
+      this.contractCallDepth,
+      this.globals,
+      this.isStaticCall,
+      this.isDelegateCall,
+      /*calldata=*/ calldata,
+      this.temporaryFunctionSelector,
+    );
+  }
+
+  public deriveEnvironmentForNestedStaticCall(address: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+    return new AvmExecutionEnvironment(
+      /*address=*/ address,
+      /*storageAddress=*/ address,
+      this.origin,
+      this.sender,
+      this.portal,
+      this.feePerL1Gas,
+      this.feePerL2Gas,
+      this.feePerDaGas,
+      this.contractCallDepth,
+      this.globals,
+      /*isStaticCall=*/ true,
+      this.isDelegateCall,
+      /*calldata=*/ calldata,
+      this.temporaryFunctionSelector,
+    );
+  }
+
+  public newDelegateCall(address: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+    return new AvmExecutionEnvironment(
+      /*address=*/ address,
+      this.storageAddress,
+      this.origin,
+      this.sender,
+      this.portal,
+      this.feePerL1Gas,
+      this.feePerL2Gas,
+      this.feePerDaGas,
+      this.contractCallDepth,
+      this.globals,
+      this.isStaticCall,
+      /*isDelegateCall=*/ true,
+      /*calldata=*/ calldata,
+      this.temporaryFunctionSelector,
+    );
+  }
+}

package/src/avm/avm_machine_state.ts

@@ -0,0 +1,93 @@
+import { Fr } from '@aztec/circuits.js';
+
+import { TaggedMemory } from './avm_memory_types.js';
+import { AvmContractCallResults } from './avm_message_call_result.js';
+
+/**
+ * A few fields of machine state are initialized from AVM session inputs or call instruction arguments
+ */
+export type InitialAvmMachineState = {
+  l1GasLeft: number;
+  l2GasLeft: number;
+  daGasLeft: number;
+};
+
+/**
+ * Avm state modified on an instruction-per-instruction basis.
+ */
+export class AvmMachineState {
+  public l1GasLeft: number;
+  /** gas remaining of the gas allocated for a contract call */
+  public l2GasLeft: number;
+  public daGasLeft: number;
+  /** program counter */
+  public pc: number = 0;
+
+  /**
+   * On INTERNALCALL, internal call stack is pushed to with the current pc + 1
+   * On INTERNALRETURN, value is popped from the internal call stack and assigned to the pc.
+   */
+  public internalCallStack: number[] = [];
+
+  /** Memory accessible to user code */
+  public readonly memory: TaggedMemory = new TaggedMemory();
+
+  /**
+   * Signals that execution should end.
+   * AvmContext execution continues executing instructions until the machine state signals "halted"
+   * */
+  public halted: boolean = false;
+  /** Signals that execution has reverted normally (this does not cover exceptional halts) */
+  private reverted: boolean = false;
+  /** Output data must NOT be modified once it is set */
+  private output: Fr[] = [];
+
+  constructor(l1GasLeft: number, l2GasLeft: number, daGasLeft: number) {
+    this.l1GasLeft = l1GasLeft;
+    this.l2GasLeft = l2GasLeft;
+    this.daGasLeft = daGasLeft;
+  }
+
+  public static fromState(state: InitialAvmMachineState): AvmMachineState {
+    return new AvmMachineState(state.l1GasLeft, state.l2GasLeft, state.daGasLeft);
+  }
+
+  /**
+   * Most instructions just increment PC before they complete
+   */
+  public incrementPc() {
+    this.pc++;
+  }
+
+  /**
+   * Halt as successful
+   * Output data must NOT be modified once it is set
+   * @param output
+   */
+  public return(output: Fr[]) {
+    this.halted = true;
+    this.output = output;
+  }
+
+  /**
+   * Halt as reverted
+   * Output data must NOT be modified once it is set
+   * @param output
+   */
+  public revert(output: Fr[]) {
+    this.halted = true;
+    this.reverted = true;
+    this.output = output;
+  }
+
+  /**
+   * Get a summary of execution results for a halted machine state
+   * @returns summary of execution results
+   */
+  public getResults(): AvmContractCallResults {
+    if (!this.halted) {
+      throw new Error('Execution results are not ready! Execution is ongoing.');
+    }
+    return new AvmContractCallResults(this.reverted, this.output);
+  }
+}

package/src/avm/avm_memory_types.ts

@@ -0,0 +1,309 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import { strict as assert } from 'assert';
+
+import { TagCheckError } from './errors.js';
+
+/** MemoryValue gathers the common operations for all memory types. */
+export abstract class MemoryValue {
+  public abstract add(rhs: MemoryValue): MemoryValue;
+  public abstract sub(rhs: MemoryValue): MemoryValue;
+  public abstract mul(rhs: MemoryValue): MemoryValue;
+  public abstract div(rhs: MemoryValue): MemoryValue;
+
+  public abstract equals(rhs: MemoryValue): boolean;
+
+  // We need this to be able to build an instance of the subclasses.
+  public abstract build(n: bigint): MemoryValue;
+
+  // Use sparingly.
+  public abstract toBigInt(): bigint;
+
+  // To field
+  public toFr(): Fr {
+    return new Fr(this.toBigInt());
+  }
+}
+
+/** IntegralValue gathers the common operations for all integral memory types. */
+export abstract class IntegralValue extends MemoryValue {
+  public abstract shl(rhs: IntegralValue): IntegralValue;
+  public abstract shr(rhs: IntegralValue): IntegralValue;
+  public abstract and(rhs: IntegralValue): IntegralValue;
+  public abstract or(rhs: IntegralValue): IntegralValue;
+  public abstract xor(rhs: IntegralValue): IntegralValue;
+  public abstract not(): IntegralValue;
+
+  public abstract lt(rhs: IntegralValue): boolean;
+}
+
+/**
+ * This function creates a class for unsigned integers of a given number of bits.
+ * In TypeScript terms, it's a class mixin.
+ **/
+function UnsignedIntegerClassFactory(bits: number) {
+  return class NewUintClass extends IntegralValue {
+    static readonly mod: bigint = 1n << BigInt(bits);
+    static readonly bitmask: bigint = this.mod - 1n;
+    public readonly n: bigint; // Cannot be private due to TS limitations.
+
+    public constructor(n: bigint | number) {
+      super();
+      this.n = BigInt(n);
+      assert(n < NewUintClass.mod, `Value ${n} is too large for ${this.constructor.name}.`);
+    }
+
+    public build(n: bigint): NewUintClass {
+      return new this.constructor.prototype.constructor(n);
+    }
+
+    public add(rhs: NewUintClass): NewUintClass {
+      return this.build((this.n + rhs.n) & NewUintClass.bitmask);
+    }
+
+    public sub(rhs: NewUintClass): NewUintClass {
+      const res: bigint = this.n - rhs.n;
+      return this.build(res >= 0 ? res : res + NewUintClass.mod);
+    }
+
+    public mul(rhs: NewUintClass): NewUintClass {
+      return this.build((this.n * rhs.n) & NewUintClass.bitmask);
+    }
+
+    public div(rhs: NewUintClass): NewUintClass {
+      return this.build(this.n / rhs.n);
+    }
+
+    // No sign extension.
+    public shr(rhs: NewUintClass): NewUintClass {
+      // Note that this.n is > 0 by class invariant.
+      return this.build(this.n >> rhs.n);
+    }
+
+    public shl(rhs: NewUintClass): NewUintClass {
+      return this.build((this.n << rhs.n) & NewUintClass.bitmask);
+    }
+
+    public and(rhs: NewUintClass): NewUintClass {
+      return this.build(this.n & rhs.n);
+    }
+
+    public or(rhs: NewUintClass): NewUintClass {
+      return this.build(this.n | rhs.n);
+    }
+
+    public xor(rhs: NewUintClass): NewUintClass {
+      return this.build(this.n ^ rhs.n);
+    }
+
+    public not(): NewUintClass {
+      return this.build(~this.n & NewUintClass.bitmask);
+    }
+
+    public equals(rhs: NewUintClass): boolean {
+      return this.n === rhs.n;
+    }
+
+    public lt(rhs: NewUintClass): boolean {
+      return this.n < rhs.n;
+    }
+
+    public toBigInt(): bigint {
+      return this.n;
+    }
+  };
+}
+
+// Now we can create the classes for each unsigned integer type.
+// We extend instead of just assigning so that the class has the right name.
+// Otherwise they are all called "NewUintClass".
+export class Uint8 extends UnsignedIntegerClassFactory(8) {}
+export class Uint16 extends UnsignedIntegerClassFactory(16) {}
+export class Uint32 extends UnsignedIntegerClassFactory(32) {}
+export class Uint64 extends UnsignedIntegerClassFactory(64) {}
+export class Uint128 extends UnsignedIntegerClassFactory(128) {}
+
+export class Field extends MemoryValue {
+  public static readonly MODULUS: bigint = Fr.MODULUS;
+  private readonly rep: Fr;
+
+  constructor(v: number | bigint | Fr) {
+    super();
+    this.rep = new Fr(v);
+  }
+
+  public build(n: bigint): Field {
+    return new Field(n);
+  }
+
+  public add(rhs: Field): Field {
+    return new Field(this.rep.add(rhs.rep));
+  }
+
+  public sub(rhs: Field): Field {
+    return new Field(this.rep.sub(rhs.rep));
+  }
+
+  public mul(rhs: Field): Field {
+    return new Field(this.rep.mul(rhs.rep));
+  }
+
+  public div(rhs: Field): Field {
+    return new Field(this.rep.div(rhs.rep));
+  }
+
+  public equals(rhs: Field): boolean {
+    return this.rep.equals(rhs.rep);
+  }
+
+  public toBigInt(): bigint {
+    return this.rep.toBigInt();
+  }
+}
+
+export enum TypeTag {
+  UNINITIALIZED,
+  UINT8,
+  UINT16,
+  UINT32,
+  UINT64,
+  UINT128,
+  FIELD,
+  INVALID,
+}
+
+// TODO: Consider automatic conversion when getting undefined values.
+export class TaggedMemory {
+  // FIXME: memory should be 2^32, but TS doesn't allow for arrays that big.
+  static readonly MAX_MEMORY_SIZE = Number((1n << 32n) - 2n);
+  private _mem: MemoryValue[];
+
+  constructor() {
+    // We do not initialize memory size here because otherwise tests blow up when diffing.
+    this._mem = [];
+  }
+
+  public get(offset: number): MemoryValue {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    return this.getAs<MemoryValue>(offset);
+  }
+
+  public getAs<T>(offset: number): T {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    const word = this._mem[offset];
+    return word as T;
+  }
+
+  public getSlice(offset: number, size: number): MemoryValue[] {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    assert(offset + size < TaggedMemory.MAX_MEMORY_SIZE);
+    return this._mem.slice(offset, offset + size);
+  }
+
+  public getSliceAs<T>(offset: number, size: number): T[] {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    assert(offset + size < TaggedMemory.MAX_MEMORY_SIZE);
+    return this._mem.slice(offset, offset + size) as T[];
+  }
+
+  public getSliceTags(offset: number, size: number): TypeTag[] {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    assert(offset + size < TaggedMemory.MAX_MEMORY_SIZE);
+    return this._mem.slice(offset, offset + size).map(TaggedMemory.getTag);
+  }
+
+  public set(offset: number, v: MemoryValue) {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    this._mem[offset] = v;
+  }
+
+  public setSlice(offset: number, vs: MemoryValue[]) {
+    assert(offset < TaggedMemory.MAX_MEMORY_SIZE);
+    assert(offset + vs.length < TaggedMemory.MAX_MEMORY_SIZE);
+    // We may need to extend the memory size, otherwise splice doesn't insert.
+    if (offset + vs.length > this._mem.length) {
+      this._mem.length = offset + vs.length;
+    }
+    this._mem.splice(offset, vs.length, ...vs);
+  }
+
+  public getTag(offset: number): TypeTag {
+    return TaggedMemory.getTag(this._mem[offset]);
+  }
+
+  /**
+   * Check that the memory at the given offset matches the specified tag.
+   */
+  public checkTag(tag: TypeTag, offset: number) {
+    if (this.getTag(offset) !== tag) {
+      throw TagCheckError.forOffset(offset, TypeTag[this.getTag(offset)], TypeTag[tag]);
+    }
+  }
+
+  public static checkIsIntegralTag(tag: TypeTag) {
+    if (![TypeTag.UINT8, TypeTag.UINT16, TypeTag.UINT32, TypeTag.UINT64, TypeTag.UINT128].includes(tag)) {
+      throw TagCheckError.forTag(TypeTag[tag], 'integral');
+    }
+  }
+
+  /**
+   * Check tags for memory at all of the specified offsets.
+   */
+  public checkTags(tag: TypeTag, ...offsets: number[]) {
+    for (const offset of offsets) {
+      this.checkTag(tag, offset);
+    }
+  }
+
+  /**
+   * Check tags for all memory in the specified range.
+   */
+  public checkTagsRange(tag: TypeTag, startOffset: number, size: number) {
+    for (let offset = startOffset; offset < startOffset + size; offset++) {
+      this.checkTag(tag, offset);
+    }
+  }
+
+  // TODO: this might be slow, but I don't want to have the types know of their tags.
+  // It might be possible to have a map<Prototype, TypeTag>.
+  public static getTag(v: MemoryValue | undefined): TypeTag {
+    let tag = TypeTag.INVALID;
+
+    if (v === undefined) {
+      tag = TypeTag.UNINITIALIZED;
+    } else if (v instanceof Field) {
+      tag = TypeTag.FIELD;
+    } else if (v instanceof Uint8) {
+      tag = TypeTag.UINT8;
+    } else if (v instanceof Uint16) {
+      tag = TypeTag.UINT16;
+    } else if (v instanceof Uint32) {
+      tag = TypeTag.UINT32;
+    } else if (v instanceof Uint64) {
+      tag = TypeTag.UINT64;
+    } else if (v instanceof Uint128) {
+      tag = TypeTag.UINT128;
+    }
+
+    return tag;
+  }
+
+  // Truncates the value to fit the type.
+  public static integralFromTag(v: bigint | number, tag: TypeTag): IntegralValue {
+    v = BigInt(v);
+    switch (tag) {
+      case TypeTag.UINT8:
+        return new Uint8(v & ((1n << 8n) - 1n));
+      case TypeTag.UINT16:
+        return new Uint16(v & ((1n << 16n) - 1n));
+      case TypeTag.UINT32:
+        return new Uint32(v & ((1n << 32n) - 1n));
+      case TypeTag.UINT64:
+        return new Uint64(v & ((1n << 64n) - 1n));
+      case TypeTag.UINT128:
+        return new Uint128(v & ((1n << 128n) - 1n));
+      default:
+        throw new Error(`${TypeTag[tag]} is not a valid integral type.`);
+    }
+  }
+}

package/src/avm/avm_message_call_result.ts

@@ -0,0 +1,29 @@
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * Results of an contract call's execution in the AVM.
+ */
+export class AvmContractCallResults {
+  public readonly reverted: boolean;
+  public readonly output: Fr[];
+
+  /** For exceptional halts */
+  public readonly revertReason: Error | undefined;
+
+  constructor(reverted: boolean, output: Fr[], revertReason?: Error) {
+    this.reverted = reverted;
+    this.output = output;
+    this.revertReason = revertReason;
+  }
+
+  /**
+   * Generate a string representation of call results.
+   */
+  toString(): string {
+    let resultsStr = `reverted: ${this.reverted}, output: ${this.output}`;
+    if (this.revertReason) {
+      resultsStr += `, revertReason: ${this.revertReason}`;
+    }
+    return resultsStr;
+  }
+}

package/src/avm/avm_simulator.ts

@@ -0,0 +1,89 @@
+import { DebugLogger, createDebugLogger } from '@aztec/foundation/log';
+
+import { strict as assert } from 'assert';
+
+import type { AvmContext } from './avm_context.js';
+import { AvmContractCallResults } from './avm_message_call_result.js';
+import { AvmExecutionError, InvalidProgramCounterError, NoBytecodeForContractError } from './errors.js';
+import type { Instruction } from './opcodes/index.js';
+import { decodeFromBytecode } from './serialization/bytecode_serialization.js';
+
+export class AvmSimulator {
+  private log: DebugLogger = createDebugLogger('aztec:avm_simulator');
+
+  constructor(private context: AvmContext) {}
+
+  /**
+   * Fetch the bytecode and execute it in the current context.
+   */
+  public async execute(): Promise<AvmContractCallResults> {
+    const instructions = await this.fetchAndDecodeBytecode();
+    return this.executeInstructions(instructions);
+  }
+
+  /**
+   * Executes the provided instructions in the current context.
+   * This method is useful for testing and debugging.
+   */
+  public async executeInstructions(instructions: Instruction[]): Promise<AvmContractCallResults> {
+    assert(instructions.length > 0);
+
+    try {
+      // Execute instruction pointed to by the current program counter
+      // continuing until the machine state signifies a halt
+      while (!this.context.machineState.halted) {
+        const instruction = instructions[this.context.machineState.pc];
+        assert(!!instruction); // This should never happen
+
+        this.log(`Executing PC=${this.context.machineState.pc}: ${instruction.toString()}`);
+        // Execute the instruction.
+        // Normal returns and reverts will return normally here.
+        // "Exceptional halts" will throw.
+        await instruction.execute(this.context);
+
+        if (this.context.machineState.pc >= instructions.length) {
+          this.log('Passed end of program!');
+          throw new InvalidProgramCounterError(this.context.machineState.pc, /*max=*/ instructions.length);
+        }
+      }
+
+      // Return results for processing by calling context
+      const results = this.context.machineState.getResults();
+      this.log(`Context execution results: ${results.toString()}`);
+      return results;
+    } catch (e) {
+      this.log('Exceptional halt');
+      if (!(e instanceof AvmExecutionError)) {
+        this.log(`Unknown error thrown by avm: ${e}`);
+        throw e;
+      }
+
+      // Return results for processing by calling context
+      // Note: "exceptional halts" cannot return data
+      const results = new AvmContractCallResults(/*reverted=*/ true, /*output=*/ [], /*revertReason=*/ e);
+      this.log(`Context execution results: ${results.toString()}`);
+      return results;
+    }
+  }
+
+  /**
+   * Fetch contract bytecode from world state and decode into executable instructions.
+   */
+  private async fetchAndDecodeBytecode(): Promise<Instruction[]> {
+    // NOTE: the following is mocked as getPublicBytecode does not exist yet
+
+    const selector = this.context.environment.temporaryFunctionSelector;
+    const bytecode = await this.context.worldState.hostStorage.contractsDb.getBytecode(
+      this.context.environment.address,
+      selector,
+    );
+
+    // This assumes that we will not be able to send messages to accounts without code
+    // Pending classes and instances impl details
+    if (!bytecode) {
+      throw new NoBytecodeForContractError(this.context.environment.address);
+    }
+
+    return decodeFromBytecode(bytecode);
+  }
+}

package/src/avm/errors.ts

@@ -0,0 +1,57 @@
+import { AztecAddress } from '@aztec/circuits.js';
+
+/**
+ * Avm-specific errors should derive from this
+ */
+export abstract class AvmExecutionError extends Error {
+  constructor(message: string, ...rest: any[]) {
+    super(message, ...rest);
+    this.name = 'AvmInterpreterError';
+  }
+}
+
+export class NoBytecodeForContractError extends AvmExecutionError {
+  constructor(contractAddress: AztecAddress) {
+    super(`No bytecode found at: ${contractAddress}`);
+    this.name = 'NoBytecodeFoundInterpreterError';
+  }
+}
+
+/**
+ * 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 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';
+  }
+}