@aztec/simulator 0.24.0 → 0.26.2

package/dest/avm/journal/journal.js

@@ -1,139 +1,154 @@
+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 { Nullifiers } from './nullifiers.js';
+import { PublicStorage } from './public_storage.js';
+import { WorldStateAccessTrace } from './trace.js';
 /**
- * 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.
  *
- * 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
+ * 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 AvmWorldStateJournal {
-    constructor(hostStorage, parentJournal) {
-        // Reading state - must be tracked for vm execution
-        // contract address -> key -> value[] (array stored in order of reads)
-        this.storageReads = new Map();
-        this.storageWrites = new Map();
-        // New written state
-        this.newNoteHashes = [];
-        this.newNullifiers = [];
-        // New Substate
+export class AvmPersistableStateManager {
+    constructor(hostStorage, parent) {
+        /** Accrued Substate **/
         this.newL1Messages = [];
         this.newLogs = [];
-        // contract address -> key -> value
-        this.currentStorageValue = new Map();
-        // Create an instance of journalUpdate that appends to the read array
-        this.journalRead = this.journalUpdate.bind(this, this.storageReads);
-        // Create an instance of journalUpdate that appends to the writes array
-        this.journalWrite = this.journalUpdate.bind(this, this.storageWrites);
         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
      */
     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
      */
