@aztec/simulator 0.23.0 → 0.24.0

package/src/avm/fixtures/index.ts

@@ -0,0 +1,90 @@
+import { GlobalVariables } from '@aztec/circuits.js';
+import { FunctionSelector } from '@aztec/foundation/abi';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+
+import { mock } from 'jest-mock-extended';
+import merge from 'lodash.merge';
+
+import { CommitmentsDB, PublicContractsDB, PublicStateDB } from '../../index.js';
+import { AvmContext } from '../avm_context.js';
+import { AvmExecutionEnvironment } from '../avm_execution_environment.js';
+import { AvmMachineState } from '../avm_machine_state.js';
+import { HostStorage } from '../journal/host_storage.js';
+import { AvmWorldStateJournal } from '../journal/journal.js';
+
+/**
+ * Create a new AVM context with default values.
+ */
+export function initContext(overrides?: {
+  worldState?: AvmWorldStateJournal;
+  env?: AvmExecutionEnvironment;
+  machineState?: AvmMachineState;
+}): AvmContext {
+  return new AvmContext(
+    overrides?.worldState || initMockWorldStateJournal(),
+    overrides?.env || initExecutionEnvironment(),
+    overrides?.machineState || initMachineState(),
+  );
+}
+
+/** Creates an empty world state with mocked storage. */
+export function initMockWorldStateJournal(): AvmWorldStateJournal {
+  const hostStorage = new HostStorage(mock<PublicStateDB>(), mock<PublicContractsDB>(), mock<CommitmentsDB>());
+  return new AvmWorldStateJournal(hostStorage);
+}
+
+/**
+ * Create an empty instance of the Execution Environment where all values are zero, unless overridden in the overrides object
+ */
+export function initExecutionEnvironment(overrides?: Partial<AvmExecutionEnvironment>): AvmExecutionEnvironment {
+  return new AvmExecutionEnvironment(
+    overrides?.address ?? AztecAddress.zero(),
+    overrides?.storageAddress ?? AztecAddress.zero(),
+    overrides?.origin ?? AztecAddress.zero(),
+    overrides?.sender ?? AztecAddress.zero(),
+    overrides?.portal ?? EthAddress.ZERO,
+    overrides?.feePerL1Gas ?? Fr.zero(),
+    overrides?.feePerL2Gas ?? Fr.zero(),
+    overrides?.feePerDaGas ?? Fr.zero(),
+    overrides?.contractCallDepth ?? Fr.zero(),
+    overrides?.globals ?? GlobalVariables.empty(),
+    overrides?.isStaticCall ?? false,
+    overrides?.isDelegateCall ?? false,
+    overrides?.calldata ?? [],
+    overrides?.temporaryFunctionSelector ?? FunctionSelector.empty(),
+  );
+}
+
+/**
+ * Create an empty instance of the Execution Environment where all values are zero, unless overridden in the overrides object
+ */
+export function initGlobalVariables(overrides?: Partial<GlobalVariables>): GlobalVariables {
+  return new GlobalVariables(
+    overrides?.chainId ?? Fr.zero(),
+    overrides?.version ?? Fr.zero(),
+    overrides?.blockNumber ?? Fr.zero(),
+    overrides?.timestamp ?? Fr.zero(),
+    overrides?.coinbase ?? EthAddress.ZERO,
+    overrides?.feeRecipient ?? AztecAddress.zero(),
+  );
+}
+
+/**
+ * Create an empty instance of the Machine State where all values are zero, unless overridden in the overrides object
+ */
+export function initMachineState(overrides?: Partial<AvmMachineState>): AvmMachineState {
+  return AvmMachineState.fromState({
+    l1GasLeft: overrides?.l1GasLeft ?? 0,
+    l2GasLeft: overrides?.l2GasLeft ?? 0,
+    daGasLeft: overrides?.daGasLeft ?? 0,
+  });
+}
+
+/**
+ * Create a new object with all the same properties as the original, except for the ones in the overrides object.
+ */
+export function allSameExcept(original: any, overrides: any): any {
+  return merge({}, original, overrides);
+}

