@aztec/simulator 0.23.0 → 0.26.1

package/src/avm/opcodes/hashing.ts

@@ -0,0 +1,170 @@
+import { toBigIntBE } from '@aztec/foundation/bigint-buffer';
+import { keccak, pedersenHash, poseidonHash, sha256 } from '@aztec/foundation/crypto';
+
+import { AvmContext } from '../avm_context.js';
+import { Field } 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.POSEIDON;
+
+  // 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 dstOffset: number,
+    private hashOffset: number,
+    private hashSize: number,
+  ) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    // We hash a set of field elements
+    const [hashOffset] = Addressing.fromWire(this.indirect).resolve([this.hashOffset], context.machineState.memory);
+
+    // Memory pointer will be indirect
+    const hashData = context.machineState.memory.getSlice(hashOffset, this.hashSize).map(word => word.toBuffer());
+
+    const hash = poseidonHash(hashData);
+    context.machineState.memory.set(this.dstOffset, new Field(hash));
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Keccak extends Instruction {
+  static type: string = 'KECCAK';
+  static readonly opcode: Opcode = Opcode.KECCAK;
+
+  // 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 dstOffset: number,
+    private hashOffset: number,
+    private hashSize: number,
+  ) {
+    super();
+  }
+
+  // Note hash output is 32 bytes, so takes up two fields
+  async execute(context: AvmContext): Promise<void> {
+    // We hash a set of field elements
+    const [hashOffset, dstOffset] = Addressing.fromWire(this.indirect).resolve(
+      [this.hashOffset, this.dstOffset],
+      context.machineState.memory,
+    );
+
+    const hashData = context.machineState.memory.getSlice(hashOffset, this.hashSize).map(word => word.toBuffer());
+
+    const hash = keccak(Buffer.concat(hashData));
+
+    // Split output into two fields
+    const high = new Field(toBigIntBE(hash.subarray(0, 16)));
+    const low = new Field(toBigIntBE(hash.subarray(16, 32)));
+
+    context.machineState.memory.set(dstOffset, high);
+    context.machineState.memory.set(dstOffset + 1, low);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Sha256 extends Instruction {
+  static type: string = 'SHA256';
+  static readonly opcode: Opcode = Opcode.SHA256;
+
+  // 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 dstOffset: number,
+    private hashOffset: number,
+    private hashSize: number,
+  ) {
+    super();
+  }
+
+  // Note hash output is 32 bytes, so takes up two fields
+  async execute(context: AvmContext): Promise<void> {
+    const [hashOffset, dstOffset] = Addressing.fromWire(this.indirect).resolve(
+      [this.hashOffset, this.dstOffset],
+      context.machineState.memory,
+    );
+
+    // We hash a set of field elements
+    const hashData = context.machineState.memory.getSlice(hashOffset, this.hashSize).map(word => word.toBuffer());
+
+    const hash = sha256(Buffer.concat(hashData));
+
+    // Split output into two fields
+    const high = new Field(toBigIntBE(hash.subarray(0, 16)));
+    const low = new Field(toBigIntBE(hash.subarray(16, 32)));
+
+    context.machineState.memory.set(dstOffset, high);
+    context.machineState.memory.set(dstOffset + 1, low);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Pedersen extends Instruction {
+  static type: string = 'PEDERSEN';
+  static readonly opcode: Opcode = Opcode.PEDERSEN;
+
+  // 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 dstOffset: number,
+    private hashOffset: number,
+    private hashSize: number,
+  ) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const [hashOffset] = Addressing.fromWire(this.indirect).resolve([this.hashOffset], context.machineState.memory);
+
+    // We hash a set of field elements
+    const hashData = context.machineState.memory.getSlice(hashOffset, this.hashSize).map(word => word.toBuffer());
+
+    // No domain sep for now
+    const hash = pedersenHash(hashData);
+    context.machineState.memory.set(this.dstOffset, new Field(hash));
+
+    context.machineState.incrementPc();
+  }
+}

package/src/avm/opcodes/index.ts

@@ -0,0 +1,10 @@
+export * from './arithmetic.js';
+export * from './bitwise.js';
+export * from './control_flow.js';
+export * from './instruction.js';
+export * from './comparators.js';
+export * from './memory.js';
+export * from './storage.js';
+export * from './external_calls.js';
+export * from './environment_getters.js';
+export * from './accrued_substate.js';

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,194 @@
+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,79 @@
+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.persistableState.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.persistableState.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;
+  }
+}