@aztec/simulator 0.0.0-test.0

package/src/public/avm/opcodes/environment_getters.ts

@@ -0,0 +1,82 @@
+import type { AvmContext } from '../avm_context.js';
+import { Field, Uint64 } from '../avm_memory_types.js';
+import { InstructionExecutionError } from '../errors.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Addressing } from './addressing_mode.js';
+import { Instruction } from './instruction.js';
+
+export enum EnvironmentVariable {
+  ADDRESS,
+  SENDER,
+  TRANSACTIONFEE,
+  CHAINID,
+  VERSION,
+  BLOCKNUMBER,
+  TIMESTAMP,
+  FEEPERL2GAS,
+  FEEPERDAGAS,
+  ISSTATICCALL,
+  L2GASLEFT,
+  DAGASLEFT,
+}
+
+function getValue(e: EnvironmentVariable, ctx: AvmContext) {
+  switch (e) {
+    case EnvironmentVariable.ADDRESS:
+      return new Field(ctx.environment.address.toField());
+    case EnvironmentVariable.SENDER:
+      return new Field(ctx.environment.sender.toField());
+    case EnvironmentVariable.TRANSACTIONFEE:
+      return new Field(ctx.environment.transactionFee);
+    case EnvironmentVariable.CHAINID:
+      return new Field(ctx.environment.globals.chainId);
+    case EnvironmentVariable.VERSION:
+      return new Field(ctx.environment.globals.version);
+    case EnvironmentVariable.BLOCKNUMBER:
+      return new Field(ctx.environment.globals.blockNumber);
+    case EnvironmentVariable.TIMESTAMP:
+      return new Uint64(ctx.environment.globals.timestamp.toBigInt());
+    case EnvironmentVariable.FEEPERL2GAS:
+      return new Field(ctx.environment.globals.gasFees.feePerL2Gas);
+    case EnvironmentVariable.FEEPERDAGAS:
+      return new Field(ctx.environment.globals.gasFees.feePerDaGas);
+    case EnvironmentVariable.ISSTATICCALL:
+      return new Field(ctx.environment.isStaticCall ? 1 : 0);
+    case EnvironmentVariable.L2GASLEFT:
+      return new Field(ctx.machineState.l2GasLeft);
+    case EnvironmentVariable.DAGASLEFT:
+      return new Field(ctx.machineState.daGasLeft);
+    default:
+      throw new Error(`Unknown environment variable ${e}`);
+  }
+}
+
+export class GetEnvVar extends Instruction {
+  public static readonly type: string = 'GETENVVAR';
+  public static readonly opcode: Opcode = Opcode.GETENVVAR_16;
+  static readonly wireFormat16: OperandType[] = [
+    OperandType.UINT8, // opcode
+    OperandType.UINT8, // indirect
+    OperandType.UINT16, // dstOffset
+    OperandType.UINT8, // variable enum (immediate)
+  ];
+
+  constructor(private indirect: number, private dstOffset: number, private varEnum: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    if (!(this.varEnum in EnvironmentVariable)) {
+      throw new InstructionExecutionError(`Invalid GETENVVAR var enum ${this.varEnum}`);
+    }
+
+    const operands = [this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [dstOffset] = addressing.resolve(operands, memory);
+
+    memory.set(dstOffset, getValue(this.varEnum as EnvironmentVariable, context));
+  }
+}

package/src/public/avm/opcodes/external_calls.ts

@@ -0,0 +1,228 @@
+import type { AvmContext } from '../avm_context.js';
+import type { AvmContractCallResult } from '../avm_contract_call_result.js';
+import { type Field, TypeTag, Uint1 } from '../avm_memory_types.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Addressing } from './addressing_mode.js';
+import { Instruction } from './instruction.js';
+
+abstract class ExternalCall extends Instruction {
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8, // Indirect
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(
+    private indirect: number,
+    private gasOffset: number,
+    private addrOffset: number,
+    private argsOffset: number,
+    private argsSizeOffset: number,
+  ) {
+    super();
+  }
+
+  public async execute(context: AvmContext) {
+    const memory = context.machineState.memory;
+    const operands = [this.gasOffset, this.addrOffset, this.argsOffset, this.argsSizeOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [gasOffset, addrOffset, argsOffset, argsSizeOffset] = addressing.resolve(operands, memory);
+    memory.checkTags(TypeTag.FIELD, gasOffset, gasOffset + 1);
+    memory.checkTag(TypeTag.FIELD, addrOffset);
+    memory.checkTag(TypeTag.UINT32, argsSizeOffset);
+
+    const calldataSize = memory.get(argsSizeOffset).toNumber();
+    const calldata = memory.getSlice(argsOffset, calldataSize).map(f => f.toFr());
+    memory.checkTagsRange(TypeTag.FIELD, argsOffset, calldataSize);
+
+    const callAddress = memory.getAs<Field>(addrOffset);
+    // If we are already in a static call, we propagate the environment.
+    const callType = context.environment.isStaticCall ? 'STATICCALL' : this.type;
+
+    // First we consume the gas for this operation.
+    context.machineState.consumeGas(this.gasCost(calldataSize));
+    // Then we consume the gas allocated for the nested call. The excess will be refunded later.
+    // Gas allocation is capped by the amount of gas left in the current context.
+    // We have to do some dancing here because the gas allocation is a field,
+    // but in the machine state we track gas as a number.
+    const allocatedL2Gas = Number(BigIntMin(memory.get(gasOffset).toBigInt(), BigInt(context.machineState.l2GasLeft)));
+    const allocatedDaGas = Number(
+      BigIntMin(memory.get(gasOffset + 1).toBigInt(), BigInt(context.machineState.daGasLeft)),
+    );
+    const allocatedGas = { l2Gas: allocatedL2Gas, daGas: allocatedDaGas };
+    context.machineState.consumeGas(allocatedGas);
+
+    const aztecAddress = callAddress.toAztecAddress();
+    const nestedContext = await context.createNestedContractCallContext(aztecAddress, calldata, allocatedGas, callType);
+
+    const simulator = await context.provideSimulator!(nestedContext);
+    const nestedCallResults: AvmContractCallResult = await simulator.execute();
+    const success = !nestedCallResults.reverted;
+
+    // Save return/revert data for later.
+    const fullReturnData = nestedCallResults.output;
+    context.machineState.nestedReturndata = fullReturnData;
+
+    // Track the success status directly
+    context.machineState.nestedCallSuccess = success;
+
+    // If the nested call reverted, we try to save the reason and the revert data.
+    // This will be used by the caller to try to reconstruct the call stack.
+    // This is only a heuristic and may not always work. It is intended to work
+    // for the case where a nested call reverts and the caller always rethrows
+    // (in Noir code).
+    if (!success) {
+      context.machineState.collectedRevertInfo = {
+        revertDataRepresentative: fullReturnData,
+        recursiveRevertReason: nestedCallResults.revertReason!,
+      };
+    }
+
+    // Refund unused gas
+    context.machineState.refundGas(nestedCallResults.gasLeft);
+
+    // Merge nested call's state and trace based on whether it succeeded.
+    if (success) {
+      await context.persistableState.merge(nestedContext.persistableState);
+    } else {
+      await context.persistableState.reject(nestedContext.persistableState);
+    }
+  }
+
+  public abstract override get type(): 'CALL' | 'STATICCALL';
+}
+
+export class Call extends ExternalCall {
+  static type = 'CALL' as const;
+  static readonly opcode: Opcode = Opcode.CALL;
+
+  public get type() {
+    return Call.type;
+  }
+}
+
+export class StaticCall extends ExternalCall {
+  static type = 'STATICCALL' as const;
+  static readonly opcode: Opcode = Opcode.STATICCALL;
+
+  public get type() {
+    return StaticCall.type;
+  }
+}
+
+export class SuccessCopy extends Instruction {
+  static type: string = 'SUCCESSCOPY';
+  static readonly opcode: Opcode = Opcode.SUCCESSCOPY;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8, // Indirect (8-bit)
+    OperandType.UINT16, // dstOffset (16-bit)
+  ];
+
+  constructor(private indirect: number, private dstOffset: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+
+    const operands = [this.dstOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [dstOffset] = addressing.resolve(operands, memory);
+
+    // Use the direct success tracking property
+    const success = context.machineState.nestedCallSuccess;
+
+    // Write the success flag to the provided memory location
+    memory.set(dstOffset, new Uint1(success ? 1 : 0));
+  }
+}
+
+export class Return extends Instruction {
+  static type: string = 'RETURN';
+  static readonly opcode: Opcode = Opcode.RETURN;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(private indirect: number, private returnOffset: number, private returnSizeOffset: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+
+    const operands = [this.returnOffset, this.returnSizeOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [returnOffset, returnSizeOffset] = addressing.resolve(operands, memory);
+
+    memory.checkTag(TypeTag.UINT32, returnSizeOffset);
+    const returnSize = memory.get(returnSizeOffset).toNumber();
+    context.machineState.consumeGas(this.gasCost(returnSize));
+
+    const output = memory.getSlice(returnOffset, returnSize).map(word => word.toFr());
+
+    context.machineState.return(output);
+  }
+
+  public override handlesPC(): boolean {
+    return true;
+  }
+}
+
+export class Revert extends Instruction {
+  static type: string = 'REVERT';
+  static readonly opcode: Opcode = Opcode.REVERT_8;
+
+  static readonly wireFormat8: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+  ];
+  static readonly wireFormat16: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(private indirect: number, private returnOffset: number, private retSizeOffset: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+
+    const operands = [this.returnOffset, this.retSizeOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [returnOffset, retSizeOffset] = addressing.resolve(operands, memory);
+
+    memory.checkTag(TypeTag.UINT32, retSizeOffset);
+    const retSize = memory.get(retSizeOffset).toNumber();
+    context.machineState.consumeGas(this.gasCost(retSize));
+    const output = memory.getSlice(returnOffset, retSize).map(word => word.toFr());
+
+    context.machineState.revert(output);
+  }
+
+  // We don't want to increase the PC after reverting because it breaks messages.
+  // Maybe we can remove this once messages don't depend on PCs.
+  public override handlesPC(): boolean {
+    return true;
+  }
+}
+
+/** Returns the smaller of two bigints. */
+function BigIntMin(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}

package/src/public/avm/opcodes/hashing.ts

@@ -0,0 +1,125 @@
+import { keccakf1600, poseidon2Permutation, sha256Compression } from '@aztec/foundation/crypto';
+
+import type { AvmContext } from '../avm_context.js';
+import { Field, TypeTag, Uint32, Uint64 } from '../avm_memory_types.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Addressing } from './addressing_mode.js';
+import { Instruction } from './instruction.js';
+
+export class Poseidon2 extends Instruction {
+  static type: string = 'POSEIDON2';
+  static readonly opcode: Opcode = Opcode.POSEIDON2;
+  static readonly stateSize = 4;
+
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(private indirect: number, private inputStateOffset: number, private outputStateOffset: number) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const memory = context.machineState.memory;
+    context.machineState.consumeGas(this.gasCost());
+
+    const operands = [this.inputStateOffset, this.outputStateOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [inputOffset, outputOffset] = addressing.resolve(operands, memory);
+
+    const inputState = memory.getSlice(inputOffset, Poseidon2.stateSize);
+    memory.checkTagsRange(TypeTag.FIELD, inputOffset, Poseidon2.stateSize);
+
+    const outputState = await poseidon2Permutation(inputState);
+    memory.setSlice(
+      outputOffset,
+      outputState.map(word => new Field(word)),
+    );
+  }
+}
+
+export class KeccakF1600 extends Instruction {
+  static type: string = 'KECCAKF1600';
+  static readonly opcode: Opcode = Opcode.KECCAKF1600;
+
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(private indirect: number, private dstOffset: number, private inputOffset: number) {
+    super();
+  }
+
+  // pub fn keccakf1600(input: [u64; 25]) -> [u64; 25]
+  public async execute(context: AvmContext): Promise<void> {
+    const inputSize = 25;
+    const memory = context.machineState.memory;
+    const operands = [this.dstOffset, this.inputOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [dstOffset, inputOffset] = addressing.resolve(operands, memory);
+    context.machineState.consumeGas(this.gasCost());
+
+    const stateData = memory.getSlice(inputOffset, inputSize).map(word => word.toBigInt());
+    memory.checkTagsRange(TypeTag.UINT64, inputOffset, inputSize);
+
+    const updatedState = keccakf1600(stateData);
+
+    const res = updatedState.map(word => new Uint64(word));
+    memory.setSlice(dstOffset, res);
+  }
+}
+
+export class Sha256Compression extends Instruction {
+  static type: string = 'SHA256COMPRESSION';
+  static readonly opcode: Opcode = Opcode.SHA256COMPRESSION;
+
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT16,
+    OperandType.UINT16,
+    OperandType.UINT16,
+  ];
+
+  constructor(
+    private indirect: number,
+    private outputOffset: number,
+    private stateOffset: number,
+    private inputsOffset: number,
+  ) {
+    super();
+  }
+
+  public async execute(context: AvmContext): Promise<void> {
+    const STATE_SIZE = 8;
+    const INPUTS_SIZE = 16;
+
+    const memory = context.machineState.memory;
+    const operands = [this.outputOffset, this.stateOffset, this.inputsOffset];
+    const addressing = Addressing.fromWire(this.indirect, operands.length);
+    const [outputOffset, stateOffset, inputsOffset] = addressing.resolve(operands, memory);
+
+    // Note: size of output is same as size of state
+    context.machineState.consumeGas(this.gasCost());
+    const inputs = Uint32Array.from(memory.getSlice(inputsOffset, INPUTS_SIZE).map(word => word.toNumber()));
+    const state = Uint32Array.from(memory.getSlice(stateOffset, STATE_SIZE).map(word => word.toNumber()));
+
+    memory.checkTagsRange(TypeTag.UINT32, inputsOffset, INPUTS_SIZE);
+    memory.checkTagsRange(TypeTag.UINT32, stateOffset, STATE_SIZE);
+
+    const output = sha256Compression(state, inputs);
+
+    // Conversion required from Uint32Array to Uint32[] (can't map directly, need `...`)
+    const res = [...output].map(word => new Uint32(word));
+    memory.setSlice(outputOffset, res);
+  }
+}

package/src/public/avm/opcodes/index.ts

@@ -0,0 +1,15 @@
+export * from './arithmetic.js';
+export * from './bitwise.js';
+export * from './control_flow.js';
+export * from './contract.js';
+export * from './conversion.js';
+export * from './instruction.js';
+export * from './comparators.js';
+export * from './memory.js';
+export * from './misc.js';
+export * from './storage.js';
+export * from './external_calls.js';
+export * from './environment_getters.js';
+export * from './accrued_substate.js';
+export * from './hashing.js';
+export * from './ec_add.js';

package/src/public/avm/opcodes/instruction.ts

@@ -0,0 +1,126 @@
+import { strict as assert } from 'assert';
+
+import type { AvmContext } from '../avm_context.js';
+import { type Gas, getBaseGasCost, getDynamicGasCost, mulGas, sumGas } from '../avm_gas.js';
+import type { BufferCursor } from '../serialization/buffer_cursor.js';
+import type { Serializable } from '../serialization/bytecode_serialization.js';
+import { Opcode, type OperandType, deserialize, serializeAs } from '../serialization/instruction_serialization.js';
+
+type InstructionConstructor = {
+  new (...args: any[]): Instruction;
+};
+
+/**
+ * Parent class for all AVM instructions.
+ * It's most important aspects are execute and (de)serialize.
+ */
+export abstract class Instruction {
+  /**
+   * Consumes gas and executes the instruction.
+   * This is the main entry point for the instruction.
+   * @param context - The AvmContext in which the instruction executes.
+   */
+  public abstract execute(context: AvmContext): Promise<void>;
+
+  /**
+   * Whether the instruction will modify the PC itself.
+   */
+  public handlesPC(): boolean {
+    return false;
+  }
+
+  /**
+   * Generate a string representation of the instruction including
+   * the instruction sub-class name all of its flags and operands.
+   * @returns Thee string representation.
+   */
+  public toString(): string {
+    let instructionStr = this.constructor.name + ': ';
+    // assumes that all properties are flags or operands
+    for (const prop of Object.getOwnPropertyNames(this) as (keyof Instruction)[]) {
+      instructionStr += `${prop}:${this[prop].toString()}, `;
+    }
+    return instructionStr;
+  }
+
+  // Default deserialization which uses Class.opcode and Class.wireFormat.
+  public static deserialize(
+    this: InstructionConstructor & { wireFormat: OperandType[]; as: any },
+    buf: BufferCursor | Buffer,
+  ): Instruction {
+    return this.as(this.wireFormat).deserialize(buf);
+  }
+
+  // Default serialization which uses Class.opcode and Class.wireFormat.
+  public serialize(): Buffer {
+    const klass = this.constructor as any;
+    assert(klass.opcode !== undefined && klass.opcode !== null);
+    assert(klass.wireFormat !== undefined && klass.wireFormat !== null);
+    return this.as(klass.opcode, klass.wireFormat).serialize();
+  }
+
+  /**
+   * Returns a new instruction instance that can be serialized with the given opcode and wire format.
+   * @param opcode The opcode of the instruction.
+   * @param wireFormat The wire format of the instruction.
+   * @returns The new instruction instance.
+   */
+  public as(opcode: Opcode, wireFormat: OperandType[]): Instruction & Serializable {
+    return Object.defineProperty(this, 'serialize', {
+      value: (): Buffer => {
+        return serializeAs(wireFormat, opcode, this);
+      },
+      enumerable: false,
+    });
+  }
+
+  /**
+   * Returns a new instruction class that can be deserialized with the given opcode and wire format.
+   * @param opcode The opcode of the instruction.
+   * @param wireFormat The wire format of the instruction.
+   * @returns The new instruction class.
+   */
+  public static as(this: InstructionConstructor, wireFormat: OperandType[]) {
+    return Object.assign(this, {
+      deserialize: (buf: BufferCursor | Buffer): Instruction => {
+        const res = deserialize(buf, wireFormat);
+        const args = res.slice(1); // Remove opcode.
+        return new this(...args);
+      },
+    });
+  }
+
+  /**
+   * Computes gas cost for the instruction based on its base cost and memory operations.
+   * @returns Gas cost.
+   */
+  protected gasCost(dynMultiplier: number = 0): Gas {
+    const baseGasCost = getBaseGasCost(this.opcode);
+    const dynGasCost = mulGas(getDynamicGasCost(this.opcode), dynMultiplier);
+    return sumGas(baseGasCost, dynGasCost);
+  }
+
+  /**
+   * Returns the stringified type of the instruction.
+   * Instruction sub-classes should have a static `type` property.
+   */
+  public get type(): string {
+    const type = 'type' in this.constructor && (this.constructor.type as string);
+    if (!type) {
+      throw new Error(`Instruction class ${this.constructor.name} does not have a static 'type' property defined.`);
+    }
+    return type;
+  }
+
+  /**
+   * Returns the opcode of the instruction.
+   * Instruction sub-classes should have a static `opcode` property.
+   */
+  public get opcode(): Opcode {
+    const opcode = 'opcode' in this.constructor ? (this.constructor.opcode as Opcode) : undefined;
+    if (opcode === undefined || Opcode[opcode] === undefined) {
+      throw new Error(`Instruction class ${this.constructor.name} does not have a static 'opcode' property defined.`);
+    }
+    return opcode;
+  }
+}

package/src/public/avm/opcodes/instruction_impl.ts

@@ -0,0 +1,36 @@
+import { OperandType } from '../serialization/instruction_serialization.js';
+import { Instruction } from './instruction.js';
+
+/** Wire format that informs deserialization for instructions with three operands. */
+export const ThreeOperandWireFormat8 = [
+  OperandType.UINT8,
+  OperandType.UINT8,
+  OperandType.UINT8,
+  OperandType.UINT8,
+  OperandType.UINT8,
+];
+export const ThreeOperandWireFormat16 = [
+  OperandType.UINT8,
+  OperandType.UINT8,
+  OperandType.UINT16,
+  OperandType.UINT16,
+  OperandType.UINT16,
+];
+
+/**
+ * Covers (de)serialization for an instruction with:
+ * indirect, inTag, and three operands.
+ */
+export abstract class ThreeOperandInstruction extends Instruction {
+  static readonly wireFormat8: OperandType[] = ThreeOperandWireFormat8;
+  static readonly wireFormat16: OperandType[] = ThreeOperandWireFormat16;
+
+  constructor(
+    protected indirect: number,
+    protected aOffset: number,
+    protected bOffset: number,
+    protected dstOffset: number,
+  ) {
+    super();
+  }
+}