@aztec/pxe 0.0.1-commit.b2a5d0dd1 → 0.0.1-commit.b3d3157a

package/dest/pxe.js

@@ -1,10 +1,10 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { createLogger } from '@aztec/foundation/log';
 import { SerialQueue } from '@aztec/foundation/queue';
 import { Timer } from '@aztec/foundation/timer';
-import { KeyStore } from '@aztec/key-store';
-import { L2TipsKVStore } from '@aztec/kv-store/stores';
 import { protocolContractNames } from '@aztec/protocol-contracts';
 import { FunctionType, decodeFunctionSignature } from '@aztec/stdlib/abi';
+import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/stdlib/block';
 import { computeContractAddressFromInstance, getContractClassFromArtifact } from '@aztec/stdlib/contract';
 import { SimulationError } from '@aztec/stdlib/errors';
 import { PrivateSimulationResult, TxProfileResult, TxProvingResult, TxSimulationResult } from '@aztec/stdlib/tx';
@@ -23,15 +23,8 @@ import { JobCoordinator } from './job_coordinator/job_coordinator.js';
 import { MessageContextService } from './messages/message_context_service.js';
 import { PrivateKernelExecutionProver } from './private_kernel/private_kernel_execution_prover.js';
 import { PrivateKernelOracle } from './private_kernel/private_kernel_oracle.js';
