@aztec/simulator 0.23.0 → 0.24.0

package/src/avm/opcodes/instruction.ts

@@ -0,0 +1,64 @@
+import { strict as assert } from 'assert';
+
+import type { AvmContext } from '../avm_context.js';
+import { BufferCursor } from '../serialization/buffer_cursor.js';
+import { OperandType, deserialize, serialize } from '../serialization/instruction_serialization.js';
+
+type InstructionConstructor = {
+  new (...args: any[]): Instruction;
+  wireFormat?: OperandType[];
+};
+
+/**
+ * Parent class for all AVM instructions.
+ * It's most important aspects are execute and (de)serialize.
+ */
+export abstract class Instruction {
+  /**
+   * Execute the instruction.
+   * Instruction sub-classes must implement this.
+   * As an AvmContext executes its contract code, it calls this function for
+   * each instruction until the machine state signals "halted".
+   * @param context - The AvmContext in which the instruction executes.
+   */
+  public abstract execute(context: AvmContext): Promise<void>;
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Serialize the instruction to a Buffer according to its wire format specified in its subclass.
+   * If you want to use this, your subclass should specify a {@code static wireFormat: OperandType[]}.
+   * @param this - The instruction to serialize.
+   * @returns The serialized instruction.
+   */
+  public serialize(this: any): Buffer {
+    assert(!!this.constructor.wireFormat, 'wireFormat must be defined on the class');
+    return serialize(this.constructor.wireFormat, this);
+  }
+
+  /**
+   * Deserializes a subclass of Instruction from a Buffer.
+   * If you want to use this, your subclass should specify a {@code static wireFormat: OperandType[]}.
+   * @param this Class object to deserialize to.
+   * @param buf Buffer to read from.
+   * @returns Constructed instance of Class.
+   */
+  public static deserialize(this: InstructionConstructor, buf: BufferCursor | Buffer): Instruction {
+    assert(!!this.wireFormat, 'wireFormat must be defined on the instruction class');
+    const res = deserialize(buf, this.wireFormat);
+    const args = res.slice(1); // Remove opcode.
+    return new this(...args);
+  }
+}

package/src/avm/opcodes/instruction_impl.ts

@@ -0,0 +1,52 @@
+import { OperandType } from '../serialization/instruction_serialization.js';
+import { Instruction } from './instruction.js';
+
+/**
+ * Covers (de)serialization for an instruction with:
+ * indirect, inTag, and two UINT32s.
+ */
+export abstract class TwoOperandInstruction extends Instruction {
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT32,
+    OperandType.UINT32,
+  ];
+
+  constructor(
+    protected indirect: number,
+    protected inTag: number,
+    protected aOffset: number,
+    protected dstOffset: number,
+  ) {
+    super();
+  }
+}
+
+/**
+ * Covers (de)serialization for an instruction with:
+ * indirect, inTag, and three UINT32s.
+ */
+export abstract class ThreeOperandInstruction extends Instruction {
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT32,
+    OperandType.UINT32,
+    OperandType.UINT32,
+  ];
+
+  constructor(
+    protected indirect: number,
+    protected inTag: number,
+    protected aOffset: number,
+    protected bOffset: number,
+    protected dstOffset: number,
+  ) {
+    super();
+  }
+}

package/src/avm/opcodes/memory.ts