package/src/avm/journal/host_storage.ts

@@ -0,0 +1,20 @@
+import { CommitmentsDB, PublicContractsDB, PublicStateDB } from '../../public/db.js';
+
+/**
+ * Host storage
+ *
+ * A wrapper around the node dbs
+ */
+export class HostStorage {
+  public readonly publicStateDb: PublicStateDB;
+
+  public readonly contractsDb: PublicContractsDB;
+
+  public readonly commitmentsDb: CommitmentsDB;
+
+  constructor(publicStateDb: PublicStateDB, contractsDb: PublicContractsDB, commitmentsDb: CommitmentsDB) {
+    this.publicStateDb = publicStateDb;
+    this.contractsDb = contractsDb;
+    this.commitmentsDb = commitmentsDb;
+  }
+}

package/src/avm/journal/index.ts

@@ -0,0 +1,2 @@
+export * from './host_storage.js';
+export * from './journal.js';

package/src/avm/journal/journal.ts

@@ -0,0 +1,266 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import { HostStorage } from './host_storage.js';
+
+/**
+ * Data held within the journal
+ */
+export type JournalData = {
+  newNoteHashes: Fr[];
+  newNullifiers: Fr[];
+  newL1Messages: Fr[][];
+  newLogs: Fr[][];
+
+  /** contract address -\> key -\> value */
+  currentStorageValue: Map<bigint, Map<bigint, Fr>>;
+
+  /** contract address -\> key -\> value[] (stored in order of access) */
+  storageWrites: Map<bigint, Map<bigint, Fr[]>>;
+  /** contract address -\> key -\> value[] (stored in order of access) */
+  storageReads: Map<bigint, Map<bigint, Fr[]>>;
+};
+
+/**
+ * A cache of the current state of the AVM
+ * The interpreter should make any state queries through this object
+ *
+ * When a nested context succeeds, it's journal is merge into the parent
+ * When a call fails, it's journal is discarded and the parent is used from this point forward
+ * When a call succeeds's we can merge a child into its parent
+ */
+export class AvmWorldStateJournal {
+  /** Reference to node storage */
+  public readonly hostStorage: HostStorage;
+
+  // Reading state - must be tracked for vm execution
+  // contract address -> key -> value[] (array stored in order of reads)
+  private storageReads: Map<bigint, Map<bigint, Fr[]>> = new Map();
+  private storageWrites: Map<bigint, Map<bigint, Fr[]>> = new Map();
+
+  // New written state
+  private newNoteHashes: Fr[] = [];
+  private newNullifiers: Fr[] = [];
+
+  // New Substate
+  private newL1Messages: Fr[][] = [];
+  private newLogs: Fr[][] = [];
+
+  // contract address -> key -> value
+  private currentStorageValue: Map<bigint, Map<bigint, Fr>> = new Map();
+
+  private parentJournal: AvmWorldStateJournal | undefined;
+
+  constructor(hostStorage: HostStorage, parentJournal?: AvmWorldStateJournal) {
+    this.hostStorage = hostStorage;
+    this.parentJournal = parentJournal;
+  }
+
+  /**
+   * Create a new world state journal forked from this one
+   */
+  public fork() {
+    return new AvmWorldStateJournal(this.hostStorage, this);
+  }
+
+  /**
+   * Write storage into journal
+   *
+   * @param contractAddress -
+   * @param key -
+   * @param value -
+   */
+  public writeStorage(contractAddress: Fr, key: Fr, value: Fr) {
+    let contractMap = this.currentStorageValue.get(contractAddress.toBigInt());
+    if (!contractMap) {
+      contractMap = new Map();
+      this.currentStorageValue.set(contractAddress.toBigInt(), contractMap);
+    }
+    contractMap.set(key.toBigInt(), value);
+
+    // We want to keep track of all performed writes in the journal
+    this.journalWrite(contractAddress, key, value);
+  }
+
+  /**
+   * Read storage from journal
+   * Read from host storage on cache miss
+   *
+   * @param contractAddress -
+   * @param key -
+   * @returns current value
+   */
+  public async readStorage(contractAddress: Fr, key: Fr): Promise<Fr> {
+    // - We first try this journal's storage cache ( if written to before in this call frame )
+    // - Then we try the parent journal's storage cache ( if it exists ) ( written to earlier in this block )
+    // - Finally we try the host storage ( a trip to the database )
+
+    // Do not early return as we want to keep track of reads in this.storageReads
+    let value = this.currentStorageValue.get(contractAddress.toBigInt())?.get(key.toBigInt());
+    if (!value && this.parentJournal) {
+      value = await this.parentJournal?.readStorage(contractAddress, key);
+    }
+    if (!value) {
+      value = await this.hostStorage.publicStateDb.storageRead(contractAddress, key);
+    }
+
+    this.journalRead(contractAddress, key, value);
+    return Promise.resolve(value);
+  }
+
+  /**
+   * We want to keep track of all performed reads in the journal
+   * This information is hinted to the avm circuit
+
+   * @param contractAddress -
+   * @param key -
+   * @param value -
+   */
+  journalUpdate(map: Map<bigint, Map<bigint, Fr[]>>, contractAddress: Fr, key: Fr, value: Fr): void {
+    let contractMap = map.get(contractAddress.toBigInt());
+    if (!contractMap) {
+      contractMap = new Map<bigint, Array<Fr>>();
+      map.set(contractAddress.toBigInt(), contractMap);
+    }
+
+    let accessArray = contractMap.get(key.toBigInt());
+    if (!accessArray) {
+      accessArray = new Array<Fr>();
+      contractMap.set(key.toBigInt(), accessArray);
+    }
+    accessArray.push(value);
+  }
+
+  // Create an instance of journalUpdate that appends to the read array
+  private journalRead = this.journalUpdate.bind(this, this.storageReads);
+  // Create an instance of journalUpdate that appends to the writes array
+  private journalWrite = this.journalUpdate.bind(this, this.storageWrites);
+
+  public writeNoteHash(noteHash: Fr) {
+    this.newNoteHashes.push(noteHash);
+  }
+
+  public writeL1Message(message: Fr[]) {
+    this.newL1Messages.push(message);
+  }
+
+  public writeNullifier(nullifier: Fr) {
+    this.newNullifiers.push(nullifier);
+  }
+
+  public writeLog(log: Fr[]) {
+    this.newLogs.push(log);
+  }
+
+  /**
+   * Accept nested world state, merging in its journal, and accepting its state modifications
+   * - Utxo objects are concatenated
+   * - Public state changes are merged, with the value in the incoming journal taking precedent
+   * - Public state journals (r/w logs), with the accessing being appended in chronological order
+   */
+  public acceptNestedWorldState(nestedJournal: AvmWorldStateJournal) {
+    // Merge UTXOs
+    this.newNoteHashes = this.newNoteHashes.concat(nestedJournal.newNoteHashes);
+    this.newL1Messages = this.newL1Messages.concat(nestedJournal.newL1Messages);
+    this.newNullifiers = this.newNullifiers.concat(nestedJournal.newNullifiers);
+    this.newLogs = this.newLogs.concat(nestedJournal.newLogs);
+
+    // Merge Public State
+    mergeCurrentValueMaps(this.currentStorageValue, nestedJournal.currentStorageValue);
+
+    // Merge storage read and write journals
+    mergeContractJournalMaps(this.storageReads, nestedJournal.storageReads);
+    mergeContractJournalMaps(this.storageWrites, nestedJournal.storageWrites);
+  }
+
+  /**
+   * Reject nested world state, merging in its journal, but not accepting its state modifications
+   * - Utxo objects are concatenated
+   * - Public state changes are dropped
+   * - Public state journals (r/w logs) are maintained, with the accessing being appended in chronological order
+   */
+  public rejectNestedWorldState(nestedJournal: AvmWorldStateJournal) {
+    // Merge storage read and write journals
+    mergeContractJournalMaps(this.storageReads, nestedJournal.storageReads);
+    mergeContractJournalMaps(this.storageWrites, nestedJournal.storageWrites);
+  }
+
+  /**
+   * Access the current state of the journal
+   *
+   * @returns a JournalData object
+   */
+  public flush(): JournalData {
+    return {
+      newNoteHashes: this.newNoteHashes,
+      newNullifiers: this.newNullifiers,
+      newL1Messages: this.newL1Messages,
+      newLogs: this.newLogs,
+      currentStorageValue: this.currentStorageValue,
+      storageReads: this.storageReads,
+      storageWrites: this.storageWrites,
+    };
+  }
+}
+
+/**
+ * Merges two contract current value together
+ * Where childMap keys will take precedent over the hostMap
+ * The assumption being that the child map is created at a later time
+ * And thus contains more up to date information
+ *
+ * @param hostMap - The map to be merged into
+ * @param childMap - The map to be merged from
+ */
+function mergeCurrentValueMaps(hostMap: Map<bigint, Map<bigint, Fr>>, childMap: Map<bigint, Map<bigint, Fr>>) {
+  for (const [key, value] of childMap) {
+    const map1Value = hostMap.get(key);
+    if (!map1Value) {
+      hostMap.set(key, value);
+    } else {
+      mergeStorageCurrentValueMaps(map1Value, value);
+    }
+  }
+}
+
+/**
+ * @param hostMap - The map to be merge into
+ * @param childMap - The map to be merged from
+ */
+function mergeStorageCurrentValueMaps(hostMap: Map<bigint, Fr>, childMap: Map<bigint, Fr>) {
+  for (const [key, value] of childMap) {
+    hostMap.set(key, value);
+  }
+}
+
+/**
+ * Merges two contract journalling maps together
+ * For read maps, we just append the childMap arrays into the host map arrays, as the order is important
+ *
+ * @param hostMap - The map to be merged into
+ * @param childMap - The map to be merged from
+ */
+function mergeContractJournalMaps(hostMap: Map<bigint, Map<bigint, Fr[]>>, childMap: Map<bigint, Map<bigint, Fr[]>>) {
+  for (const [key, value] of childMap) {
+    const map1Value = hostMap.get(key);
+    if (!map1Value) {
+      hostMap.set(key, value);
+    } else {
+      mergeStorageJournalMaps(map1Value, value);
+    }
+  }
+}
+
+/**
+ * @param hostMap - The map to be merge into
+ * @param childMap - The map to be merged from
+ */
+function mergeStorageJournalMaps(hostMap: Map<bigint, Fr[]>, childMap: Map<bigint, Fr[]>) {
+  for (const [key, value] of childMap) {
+    const readArr = hostMap.get(key);
+    if (!readArr) {
+      hostMap.set(key, value);
+    } else {
+      hostMap.set(key, readArr?.concat(...value));
+    }
+  }
+}