-import { AddressStore } from './storage/address_store/address_store.js';
-import { AnchorBlockStore } from './storage/anchor_block_store/anchor_block_store.js';
-import { CapsuleStore } from './storage/capsule_store/capsule_store.js';
-import { ContractStore } from './storage/contract_store/contract_store.js';
-import { NoteStore } from './storage/note_store/note_store.js';
-import { PrivateEventStore } from './storage/private_event_store/private_event_store.js';
-import { RecipientTaggingStore } from './storage/tagging_store/recipient_tagging_store.js';
-import { SenderAddressBookStore } from './storage/tagging_store/sender_address_book_store.js';
-import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store.js';
+import { openPxeStores } from './storage/open_pxe_stores.js';
+import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
 /**
  * Private eXecution Environment (PXE) is a library used by wallets to simulate private phase of transactions and to
  * manage private state of users.
@@ -54,13 +47,16 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
     l2TipsStore;
     simulator;
     proverEnabled;
+    autoSync;
     proofCreator;
     protocolContractsProvider;
+    preloadedContractsProvider;
     log;
     jobQueue;
     jobCoordinator;
     debug;
-    constructor(node, db, blockStateSynchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, messageContextService, l2TipsStore, simulator, proverEnabled, proofCreator, protocolContractsProvider, log, jobQueue, jobCoordinator, debug){
+    hooks;
+    constructor(node, db, blockStateSynchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, messageContextService, l2TipsStore, simulator, proverEnabled, autoSync, proofCreator, protocolContractsProvider, preloadedContractsProvider, log, jobQueue, jobCoordinator, debug, hooks){
         this.node = node;
         this.db = db;
         this.blockStateSynchronizer = blockStateSynchronizer;
@@ -79,12 +75,15 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         this.l2TipsStore = l2TipsStore;
         this.simulator = simulator;
         this.proverEnabled = proverEnabled;
+        this.autoSync = autoSync;
         this.proofCreator = proofCreator;
         this.protocolContractsProvider = protocolContractsProvider;
+        this.preloadedContractsProvider = preloadedContractsProvider;
         this.log = log;
         this.jobQueue = jobQueue;
         this.jobCoordinator = jobCoordinator;
         this.debug = debug;
+        this.hooks = hooks;
     }
     /**
    * Creates an instance of a PXE by instantiating all the necessary data providers and services.
@@ -92,26 +91,23 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * can be contacted.
    *
    * @returns A promise that resolves PXE is ready to be used.
-   */ static async create({ node, store, proofCreator, simulator, protocolContractsProvider, config, loggerOrSuffix }) {
+   */ static async create({ node, store, proofCreator, simulator, protocolContractsProvider, preloadedContractsProvider, config, loggerOrSuffix, hooks }) {
         // Extract bindings from the logger, or use empty bindings if a string suffix is provided.
         const bindings = loggerOrSuffix && typeof loggerOrSuffix !== 'string' ? loggerOrSuffix.getBindings() : undefined;
         const log = !loggerOrSuffix || typeof loggerOrSuffix === 'string' ? createLogger(loggerOrSuffix ? `pxe:service:${loggerOrSuffix}` : `pxe:service`) : loggerOrSuffix;
         const info = await node.getNodeInfo();
+        // Source the genesis block hash from the node so PXE's L2BlockStream agrees with the node's
+        // archiver on the dynamic initial header hash. Without this the tip store would fall back to
+        // the static `GENESIS_BLOCK_HEADER_HASH` constant, which only matches deployments with the
+        // default empty genesis (timestamp 0, no prefilled public data) and diverges otherwise — the
+        // sync at block 0 would then get stuck in `areBlockHashesEqualAt` and abort. If the node does
+        // not return a genesis block (older node or test fixture) we fall back to the static constant.
+        const initialBlockHash = (await node.getBlock(BlockNumber.ZERO))?.hash ?? GENESIS_BLOCK_HEADER_HASH;
         const proverEnabled = config.proverEnabled !== undefined ? config.proverEnabled : info.realProofs;
-        const addressStore = new AddressStore(store);
-        const privateEventStore = new PrivateEventStore(store);
-        const contractStore = new ContractStore(store);
-        const noteStore = new NoteStore(store);
-        const anchorBlockStore = new AnchorBlockStore(store);
-        const senderTaggingStore = new SenderTaggingStore(store);
-        const senderAddressBookStore = new SenderAddressBookStore(store);
-        const recipientTaggingStore = new RecipientTaggingStore(store);
-        const capsuleStore = new CapsuleStore(store);
-        const keyStore = new KeyStore(store);
-        const tipsStore = new L2TipsKVStore(store, 'pxe');
+        const { addressStore, privateEventStore, contractStore, noteStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, capsuleStore, keyStore, l2TipsStore } = openPxeStores(store, initialBlockHash);
         const contractSyncService = new ContractSyncService(node, contractStore, noteStore, createLogger('pxe:contract_sync', bindings));
         const messageContextService = new MessageContextService(node);
-        const synchronizer = new BlockSynchronizer(node, store, anchorBlockStore, noteStore, privateEventStore, tipsStore, contractSyncService, config, bindings);
+        const synchronizer = new BlockSynchronizer(node, store, anchorBlockStore, noteStore, privateEventStore, l2TipsStore, contractSyncService, config, bindings);
         const jobCoordinator = new JobCoordinator(store, bindings);
         jobCoordinator.registerStores([
             capsuleStore,
@@ -123,10 +119,13 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         ]);
         const debugUtils = new PXEDebugUtils(contractSyncService, noteStore, synchronizer, anchorBlockStore);
         const jobQueue = new SerialQueue();
-        const pxe = new PXE(node, store, synchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, messageContextService, tipsStore, simulator, proverEnabled, proofCreator, protocolContractsProvider, log, jobQueue, jobCoordinator, debugUtils);
+        const pxe = new PXE(node, store, synchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, messageContextService, l2TipsStore, simulator, proverEnabled, config.autoSync, proofCreator, protocolContractsProvider, preloadedContractsProvider, log, jobQueue, jobCoordinator, debugUtils, hooks);
         debugUtils.setPXEHelpers(pxe.#putInJobQueue.bind(pxe), pxe.#getSimulatorForTx.bind(pxe), pxe.#executeUtility.bind(pxe));
         pxe.jobQueue.start();
-        await pxe.#registerProtocolContracts();
+        await Promise.all([
+            pxe.#registerProtocolContracts(),
+            pxe.#registerPreloadedContracts()
+        ]);
         log.info(`Started PXE connected to chain ${info.l1ChainId} version ${info.rollupVersion}`);
         return pxe;
     }
@@ -147,7 +146,8 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             privateEventStore: this.privateEventStore,
             simulator: this.simulator,
             contractSyncService: this.contractSyncService,
-            messageContextService: this.messageContextService
+            messageContextService: this.messageContextService,
+            hooks: this.hooks
         });
     }
     #contextualizeError(err, ...context) {
@@ -189,18 +189,30 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         });
     }
     async #registerProtocolContracts() {
-        const registered = {};
-        for (const name of protocolContractNames){
+        const registered = Object.fromEntries(await Promise.all(protocolContractNames.map(async (name)=>{
             const { address, instance, artifact } = await this.protocolContractsProvider.getProtocolContractArtifact(name);
             await this.contractStore.addContractArtifact(artifact);
             await this.contractStore.addContractInstance(instance);
-            registered[name] = address.toString();
-        }
+            return [
+                name,
+                address.toString()
+            ];
+        })));
         this.log.verbose(`Registered protocol contracts in pxe`, registered);
     }