@@ -0,0 +1,193 @@
+import type { AvmContext } from '../avm_context.js';
+import { Field, TaggedMemory, TypeTag } from '../avm_memory_types.js';
+import { InstructionExecutionError } from '../errors.js';
+import { BufferCursor } from '../serialization/buffer_cursor.js';
+import { Opcode, OperandType, deserialize, serialize } from '../serialization/instruction_serialization.js';
+import { Addressing } from './addressing_mode.js';
+import { Instruction } from './instruction.js';
+import { TwoOperandInstruction } from './instruction_impl.js';
+
+const TAG_TO_OPERAND_TYPE = new Map<TypeTag, OperandType>([
+  [TypeTag.UINT8, OperandType.UINT8],
+  [TypeTag.UINT16, OperandType.UINT16],
+  [TypeTag.UINT32, OperandType.UINT32],
+  [TypeTag.UINT64, OperandType.UINT64],
+  [TypeTag.UINT128, OperandType.UINT128],
+]);
+
+function getOperandTypeFromInTag(inTag: number | bigint): OperandType {
+  inTag = inTag as number;
+  const tagOperandType = TAG_TO_OPERAND_TYPE.get(inTag);
+  if (tagOperandType === undefined) {
+    throw new Error(`Invalid tag ${inTag} for SET.`);
+  }
+  return tagOperandType;
+}
+
+export class Set extends Instruction {
+  static readonly type: string = 'SET';
+  static readonly opcode: Opcode = Opcode.SET;
+
+  private static readonly wireFormatBeforeConst: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT8,
+  ];
+  private static readonly wireFormatAfterConst: OperandType[] = [OperandType.UINT32];
+
+  constructor(
+    private indirect: number,
+    private inTag: number,
+    private value: bigint | number,
+    private dstOffset: number,
+  ) {
+    super();
+  }
+
+  /** We need to use a custom serialize function because of the variable length of the value. */
+  public serialize(): Buffer {
+    const format: OperandType[] = [
+      ...Set.wireFormatBeforeConst,
+      getOperandTypeFromInTag(this.inTag),
+      ...Set.wireFormatAfterConst,
+    ];
+    return serialize(format, this);
+  }
+
+  /** We need to use a custom deserialize function because of the variable length of the value. */
+  public static deserialize(this: typeof Set, buf: BufferCursor | Buffer): Set {
+    if (buf instanceof Buffer) {
+      buf = new BufferCursor(buf);
+    }
+    const beforeConst = deserialize(buf, Set.wireFormatBeforeConst);
+    const tag = beforeConst[beforeConst.length - 1];
+    const val = deserialize(buf, [getOperandTypeFromInTag(tag)]);
+    const afterConst = deserialize(buf, Set.wireFormatAfterConst);
+    const res = [...beforeConst, ...val, ...afterConst];
+    const args = res.slice(1) as ConstructorParameters<typeof Set>; // Remove opcode.
+    return new this(...args);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    // Per the YP, the tag cannot be a field.
+    if ([TypeTag.FIELD, TypeTag.UNINITIALIZED, TypeTag.INVALID].includes(this.inTag)) {
+      throw new InstructionExecutionError(`Invalid tag ${TypeTag[this.inTag]} for SET.`);
+    }
+
+    const res = TaggedMemory.integralFromTag(this.value, this.inTag);
+    context.machineState.memory.set(this.dstOffset, res);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class CMov extends Instruction {
+  static readonly type: string = 'CMOV';
+  static readonly opcode: Opcode = Opcode.CMOV;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT32,
+    OperandType.UINT32,
+    OperandType.UINT32,
+    OperandType.UINT32,
+  ];
+
+  constructor(
+    private indirect: number,
+    private aOffset: number,
+    private bOffset: number,
+    private condOffset: number,
+    private dstOffset: number,
+  ) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const a = context.machineState.memory.get(this.aOffset);
+    const b = context.machineState.memory.get(this.bOffset);
+    const cond = context.machineState.memory.get(this.condOffset);
+
+    // TODO: reconsider toBigInt() here
+    context.machineState.memory.set(this.dstOffset, cond.toBigInt() > 0 ? a : b);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Cast extends TwoOperandInstruction {
+  static readonly type: string = 'CAST';
+  static readonly opcode = Opcode.CAST;
+
+  constructor(indirect: number, dstTag: number, aOffset: number, dstOffset: number) {
+    super(indirect, dstTag, aOffset, dstOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const a = context.machineState.memory.get(this.aOffset);
+
+    // TODO: consider not using toBigInt()
+    const casted =
+      this.inTag == TypeTag.FIELD ? new Field(a.toBigInt()) : TaggedMemory.integralFromTag(a.toBigInt(), this.inTag);
+
+    context.machineState.memory.set(this.dstOffset, casted);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Mov extends Instruction {
+  static readonly type: string = 'MOV';
+  static readonly opcode: Opcode = Opcode.MOV;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT32,
+    OperandType.UINT32,
+  ];
+
+  constructor(private indirect: number, private srcOffset: number, private dstOffset: number) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const [srcOffset, dstOffset] = Addressing.fromWire(this.indirect).resolve(
+      [this.srcOffset, this.dstOffset],
+      context.machineState.memory,
+    );
+
+    const a = context.machineState.memory.get(srcOffset);
+
+    context.machineState.memory.set(dstOffset, a);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class CalldataCopy extends Instruction {
+  static readonly type: string = 'CALLDATACOPY';
+  static readonly opcode: Opcode = Opcode.CALLDATACOPY;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT32,
+    OperandType.UINT32,
+    OperandType.UINT32,
+  ];
+
+  constructor(private indirect: number, private cdOffset: number, private copySize: number, private dstOffset: number) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const transformedData = context.environment.calldata
+      .slice(this.cdOffset, this.cdOffset + this.copySize)
+      .map(f => new Field(f));
+    context.machineState.memory.setSlice(this.dstOffset, transformedData);
+
+    context.machineState.incrementPc();
+  }
+}

package/src/avm/opcodes/storage.ts

@@ -0,0 +1,76 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import type { AvmContext } from '../avm_context.js';
+import { Field } from '../avm_memory_types.js';
+import { InstructionExecutionError } from '../errors.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Instruction } from './instruction.js';
+
+abstract class BaseStorageInstruction extends Instruction {
+  // Informs (de)serialization. See Instruction.deserialize.
+  public static readonly wireFormat: OperandType[] = [
+    OperandType.UINT8,
+    OperandType.UINT8,
+    OperandType.UINT32,
+    OperandType.UINT32,
+  ];
+
+  constructor(protected indirect: number, protected aOffset: number, protected bOffset: number) {
+    super();
+  }
+}
+
+export class SStore extends BaseStorageInstruction {
+  static readonly type: string = 'SSTORE';
+  static readonly opcode = Opcode.SSTORE;
+
+  constructor(indirect: number, srcOffset: number, slotOffset: number) {
+    super(indirect, srcOffset, slotOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    if (context.environment.isStaticCall) {
+      throw new StaticCallStorageAlterError();
+    }
+
+    const slot = context.machineState.memory.get(this.aOffset);
+    const data = context.machineState.memory.get(this.bOffset);
+
+    context.worldState.writeStorage(
+      context.environment.storageAddress,
+      new Fr(slot.toBigInt()),
+      new Fr(data.toBigInt()),
+    );
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class SLoad extends BaseStorageInstruction {
+  static readonly type: string = 'SLOAD';
+  static readonly opcode = Opcode.SLOAD;
+
+  constructor(indirect: number, slotOffset: number, dstOffset: number) {
+    super(indirect, slotOffset, dstOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const slot = context.machineState.memory.get(this.aOffset);
+
+    const data: Fr = await context.worldState.readStorage(context.environment.storageAddress, new Fr(slot.toBigInt()));
+
+    context.machineState.memory.set(this.bOffset, new Field(data));
+
+    context.machineState.incrementPc();
+  }
+}
+
+/**
+ * Error is thrown when a static call attempts to alter storage
+ */
+export class StaticCallStorageAlterError extends InstructionExecutionError {
+  constructor() {
+    super('Static calls cannot alter storage');
+    this.name = 'StaticCallStorageAlterError';
+  }
+}

package/src/avm/serialization/buffer_cursor.ts

@@ -0,0 +1,109 @@
+import { strict as assert } from 'assert';
+
+/*
+ * A Buffer-like class that automatically advances the position.
+ */
+export class BufferCursor {
+  constructor(private _buffer: Buffer, private _position: number = 0) {}
+
+  public position(): number {
+    return this._position;
+  }
+
+  public eof(): boolean {
+    return this._position === this._buffer.length;
+  }
+
+  public bufferAtPosition(): Buffer {
+    return this._buffer.subarray(this._position);
+  }
+
+  public advance(n: number): void {
+    this._position += n;
+    assert(n < this._buffer.length);
+  }
+
+  public readUint8(): number {
+    const ret = this._buffer.readUint8(this._position);
+    this._position += 1;
+    return ret;
+  }
+
+  public readUint16LE(): number {
+    const ret = this._buffer.readUint16LE(this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public readUint16BE(): number {
+    const ret = this._buffer.readUint16BE(this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public readUint32LE(): number {
+    const ret = this._buffer.readUint32LE(this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public readUint32BE(): number {
+    const ret = this._buffer.readUint32BE(this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public readBigInt64LE(): bigint {
+    const ret = this._buffer.readBigInt64LE(this._position);
+    this._position += 8;
+    return ret;
+  }
+
+  public readBigInt64BE(): bigint {
+    const ret = this._buffer.readBigInt64BE(this._position);
+    this._position += 8;
+    return ret;
+  }
+
+  public writeUint8(v: number) {
+    const ret = this._buffer.writeUint8(v, this._position);
+    this._position += 1;
+    return ret;
+  }
+
+  public writeUint16LE(v: number) {
+    const ret = this._buffer.writeUint16LE(v, this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public writeUint16BE(v: number) {
+    const ret = this._buffer.writeUint16BE(v, this._position);
+    this._position += 2;
+    return ret;
+  }
+
+  public writeUint32LE(v: number) {
+    const ret = this._buffer.writeUint32LE(v, this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public writeUint32BE(v: number) {
+    const ret = this._buffer.writeUint32BE(v, this._position);
+    this._position += 4;
+    return ret;
+  }
+
+  public writeBigInt64LE(v: bigint) {
+    const ret = this._buffer.writeBigInt64LE(v, this._position);
+    this._position += 8;
+    return ret;
+  }
+
+  public writeBigInt64BE(v: bigint) {
+    const ret = this._buffer.writeBigInt64BE(v, this._position);
+    this._position += 8;
+    return ret;
+  }
+}

package/src/avm/serialization/bytecode_serialization.ts

@@ -0,0 +1,172 @@
+import {
+  Add,
+  Address,
+  And,
+  BlockNumber,
+  CMov,
+  Call,
+  CalldataCopy,
+  Cast,
+  ChainId,
+  Div,
+  EmitNoteHash,
+  EmitNullifier,
+  EmitUnencryptedLog,
+  Eq,
+  FeePerDAGas,
+  FeePerL1Gas,
+  FeePerL2Gas,
+  InternalCall,
+  InternalReturn,
+  Jump,
+  JumpI,
+  Lt,
+  Lte,
+  Mov,
+  Mul,
+  Not,
+  Or,
+  Origin,
+  Portal,
+  Return,
+  Revert,
+  SLoad,
+  SStore,
+  SendL2ToL1Message,
+  Sender,
+  Set,
+  Shl,
+  Shr,
+  StaticCall,
+  StorageAddress,
+  Sub,
+  Timestamp,
+  Version,
+  Xor,
+} from '../opcodes/index.js';
+import type { Instruction } from '../opcodes/index.js';
+import { BufferCursor } from './buffer_cursor.js';
+import { Opcode } from './instruction_serialization.js';
+
+interface DeserializableInstruction {
+  deserialize(buf: BufferCursor | Buffer): Instruction;
+  opcode: Opcode;
+}
+
+export type InstructionSet = Map<Opcode, DeserializableInstruction>;
+// TODO(4359): This is a function so that Call and StaticCall can be lazily resolved.
+// This is a temporary solution until we solve the dependency cycle.
+const INSTRUCTION_SET = () =>
+  new Map<Opcode, DeserializableInstruction>([
+    [Add.opcode, Add],
+    [Sub.opcode, Sub],
+    [Mul.opcode, Mul],
+    [Div.opcode, Div],
+    [Eq.opcode, Eq],
+    [Lt.opcode, Lt],
+    [Lte.opcode, Lte],
+    [And.opcode, And],
+    [Or.opcode, Or],
+    [Xor.opcode, Xor],
+    [Not.opcode, Not],
+    [Shl.opcode, Shl],
+    [Shr.opcode, Shr],
+    [Cast.opcode, Cast],
+    [Address.opcode, Address],
+    [StorageAddress.opcode, StorageAddress],
+    [Origin.opcode, Origin],
+    [Sender.opcode, Sender],
+    [Portal.opcode, Portal],
+    [FeePerL1Gas.opcode, FeePerL1Gas],
+    [FeePerL2Gas.opcode, FeePerL2Gas],
+    [FeePerDAGas.opcode, FeePerDAGas],
+    //[Contractcalldepth.opcode, Contractcalldepth],
+    // Execution Environment - Globals
+    [ChainId.opcode, ChainId],
+    [Version.opcode, Version],
+    [BlockNumber.opcode, BlockNumber],
+    [Timestamp.opcode, Timestamp],
+    //[Coinbase.opcode, Coinbase],
+    //[Blockl1gaslimit.opcode, Blockl1gaslimit],
+    //[Blockl2gaslimit.opcode, Blockl2gaslimit],
+    //[Blockdagaslimit.opcode, Blockdagaslimit],
+    // Execution Environment - Calldata
+    [CalldataCopy.opcode, CalldataCopy],
+
+    // Machine State
+    // Machine State - Gas
+    //[L1gasleft.opcode, L1gasleft],
+    //[L2gasleft.opcode, L2gasleft],
+    //[Dagasleft.opcode, Dagasleft],
+    // Machine State - Internal Control Flow
+    [Jump.opcode, Jump],
+    [JumpI.opcode, JumpI],
+    [InternalCall.opcode, InternalCall],
+    [InternalReturn.opcode, InternalReturn],
+    [Set.opcode, Set],
+    [Mov.opcode, Mov],
+    [CMov.opcode, CMov],
+
+    // World State
+    [SLoad.opcode, SLoad], // Public Storage
+    [SStore.opcode, SStore], // Public Storage
+    //[NoteHashExists.opcode, NoteHashExists], // Notes & Nullifiers
+    [EmitNoteHash.opcode, EmitNoteHash], // Notes & Nullifiers
+    //[NullifierExists.opcode, NullifierExists], // Notes & Nullifiers
+    [EmitNullifier.opcode, EmitNullifier], // Notes & Nullifiers
+    //[Readl1tol2msg.opcode, Readl1tol2msg], // Messages
+    //[HeaderMember.opcode, HeaderMember], // Header
+
+    // Accrued Substate
+    [EmitUnencryptedLog.opcode, EmitUnencryptedLog],
+    [SendL2ToL1Message.opcode, SendL2ToL1Message],
+
+    // Control Flow - Contract Calls
+    [Call.opcode, Call],
+    [StaticCall.opcode, StaticCall],
+    [Return.opcode, Return],
+    [Revert.opcode, Revert],
+
+    // Gadgets
+    //[Keccak.opcode, Keccak],
+    //[Poseidon.opcode, Poseidon],
+  ]);
+
+interface Serializable {
+  serialize(): Buffer;
+}
+
+/**
+ * Serializes an array of instructions to bytecode.
+ */
+export function encodeToBytecode(instructions: Serializable[]): Buffer {
+  return Buffer.concat(instructions.map(i => i.serialize()));
+}
+
+/**
+ * Convert a buffer of bytecode into an array of instructions.
+ * @param bytecode Buffer of bytecode.
+ * @param instructionSet Optional {@code InstructionSet} to be used for deserialization.
+ * @returns Bytecode decoded into an ordered array of Instructions
+ */
+export function decodeFromBytecode(
+  bytecode: Buffer,
+  instructionSet: InstructionSet = INSTRUCTION_SET(),
+): Instruction[] {
+  const instructions: Instruction[] = [];
+  const cursor = new BufferCursor(bytecode);
+
+  while (!cursor.eof()) {
+    const opcode: Opcode = cursor.bufferAtPosition().readUint8(); // peek.
+    const instructionDeserializerOrUndef = instructionSet.get(opcode);
+    if (instructionDeserializerOrUndef === undefined) {
+      throw new Error(`Opcode ${Opcode[opcode]} (0x${opcode.toString(16)}) not implemented`);
+    }
+
+    const instructionDeserializer: DeserializableInstruction = instructionDeserializerOrUndef;
+    const i: Instruction = instructionDeserializer.deserialize(cursor);
+    instructions.push(i);
+  }
+
+  return instructions;
+}