package/src/avm/opcodes/.eslintrc.cjs

@@ -0,0 +1,8 @@
+const baseConfig = require('@aztec/foundation/eslint');
+module.exports = {
+  ...baseConfig,
+  rules: {
+    ...baseConfig.rules,
+    'require-await': 'off',
+  },
+};

package/src/avm/opcodes/accrued_substate.ts

@@ -0,0 +1,92 @@
+import type { AvmContext } from '../avm_context.js';
+import { Opcode, OperandType } from '../serialization/instruction_serialization.js';
+import { Instruction } from './instruction.js';
+import { StaticCallStorageAlterError } from './storage.js';
+
+export class EmitNoteHash extends Instruction {
+  static type: string = 'EMITNOTEHASH';
+  static readonly opcode: Opcode = Opcode.EMITNOTEHASH;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat = [OperandType.UINT8, OperandType.UINT8, OperandType.UINT32];
+
+  constructor(private indirect: number, private noteHashOffset: number) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    if (context.environment.isStaticCall) {
+      throw new StaticCallStorageAlterError();
+    }
+
+    const noteHash = context.machineState.memory.get(this.noteHashOffset).toFr();
+    context.worldState.writeNoteHash(noteHash);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class EmitNullifier extends Instruction {
+  static type: string = 'EMITNULLIFIER';
+  static readonly opcode: Opcode = Opcode.EMITNULLIFIER;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat = [OperandType.UINT8, OperandType.UINT8, OperandType.UINT32];
+
+  constructor(private indirect: number, private nullifierOffset: number) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    if (context.environment.isStaticCall) {
+      throw new StaticCallStorageAlterError();
+    }
+
+    const nullifier = context.machineState.memory.get(this.nullifierOffset).toFr();
+    context.worldState.writeNullifier(nullifier);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class EmitUnencryptedLog extends Instruction {
+  static type: string = 'EMITUNENCRYPTEDLOG';
+  static readonly opcode: Opcode = Opcode.EMITUNENCRYPTEDLOG;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat = [OperandType.UINT8, OperandType.UINT8, OperandType.UINT32, OperandType.UINT32];
+
+  constructor(private indirect: number, private logOffset: number, private logSize: number) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    if (context.environment.isStaticCall) {
+      throw new StaticCallStorageAlterError();
+    }
+
+    const log = context.machineState.memory.getSlice(this.logOffset, this.logSize).map(f => f.toFr());
+    context.worldState.writeLog(log);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class SendL2ToL1Message extends Instruction {
+  static type: string = 'SENDL2TOL1MSG';
+  static readonly opcode: Opcode = Opcode.SENDL2TOL1MSG;
+  // Informs (de)serialization. See Instruction.deserialize.
+  static readonly wireFormat = [OperandType.UINT8, OperandType.UINT8, OperandType.UINT32, OperandType.UINT32];
+
+  constructor(private indirect: number, private msgOffset: number, private msgSize: number) {
+    super();
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    if (context.environment.isStaticCall) {
+      throw new StaticCallStorageAlterError();
+    }
+
+    const msg = context.machineState.memory.getSlice(this.msgOffset, this.msgSize).map(f => f.toFr());
+    context.worldState.writeL1Message(msg);
+
+    context.machineState.incrementPc();
+  }
+}

package/src/avm/opcodes/addressing_mode.ts

@@ -0,0 +1,66 @@
+import { strict as assert } from 'assert';
+
+import { TaggedMemory, TypeTag } from '../avm_memory_types.js';
+
+export enum AddressingMode {
+  DIRECT,
+  INDIRECT,
+  INDIRECT_PLUS_CONSTANT, // Not implemented yet.
+}
+
+/** A class to represent the addressing mode of an instruction. */
+export class Addressing {
+  public constructor(
+    /** The addressing mode for each operand. The length of this array is the number of operands of the instruction. */
+    private readonly modePerOperand: AddressingMode[],
+  ) {
+    assert(modePerOperand.length <= 8, 'At most 8 operands are supported');
+  }
+
+  public static fromWire(wireModes: number): Addressing {
+    // The modes are stored in the wire format as a byte, with each bit representing the mode for an operand.
+    // The least significant bit represents the zeroth operand, and the most significant bit represents the last operand.
+    const modes = new Array<AddressingMode>(8);
+    for (let i = 0; i < 8; i++) {
+      modes[i] = (wireModes & (1 << i)) === 0 ? AddressingMode.DIRECT : AddressingMode.INDIRECT;
+    }
+    return new Addressing(modes);
+  }
+
+  public toWire(): number {
+    // The modes are stored in the wire format as a byte, with each bit representing the mode for an operand.
+    // The least significant bit represents the zeroth operand, and the least significant bit represents the last operand.
+    let wire: number = 0;
+    for (let i = 0; i < 8; i++) {
+      if (this.modePerOperand[i] === AddressingMode.INDIRECT) {
+        wire |= 1 << i;
+      }
+    }
+    return wire;
+  }
+
+  /**
+   * Resolves the offsets using the addressing mode.
+   * @param offsets The offsets to resolve.
+   * @param mem The memory to use for resolution.
+   * @returns The resolved offsets. The length of the returned array is the same as the length of the input array.
+   */
+  public resolve(offsets: number[], mem: TaggedMemory): number[] {
+    assert(offsets.length <= this.modePerOperand.length);
+    const resolved = new Array(offsets.length);
+    for (const [i, offset] of offsets.entries()) {
+      switch (this.modePerOperand[i]) {
+        case AddressingMode.INDIRECT:
+          mem.checkTag(TypeTag.UINT32, offset);
+          resolved[i] = Number(mem.get(offset).toBigInt());
+          break;
+        case AddressingMode.DIRECT:
+          resolved[i] = offset;
+          break;
+        default:
+          throw new Error(`Unimplemented addressing mode: ${AddressingMode[this.modePerOperand[i]]}`);
+      }
+    }
+    return resolved;
+  }
+}

package/src/avm/opcodes/arithmetic.ts

@@ -0,0 +1,79 @@
+import type { AvmContext } from '../avm_context.js';
+import { Opcode } from '../serialization/instruction_serialization.js';
+import { ThreeOperandInstruction } from './instruction_impl.js';
+
+export class Add extends ThreeOperandInstruction {
+  static readonly type: string = 'ADD';
+  static readonly opcode = Opcode.ADD;
+
+  constructor(indirect: number, inTag: number, aOffset: number, bOffset: number, dstOffset: number) {
+    super(indirect, inTag, aOffset, bOffset, dstOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const a = context.machineState.memory.get(this.aOffset);
+    const b = context.machineState.memory.get(this.bOffset);
+
+    const dest = a.add(b);
+    context.machineState.memory.set(this.dstOffset, dest);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Sub extends ThreeOperandInstruction {
+  static readonly type: string = 'SUB';
+  static readonly opcode = Opcode.SUB;
+
+  constructor(indirect: number, inTag: number, aOffset: number, bOffset: number, dstOffset: number) {
+    super(indirect, inTag, aOffset, bOffset, dstOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const a = context.machineState.memory.get(this.aOffset);
+    const b = context.machineState.memory.get(this.bOffset);
+
+    const dest = a.sub(b);
+    context.machineState.memory.set(this.dstOffset, dest);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Mul extends ThreeOperandInstruction {
+  static type: string = 'MUL';
+  static readonly opcode = Opcode.MUL;
+
+  constructor(indirect: number, inTag: number, aOffset: number, bOffset: number, dstOffset: number) {
+    super(indirect, inTag, aOffset, bOffset, dstOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const a = context.machineState.memory.get(this.aOffset);
+    const b = context.machineState.memory.get(this.bOffset);
+
+    const dest = a.mul(b);
+    context.machineState.memory.set(this.dstOffset, dest);
+
+    context.machineState.incrementPc();
+  }
+}
+
+export class Div extends ThreeOperandInstruction {
+  static type: string = 'DIV';
+  static readonly opcode = Opcode.DIV;
+
+  constructor(indirect: number, inTag: number, aOffset: number, bOffset: number, dstOffset: number) {
+    super(indirect, inTag, aOffset, bOffset, dstOffset);
+  }
+
+  async execute(context: AvmContext): Promise<void> {
+    const a = context.machineState.memory.get(this.aOffset);
+    const b = context.machineState.memory.get(this.bOffset);
+
+    const dest = a.div(b);
+    context.machineState.memory.set(this.dstOffset, dest);
+
+    context.machineState.incrementPc();
+  }
+}