@aztec/simulator 0.76.4 → 0.77.0-testnet-ignition.21

package/dest/public/avm/journal/journal.js

@@ -0,0 +1,486 @@
+import { CANONICAL_AUTH_REGISTRY_ADDRESS, DEPLOYER_CONTRACT_ADDRESS, FEE_JUICE_ADDRESS, MULTI_CALL_ENTRYPOINT_ADDRESS, REGISTERER_CONTRACT_ADDRESS, ROUTER_ADDRESS } from '@aztec/constants';
+import { poseidon2Hash } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { createLogger } from '@aztec/foundation/log';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { AvmPublicDataReadTreeHint, PublicDataWrite } from '@aztec/stdlib/avm';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { SerializableContractInstance } from '@aztec/stdlib/contract';
+import { computeNoteHashNonce, computePublicDataTreeLeafSlot, computeUniqueNoteHash, siloNoteHash, siloNullifier } from '@aztec/stdlib/hash';
+import { SharedMutableValues, SharedMutableValuesWithHash } from '@aztec/stdlib/shared-mutable';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+import { strict as assert } from 'assert';
+import cloneDeep from 'lodash.clonedeep';
+import { getPublicFunctionDebugName } from '../../../common/debug_fn_name.js';
+import { NullifierCollisionError, NullifierManager } from './nullifiers.js';
+import { PublicStorage } from './public_storage.js';
+/**
+ * A class to manage persistable AVM state for contract calls.
+ * Maintains a cache of the current world state,
+ * a trace of all side effects.
+ *
+ * The simulator should make any world state / tree queries through this object.
+ *
+ * Manages merging of successful/reverted child state into current state.
+ */ export class AvmPersistableStateManager {
+    worldStateDB;
+    trace;
+    publicStorage;
+    nullifiers;
+    doMerkleOperations;
+    db;
+    firstNullifier;
+    log;
+    /** Make sure a forked state is never merged twice. */ alreadyMergedIntoParent;
+    constructor(/** Reference to node storage */ worldStateDB, /** Side effect trace */ // TODO(5818): make private once no longer accessed in executor
+    trace, /** Public storage, including cached writes */ publicStorage = new PublicStorage(worldStateDB), /** Nullifier set, including cached/recently-emitted nullifiers */ nullifiers = new NullifierManager(worldStateDB), doMerkleOperations = false, /** DB interface for merkle tree operations */ db, firstNullifier){
+        this.worldStateDB = worldStateDB;
+        this.trace = trace;
+        this.publicStorage = publicStorage;
+        this.nullifiers = nullifiers;
+        this.doMerkleOperations = doMerkleOperations;
+        this.db = db;
+        this.firstNullifier = firstNullifier;
+        this.log = createLogger('simulator:avm:state_manager');
+        this.alreadyMergedIntoParent = false;
+    }
+    /**
+   * Create a new state manager
+   */ static create(worldStateDB, trace, doMerkleOperations = false, firstNullifier) {
+        // TODO(dbanks12): temporary until we establish a better world state interface
+        const db = worldStateDB.getMerkleInterface();
+        return new AvmPersistableStateManager(worldStateDB, trace, /*publicStorage=*/ new PublicStorage(worldStateDB), /*nullifiers=*/ new NullifierManager(worldStateDB), /*doMerkleOperations=*/ doMerkleOperations, db, firstNullifier);
+    }
+    /**
+   * Create a new state manager forked from this one
+   */ async fork() {
+        await this.worldStateDB.createCheckpoint();
+        return new AvmPersistableStateManager(this.worldStateDB, this.trace.fork(), this.publicStorage.fork(), this.nullifiers.fork(), this.doMerkleOperations, this.db, this.firstNullifier);
+    }
+    /**
+   * Accept forked world state modifications & traced side effects / hints
+   */ async merge(forkedState) {
+        await this._merge(forkedState, /*reverted=*/ false);
+    }
+    /**
+   * Reject forked world state modifications & traced side effects, keep traced hints
+   */ async reject(forkedState) {
+        await this._merge(forkedState, /*reverted=*/ true);
+    }
+    async _merge(forkedState, reverted) {
+        // sanity check to avoid merging the same forked trace twice
+        assert(!forkedState.alreadyMergedIntoParent, 'Cannot merge forked state that has already been merged into its parent!');
+        forkedState.alreadyMergedIntoParent = true;
+        this.publicStorage.acceptAndMerge(forkedState.publicStorage);
+        this.nullifiers.acceptAndMerge(forkedState.nullifiers);
+        this.trace.merge(forkedState.trace, reverted);
+        if (reverted) {
+            await this.worldStateDB.revertCheckpoint();
+            if (this.doMerkleOperations) {
+                this.log.trace(`Rolled back nullifier tree to root ${new Fr((await this.db.getTreeInfo(MerkleTreeId.NULLIFIER_TREE)).root)}`);
+            }
+        } else {
+            this.log.trace('Merging forked state into parent...');
+            await this.worldStateDB.commitCheckpoint();
+        }
+    }
+    /**
+   * Write to public storage, journal/trace the write.
+   *
+   * @param contractAddress - 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
+   */ async writeStorage(contractAddress, slot, value, protocolWrite = false) {
+        const leafSlot = await computePublicDataTreeLeafSlot(contractAddress, slot);
+        this.log.trace(`Storage write (address=${contractAddress}, slot=${slot}): value=${value}, leafSlot=${leafSlot}`);
+        if (this.doMerkleOperations) {
+            // write to native merkle trees
+            const publicDataWrite = new PublicDataWrite(leafSlot, value);
+            const result = await this.db.sequentialInsert(MerkleTreeId.PUBLIC_DATA_TREE, [
+                publicDataWrite.toBuffer()
+            ]);
+            assert(result !== undefined, 'Public data tree insertion error. You might want to disable doMerkleOperations.');
+            this.log.trace(`Inserted public data tree leaf at leafSlot ${leafSlot}, value: ${value}`);
+            // low leaf hint
+            const lowLeafPreimage = result.lowLeavesWitnessData[0].leafPreimage;
+            const lowLeafIndex = result.lowLeavesWitnessData[0].index;
+            const lowLeafPath = result.lowLeavesWitnessData[0].siblingPath.toFields();
+            // new leaf insertion
+            const newLeafPreimage = cloneDeep(lowLeafPreimage);
+            let insertionPath;
+            if (result.insertionWitnessData.length === 0) {
+                assert(newLeafPreimage.value.equals(value), `Value mismatch when performing public data write (got value: ${value}, value in tree: ${newLeafPreimage.value})`);
+            } else {
+                // The new leaf preimage should have the new value and slot
+                newLeafPreimage.slot = leafSlot;
+                newLeafPreimage.value = value;
+                // TODO: is this necessary?! Why doesn't sequentialInsert return the newLeafPreimage via
+                // result.insertionWitnessData[0].leafPreimage?
+                this.log.trace(`newLeafPreimage.slot: ${newLeafPreimage.slot}, newLeafPreimage.value: ${newLeafPreimage.value}, insertionIndex: ${result.insertionWitnessData[0].index}`);
+                insertionPath = result.insertionWitnessData[0].siblingPath.toFields();
+            }
+            await this.trace.tracePublicStorageWrite(contractAddress, slot, value, protocolWrite, lowLeafPreimage, new Fr(lowLeafIndex), lowLeafPath, newLeafPreimage, insertionPath);
+        } else {
+            // Cache storage writes for later reference/reads
+            this.publicStorage.write(contractAddress, slot, value);
+            await this.trace.tracePublicStorageWrite(contractAddress, slot, value, protocolWrite);
+        }
+    }
+    /**
+   * Read from public storage, trace the read.
+   *
+   * @param contractAddress - 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, slot) {
+        if (this.doMerkleOperations) {
+            const { value, leafPreimage, leafIndex, leafPath } = await this.getPublicDataMembership(contractAddress, slot);
+            this.trace.tracePublicStorageRead(contractAddress, slot, value, leafPreimage, leafIndex, leafPath);
+            return value;
+        } else {
+            const read = await this.publicStorage.read(contractAddress, slot);
+            this.log.trace(`Storage read results (address=${contractAddress}, slot=${slot}): value=${read.value}, cached=${read.cached}`);
+            this.trace.tracePublicStorageRead(contractAddress, slot, read.value);
+            return read.value;
+        }
+    }
+    async getPublicDataMembership(contractAddress, slot) {
+        const leafSlot = await computePublicDataTreeLeafSlot(contractAddress, slot);
+        const treeId = MerkleTreeId.PUBLIC_DATA_TREE;
+        // Get leaf if present, low leaf if absent
+        // If leaf is present, hint/trace it. Otherwise, hint/trace the low leaf.
+        const { preimage, leafOrLowLeafIndex, alreadyPresent } = await this.getLeafOrLowLeafInfo(treeId, leafSlot.toBigInt());
+        // The index and preimage here is either the low leaf or the leaf itself (depending on the value of update flag)
+        // In either case, we just want the sibling path to this leaf - it's up to the avm to distinguish if it's a low leaf or not
+        const leafPath = await this.db.getSiblingPath(MerkleTreeId.PUBLIC_DATA_TREE, leafOrLowLeafIndex);
+        const leafPreimage = preimage;
+        const value = alreadyPresent ? leafPreimage.value : Fr.zero(); // default value of 0
+        if (!alreadyPresent) {
+            this.log.trace(`Slot has never been written before!`);
+            // Sanity check that the leaf slot is skipped by low leaf when it doesn't exist
+            assert(leafPreimage.slot.toBigInt() < leafSlot.toBigInt() && (leafPreimage.nextIndex === 0n || leafPreimage.nextSlot.toBigInt() > leafSlot.toBigInt()), 'Public data tree low leaf should skip the target leaf slot when the target leaf does not exist or is the max value.');
+        }
+        this.log.trace(`Storage read results (address=${contractAddress}, slot=${slot}, leafSlot=${leafSlot}): value=${value}, previouslyWritten=${alreadyPresent}`);
+        return {
+            value,
+            leafPreimage,
+            leafIndex: new Fr(leafOrLowLeafIndex),
+            leafPath: leafPath.toFields()
+        };
+    }
+    /**
+   * Read from public storage, don't trace the read.
+   *
+   * @param contractAddress - 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 peekStorage(contractAddress, slot) {
+        const { value, cached } = await this.publicStorage.read(contractAddress, slot);
+        this.log.trace(`Storage peek  (address=${contractAddress}, slot=${slot}): value=${value},  cached=${cached}`);
+        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 contractAddress - 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
+   */ async checkNoteHashExists(contractAddress, noteHash, leafIndex) {
+        const gotLeafValue = await this.worldStateDB.getCommitmentValue(leafIndex.toBigInt()) ?? Fr.ZERO;
+        const exists = gotLeafValue.equals(noteHash);
+        this.log.trace(`noteHashes(${contractAddress})@${noteHash} ?? leafIndex: ${leafIndex} | gotLeafValue: ${gotLeafValue}, exists: ${exists}.`);
+        if (this.doMerkleOperations) {
+            const path = await this.db.getSiblingPath(MerkleTreeId.NOTE_HASH_TREE, leafIndex.toBigInt());
+            this.trace.traceNoteHashCheck(contractAddress, gotLeafValue, leafIndex, exists, path.toFields());
+        } else {
+            this.trace.traceNoteHashCheck(contractAddress, gotLeafValue, leafIndex, exists);
+        }
+        return Promise.resolve(exists);
+    }
+    /**
+   * Write a raw note hash, silo it and make it unique, then trace the write.
+   * @param noteHash - the unsiloed note hash to write
+   */ async writeNoteHash(contractAddress, noteHash) {
+        this.log.trace(`noteHashes(${contractAddress}) += ${noteHash}.`);
+        const siloedNoteHash = await siloNoteHash(contractAddress, noteHash);
+        await this.writeSiloedNoteHash(siloedNoteHash);
+    }
+    /**
+   * Write a note hash, make it unique, trace the write.
+   * @param siloedNoteHash - the non unique note hash to write
+   */ async writeSiloedNoteHash(siloedNoteHash) {
+        const nonce = await computeNoteHashNonce(this.firstNullifier, this.trace.getNoteHashCount());
+        const uniqueNoteHash = await computeUniqueNoteHash(nonce, siloedNoteHash);
+        await this.writeUniqueNoteHash(uniqueNoteHash);
+    }
+    /**
+   * Write a note hash, trace the write.
+   * @param uniqueNoteHash - the siloed unique hash to write
+   */ async writeUniqueNoteHash(uniqueNoteHash) {
+        this.log.trace(`noteHashes += @${uniqueNoteHash}.`);
+        if (this.doMerkleOperations) {
+            // Should write a helper for this
+            const treeInfo = await this.db.getTreeInfo(MerkleTreeId.NOTE_HASH_TREE);
+            const leafIndex = new Fr(treeInfo.size);
+            await this.db.appendLeaves(MerkleTreeId.NOTE_HASH_TREE, [
+                uniqueNoteHash
+            ]);
+            const insertionPath = await this.db.getSiblingPath(MerkleTreeId.NOTE_HASH_TREE, leafIndex.toBigInt());
+            this.trace.traceNewNoteHash(uniqueNoteHash, leafIndex, insertionPath.toFields());
+        } else {
+            this.trace.traceNewNoteHash(uniqueNoteHash);
+        }
+    }
+    /**
+   * Check if a nullifier exists, trace the check.
+   * @param contractAddress - 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(contractAddress, nullifier) {
+        this.log.trace(`Checking existence of nullifier (address=${contractAddress}, nullifier=${nullifier})`);
+        const siloedNullifier = await siloNullifier(contractAddress, nullifier);
+        if (this.doMerkleOperations) {
+            const { exists, leafOrLowLeafPreimage, leafOrLowLeafIndex, leafOrLowLeafPath } = await this.getNullifierMembership(siloedNullifier);
+            this.trace.traceNullifierCheck(siloedNullifier, exists, leafOrLowLeafPreimage, new Fr(leafOrLowLeafIndex), leafOrLowLeafPath);
+            return Promise.resolve(exists);
+        } else {
+            const { exists, cacheHit } = await this.nullifiers.checkExists(siloedNullifier);
+            this.log.trace(`Checked siloed nullifier ${siloedNullifier} (exists=${exists}), cacheHit=${cacheHit}`);
+            this.trace.traceNullifierCheck(siloedNullifier, exists);
+            return Promise.resolve(exists);
+        }
+    }
+    /**
+   * Helper to get membership information for a siloed nullifier when checking its existence.
+   * Optionally trace the nullifier check.
+   *
+   * @param siloedNullifier - the siloed nullifier to get membership information for
+   * @returns
+   *     - exists - whether the nullifier exists in the nullifier set
+   *     - leafOrLowLeafPreimage - the preimage of the nullifier leaf or its low-leaf if it doesn't exist
+   *     - leafOrLowLeafIndex - the leaf index of the nullifier leaf or its low-leaf if it doesn't exist
+   *     - leafOrLowLeafPath - the sibling path of the nullifier leaf or its low-leaf if it doesn't exist
+   */ async getNullifierMembership(siloedNullifier) {
+        // Get leaf if present, low leaf if absent
+        // If leaf is present, hint/trace it. Otherwise, hint/trace the low leaf.
+        const treeId = MerkleTreeId.NULLIFIER_TREE;
+        const { preimage: leafPreimage, leafOrLowLeafIndex, alreadyPresent } = await this.getLeafOrLowLeafInfo(treeId, siloedNullifier.toBigInt());
+        this.log.trace(`Checked siloed nullifier ${siloedNullifier} (exists=${alreadyPresent})`);
+        const leafPath = await this.db.getSiblingPath(treeId, leafOrLowLeafIndex);
+        if (alreadyPresent) {
+            this.log.trace(`Siloed nullifier ${siloedNullifier} exists at leafIndex=${leafOrLowLeafIndex}`);
+        } else {
+            // Sanity check that the leaf value is skipped by low leaf when it doesn't exist
+            assert(leafPreimage.nullifier.toBigInt() < siloedNullifier.toBigInt() && (leafPreimage.nextIndex === 0n || leafPreimage.nextNullifier.toBigInt() > siloedNullifier.toBigInt()), 'Nullifier tree low leaf should skip the target leaf nullifier when the target leaf does not exist.');
+        }
+        return {
+            exists: alreadyPresent,
+            leafOrLowLeafPreimage: leafPreimage,
+            leafOrLowLeafIndex,
+            leafOrLowLeafPath: leafPath.toFields()
+        };
+    }
+    /**
+   * Write a nullifier to the nullifier set, trace the write.
+   * @param contractAddress - address of the contract that the nullifier is associated with
+   * @param nullifier - the unsiloed nullifier to write
+   */ async writeNullifier(contractAddress, nullifier) {
+        this.log.trace(`Inserting new nullifier (address=${nullifier}, nullifier=${contractAddress})`);
+        const siloedNullifier = await siloNullifier(contractAddress, nullifier);
+        await this.writeSiloedNullifier(siloedNullifier);
+    }
+    /**
+   * Write a nullifier to the nullifier set, trace the write.
+   * @param siloedNullifier - the siloed nullifier to write
+   */ async writeSiloedNullifier(siloedNullifier) {
+        this.log.trace(`Inserting siloed nullifier=${siloedNullifier}`);
+        if (this.doMerkleOperations) {
+            const treeId = MerkleTreeId.NULLIFIER_TREE;
+            const { preimage: leafPreimage, leafOrLowLeafIndex, alreadyPresent } = await this.getLeafOrLowLeafInfo(treeId, siloedNullifier.toBigInt());
+            if (alreadyPresent) {
+                this.log.verbose(`Siloed nullifier ${siloedNullifier} already present in tree at index ${leafOrLowLeafIndex}!`);
+                // If the nullifier is already present, we should not insert it again
+                // instead we provide the direct membership path
+                const membershipPath = await this.db.getSiblingPath(treeId, leafOrLowLeafIndex);
+                // This just becomes a nullifier read hint
+                this.trace.traceNullifierCheck(siloedNullifier, /*exists=*/ alreadyPresent, leafPreimage, new Fr(leafOrLowLeafIndex), membershipPath.toFields());
+                throw new NullifierCollisionError(`Siloed nullifier ${siloedNullifier} already exists in parent cache or host.`);
+            } else {
+                const appendResult = await this.db.sequentialInsert(treeId, [
+                    siloedNullifier.toBuffer()
+                ]);
+                const lowLeafWitnessData = appendResult.lowLeavesWitnessData[0];
+                const lowLeafPreimage = lowLeafWitnessData.leafPreimage;
+                const lowLeafIndex = lowLeafWitnessData.index;
+                const lowLeafPath = lowLeafWitnessData.siblingPath.toFields();
+                const insertionPath = appendResult.insertionWitnessData[0].siblingPath.toFields();
+                this.trace.traceNewNullifier(siloedNullifier, lowLeafPreimage, new Fr(lowLeafIndex), lowLeafPath, insertionPath);
+            }
+        } else {
+            // Cache pending nullifiers for later access
+            await this.nullifiers.append(siloedNullifier);
+            this.trace.traceNewNullifier(siloedNullifier);
+        }
+    }
+    async writeSiloedNullifiersFromPrivate(siloedNullifiers) {
+        for (const siloedNullifier of siloedNullifiers.filter((n)=>!n.isEmpty())){
+            await this.writeSiloedNullifier(siloedNullifier);
+        }
+    }
+    /**
+   * 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(contractAddress, msgHash, msgLeafIndex) {
+        const valueAtIndex = await this.worldStateDB.getL1ToL2LeafValue(msgLeafIndex.toBigInt()) ?? Fr.ZERO;
+        const exists = valueAtIndex.equals(msgHash);
+        this.log.trace(`l1ToL2Messages(@${msgLeafIndex}) ?? exists: ${exists}, expected: ${msgHash}, found: ${valueAtIndex}.`);
+        if (this.doMerkleOperations) {
+            const path = await this.db.getSiblingPath(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, msgLeafIndex.toBigInt());
+            this.trace.traceL1ToL2MessageCheck(contractAddress, valueAtIndex, msgLeafIndex, exists, path.toFields());
+        } else {
+            this.trace.traceL1ToL2MessageCheck(contractAddress, valueAtIndex, msgLeafIndex, exists);
+        }
+        return Promise.resolve(exists);
+    }
+    /**
+   * Write an L2 to L1 message.
+   * @param contractAddress - L2 contract address that created this message
+   * @param recipient - L1 contract address to send the message to.
+   * @param content - Message content.
+   */ writeL2ToL1Message(contractAddress, recipient, content) {
+        this.log.trace(`L2ToL1Messages(${contractAddress}) += (recipient: ${recipient}, content: ${content}).`);
+        this.trace.traceNewL2ToL1Message(contractAddress, recipient, content);
+    }
+    /**
+   * Write a public log
+   * @param contractAddress - address of the contract that emitted the log
+   * @param log - log contents
+   */ writePublicLog(contractAddress, log) {
+        this.log.trace(`PublicLog(${contractAddress}) += event with ${log.length} fields.`);
+        this.trace.tracePublicLog(contractAddress, log);
+    }
+    /**
+   * Get a contract instance.
+   * @param contractAddress - address of the contract instance to retrieve.
+   * @returns the contract instance or undefined if it does not exist.
+   */ async getContractInstance(contractAddress) {
+        this.log.trace(`Getting contract instance for address ${contractAddress}`);
+        const instanceWithAddress = await this.worldStateDB.getContractInstance(contractAddress);
+        const exists = instanceWithAddress !== undefined;
+        const instance = exists ? new SerializableContractInstance(instanceWithAddress) : undefined;
+        if (!exists) {
+            this.log.debug(`Contract instance NOT FOUND (address=${contractAddress})`);
+            this.trace.traceGetContractInstance(contractAddress, exists);
+            return undefined;
+        }
+        this.log.trace(`Got contract instance (address=${contractAddress}): instance=${jsonStringify(instance)}`);
+        // Canonical addresses do not trigger nullifier & public storage checks
+        if (contractAddressIsCanonical(contractAddress)) {
+            this.trace.traceGetContractInstance(contractAddress, exists, instance);
+            return instance;
+        }
+        // This will decide internally whether to check the nullifier tree or not depending on doMerkleOperations.
+        const nullifierExistsInTree = await this.checkNullifierExists(AztecAddress.fromNumber(DEPLOYER_CONTRACT_ADDRESS), contractAddress.toField());
+        assert(exists == nullifierExistsInTree, 'WorldStateDB contains contract instance, but nullifier tree does not contain contract address (or vice versa).... This is a bug!');
+        if (this.doMerkleOperations) {
+            // TODO(fcarreiro): this should be done via a public read.
+            const { updateMembership, updatePreimage } = await this.getContractUpdateHints(contractAddress);
+            this.trace.traceGetContractInstance(contractAddress, exists, instance, updateMembership, updatePreimage);
+        } else {
+            this.trace.traceGetContractInstance(contractAddress, exists, instance);
+        }
+        return instance;
+    }
+    /**
+   * Get a contract class.
+   * @param classId - class id to retrieve.
+   * @returns the contract class or undefined if it does not exist.
+   */ async getContractClass(classId) {
+        this.log.trace(`Getting contract class for id ${classId}`);
+        const klass = await this.worldStateDB.getContractClass(classId);
+        const exists = klass !== undefined;
+        let extendedClass = undefined;
+        // Note: We currently do not generate info to check the nullifier tree, because
+        // this is not needed for our use cases.
+        if (exists) {
+            this.log.trace(`Got contract class (id=${classId})`);
+            // Extend class information with public bytecode commitment.
+            const bytecodeCommitment = await this.worldStateDB.getBytecodeCommitment(classId);
+            assert(bytecodeCommitment, `Bytecode commitment was not found in DB for contract class (${classId}). This should not happen!`);
+            extendedClass = {
+                ...klass,
+                publicBytecodeCommitment: bytecodeCommitment
+            };
+        } else {
+            this.log.debug(`Contract instance NOT FOUND (id=${classId})`);
+        }
+        this.trace.traceGetContractClass(classId, exists, extendedClass);
+        return extendedClass;
+    }
+    /**
+   * Get a contract's bytecode from the contracts DB, also trace the contract class and instance indirectly.
+   */ async getBytecode(contractAddress) {
+        this.log.debug(`Getting bytecode for contract address ${contractAddress}`);
+        const contractInstance = await this.getContractInstance(contractAddress);
+        if (!contractInstance) {
+            return undefined;
+        }
+        const contractClass = await this.getContractClass(contractInstance.currentContractClassId);
+        assert(contractClass, `Contract class not found in DB, but a contract instance was found with this class ID (${contractInstance.currentContractClassId}). This should not happen!`);
+        // NOTE: If the contract instance is not found, we assume it has not been deployed.
+        // It doesnt matter what the values of the contract instance are in this case, as long as we tag it with exists=false.
+        // This will hint to the avm circuit to just perform the non-membership check on the address and disregard the bytecode hash
+        return contractClass.packedBytecode;
+    }
+    async getContractUpdateHints(contractAddress) {
+        const { sharedMutableSlot, sharedMutableHashSlot } = await SharedMutableValuesWithHash.getContractUpdateSlots(contractAddress);
+        const { value: hash, leafPreimage, leafIndex, leafPath } = await this.getPublicDataMembership(ProtocolContractAddress.ContractInstanceDeployer, sharedMutableHashSlot);
+        const updateMembership = new AvmPublicDataReadTreeHint(leafPreimage, leafIndex, leafPath);
+        const readStorage = async (storageSlot)=>(await this.publicStorage.read(ProtocolContractAddress.ContractInstanceDeployer, storageSlot)).value;
+        const sharedMutableValues = await SharedMutableValues.readFromTree(sharedMutableSlot, readStorage);
+        const updatePreimage = sharedMutableValues.toFields();
+        if (!hash.isZero()) {
+            const hashed = await poseidon2Hash(updatePreimage);
+            if (!hashed.equals(hash)) {
+                throw new Error(`Update hint hash mismatch: ${hash} != ${hashed}`);
+            }
+            this.log.trace(`Non empty update hint found for contract ${contractAddress}`);
+        } else {
+            if (updatePreimage.some((f)=>!f.isZero())) {
+                throw new Error(`Update hint hash is zero, but update preimage is not: ${updatePreimage}`);
+            }
+            this.log.trace(`No update hint found for contract ${contractAddress}`);
+        }
+        return {
+            updateMembership,
+            updatePreimage
+        };
+    }
+    traceEnqueuedCall(publicCallRequest, calldata, reverted) {
+        this.trace.traceEnqueuedCall(publicCallRequest, calldata, reverted);
+    }
+    async getPublicFunctionDebugName(avmEnvironment) {
+        return await getPublicFunctionDebugName(this.worldStateDB, avmEnvironment.address, avmEnvironment.calldata);
+    }
+    async getLeafOrLowLeafInfo(treeId, key) {
+        // "key" is siloed slot (leafSlot) or siloed nullifier
+        const leafOrLowLeafInfo = await this.db.getPreviousValueIndex(treeId, key);
+        assert(leafOrLowLeafInfo !== undefined, `${MerkleTreeId[treeId]} low leaf index should always be found (even if target leaf does not exist)`);
+        const { index: leafOrLowLeafIndex, alreadyPresent } = leafOrLowLeafInfo;
+        const leafPreimage = await this.db.getLeafPreimage(treeId, leafOrLowLeafIndex);
+        assert(leafPreimage !== undefined, `${MerkleTreeId[treeId]}  low leaf preimage should never be undefined (even if target leaf does not exist)`);
+        return {
+            preimage: leafPreimage,
+            leafOrLowLeafIndex,
+            alreadyPresent
+        };
+    }
+}
+function contractAddressIsCanonical(contractAddress) {
+    return contractAddress.equals(AztecAddress.fromNumber(CANONICAL_AUTH_REGISTRY_ADDRESS)) || contractAddress.equals(AztecAddress.fromNumber(DEPLOYER_CONTRACT_ADDRESS)) || contractAddress.equals(AztecAddress.fromNumber(REGISTERER_CONTRACT_ADDRESS)) || contractAddress.equals(AztecAddress.fromNumber(MULTI_CALL_ENTRYPOINT_ADDRESS)) || contractAddress.equals(AztecAddress.fromNumber(FEE_JUICE_ADDRESS)) || contractAddress.equals(AztecAddress.fromNumber(ROUTER_ADDRESS));
+}