+    async #registerPreloadedContracts() {
+        const contracts = await this.preloadedContractsProvider.getPreloadedContracts();
+        await Promise.all(contracts.map(({ instance, artifact })=>this.registerContract({
+                instance,
+                artifact
+            })));
+        this.log.verbose(`Registered preloaded contracts in pxe`, {
+            contracts: contracts.map(({ instance })=>instance.address.toString())
+        });
+    }
     // Executes the entrypoint private function, as well as all nested private
     // functions that might arise.
-    async #executePrivate(contractFunctionSimulator, txRequest, anchorBlockHeader, scopes, jobId) {
+    async #executePrivate({ contractFunctionSimulator, txRequest, anchorBlockHeader, scopes, jobId, senderForTags }) {
         const { origin: contractAddress, functionSelector } = txRequest;
         try {
             await this.contractSyncService.ensureContractSynced(contractAddress, functionSelector, (privateSyncCall, execScopes)=>this.#executeUtility(contractFunctionSimulator, privateSyncCall, [], execScopes, jobId), anchorBlockHeader, jobId, scopes);
@@ -209,7 +221,8 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                 selector: functionSelector,
                 anchorBlockHeader,
                 scopes,
-                jobId
+                jobId,
+                senderForTags
             });
             this.log.debug(`Private simulation completed for ${contractAddress.toString()}:${functionSelector}`);
             return result;
@@ -249,11 +262,11 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * This allows to catch public execution errors before submitting the transaction.
    * It can also be used for estimating gas in the future.
    * @param tx - The transaction to be simulated.
-   */ async #simulatePublicCalls(tx, skipFeeEnforcement) {
+   */ async #simulatePublicCalls(tx, skipFeeEnforcement, overrides) {
         // Simulating public calls can throw if the TX fails in a phase that doesn't allow reverts (setup)
         // Or return as reverted if it fails in a phase that allows reverts (app logic, teardown)
         try {
-            const result = await this.node.simulatePublicCalls(tx, skipFeeEnforcement);
+            const result = await this.node.simulatePublicCalls(tx, skipFeeEnforcement, overrides);
             if (result.revertReason) {
                 throw result.revertReason;
             }
@@ -285,8 +298,24 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         this.log.debug(`Executing kernel trace prover (${JSON.stringify(config)})...`);
         return await kernelTraceProver.proveWithKernels(txExecutionRequest.toTxRequest(), privateExecutionResult, config);
     }
