@aztec/simulator 0.24.0 → 0.26.1

package/src/avm/journal/journal.ts

@@ -1,15 +1,26 @@
+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[];
-  newL1Messages: Fr[][];
-  newLogs: Fr[][];
+  l1ToL2MessageChecks: TracedL1toL2MessageCheck[];
+
+  newL1Messages: L2ToL1Message[];
+  newLogs: UnencryptedL2Log[];
 
   /** contract address -\> key -\> value */
   currentStorageValue: Map<bigint, Map<bigint, Fr>>;
@@ -21,167 +32,181 @@ export type JournalData = {
 };
 
 /**
- * A cache of the current state of the AVM
- * The interpreter should make any state queries through this object
+ * 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.
  *
- * 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
+ * Manages merging of successful/reverted child state into current state.
  */
-export class AvmWorldStateJournal {
+export class AvmPersistableStateManager {
   /** 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[][] = [];
+  /** World State */
+  /** Public storage, including cached writes */
+  private publicStorage: PublicStorage;
+  /** Nullifier set, including cached/recently-emitted nullifiers */
+  private nullifiers: Nullifiers;
 
-  // contract address -> key -> value
-  private currentStorageValue: Map<bigint, Map<bigint, Fr>> = new Map();
+  /** World State Access Trace */
+  private trace: WorldStateAccessTrace;
 
-  private parentJournal: AvmWorldStateJournal | undefined;
+  /** Accrued Substate **/
+  private newL1Messages: L2ToL1Message[] = [];
+  private newLogs: UnencryptedL2Log[] = [];
 
-  constructor(hostStorage: HostStorage, parentJournal?: AvmWorldStateJournal) {
+  constructor(hostStorage: HostStorage, parent?: AvmPersistableStateManager) {
     this.hostStorage = hostStorage;
-    this.parentJournal = parentJournal;
+    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 world state journal forked from this one
+   * Create a new state manager forked from this one
    */
   public fork() {
-    return new AvmWorldStateJournal(this.hostStorage, this);
+    return new AvmPersistableStateManager(this.hostStorage, this);
   }
 
   /**
-   * Write storage into journal
+   * Write to public storage, journal/trace the write.
    *
-   * @param contractAddress -
-   * @param key -
-   * @param value -
+   * @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(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);
+  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 storage from journal
-   * Read from host storage on cache miss
+   * Read from public storage, trace the read.
    *
-   * @param contractAddress -
-   * @param key -
-   * @returns current value
+   * @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(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);
+  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.
   /**
-   * 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 -
+   * 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
    */
-  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);
-    }
+  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);
+  }
 
-    let accessArray = contractMap.get(key.toBigInt());
-    if (!accessArray) {
-      accessArray = new Array<Fr>();
-      contractMap.set(key.toBigInt(), accessArray);
-    }
-    accessArray.push(value);
+  /**
+   * 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);
   }
 
-  // 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);
+  /**
+   * 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);
+  }
 
-  public writeNoteHash(noteHash: Fr) {
-    this.newNoteHashes.push(noteHash);
+  /**
+   * 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);
   }
 
-  public writeL1Message(message: Fr[]) {
-    this.newL1Messages.push(message);
+  /**
+   * 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);
   }
 
-  public writeNullifier(nullifier: Fr) {
-    this.newNullifiers.push(nullifier);
+  /**
+   * 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(log: Fr[]) {
-    this.newLogs.push(log);
+  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, 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
+   * Accept nested world state modifications, merging in its trace and accrued substate
    */
-  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);
+  public acceptNestedCallState(nestedJournal: AvmPersistableStateManager) {
+    // Merge Public Storage
+    this.publicStorage.acceptAndMerge(nestedJournal.publicStorage);
 
-    // Merge Public State
-    mergeCurrentValueMaps(this.currentStorageValue, nestedJournal.currentStorageValue);
+    // Merge World State Access Trace
+    this.trace.acceptAndMerge(nestedJournal.trace);
 
-    // Merge storage read and write journals
-    mergeContractJournalMaps(this.storageReads, nestedJournal.storageReads);
-    mergeContractJournalMaps(this.storageWrites, nestedJournal.storageWrites);
+    // Accrued Substate
+    this.newL1Messages = this.newL1Messages.concat(nestedJournal.newL1Messages);
+    this.newLogs = this.newLogs.concat(nestedJournal.newLogs);
   }
 
   /**
-   * 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
+   * Reject nested world state, merging in its trace, but not accepting any state modifications
    */
-  public rejectNestedWorldState(nestedJournal: AvmWorldStateJournal) {
-    // Merge storage read and write journals
-    mergeContractJournalMaps(this.storageReads, nestedJournal.storageReads);
-    mergeContractJournalMaps(this.storageWrites, nestedJournal.storageWrites);
+  public rejectNestedCallState(nestedJournal: AvmPersistableStateManager) {
+    // Merge World State Access Trace
+    this.trace.acceptAndMerge(nestedJournal.trace);
   }
 
   /**
@@ -191,76 +216,16 @@ export class AvmWorldStateJournal {
    */
   public flush(): JournalData {
     return {
-      newNoteHashes: this.newNoteHashes,
-      newNullifiers: this.newNullifiers,
+      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.currentStorageValue,
-      storageReads: this.storageReads,
-      storageWrites: this.storageWrites,
+      currentStorageValue: this.publicStorage.getCache().cachePerContract,
+      storageReads: this.trace.publicStorageReads,
+      storageWrites: this.trace.publicStorageWrites,
     };
   }
 }
-
-/**
- * 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/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';
+  }
+}