package/dest/{avm → public/avm}/journal/nullifiers.d.ts

@@ -1,5 +1,5 @@
-import { Fr } from '@aztec/foundation/fields';
-import type { CommitmentsDB } from '../../server.js';
+import type { Fr } from '@aztec/foundation/fields';
+import type { WorldStateDB } from '../../public_db_sources.js';
 /**
  * A class to manage new nullifier staging and existence checks during a contract call's AVM simulation.
  * Maintains a siloed nullifier cache, and ensures that existence checks fall back to the correct source.
@@ -14,7 +14,7 @@ export declare class NullifierManager {
     private readonly parent?;
     constructor(
     /** Reference to node storage. Checked on parent cache-miss. */
-    hostNullifiers: CommitmentsDB, 
+    hostNullifiers: WorldStateDB, 
     /** Cache of siloed nullifiers. */
     cache?: Set<bigint>, 
     /** Parent nullifier manager to fall back on */
@@ -39,10 +39,12 @@ export declare class NullifierManager {
      *
      * @param siloedNullifier - 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).
+     *          cacheHit: whether the nullifier was found in a cache,
      */
-    checkExists(siloedNullifier: Fr): Promise<[/*exists=*/ boolean, /*isPending=*/ boolean, /*leafIndex=*/ Fr]>;
+    checkExists(siloedNullifier: Fr): Promise<{
+        exists: boolean;
+        cacheHit: boolean;
+    }>;
     /**
      * Stage a new nullifier (append it to the cache).
      *

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

@@ -0,0 +1 @@
+{"version":3,"file":"nullifiers.d.ts","sourceRoot":"","sources":["../../../../src/public/avm/journal/nullifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,gBAAgB;IAEzB,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,kCAAkC;IAClC,OAAO,CAAC,KAAK;IACb,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;;IALxB,+DAA+D;IAC9C,cAAc,EAAE,YAAY;IAC7C,kCAAkC;IAC1B,KAAK,GAAE,GAAG,CAAC,MAAM,CAAa;IACtC,+CAA+C;IAC9B,MAAM,CAAC,8BAAkB;IAG5C;;OAEG;IACI,IAAI;IAIX;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;;;;;;;;OAUG;IACU,WAAW,CAAC,eAAe,EAAE,EAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAmB9F;;;;OAIG;IACU,MAAM,CAAC,eAAe,EAAE,EAAE;IAQvC;;;;OAIG;IACI,cAAc,CAAC,kBAAkB,EAAE,gBAAgB;CAU3D;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;CAI5C"}

package/dest/public/avm/journal/nullifiers.js

@@ -0,0 +1,97 @@
+/**
+ * A class to manage new nullifier staging and existence checks during a contract call's AVM simulation.
+ * Maintains a siloed 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 NullifierManager {
+    hostNullifiers;
+    cache;
+    parent;
+    constructor(/** Reference to node storage. Checked on parent cache-miss. */ hostNullifiers, /** Cache of siloed nullifiers. */ cache = new Set(), /** Parent nullifier manager to fall back on */ parent){
+        this.hostNullifiers = hostNullifiers;
+        this.cache = cache;
+        this.parent = parent;
+    }
+    /**
+   * Create a new nullifiers manager forked from this one
+   */ fork() {
+        return new NullifierManager(this.hostNullifiers, new Set(), this);
+    }
+    /**
+   * Get a nullifier's existence in this' cache or parent's (recursively).
+   * DOES NOT CHECK HOST STORAGE!
+   * @param siloedNullifier - the nullifier to check for
+   * @returns exists: whether the nullifier exists in cache here or in parent's
+   */ checkExistsHereOrParent(siloedNullifier) {
+        // First check this cache
+        let existsAsPending = this.cache.has(siloedNullifier.toBigInt());
+        // Then try parent's nullifier cache
+        if (!existsAsPending && this.parent) {
+            // Note: this will recurse to grandparent/etc until a cache-hit is encountered.
+            existsAsPending = this.parent.checkExistsHereOrParent(siloedNullifier);
+        }
+        return existsAsPending;
+    }
+    /**
+   * Get a nullifier's existence status.
+   * 1. Check cache.
+   * 2. Check parent cache.
+   * 3. Fall back to the host state.
+   * 4. Not found! Nullifier does not exist.
+   *
+   * @param siloedNullifier - the nullifier to check for
+   * @returns exists: whether the nullifier exists at all,
+   *          cacheHit: whether the nullifier was found in a cache,
+   */ async checkExists(siloedNullifier) {
+        // Check this cache and parent's (recursively)
+        const cacheHit = this.checkExistsHereOrParent(siloedNullifier);
+        let existsInTree = false;
+        if (!cacheHit) {
+            // Finally try the host's Aztec state (a trip to the database)
+            //const leafOrLowLeafIndex = await this.hostNullifiers.db.getPreviousValueIndex(MerkleTreeId.NULLIFIER_TREE, siloedNullifier.toBigInt());
+            //assert(
+            //  leafOrLowLeafIndex !== undefined,
+            //  `${MerkleTreeId[MerkleTreeId.NULLIFIER_TREE]} low leaf index should always be found (even if target leaf does not exist)`,
+            //);
+            //existsInTree = leafOrLowLeafIndex.alreadyPresent;
+            const leafIndex = await this.hostNullifiers.getNullifierIndex(siloedNullifier);
+            existsInTree = leafIndex !== undefined;
+        }
+        const exists = cacheHit || existsInTree;
+        return Promise.resolve({
+            exists,
+            cacheHit
+        });
+    }
+    /**
+   * Stage a new nullifier (append it to the cache).
+   *
+   * @param siloedNullifier - the nullifier to stage
+   */ async append(siloedNullifier) {
+        const { exists } = await this.checkExists(siloedNullifier);
+        if (exists) {
+            throw new NullifierCollisionError(`Siloed nullifier ${siloedNullifier} already exists in parent cache or host.`);
+        }
+        this.cache.add(siloedNullifier.toBigInt());
+    }
+    /**
+   * Merges another nullifier cache into this one.
+   *
+   * @param incomingNullifiers - the incoming cached nullifiers to merge into this instance's
+   */ acceptAndMerge(incomingNullifiers) {
+        for (const incomingNullifier of incomingNullifiers.cache){
+            if (this.cache.has(incomingNullifier)) {
+                throw new NullifierCollisionError(`Failed to merge in fork's cached nullifiers. Siloed nullifier ${incomingNullifier} already exists in parent cache.`);
+            }
+        }
+        this.cache = new Set([
+            ...this.cache,
+            ...incomingNullifiers.cache
+        ]);
+    }
+}
+export class NullifierCollisionError extends Error {
+    constructor(message, ...rest){
+        super(message, ...rest);
+        this.name = 'NullifierCollisionError';
+    }
+}