+    /**
+   * Syncs with the node only when `autoSync` is enabled.
+   * When `autoSync` is disabled, callers (typically a wallet) are
+   * responsible for invoking `pxe.sync()` at the right granularity.
+   */ async #maybeSync() {
+        if (this.autoSync) {
+            await this.blockStateSynchronizer.sync();
+        }
+    }
     // Public API
     /**
+   * Triggers a sync of PXE state with the node, regardless of the `autoSync` config flag. Use this to
+   * batch syncs across composite flows when `autoSync` is disabled (e.g. one sync per simulate+send
+   * instead of one per inner PXE call). Serialized through the job queue.
+   */ sync() {
+        return this.#putInJobQueue(()=>this.blockStateSynchronizer.sync());
+    }
+    /**
    * Returns the block header up to which the PXE has synced.
    * @returns The synced block header
    */ getSyncedBlockHeader() {
@@ -320,7 +349,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    */ async registerAccount(secretKey, partialAddress) {
         const accounts = await this.keyStore.getAccounts();
         const accountCompleteAddress = await this.keyStore.addAccount(secretKey, partialAddress);
-        if (accounts.includes(accountCompleteAddress.address)) {
+        if (accounts.some((a)=>a.equals(accountCompleteAddress.address))) {
             this.log.info(`Account:\n "${accountCompleteAddress.address.toString()}"\n already registered.`);
             return accountCompleteAddress;
         } else {
@@ -344,7 +373,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             throw new Error(`Address ${sender} is not valid: it does not correspond to a point on the Grumpkin curve. Cannot register it as a sender.`);
         }
         const accounts = await this.keyStore.getAccounts();
-        if (accounts.includes(sender)) {
+        if (accounts.some((a)=>a.equals(sender))) {
             this.log.info(`Sender:\n "${sender.toString()}"\n already registered.`);
             return sender;
         }
@@ -416,7 +445,9 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             }
             await this.contractStore.addContractArtifact(artifact, contractClass);
             const publicFunctionSignatures = artifact.functions.filter((fn)=>fn.functionType === FunctionType.PUBLIC).map((fn)=>decodeFunctionSignature(fn.name, fn.parameters));
-            await this.node.registerContractFunctionSignatures(publicFunctionSignatures);
+            if (publicFunctionSignatures.length > 0) {
+                await this.node.registerContractFunctionSignatures(publicFunctionSignatures);
+            }
         } else {
             // Otherwise, make sure there is an artifact already registered for that class id
             artifact = await this.contractStore.getContractArtifact(instance.currentContractClassId);
@@ -444,14 +475,16 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                 throw new Error(`Instance not found when updating a contract. Contract address: ${contractAddress}.`);
             }
             const contractClass = await getContractClassFromArtifact(artifact);
-            await this.blockStateSynchronizer.sync();
+            await this.#maybeSync();
             const header = await this.anchorBlockStore.getBlockHeader();
             const currentClassId = await readCurrentClassId(contractAddress, currentInstance, this.node, header);
             if (!contractClass.id.equals(currentClassId)) {
                 throw new Error('Could not update contract to a class different from the current one.');
             }
             const publicFunctionSignatures = artifact.functions.filter((fn)=>fn.functionType === FunctionType.PUBLIC).map((fn)=>decodeFunctionSignature(fn.name, fn.parameters));
-            await this.node.registerContractFunctionSignatures(publicFunctionSignatures);
+            if (publicFunctionSignatures.length > 0) {
+                await this.node.registerContractFunctionSignatures(publicFunctionSignatures);
+            }
             currentInstance.currentContractClassId = contractClass.id;
             await Promise.all([
                 this.contractStore.addContractArtifact(artifact, contractClass),
@@ -475,7 +508,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * @returns A result containing the proof and public inputs of the tail circuit.
    * @throws If contract code not found, or public simulation reverts.
    * Also throws if simulatePublic is true and public simulation reverts.
-   */ proveTx(txRequest, scopes) {
+   */ proveTx(txRequest, { scopes, senderForTags }) {
         let privateExecutionResult;
         // We disable proving concurrently mostly out of caution, since it accesses some of our stores. Proving is so
         // computationally demanding that it'd be rare for someone to try to do it concurrently regardless.
@@ -483,11 +516,18 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             const totalTimer = new Timer();
             try {
                 const syncTimer = new Timer();
-                await this.blockStateSynchronizer.sync();
+                await this.#maybeSync();
                 const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
                 const syncTime = syncTimer.ms();
                 const contractFunctionSimulator = this.#getSimulatorForTx();
-                privateExecutionResult = await this.#executePrivate(contractFunctionSimulator, txRequest, anchorBlockHeader, scopes, jobId);
+                privateExecutionResult = await this.#executePrivate({
+                    contractFunctionSimulator,
+                    txRequest,
+                    anchorBlockHeader,
+                    scopes,
+                    jobId,
+                    senderForTags
+                });
                 const { publicInputs, chonkProof, executionSteps, timings: { proving } = {} } = await this.#prove(txRequest, this.proofCreator, privateExecutionResult, anchorBlockHeader, {
                     simulate: false,
                     skipFeeEnforcement: false,
@@ -513,22 +553,13 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                     timings,
                     nodeRPCCalls: contractFunctionSimulator?.getStats().nodeRPCCalls
                 });
-                // While not strictly necessary to store tagging cache contents in the DB since we sync tagging indexes from
-                // chain before sending new logs, the sync can only see logs already included in blocks. If we send another
-                // transaction before this one is included in a block from this PXE, and that transaction contains a log with
-                // a tag derived from the same secret, we would reuse the tag and the transactions would be linked. Hence
-                // storing the tags here prevents linkage of txs sent from the same PXE.
-                const taggingIndexRangesUsedInTheTx = privateExecutionResult.entrypoint.taggingIndexRanges;
-                if (taggingIndexRangesUsedInTheTx.length > 0) {
-                    // TODO(benesjan): The following is an expensive operation. Figure out a way to avoid it.
-                    const txHash = (await txProvingResult.toTx()).txHash;
-                    await this.senderTaggingStore.storePendingIndexes(taggingIndexRangesUsedInTheTx, txHash, jobId);
-                    this.log.debug(`Stored used tagging index ranges as sender for the tx`, {
-                        taggingIndexRangesUsedInTheTx
-                    });
-                } else {
-                    this.log.debug(`No tagging index ranges used in the tx`);
-                }
+                // We keep track of which tagging indices we've used in this tx so that we don't repeat them in future txs
+                // (which would link them) without having to rely on this tx being mined (and us seeing the indices being used
+                // onchain).
+                // Note that this must happen _after_ proving as it requires the proof's public inputs, from which the kernels
+                // may have removed some logs due to note-nullifier squashing - this may lead to range of tagging indices we've
+                // actually used to being reduced.
+                await persistSenderTaggingIndexRangesForTx(this.senderTaggingStore, privateExecutionResult.entrypoint.taggingIndexRanges, publicInputs, ()=>txProvingResult.getTxHash(), jobId, this.log);
                 return txProvingResult;
             } catch (err) {
                 throw this.#contextualizeError(err, inspect(txRequest), inspect(privateExecutionResult));
@@ -540,7 +571,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * @param txRequest - An authenticated tx request ready for simulation.
    * @returns A trace of the program execution with gate counts.
    * @throws If the code for the functions executed in this transaction have not been made available via `addContracts`.
-   */ profileTx(txRequest, { profileMode, skipProofGeneration = true, scopes }) {
+   */ profileTx(txRequest, { profileMode, skipProofGeneration = true, scopes, senderForTags }) {
         // We disable concurrent profiles for consistency with simulateTx.
         return this.#putInJobQueue(async (jobId)=>{
             const totalTimer = new Timer();
@@ -555,11 +586,18 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                 };
                 this.log.info(`Profiling transaction execution request to ${txRequest.functionSelector} at ${txRequest.origin}`, txInfo);
                 const syncTimer = new Timer();
-                await this.blockStateSynchronizer.sync();
+                await this.#maybeSync();
                 const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
                 const syncTime = syncTimer.ms();
                 const contractFunctionSimulator = this.#getSimulatorForTx();
-                const privateExecutionResult = await this.#executePrivate(contractFunctionSimulator, txRequest, anchorBlockHeader, scopes, jobId);
+                const privateExecutionResult = await this.#executePrivate({
+                    contractFunctionSimulator,
+                    txRequest,
+                    anchorBlockHeader,
+                    scopes,
+                    jobId,
+                    senderForTags
+                });
                 const { executionSteps, timings: { proving } = {} } = await this.#prove(txRequest, this.proofCreator, privateExecutionResult, anchorBlockHeader, {
                     simulate: skipProofGeneration,
                     skipFeeEnforcement: false,
@@ -610,7 +648,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * Also throws if simulatePublic is true and public simulation reverts.
    *
    * TODO(#7456) Prevent msgSender being defined here for the first call
-   */ simulateTx(txRequest, { simulatePublic, skipTxValidation = false, skipFeeEnforcement = false, skipKernels = true, overrides, scopes }) {
+   */ simulateTx(txRequest, { simulatePublic, skipTxValidation = false, skipFeeEnforcement = false, skipKernels = true, overrides, scopes, senderForTags }) {
         // We disable concurrent simulations since those might execute oracles which read and write to the PXE stores (e.g.
         // to the capsules), and we need to prevent concurrent runs from interfering with one another (e.g. attempting to
         // delete the same read value, or reading values that another simulation is currently modifying).
@@ -627,22 +665,22 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                 };
                 this.log.info(`Simulating transaction execution request to ${txRequest.functionSelector} at ${txRequest.origin}`, txInfo);
                 const syncTimer = new Timer();
-                await this.blockStateSynchronizer.sync();
+                await this.#maybeSync();
                 const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
                 const syncTime = syncTimer.ms();
-                const overriddenContracts = overrides?.contracts ? new Set(Object.keys(overrides.contracts)) : undefined;
-                const hasOverriddenContracts = overriddenContracts !== undefined && overriddenContracts.size > 0;
-                if (hasOverriddenContracts && !skipKernels) {
+                if (overrides?.contracts && Object.keys(overrides.contracts).length > 0 && !skipKernels) {
                     throw new Error('Simulating with overridden contracts is not compatible with kernel execution. Please set skipKernels to true when simulating with overridden contracts.');
                 }
                 const contractFunctionSimulator = this.#getSimulatorForTx(overrides);
-                if (hasOverriddenContracts) {
-                    // Overridden contracts don't have a sync function, so calling sync on them would fail.
-                    // We exclude them so the sync service skips them entirely.
-                    this.contractSyncService.setExcludedFromSync(jobId, overriddenContracts);
-                }
                 // Execution of private functions only; no proving, and no kernel logic.
-                const privateExecutionResult = await this.#executePrivate(contractFunctionSimulator, txRequest, anchorBlockHeader, scopes, jobId);
+                const privateExecutionResult = await this.#executePrivate({
+                    contractFunctionSimulator,
+                    txRequest,
+                    anchorBlockHeader,
+                    scopes,
+                    jobId,
+                    senderForTags
+                });
                 let publicInputs;
                 let executionSteps = [];
                 if (skipKernels) {
@@ -661,7 +699,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                 let publicOutput;
                 if (simulatePublic && publicInputs.forPublic) {
                     const publicSimulationTimer = new Timer();
-                    publicOutput = await this.#simulatePublicCalls(simulatedTx, skipFeeEnforcement);
+                    publicOutput = await this.#simulatePublicCalls(simulatedTx, skipFeeEnforcement, overrides);
                     publicSimulationTime = publicSimulationTimer.ms();
                     if (publicOutput?.debugLogs?.length) {
                         await displayDebugLogs(publicOutput.debugLogs, (addr)=>this.contractStore.getDebugContractName(addr));
@@ -727,7 +765,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             try {
                 const totalTimer = new Timer();
                 const syncTimer = new Timer();
-                await this.blockStateSynchronizer.sync();
+                await this.#maybeSync();
                 const syncTime = syncTimer.ms();
                 const functionTimer = new Timer();
                 const contractFunctionSimulator = this.#getSimulatorForTx();
@@ -780,7 +818,7 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    */ async getPrivateEvents(eventSelector, filter) {
         let anchorBlockNumber;
         await this.#putInJobQueue(async (jobId)=>{
-            await this.blockStateSynchronizer.sync();
+            await this.#maybeSync();
             const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
             anchorBlockNumber = anchorBlockHeader.getBlockNumber();
             const contractFunctionSimulator = this.#getSimulatorForTx();

package/dest/storage/backwards_compatibility_tests/kv_store_snapshot.d.ts

@@ -0,0 +1,42 @@
+import type { AztecAsyncArray, AztecAsyncMap, AztecAsyncSingleton, Key } from '@aztec/kv-store';
+/**
+ * This file contains helpers that produce stable, snapshot-friendly text representations of our kv-stores'
+ * contents (map / multimap / array / singleton). Used by the backwards compatibility tests in this directory to
+ * fingerprint the bytes PXE persists.
+ *
+ * Each backwards compatibility schema scenario test follows the same shape:
+ *
+ * 1. drive the production write path through the store class's public API.
+ * 2. re-open the underlying kv-store by name, bypassing the store abstraction layer (eg:
+ * `kvStore.openMap<K, Buffer>('foo')`) and snapshot it via the helpers below.
+ * 3. compare fresh snapshots with committed ones.
+ *
+ * Why text rather than buffers: Jest snapshots are stored as JS literals; `Buffer` instances render as the verbose
+ * `Buffer <01 02 03>` form, which clutters `.snap` files and resists clean diffs. Each collection's contents are
+ * normalized into strings before being fed to `toMatchSnapshot()`.
+ */
+/** A single map/multimap entry, rendered as strings for stable snapshotting. */
+export type MapEntry = {
+    key: string;
+    value: string;
+};
+/** A single array entry, rendered as a string for stable snapshotting. */
+export type ArrayEntry = {
+    index: number;
+    value: string;
+};
+/**
+ * Returns every entry of the given map (or multimap), with both keys and values rendered as strings, sorted by key
+ * with value as a tiebreaker.
+ */
+export declare function snapshotMap<K extends Key, V>(map: AztecAsyncMap<K, V>): Promise<MapEntry[]>;
+/**
+ * Returns the contents of `array` paired with their numeric indices, in insertion order.
+ *
+ * Unlike {@link snapshotMap}, no sort: arrays are inherently ordered by index and that order *is* part of the schema.
+ * The `index` field is preserved on each entry so any unintended reorder shows up in the diff.
+ */
+export declare function snapshotArray<V>(array: AztecAsyncArray<V>): Promise<ArrayEntry[]>;
+/** Returns the singleton's value rendered as a string, or `null` if unset. */
+export declare function snapshotSingleton<V>(singleton: AztecAsyncSingleton<V>): Promise<string | null>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoia3Zfc3RvcmVfc25hcHNob3QuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2JhY2t3YXJkc19jb21wYXRpYmlsaXR5X3Rlc3RzL2t2X3N0b3JlX3NuYXBzaG90LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGVBQWUsRUFBRSxhQUFhLEVBQUUsbUJBQW1CLEVBQUUsR0FBRyxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFaEc7Ozs7Ozs7Ozs7Ozs7OztHQWVHO0FBRUgsZ0ZBQWdGO0FBQ2hGLE1BQU0sTUFBTSxRQUFRLEdBQUc7SUFBRSxHQUFHLEVBQUUsTUFBTSxDQUFDO0lBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBQTtDQUFFLENBQUM7QUFFdEQsMEVBQTBFO0FBQzFFLE1BQU0sTUFBTSxVQUFVLEdBQUc7SUFBRSxLQUFLLEVBQUUsTUFBTSxDQUFDO0lBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBQTtDQUFFLENBQUM7QUFFMUQ7OztHQUdHO0FBQ0gsd0JBQXNCLFdBQVcsQ0FBQyxDQUFDLFNBQVMsR0FBRyxFQUFFLENBQUMsRUFBRSxHQUFHLEVBQUUsYUFBYSxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsR0FBRyxPQUFPLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FNakc7QUFFRDs7Ozs7R0FLRztBQUNILHdCQUFzQixhQUFhLENBQUMsQ0FBQyxFQUFFLEtBQUssRUFBRSxlQUFlLENBQUMsQ0FBQyxDQUFDLEdBQUcsT0FBTyxDQUFDLFVBQVUsRUFBRSxDQUFDLENBT3ZGO0FBRUQsOEVBQThFO0FBQzlFLHdCQUFzQixpQkFBaUIsQ0FBQyxDQUFDLEVBQUUsU0FBUyxFQUFFLG1CQUFtQixDQUFDLENBQUMsQ0FBQyxHQUFHLE9BQU8sQ0FBQyxNQUFNLEdBQUcsSUFBSSxDQUFDLENBR3BHIn0=

package/dest/storage/backwards_compatibility_tests/kv_store_snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv_store_snapshot.d.ts","sourceRoot":"","sources":["../../../src/storage/backwards_compatibility_tests/kv_store_snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAEhG;;;;;;;;;;;;;;;GAeG;AAEH,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAMjG;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAOvF;AAED,8EAA8E;AAC9E,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGpG"}

package/dest/storage/backwards_compatibility_tests/kv_store_snapshot.js

@@ -0,0 +1,93 @@
+/**
+ * Returns every entry of the given map (or multimap), with both keys and values rendered as strings, sorted by key
+ * with value as a tiebreaker.
+ */ export async function snapshotMap(map) {
+    const entries = [];
+    for await (const [k, v] of map.entriesAsync()){
+        entries.push({
+            key: keyToString(k),
+            value: valueToString(v)
+        });
+    }
+    return entries.sort(compareMapEntries);
+}
+/**
+ * Returns the contents of `array` paired with their numeric indices, in insertion order.
+ *
+ * Unlike {@link snapshotMap}, no sort: arrays are inherently ordered by index and that order *is* part of the schema.
+ * The `index` field is preserved on each entry so any unintended reorder shows up in the diff.
+ */ export async function snapshotArray(array) {
+    const entries = [];
+    let index = 0;
+    for await (const v of array.valuesAsync()){
+        entries.push({
+            index: index++,
+            value: valueToString(v)
+        });
+    }
+    return entries;
+}
+/** Returns the singleton's value rendered as a string, or `null` if unset. */ export async function snapshotSingleton(singleton) {
+    const value = await singleton.getAsync();
+    return value === undefined ? null : valueToString(value);
+}
+function compareMapEntries(a, b) {
+    return a.key === b.key ? a.value.localeCompare(b.value) : a.key.localeCompare(b.key);
+}
+/**
+ * Renders a key as a stable string. Buffers and `Uint8Array`s become `0x`-prefixed hex (matching the canonical byte
+ * form used by `Fr.toString()`, `AztecAddress.toString()`, etc. elsewhere in the codebase); primitives carry a type
+ * prefix (`utf8:`, `num:`) so that different runtime types can't alias to the same string in a snapshot. Without the
+ * prefix, a future change that swapped a `number` key for a `string` of the same digits would be invisible in the
+ * diff.
+ */ function keyToString(k) {
+    if (typeof k === 'string') {
+        return `utf8:${k}`;
+    }
+    if (typeof k === 'number') {
+        return `num:${k}`;
+    }
+    if (Buffer.isBuffer(k)) {
+        return `0x${k.toString('hex')}`;
+    }
+    if (k instanceof Uint8Array) {
+        return `0x${Buffer.from(k).toString('hex')}`;
+    }
+    if (Array.isArray(k)) {
+        return `[${k.map(keyToString).join(',')}]`;
+    }
+    return JSON.stringify(k);
+}
+/**
+ * Renders a value for snapshotting. Same type-prefix discipline as {@link keyToString} so primitives can't
+ * accidentally render identically to buffers carrying the same bytes.
+ *
+ * Resolution order:
+ *   1. `Buffer` / `Uint8Array` -> hex. This is the on-disk byte view; the kv-store layer treats these as opaque, so
+ *      what we see here is exactly what's persisted.
+ *   2. Tagged primitives (`num:`, `big:`, `utf8:`).
+ *   3. `Bufferable` fallback: any object with a `.toBuffer()` method renders as `value.toBuffer().toString('hex')`.
+ *      Covers stdlib domain types stored without pre-serialization. The canonical byte form is what we want to
+ *      fingerprint.
+ *   4. `JSON.stringify` for plain objects, matching how the kv-store layer encodes arbitrary structures on disk.
+ */ function valueToString(v) {
+    if (Buffer.isBuffer(v)) {
+        return v.toString('hex');
+    }
+    if (v instanceof Uint8Array) {
+        return Buffer.from(v).toString('hex');
+    }
+    if (typeof v === 'number') {
+        return `num:${v}`;
+    }
+    if (typeof v === 'bigint') {
+        return `big:${v.toString()}`;
+    }
+    if (typeof v === 'string') {
+        return `utf8:${v}`;
+    }
+    if (v && typeof v.toBuffer === 'function') {
+        return v.toBuffer().toString('hex');
+    }
+    return JSON.stringify(v);
+}

package/dest/storage/backwards_compatibility_tests/schema_tests.d.ts

@@ -0,0 +1,15 @@
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+/**
+ * Template of a specific store's backwards compatibility checks.
+ *
+ * 1. `name` is the store's name (`AddressStore`, `NoteStore`, etc).
+ * 2. `writeToStore` drives writes through each store's own production API (`addNote`, `setCapsule`, etc).
+ * 3. `snapshotStore` re-opens the underlying kv-stores by name (raw) and renders them as snapshots.
+ */
+export type SchemaTest = {
+    name: string;
+    writeToStore: (kvStore: AztecAsyncKVStore) => Promise<void>;
+    snapshotStore: (kvStore: AztecAsyncKVStore) => Promise<Record<string, unknown>>;
+};
+export declare const SCHEMA_TESTS: readonly SchemaTest[];
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hX3Rlc3RzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9iYWNrd2FyZHNfY29tcGF0aWJpbGl0eV90ZXN0cy9zY2hlbWFfdGVzdHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBT0EsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQXVDekQ7Ozs7OztHQU1HO0FBQ0gsTUFBTSxNQUFNLFVBQVUsR0FBRztJQUN2QixJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsWUFBWSxFQUFFLENBQUMsT0FBTyxFQUFFLGlCQUFpQixLQUFLLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUM1RCxhQUFhLEVBQUUsQ0FBQyxPQUFPLEVBQUUsaUJBQWlCLEtBQUssT0FBTyxDQUFDLE1BQU0sQ0FBQyxNQUFNLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQztDQUNqRixDQUFDO0FBRUYsZUFBTyxNQUFNLFlBQVksRUFBRSxTQUFTLFVBQVUsRUFvZ0I3QyxDQUFDIn0=

package/dest/storage/backwards_compatibility_tests/schema_tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_tests.d.ts","sourceRoot":"","sources":["../../../src/storage/backwards_compatibility_tests/schema_tests.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAuCzD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,aAAa,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjF,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAogB7C,CAAC"}