@aztec/simulator 0.23.0 → 0.26.1

package/src/avm/journal/journal.ts

@@ -0,0 +1,231 @@
+import { UnencryptedL2Log } from '@aztec/circuit-types';
+import { AztecAddress, EthAddress, L2ToL1Message } from '@aztec/circuits.js';
+import { EventSelector } from '@aztec/foundation/abi';
+import { Fr } from '@aztec/foundation/fields';
+
+import { HostStorage } from './host_storage.js';
+import { Nullifiers } from './nullifiers.js';
+import { PublicStorage } from './public_storage.js';
+import { WorldStateAccessTrace } from './trace.js';
+import { TracedL1toL2MessageCheck, TracedNoteHashCheck, TracedNullifierCheck } from './trace_types.js';
+
+/**
+ * Data held within the journal
+ */
+export type JournalData = {
+  noteHashChecks: TracedNoteHashCheck[];
+  newNoteHashes: Fr[];
+  nullifierChecks: TracedNullifierCheck[];
+  newNullifiers: Fr[];
+  l1ToL2MessageChecks: TracedL1toL2MessageCheck[];
+
+  newL1Messages: L2ToL1Message[];
+  newLogs: UnencryptedL2Log[];
+
+  /** 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 class to manage persistable AVM state for contract calls.
+ * Maintains a cache of the current world state,
+ * a trace of all world state accesses, and a list of accrued substate items.
+ *
+ * The simulator should make any world state and accrued substate queries through this object.
+ *
+ * Manages merging of successful/reverted child state into current state.
+ */
+export class AvmPersistableStateManager {
+  /** Reference to node storage */
+  public readonly hostStorage: HostStorage;
+
+  /** World State */
+  /** Public storage, including cached writes */
+  private publicStorage: PublicStorage;
+  /** Nullifier set, including cached/recently-emitted nullifiers */
+  private nullifiers: Nullifiers;
+
+  /** World State Access Trace */
+  private trace: WorldStateAccessTrace;
+
+  /** Accrued Substate **/
+  private newL1Messages: L2ToL1Message[] = [];
+  private newLogs: UnencryptedL2Log[] = [];
+
+  constructor(hostStorage: HostStorage, parent?: AvmPersistableStateManager) {
+    this.hostStorage = hostStorage;
+    this.publicStorage = new PublicStorage(hostStorage.publicStateDb, parent?.publicStorage);
+    this.nullifiers = new Nullifiers(hostStorage.commitmentsDb, parent?.nullifiers);
+    this.trace = new WorldStateAccessTrace(parent?.trace);
+  }
+
+  /**
+   * Create a new state manager forked from this one
+   */
+  public fork() {
+    return new AvmPersistableStateManager(this.hostStorage, this);
+  }
+
+  /**
+   * Write to public storage, journal/trace the write.
+   *
+   * @param storageAddress - the address of the contract whose storage is being written to
+   * @param slot - the slot in the contract's storage being written to
+   * @param value - the value being written to the slot
+   */
+  public writeStorage(storageAddress: Fr, slot: Fr, value: Fr) {
+    // Cache storage writes for later reference/reads
+    this.publicStorage.write(storageAddress, slot, value);
+    // Trace all storage writes (even reverted ones)
+    this.trace.tracePublicStorageWrite(storageAddress, slot, value);
+  }
+
+  /**
+   * Read from public storage, trace the read.
+   *
+   * @param storageAddress - the address of the contract whose storage is being read from
+   * @param slot - the slot in the contract's storage being read from
+   * @returns the latest value written to slot, or 0 if never written to before
+   */
+  public async readStorage(storageAddress: Fr, slot: Fr): Promise<Fr> {
+    const [_exists, value] = await this.publicStorage.read(storageAddress, slot);
+    // We want to keep track of all performed reads (even reverted ones)
+    this.trace.tracePublicStorageRead(storageAddress, slot, value);
+    return Promise.resolve(value);
+  }
+
+  // TODO(4886): We currently don't silo note hashes.
+  /**
+   * Check if a note hash exists at the given leaf index, trace the check.
+   *
+   * @param storageAddress - the address of the contract whose storage is being read from
+   * @param noteHash - the unsiloed note hash being checked
+   * @param leafIndex - the leaf index being checked
+   * @returns true if the note hash exists at the given leaf index, false otherwise
+   */
+  public async checkNoteHashExists(storageAddress: Fr, noteHash: Fr, leafIndex: Fr): Promise<boolean> {
+    const gotLeafIndex = await this.hostStorage.commitmentsDb.getCommitmentIndex(noteHash);
+    const exists = gotLeafIndex === leafIndex.toBigInt();
+    this.trace.traceNoteHashCheck(storageAddress, noteHash, exists, leafIndex);
+    return Promise.resolve(exists);
+  }
+
+  /**
+   * Write a note hash, trace the write.
+   * @param noteHash - the unsiloed note hash to write
+   */
+  public writeNoteHash(noteHash: Fr) {
+    this.trace.traceNewNoteHash(/*storageAddress*/ Fr.ZERO, noteHash);
+  }
+
+  /**
+   * Check if a nullifier exists, trace the check.
+   * @param storageAddress - address of the contract that the nullifier is associated with
+   * @param nullifier - the unsiloed nullifier to check
+   * @returns exists - whether the nullifier exists in the nullifier set
+   */
+  public async checkNullifierExists(storageAddress: Fr, nullifier: Fr): Promise<boolean> {
+    const [exists, isPending, leafIndex] = await this.nullifiers.checkExists(storageAddress, nullifier);
+    this.trace.traceNullifierCheck(storageAddress, nullifier, exists, isPending, leafIndex);
+    return Promise.resolve(exists);
+  }
+
+  /**
+   * Write a nullifier to the nullifier set, trace the write.
+   * @param storageAddress - address of the contract that the nullifier is associated with
+   * @param nullifier - the unsiloed nullifier to write
+   */
+  public async writeNullifier(storageAddress: Fr, nullifier: Fr) {
+    // Cache pending nullifiers for later access
+    await this.nullifiers.append(storageAddress, nullifier);
+    // Trace all nullifier creations (even reverted ones)
+    this.trace.traceNewNullifier(storageAddress, nullifier);
+  }
+
+  /**
+   * Check if an L1 to L2 message exists, trace the check.
+   * @param msgHash - the message hash to check existence of
+   * @param msgLeafIndex - the message leaf index to use in the check
+   * @returns exists - whether the message exists in the L1 to L2 Messages tree
+   */
+  public async checkL1ToL2MessageExists(msgHash: Fr, msgLeafIndex: Fr): Promise<boolean> {
+    let exists = false;
+    try {
+      const gotMessage = await this.hostStorage.commitmentsDb.getL1ToL2MembershipWitness(msgHash);
+      exists = gotMessage !== undefined && gotMessage.index == msgLeafIndex.toBigInt();
+    } catch {
+      // error getting message - doesn't exist!
+      exists = false;
+    }
+    this.trace.traceL1ToL2MessageCheck(msgHash, msgLeafIndex, exists);
+    return Promise.resolve(exists);
+  }
+
+  /**
+   * Write an L2 to L1 message.
+   * @param recipient - L1 contract address to send the message to.
+   * @param content - Message content.
+   */
+  public writeL1Message(recipient: EthAddress | Fr, content: Fr) {
+    const recipientAddress = recipient instanceof EthAddress ? recipient : EthAddress.fromField(recipient);
+    this.newL1Messages.push(new L2ToL1Message(recipientAddress, content));
+  }
+
+  public writeLog(contractAddress: Fr, event: Fr, log: Fr[]) {
+    this.newLogs.push(
+      new UnencryptedL2Log(
+        AztecAddress.fromField(contractAddress),
+        EventSelector.fromField(event),
+        Buffer.concat(log.map(f => f.toBuffer())),
+      ),
+    );
+  }
+
+  /**
+   * Accept nested world state modifications, merging in its trace and accrued substate
+   */
+  public acceptNestedCallState(nestedJournal: AvmPersistableStateManager) {
+    // Merge Public Storage
+    this.publicStorage.acceptAndMerge(nestedJournal.publicStorage);
+
+    // Merge World State Access Trace
+    this.trace.acceptAndMerge(nestedJournal.trace);
+
+    // Accrued Substate
+    this.newL1Messages = this.newL1Messages.concat(nestedJournal.newL1Messages);
+    this.newLogs = this.newLogs.concat(nestedJournal.newLogs);
+  }
+
+  /**
+   * Reject nested world state, merging in its trace, but not accepting any state modifications
+   */
+  public rejectNestedCallState(nestedJournal: AvmPersistableStateManager) {
+    // Merge World State Access Trace
+    this.trace.acceptAndMerge(nestedJournal.trace);
+  }
+
+  /**
+   * Access the current state of the journal
+   *
+   * @returns a JournalData object
+   */
+  public flush(): JournalData {
+    return {
+      noteHashChecks: this.trace.noteHashChecks,
+      newNoteHashes: this.trace.newNoteHashes,
+      nullifierChecks: this.trace.nullifierChecks,
+      newNullifiers: this.trace.newNullifiers,
+      l1ToL2MessageChecks: this.trace.l1ToL2MessageChecks,
+      newL1Messages: this.newL1Messages,
+      newLogs: this.newLogs,
+      currentStorageValue: this.publicStorage.getCache().cachePerContract,
+      storageReads: this.trace.publicStorageReads,
+      storageWrites: this.trace.publicStorageWrites,
+    };
+  }
+}

package/src/avm/journal/nullifiers.ts

@@ -0,0 +1,170 @@
+import { siloNullifier } from '@aztec/circuits.js/hash';
+import { Fr } from '@aztec/foundation/fields';
+
+import type { CommitmentsDB } from '../../index.js';
+
+/**
+ * A class to manage new nullifier staging and existence checks during a contract call's AVM simulation.
+ * Maintains a nullifier cache, and ensures that existence checks fall back to the correct source.
+ * When a contract call completes, its cached nullifier set can be merged into its parent's.
+ */
+export class Nullifiers {
+  /** Cached nullifiers. */
+  private cache: NullifierCache;
+  /** Parent's nullifier cache. Checked on cache-miss. */
+  private readonly parentCache: NullifierCache | undefined;
+  /** Reference to node storage. Checked on parent cache-miss. */
+  private readonly hostNullifiers: CommitmentsDB;
+
+  constructor(hostNullifiers: CommitmentsDB, parent?: Nullifiers) {
+    this.hostNullifiers = hostNullifiers;
+    this.parentCache = parent?.cache;
+    this.cache = new NullifierCache();
+  }
+
+  /**
+   * Get a nullifier's existence status.
+   * 1. Check cache.
+   * 2. Check parent's cache.
+   * 3. Fall back to the host state.
+   * 4. Not found! Nullifier does not exist.
+   *
+   * @param storageAddress - the address of the contract whose storage is being read from
+   * @param nullifier - the nullifier to check for
+   * @returns exists: whether the nullifier exists at all,
+   *          isPending: whether the nullifier was found in a cache,
+   *          leafIndex: the nullifier's leaf index if it exists and is not pending (comes from host state).
+   */
+  public async checkExists(
+    storageAddress: Fr,
+    nullifier: Fr,
+  ): Promise<[/*exists=*/ boolean, /*isPending=*/ boolean, /*leafIndex=*/ Fr]> {
+    // First check this cache
+    let existsAsPending = this.cache.exists(storageAddress, nullifier);
+    // Then check parent's cache
+    if (!existsAsPending && this.parentCache) {
+      existsAsPending = this.parentCache?.exists(storageAddress, nullifier);
+    }
+    // Finally try the host's Aztec state (a trip to the database)
+    // If the value is found in the database, it will be associated with a leaf index!
+    let leafIndex: bigint | undefined = undefined;
+    if (!existsAsPending) {
+      // silo the nullifier before checking for its existence in the host
+      leafIndex = await this.hostNullifiers.getNullifierIndex(siloNullifier(storageAddress, nullifier));
+    }
+    const exists = existsAsPending || leafIndex !== undefined;
+    leafIndex = leafIndex === undefined ? BigInt(0) : leafIndex;
+    return Promise.resolve([exists, existsAsPending, new Fr(leafIndex)]);
+  }
+
+  /**
+   * Stage a new nullifier (append it to the cache).
+   *
+   * @param storageAddress - the address of the contract that the nullifier is associated with
+   * @param nullifier - the nullifier to stage
+   */
+  public async append(storageAddress: Fr, nullifier: Fr) {
+    const [exists, ,] = await this.checkExists(storageAddress, nullifier);
+    if (exists) {
+      throw new NullifierCollisionError(
+        `Nullifier ${nullifier} at contract ${storageAddress} already exists in parent cache or host.`,
+      );
+    }
+    this.cache.append(storageAddress, nullifier);
+  }
+
+  /**
+   * Merges another nullifier cache into this one.
+   *
+   * @param incomingNullifiers - the incoming cached nullifiers to merge into this instance's
+   */
+  public acceptAndMerge(incomingNullifiers: Nullifiers) {
+    this.cache.acceptAndMerge(incomingNullifiers.cache);
+  }
+}
+
+/**
+ * A class to cache nullifiers created during a contract call's AVM simulation.
+ * "append" updates a map, "exists" checks that map.
+ * An instance of this class can merge another instance's cached nullifiers into its own.
+ */
+export class NullifierCache {
+  /**
+   * Map for staging nullifiers.
+   * One inner-set per contract storage address,
+   * each entry being a nullifier.
+   */
+  private cachePerContract: Map<bigint, Set<bigint>> = new Map();
+
+  /**
+   * Check whether a nullifier exists in the cache.
+   *
+   * @param storageAddress - the address of the contract that the nullifier is associated with
+   * @param nullifier - the nullifier to check existence of
+   * @returns whether the nullifier is found in the cache
+   */
+  public exists(storageAddress: Fr, nullifier: Fr): boolean {
+    const exists = this.cachePerContract.get(storageAddress.toBigInt())?.has(nullifier.toBigInt());
+    return exists ? true : false;
+  }
+
+  /**
+   * Stage a new nullifier (append it to the cache).
+   *
+   * @param storageAddress - the address of the contract that the nullifier is associated with
+   * @param nullifier - the nullifier to stage
+   */
+  public append(storageAddress: Fr, nullifier: Fr) {
+    let nullifiersForContract = this.cachePerContract.get(storageAddress.toBigInt());
+    // If this contract's nullifier set has no cached nullifiers, create a new Set to store them
+    if (!nullifiersForContract) {
+      nullifiersForContract = new Set();
+      this.cachePerContract.set(storageAddress.toBigInt(), nullifiersForContract);
+    }
+    if (nullifiersForContract.has(nullifier.toBigInt())) {
+      throw new NullifierCollisionError(
+        `Nullifier ${nullifier} at contract ${storageAddress} already exists in cache.`,
+      );
+    }
+    nullifiersForContract.add(nullifier.toBigInt());
+  }
+
+  /**
+   * Merge another cache's nullifiers into this instance's.
+   *
+   * Cached nullifiers in "incoming" must not collide with any present in "this".
+   *
+   * In practice, "this" is a parent call's pending nullifiers, and "incoming" is a nested call's.
+   *
+   * @param incomingNullifiers - the incoming cached nullifiers to merge into this instance's
+   */
+  public acceptAndMerge(incomingNullifiers: NullifierCache) {
+    // Iterate over all contracts with staged writes in the child.
+    for (const [incomingAddress, incomingCacheAtContract] of incomingNullifiers.cachePerContract) {
+      const thisCacheAtContract = this.cachePerContract.get(incomingAddress);
+      if (!thisCacheAtContract) {
+        // This contract has no nullifiers cached here
+        // so just accept incoming cache as-is for this contract.
+        this.cachePerContract.set(incomingAddress, incomingCacheAtContract);
+      } else {
+        // "Incoming" and "this" both have cached nullifiers for this contract.
+        // Merge in incoming nullifiers, erroring if there are any duplicates.
+        for (const nullifier of incomingCacheAtContract) {
+          if (thisCacheAtContract.has(nullifier)) {
+            throw new NullifierCollisionError(
+              `Failed to accept child call's nullifiers. Nullifier ${nullifier} already exists at contract ${incomingAddress}.`,
+            );
+          }
+          thisCacheAtContract.add(nullifier);
+        }
+      }
+    }
+  }
+}
+
+export class NullifierCollisionError extends Error {
+  constructor(message: string, ...rest: any[]) {
+    super(message, ...rest);
+    this.name = 'NullifierCollisionError';
+  }
+}

package/src/avm/journal/public_storage.ts

@@ -0,0 +1,149 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import type { PublicStateDB } from '../../index.js';
+
+/**
+ * A class to manage public storage reads and writes during a contract call's AVM simulation.
+ * Maintains a storage write cache, and ensures that reads fall back to the correct source.
+ * When a contract call completes, its storage cache can be merged into its parent's.
+ */
+export class PublicStorage {
+  /** Cached storage writes. */
+  private cache: PublicStorageCache;
+  /** Parent's storage cache. Checked on cache-miss. */
+  private readonly parentCache: PublicStorageCache | undefined;
+  /** Reference to node storage. Checked on parent cache-miss. */
+  private readonly hostPublicStorage: PublicStateDB;
+
+  constructor(hostPublicStorage: PublicStateDB, parent?: PublicStorage) {
+    this.hostPublicStorage = hostPublicStorage;
+    this.parentCache = parent?.cache;
+    this.cache = new PublicStorageCache();
+  }
+
+  /**
+   * Get the pending storage.
+   */
+  public getCache() {
+    return this.cache;
+  }
+
+  /**
+   * Read a value from storage.
+   * 1. Check cache.
+   * 2. Check parent's cache.
+   * 3. Fall back to the host state.
+   * 4. Not found! Value has never been written to before. Flag it as non-existent and return value zero.
+   *
+   * @param storageAddress - the address of the contract whose storage is being read from
+   * @param slot - the slot in the contract's storage being read from
+   * @returns exists: whether the slot has EVER been written to before, value: the latest value written to slot, or 0 if never written to before
+   */
+  public async read(storageAddress: Fr, slot: Fr): Promise<[/*exists=*/ boolean, /*value=*/ Fr]> {
+    // First try check this storage cache
+    let value = this.cache.read(storageAddress, slot);
+    // Then try parent's storage cache (if it exists / written to earlier in this TX)
+    if (!value && this.parentCache) {
+      value = this.parentCache?.read(storageAddress, slot);
+    }
+    // Finally try the host's Aztec state (a trip to the database)
+    if (!value) {
+      value = await this.hostPublicStorage.storageRead(storageAddress, slot);
+    }
+    // if value is undefined, that means this slot has never been written to!
+    const exists = value !== undefined;
+    const valueOrZero = exists ? value : Fr.ZERO;
+    return Promise.resolve([exists, valueOrZero]);
+  }
+
+  /**
+   * Stage a storage write.
+   *
+   * @param storageAddress - the address of the contract whose storage is being written to
+   * @param slot - the slot in the contract's storage being written to
+   * @param value - the value being written to the slot
+   */
+  public write(storageAddress: Fr, key: Fr, value: Fr) {
+    this.cache.write(storageAddress, key, value);
+  }
+
+  /**
+   * Merges another PublicStorage's cache (pending writes) into this one.
+   *
+   * @param incomingPublicStorage - the incoming public storage to merge into this instance's
+   */
+  public acceptAndMerge(incomingPublicStorage: PublicStorage) {
+    this.cache.acceptAndMerge(incomingPublicStorage.cache);
+  }
+}
+
+/**
+ * A class to cache writes to public storage during a contract call's AVM simulation.
+ * "Writes" update a map, "reads" check that map or return undefined.
+ * An instance of this class can merge another instance's staged writes into its own.
+ */
+class PublicStorageCache {
+  /**
+   * Map for staging storage writes.
+   * One inner-map per contract storage address,
+   * mapping storage slot to latest staged write value.
+   */
+  public cachePerContract: Map<bigint, Map<bigint, Fr>> = new Map();
+  // FIXME: storage ^ should be private, but its value is used in tests for "currentStorageValue"
+
+  /**
+   * Read a staged value from storage, if it has been previously written to.
+   *
+   * @param storageAddress - the address of the contract whose storage is being read from
+   * @param slot - the slot in the contract's storage being read from
+   * @returns the latest value written to slot, or undefined if no value has been written
+   */
+  public read(storageAddress: Fr, slot: Fr): Fr | undefined {
+    return this.cachePerContract.get(storageAddress.toBigInt())?.get(slot.toBigInt());
+  }
+
+  /**
+   * Stage a storage write.
+   *
+   * @param storageAddress - the address of the contract whose storage is being written to
+   * @param slot - the slot in the contract's storage being written to
+   * @param value - the value being written to the slot
+   */
+  public write(storageAddress: Fr, slot: Fr, value: Fr) {
+    let cacheAtContract = this.cachePerContract.get(storageAddress.toBigInt());
+    if (!cacheAtContract) {
+      // If this contract's storage has no staged modifications, create a new inner map to store them
+      cacheAtContract = new Map();
+      this.cachePerContract.set(storageAddress.toBigInt(), cacheAtContract);
+    }
+    cacheAtContract.set(slot.toBigInt(), value);
+  }
+
+  /**
+   * Merges another cache's staged writes into this instance's cache.
+   *
+   * Staged modifications in "incoming" take precedence over those
+   * present in "this" as they are assumed to occur after this' writes.
+   *
+   * In practice, "this" is a parent call's storage cache, and "incoming" is a nested call's.
+   *
+   * @param incomingStorageCache - the incoming storage write cache to merge into this instance's
+   */
+  public acceptAndMerge(incomingStorageCache: PublicStorageCache) {
+    // Iterate over all incoming contracts with staged writes.
+    for (const [incomingAddress, incomingCacheAtContract] of incomingStorageCache.cachePerContract) {
+      const thisCacheAtContract = this.cachePerContract.get(incomingAddress);
+      if (!thisCacheAtContract) {
+        // The contract has no storage writes staged here
+        // so just accept the incoming cache as-is for this contract.
+        this.cachePerContract.set(incomingAddress, incomingCacheAtContract);
+      } else {
+        // "Incoming" and "this" both have staged writes for this contract.
+        // Merge in incoming staged writes, giving them precedence over this'.
+        for (const [slot, value] of incomingCacheAtContract) {
+          thisCacheAtContract.set(slot, value);
+        }
+      }
+    }
+  }
+}