package/dest/{avm → public/avm}/journal/public_storage.d.ts

@@ -1,6 +1,6 @@
-import { type AztecAddress } from '@aztec/circuits.js';
 import { Fr } from '@aztec/foundation/fields';
-import type { PublicStateDB } from '../../server.js';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { PublicStateDB } from '../../../common/db_interfaces.js';
 type PublicStorageReadResult = {
     value: Fr;
     cached: boolean;

package/dest/public/avm/journal/public_storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public_storage.d.ts","sourceRoot":"","sources":["../../../../src/public/avm/journal/public_storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,0BAA0B,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE,KAAK,uBAAuB,GAAG;IAC7B,KAAK,EAAE,EAAE,CAAC;IACV,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,aAAa;IAKtB,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAP1B,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;;IAGzC,+DAA+D;IAC9C,iBAAiB,EAAE,aAAa;IACjD,qDAAqD;IACpC,MAAM,CAAC,2BAAe;IAKzC;;OAEG;IACI,IAAI;IAIX;;;;;;;OAOG;IACI,gBAAgB,CAAC,eAAe,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS;IAWhF;;;;;;;;;;OAUG;IACU,IAAI,CAAC,eAAe,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAmB5F;;;;;;OAMG;IACI,KAAK,CAAC,eAAe,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE;IAI/D;;;;OAIG;IACI,cAAc,CAAC,qBAAqB,EAAE,aAAa;CAG3D"}