-    writeStorage(contractAddress, key, value) {
-        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);
+    writeStorage(storageAddress, slot, value) {
+        // 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
      */
-    async readStorage(contractAddress, key) {
-        // - 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);
+    async readStorage(storageAddress, slot) {
+        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, contractAddress, key, value) {
-        let contractMap = map.get(contractAddress.toBigInt());
-        if (!contractMap) {
-            contractMap = new Map();
-            map.set(contractAddress.toBigInt(), contractMap);
-        }
-        let accessArray = contractMap.get(key.toBigInt());
-        if (!accessArray) {
-            accessArray = new Array();
-            contractMap.set(key.toBigInt(), accessArray);
-        }
-        accessArray.push(value);
+    async checkNoteHashExists(storageAddress, noteHash, leafIndex) {
+        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
+     */
     writeNoteHash(noteHash) {
-        this.newNoteHashes.push(noteHash);
+        this.trace.traceNewNoteHash(/*storageAddress*/ Fr.ZERO, noteHash);
     }
-    writeL1Message(message) {
-        this.newL1Messages.push(message);
+    /**
+     * 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
+     */
+    async checkNullifierExists(storageAddress, nullifier) {
+        const [exists, isPending, leafIndex] = await this.nullifiers.checkExists(storageAddress, nullifier);
+        this.trace.traceNullifierCheck(storageAddress, nullifier, exists, isPending, leafIndex);
+        return Promise.resolve(exists);
     }
-    writeNullifier(nullifier) {
-        this.newNullifiers.push(nullifier);
+    /**
+     * 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
+     */
+    async writeNullifier(storageAddress, nullifier) {
+        // Cache pending nullifiers for later access
+        await this.nullifiers.append(storageAddress, nullifier);
+        // Trace all nullifier creations (even reverted ones)
+        this.trace.traceNewNullifier(storageAddress, nullifier);
     }
-    writeLog(log) {
-        this.newLogs.push(log);
+    /**
+     * 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
+     */
+    async checkL1ToL2MessageExists(msgHash, msgLeafIndex) {
+        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);
     }
     /**
-     * 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
+     * Write an L2 to L1 message.
+     * @param recipient - L1 contract address to send the message to.
+     * @param content - Message content.
      */
-    acceptNestedWorldState(nestedJournal) {
-        // Merge UTXOs
-        this.newNoteHashes = this.newNoteHashes.concat(nestedJournal.newNoteHashes);
+    writeL1Message(recipient, content) {
+        const recipientAddress = recipient instanceof EthAddress ? recipient : EthAddress.fromField(recipient);
+        this.newL1Messages.push(new L2ToL1Message(recipientAddress, content));
+    }
+    writeLog(contractAddress, event, log) {
+        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
+     */
+    acceptNestedCallState(nestedJournal) {
+        // 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.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
+     * Reject nested world state, merging in its trace, but not accepting any state modifications
      */
-    rejectNestedWorldState(nestedJournal) {
-        // Merge storage read and write journals
-        mergeContractJournalMaps(this.storageReads, nestedJournal.storageReads);
-        mergeContractJournalMaps(this.storageWrites, nestedJournal.storageWrites);
+    rejectNestedCallState(nestedJournal) {
+        // Merge World State Access Trace
+        this.trace.acceptAndMerge(nestedJournal.trace);
     }
     /**
      * Access the current state of the journal
@@ -142,76 +157,17 @@ export class AvmWorldStateJournal {
      */
     flush() {
         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, childMap) {
-    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, childMap) {
-    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, childMap) {
-    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, childMap) {
-    for (const [key, value] of childMap) {
-        const readArr = hostMap.get(key);
-        if (!readArr) {
-            hostMap.set(key, value);
-        }
-        else {
-            hostMap.set(key, readArr?.concat(...value));
-        }
-    }
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiam91cm5hbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9hdm0vam91cm5hbC9qb3VybmFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNCQTs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxPQUFPLG9CQUFvQjtJQXNCL0IsWUFBWSxXQUF3QixFQUFFLGFBQW9DO1FBbEIxRSxtREFBbUQ7UUFDbkQsc0VBQXNFO1FBQzlELGlCQUFZLEdBQW1DLElBQUksR0FBRyxFQUFFLENBQUM7UUFDekQsa0JBQWEsR0FBbUMsSUFBSSxHQUFHLEVBQUUsQ0FBQztRQUVsRSxvQkFBb0I7UUFDWixrQkFBYSxHQUFTLEVBQUUsQ0FBQztRQUN6QixrQkFBYSxHQUFTLEVBQUUsQ0FBQztRQUVqQyxlQUFlO1FBQ1Asa0JBQWEsR0FBVyxFQUFFLENBQUM7UUFDM0IsWUFBTyxHQUFXLEVBQUUsQ0FBQztRQUU3QixtQ0FBbUM7UUFDM0Isd0JBQW1CLEdBQWlDLElBQUksR0FBRyxFQUFFLENBQUM7UUFvRnRFLHFFQUFxRTtRQUM3RCxnQkFBVyxHQUFHLElBQUksQ0FBQyxhQUFhLENBQUMsSUFBSSxDQUFDLElBQUksRUFBRSxJQUFJLENBQUMsWUFBWSxDQUFDLENBQUM7UUFDdkUsdUVBQXVFO1FBQy9ELGlCQUFZLEdBQUcsSUFBSSxDQUFDLGFBQWEsQ0FBQyxJQUFJLENBQUMsSUFBSSxFQUFFLElBQUksQ0FBQyxhQUFhLENBQUMsQ0FBQztRQWxGdkUsSUFBSSxDQUFDLFdBQVcsR0FBRyxXQUFXLENBQUM7UUFDL0IsSUFBSSxDQUFDLGFBQWEsR0FBRyxhQUFhLENBQUM7SUFDckMsQ0FBQztJQUVEOztPQUVHO0lBQ0ksSUFBSTtRQUNULE9BQU8sSUFBSSxvQkFBb0IsQ0FBQyxJQUFJLENBQUMsV0FBVyxFQUFFLElBQUksQ0FBQyxDQUFDO0lBQzFELENBQUM7SUFFRDs7Ozs7O09BTUc7SUFDSSxZQUFZLENBQUMsZUFBbUIsRUFBRSxHQUFPLEVBQUUsS0FBUztR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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiam91cm5hbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9hdm0vam91cm5hbC9qb3VybmFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBQ3hELE9BQU8sRUFBRSxZQUFZLEVBQUUsVUFBVSxFQUFFLGFBQWEsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQzdFLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN0RCxPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFHOUMsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQzdDLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNwRCxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxZQUFZLENBQUM7QUF5Qm5EOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxPQUFPLDBCQUEwQjtJQWlCckMsWUFBWSxXQUF3QixFQUFFLE1BQW1DO1FBSnpFLHdCQUF3QjtRQUNoQixrQkFBYSxHQUFvQixFQUFFLENBQUM7UUFDcEMsWUFBTyxHQUF1QixFQUFFLENBQUM7UUFHdkMsSUFBSSxDQUFDLFdBQVcsR0FBRyxXQUFXLENBQUM7UUFDL0IsSUFBSSxDQUFDLGFBQWEsR0FBRyxJQUFJLGFBQWEsQ0FBQyxXQUFXLENBQUMsYUFBYSxFQUFFLE1BQU0sRUFBRSxhQUFhLENBQUMsQ0FBQztRQUN6RixJQUFJLENBQUMsVUFBVSxHQUFHLElBQUksVUFBVSxDQUFDLFdBQVcsQ0FBQyxhQUFhLEVBQUUsTUFBTSxFQUFFLFVBQVUsQ0FBQyxDQUFDO1FBQ2hGLElBQUksQ0FBQyxLQUFLLEdBQUcsSUFBSSxxQkFBcUIsQ0FBQyxNQUFNLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDeEQsQ0FBQztJQUVEOztPQUVHO0lBQ0ksSUFBSTtRQUNULE9BQU8s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

package/dest/avm/journal/nullifiers.d.ts

@@ -0,0 +1,85 @@
+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 declare class Nullifiers {
+    /** Cached nullifiers. */
+    private cache;
+    /** Parent's nullifier cache. Checked on cache-miss. */
+    private readonly parentCache;
+    /** Reference to node storage. Checked on parent cache-miss. */
+    private readonly hostNullifiers;
+    constructor(hostNullifiers: CommitmentsDB, parent?: Nullifiers);
+    /**
+     * 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).
+     */
+    checkExists(storageAddress: Fr, nullifier: Fr): Promise<[/*exists=*/ boolean, /*isPending=*/ boolean, /*leafIndex=*/ Fr]>;
+    /**
+     * 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
+     */
+    append(storageAddress: Fr, nullifier: Fr): Promise<void>;
+    /**
+     * Merges another nullifier cache into this one.
+     *
+     * @param incomingNullifiers - the incoming cached nullifiers to merge into this instance's
+     */
+    acceptAndMerge(incomingNullifiers: Nullifiers): void;
+}
+/**
+ * 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 declare class NullifierCache {
+    /**
+     * Map for staging nullifiers.
+     * One inner-set per contract storage address,
+     * each entry being a nullifier.
+     */
+    private cachePerContract;
+    /**
+     * 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
+     */
+    exists(storageAddress: Fr, nullifier: Fr): boolean;
+    /**
+     * 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
+     */
+    append(storageAddress: Fr, nullifier: Fr): void;
+    /**
+     * 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
+     */
+    acceptAndMerge(incomingNullifiers: NullifierCache): void;
+}
+export declare class NullifierCollisionError extends Error {
+    constructor(message: string, ...rest: any[]);
+}
+//# sourceMappingURL=nullifiers.d.ts.map

package/dest/avm/journal/nullifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nullifiers.d.ts","sourceRoot":"","sources":["../../../src/avm/journal/nullifiers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAE9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,yBAAyB;IACzB,OAAO,CAAC,KAAK,CAAiB;IAC9B,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;gBAEnC,cAAc,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,UAAU;IAM9D;;;;;;;;;;;;OAYG;IACU,WAAW,CACtB,cAAc,EAAE,EAAE,EAClB,SAAS,EAAE,EAAE,GACZ,OAAO,CAAC,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;IAmB5E;;;;;OAKG;IACU,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE;IAUrD;;;;OAIG;IACI,cAAc,CAAC,kBAAkB,EAAE,UAAU;CAGrD;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAuC;IAE/D;;;;;;OAMG;IACI,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,GAAG,OAAO;IAKzD;;;;;OAKG;IACI,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE;IAe/C;;;;;;;;OAQG;IACI,cAAc,CAAC,kBAAkB,EAAE,cAAc;CAsBzD;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;CAI5C"}

package/dest/avm/journal/nullifiers.js

@@ -0,0 +1,147 @@
+import { siloNullifier } from '@aztec/circuits.js/hash';
+import { Fr } from '@aztec/foundation/fields';
+/**
+ * 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 {
+    constructor(hostNullifiers, parent) {
+        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).
+     */
+    async checkExists(storageAddress, nullifier) {
+        // 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 = 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
+     */
+    async append(storageAddress, nullifier) {
+        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
+     */
+    acceptAndMerge(incomingNullifiers) {
+        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 {
+    constructor() {
+        /**
+         * Map for staging nullifiers.
+         * One inner-set per contract storage address,
+         * each entry being a nullifier.
+         */
+        this.cachePerContract = 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
+     */
+    exists(storageAddress, nullifier) {
+        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
+     */
+    append(storageAddress, nullifier) {
+        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
+     */
+    acceptAndMerge(incomingNullifiers) {
+        // 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, ...rest) {
+        super(message, ...rest);
+        this.name = 'NullifierCollisionError';
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibnVsbGlmaWVycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9hdm0vam91cm5hbC9udWxsaWZpZXJzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUN4RCxPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFJOUM7Ozs7R0FJRztBQUNILE1BQU0sT0FBTyxVQUFVO0lBUXJCLFlBQVksY0FBNkIsRUFBRSxNQUFtQjtRQUM1RCxJQUFJLENBQUMsY0FBYyxHQUFHLGNBQWMsQ0FBQztRQUNyQyxJQUFJLENBQUMsV0FBVyxHQUFHLE1BQU0sRUFBRSxLQUFLLENBQUM7UUFDakMsSUFBSSxDQUFDLEtBQUssR0FBRyxJQUFJLGNBQWMsRUFBRSxDQUFDO0lBQ3BDLENBQUM7SUFFRDs7Ozs7Ozs7Ozs7O09BWUc7SUFDSSxLQUFLLENBQUMsV0FBVyxDQUN0QixjQUFrQixFQUNsQixTQUFhO1FBRWIseUJBQXlCO1FBQ3pCLElBQUksZUFBZSxHQUFHLElBQUksQ0FBQyxLQUFLLENBQUMsTUFBTSxDQUFDLGNBQWMsRUFBRSxTQUFTLENBQUMsQ0FBQztRQUNuRSw0QkFBNEI7UUFDNUIsSUFBSSxDQUFDLGVBQWUsSUFBSSxJQUFJLENBQUMsV0FBVyxFQUFFLENBQUM7WUFDekMsZUFBZSxHQUFHLElBQUksQ0FBQyxXQUFXLEVBQUUsTUFBTSxDQUFDLGNBQWMsRUFBRSxTQUFTLENBQUMsQ0FBQztRQUN4RSxDQUFDO1FBQ0QsOERBQThEO1FBQzlELGtGQUFrRjtRQUNsRixJQUFJLFNBQVMsR0FBdUIsU0FBUyxDQUFDO1FBQzlDLElBQUksQ0FBQyxlQUFlLEVBQUUsQ0FBQztZQUNyQixtRUFBbUU7WUFDbkUsU0FBUyxHQUFHLE1BQU0sSUFBSSxDQUFDLGNBQWMsQ0FBQyxpQkFBaUIsQ0FBQyxhQUFhLENBQUMsY0FBYyxFQUFFLFNBQVMsQ0FBQyxDQUFD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