@aztec/pxe 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5a9928

package/dest/pxe.js

@@ -1,82 +1,98 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Point } from '@aztec/foundation/curves/grumpkin';
 import { createLogger } from '@aztec/foundation/log';
+import { allToCompletion } from '@aztec/foundation/promise';
 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 { computeContractAddressFromInstance, getContractClassFromArtifact } from '@aztec/stdlib/contract';
+import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/stdlib/block';
+import { computeContractAddressFromInstance } from '@aztec/stdlib/contract';
 import { SimulationError } from '@aztec/stdlib/errors';
+import { computeAddressSecret } from '@aztec/stdlib/keys';
+import { deriveEcdhSharedSecretPoint, protectFromForgery } from '@aztec/stdlib/logs';
 import { PrivateSimulationResult, TxProfileResult, TxProvingResult, TxSimulationResult } from '@aztec/stdlib/tx';
 import { inspect } from 'util';
 import { BlockSynchronizer } from './block_synchronizer/index.js';
-import { BenchmarkedNodeFactory } from './contract_function_simulator/benchmarked_node.js';
+import { ContractClassService } from './contract/contract_class_service.js';
+import { ContractSyncService } from './contract/contract_sync_service.js';
 import { ContractFunctionSimulator, generateSimulatedProvingResult } from './contract_function_simulator/contract_function_simulator.js';
-import { ProxiedContractStoreFactory } from './contract_function_simulator/proxied_contract_data_source.js';
-import { ContractSyncService } from './contract_sync/contract_sync_service.js';
-import { readCurrentClassId } from './contract_sync/helpers.js';
+import { displayDebugLogs } from './contract_logging.js';
 import { PXEDebugUtils } from './debug/pxe_debug_utils.js';
 import { enrichPublicSimulationError, enrichSimulationError } from './error_enriching.js';
 import { PrivateEventFilterValidator } from './events/private_event_filter_validator.js';
 import { JobCoordinator } from './job_coordinator/job_coordinator.js';
+import { TxResolverService } from './messages/tx_resolver_service.js';
+import { withCache } from './node/caching_aztec_node.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.
  */ export class PXE {
     node;
+    nodeDebug;
+    db;
     blockStateSynchronizer;
     keyStore;
     contractStore;
     noteStore;
     capsuleStore;
+    factStore;
     anchorBlockStore;
     senderTaggingStore;
-    senderAddressBookStore;
+    taggingSecretSourcesStore;
     recipientTaggingStore;
     addressStore;
     privateEventStore;
     contractSyncService;
+    contractClassService;
+    txResolver;
+    l2TipsStore;
     simulator;
     proverEnabled;
+    autoSync;
     proofCreator;
     protocolContractsProvider;
+    preloadedContractsProvider;
     log;
     jobQueue;
     jobCoordinator;
     debug;
-    constructor(node, blockStateSynchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, simulator, proverEnabled, proofCreator, protocolContractsProvider, log, jobQueue, jobCoordinator, debug){
+    hooks;
+    constructor(node, nodeDebug, db, blockStateSynchronizer, keyStore, contractStore, noteStore, capsuleStore, factStore, anchorBlockStore, senderTaggingStore, taggingSecretSourcesStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, contractClassService, txResolver, l2TipsStore, simulator, proverEnabled, autoSync, proofCreator, protocolContractsProvider, preloadedContractsProvider, log, jobQueue, jobCoordinator, debug, hooks){
         this.node = node;
+        this.nodeDebug = nodeDebug;
+        this.db = db;
         this.blockStateSynchronizer = blockStateSynchronizer;
         this.keyStore = keyStore;
         this.contractStore = contractStore;
         this.noteStore = noteStore;
         this.capsuleStore = capsuleStore;
+        this.factStore = factStore;
         this.anchorBlockStore = anchorBlockStore;
         this.senderTaggingStore = senderTaggingStore;
-        this.senderAddressBookStore = senderAddressBookStore;
+        this.taggingSecretSourcesStore = taggingSecretSourcesStore;
         this.recipientTaggingStore = recipientTaggingStore;
         this.addressStore = addressStore;
         this.privateEventStore = privateEventStore;
         this.contractSyncService = contractSyncService;
+        this.contractClassService = contractClassService;
+        this.txResolver = txResolver;
+        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.
@@ -84,24 +100,28 @@ 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, nodeDebug, 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 proverEnabled = !!config.proverEnabled;
-        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 contractSyncService = new ContractSyncService(node, contractStore, noteStore, createLogger('pxe:contract_sync', bindings));
-        const synchronizer = new BlockSynchronizer(node, store, anchorBlockStore, noteStore, privateEventStore, tipsStore, contractSyncService, config, bindings);
+        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, privateEventStore, contractStore, noteStore, anchorBlockStore, senderTaggingStore, taggingSecretSourcesStore, recipientTaggingStore, capsuleStore, keyStore, l2TipsStore, factStore } = openPxeStores(store, initialBlockHash);
+        // Every PXE consumer reads through this one wrapper, so a read cached by one is served to the rest. Only
+        // immutable, hash-pinned reads are cached (the rule lives on `withCache`), which makes it safe regardless of
+        // the consumer's anchor block; the block synchronizer wipes it on anchor updates to bound memory.
+        const readCachedNode = withCache(node);
+        const contractClassService = new ContractClassService(readCachedNode, contractStore);
+        const contractSyncService = new ContractSyncService(readCachedNode, contractStore, contractClassService, noteStore, createLogger('pxe:contract_sync', bindings));
+        const txResolver = new TxResolverService(readCachedNode);
+        const synchronizer = new BlockSynchronizer(readCachedNode, store, anchorBlockStore, noteStore, privateEventStore, factStore, l2TipsStore, contractSyncService, config, bindings);
         const jobCoordinator = new JobCoordinator(store, bindings);
         jobCoordinator.registerStores([
             capsuleStore,
@@ -109,22 +129,59 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             recipientTaggingStore,
             privateEventStore,
             noteStore,
+            factStore,
             contractSyncService
         ]);
         const debugUtils = new PXEDebugUtils(contractSyncService, noteStore, synchronizer, anchorBlockStore);
         const jobQueue = new SerialQueue();
-        const pxe = new PXE(node, synchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, simulator, proverEnabled, proofCreator, protocolContractsProvider, log, jobQueue, jobCoordinator, debugUtils);
-        debugUtils.setPXEHelpers(pxe.#putInJobQueue.bind(pxe), pxe.#getSimulatorForTx.bind(pxe), pxe.#simulateUtility.bind(pxe));
+        const pxe = new PXE(readCachedNode, nodeDebug, store, synchronizer, keyStore, contractStore, noteStore, capsuleStore, factStore, anchorBlockStore, senderTaggingStore, taggingSecretSourcesStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, contractClassService, txResolver, 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();
-        const info = await node.getNodeInfo();
+        await allToCompletion([
+            pxe.#registerProtocolContracts(),
+            pxe.#registerPreloadedContracts()
+        ]);
         log.info(`Started PXE connected to chain ${info.l1ChainId} version ${info.rollupVersion}`);
         return pxe;
     }
     // Internal methods
     #getSimulatorForTx(overrides) {
-        const proxyContractStore = ProxiedContractStoreFactory.create(this.contractStore, overrides?.contracts);
-        return new ContractFunctionSimulator(proxyContractStore, this.noteStore, this.keyStore, this.addressStore, BenchmarkedNodeFactory.create(this.node), this.senderTaggingStore, this.recipientTaggingStore, this.senderAddressBookStore, this.capsuleStore, this.privateEventStore, this.simulator, this.contractSyncService);
+        return new ContractFunctionSimulator({
+            contractStore: this.contractStore,
+            contractClassService: this.contractClassService,
+            overrides: overrides?.contracts,
+            noteStore: this.noteStore,
+            keyStore: this.keyStore,
+            addressStore: this.addressStore,
+            aztecNode: this.node,
+            l2TipsStore: this.l2TipsStore,
+            senderTaggingStore: this.senderTaggingStore,
+            recipientTaggingStore: this.recipientTaggingStore,
+            taggingSecretSourcesStore: this.taggingSecretSourcesStore,
+            capsuleStore: this.capsuleStore,
+            factStore: this.factStore,
+            privateEventStore: this.privateEventStore,
+            simulator: this.simulator,
+            contractSyncService: this.contractSyncService,
+            txResolver: this.txResolver,
+            hooks: this.hooks
+        });
+    }
+    /** Best-effort debug function name for the class `address` runs at `anchorBlockHeader`. Used for log display only. */ async #getDebugFunctionName(address, selector, anchorBlockHeader) {
+        try {
+            const classId = await this.contractClassService.getCurrentClassId(address, anchorBlockHeader);
+            return classId ? await this.contractStore.getDebugFunctionName(classId, selector) : `${address}:${selector}`;
+        } catch  {
+            return `${address}:${selector}`;
+        }
+    }
+    /** Best-effort debug contract name for the class `address` runs at `anchorBlockHeader`. Used for log display only. */ async #getDebugContractName(address, anchorBlockHeader) {
+        try {
+            const classId = await this.contractClassService.getCurrentClassId(address, anchorBlockHeader);
+            return classId ? await this.contractStore.getDebugContractName(classId) : undefined;
+        } catch  {
+            return undefined;
+        }
     }
     #contextualizeError(err, ...context) {
         let contextStr = '';
@@ -165,50 +222,71 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         });
     }
     async #registerProtocolContracts() {
-        const registered = {};
-        for (const name of protocolContractNames){
-            const { address, contractClass, instance, artifact } = await this.protocolContractsProvider.getProtocolContractArtifact(name);
-            await this.contractStore.addContractArtifact(contractClass.id, artifact);
+        const registered = Object.fromEntries(await allToCompletion(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 allToCompletion(contracts.map(async ({ instance, artifact })=>{
+            if (artifact) {
+                await this.registerContractClass(artifact);
+            }
+            await this.registerContract(instance);
+        }));
+        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, scopes, jobId) {
+    async #executePrivate({ contractFunctionSimulator, txRequest, anchorBlockHeader, scopes, jobId, senderForTags }) {
         const { origin: contractAddress, functionSelector } = txRequest;
         try {
-            const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
-            await this.contractSyncService.ensureContractSynced(contractAddress, functionSelector, (privateSyncCall)=>this.#simulateUtility(contractFunctionSimulator, privateSyncCall, [], undefined, jobId), anchorBlockHeader, jobId);
-            const result = await contractFunctionSimulator.run(txRequest, contractAddress, functionSelector, undefined, anchorBlockHeader, // The sender for tags is set by contracts, typically by an account
-            // contract entrypoint
-            undefined, scopes, jobId);
+            await this.contractSyncService.ensureContractSynced(contractAddress, functionSelector, (privateSyncCall, execScopes)=>this.#executeUtility(contractFunctionSimulator, privateSyncCall, [], execScopes, jobId), anchorBlockHeader, jobId, scopes);
+            const result = await contractFunctionSimulator.run(txRequest, {
+                anchorBlockHeader,
+                scopes,
+                jobId,
+                senderForTags
+            });
             this.log.debug(`Private simulation completed for ${contractAddress.toString()}:${functionSelector}`);
             return result;
         } catch (err) {
             if (err instanceof SimulationError) {
-                await enrichSimulationError(err, this.contractStore, this.log);
+                await enrichSimulationError(err, this.contractStore, this.contractClassService, anchorBlockHeader, this.log);
             }
             throw err;
         }
     }
     /**
-   * Simulate a utility function call on the given contract.
+   * Execute a utility function call on the given contract.
    * @param contractFunctionSimulator - The simulator to use for the function call.
    * @param call - The function call to execute.
    * @param authWitnesses - Authentication witnesses required for the function call.
    * @param scopes - Optional array of account addresses whose notes can be accessed in this call. Defaults to all
    * accounts if not specified.
    * @param jobId - The job ID for staged writes.
-   * @returns The simulation result containing the outputs of the utility function.
-   */ async #simulateUtility(contractFunctionSimulator, call, authWitnesses, scopes, jobId) {
+   * @returns The execution result containing the outputs of the utility function.
+   */ async #executeUtility(contractFunctionSimulator, call, authWitnesses, scopes, jobId) {
         try {
             const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
-            return contractFunctionSimulator.runUtility(call, authWitnesses ?? [], anchorBlockHeader, scopes, jobId);
+            const { result, offchainEffects } = await contractFunctionSimulator.runUtility(call, authWitnesses ?? [], anchorBlockHeader, scopes, jobId);
+            return {
+                result,
+                offchainEffects
+            };
         } catch (err) {
             if (err instanceof SimulationError) {
-                await enrichSimulationError(err, this.contractStore, this.log);
+                const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
+                await enrichSimulationError(err, this.contractStore, this.contractClassService, anchorBlockHeader, this.log);
             }
             throw err;
         }
@@ -218,11 +296,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;
             }
@@ -230,7 +308,8 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         } catch (err) {
             if (err instanceof SimulationError) {
                 try {
-                    await enrichPublicSimulationError(err, this.contractStore, this.log);
+                    const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
+                    await enrichPublicSimulationError(err, this.contractStore, this.contractClassService, anchorBlockHeader, this.log);
                 } catch (enrichErr) {
                     this.log.error(`Failed to enrich public simulation error: ${enrichErr}`);
                 }
@@ -248,25 +327,41 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * @param privateExecutionResult - The result of the private execution
    * @param config - The configuration for the kernel execution prover.
    * @returns An object that contains the output of the kernel execution, including the ChonkProof if proving is enabled.
-   */ async #prove(txExecutionRequest, proofCreator, privateExecutionResult, config) {
-        const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
-        const anchorBlockHash = await anchorBlockHeader.hash();
-        const kernelOracle = new PrivateKernelOracle(this.contractStore, this.keyStore, this.node, anchorBlockHash);
+   */ async #prove(txExecutionRequest, proofCreator, privateExecutionResult, anchorBlockHeader, config) {
+        const kernelOracle = new PrivateKernelOracle(this.contractStore, this.contractClassService, this.keyStore, this.node, anchorBlockHeader);
         const kernelTraceProver = new PrivateKernelExecutionProver(kernelOracle, proofCreator, !this.proverEnabled, this.log.getBindings());
         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() {
-        return this.anchorBlockStore.getBlockHeader();
+        return this.#putInJobQueue(()=>{
+            return this.anchorBlockStore.getBlockHeader();
+        });
     }
     /**
-   * Returns the contract instance for a given address, if it's registered in the PXE.
+   * Returns the address preimage of the contract instance at a given address, if it's registered in the PXE.
    * @param address - The contract address.
-   * @returns The contract instance if found, undefined otherwise.
+   * @returns The contract instance address preimage if found, undefined otherwise.
    */ getContractInstance(address) {
         return this.contractStore.getContractInstance(address);
     }
@@ -278,18 +373,22 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         return await this.contractStore.getContractArtifact(id);
     }
     /**
-   * Registers a user account in PXE given its master encryption private key.
-   * Once a new account is registered, the PXE will trial-decrypt all published notes on
-   * the chain and store those that correspond to the registered account. Will do nothing if the
-   * account is already registered.
+   * Registers a user account in PXE.
+   *
+   * PXE holds the account's four privacy secret keys but only the *public* message-signing and fallback keys: their
+   * secret keys are withheld, since PXE is not trusted to hold them.
+   *
+   * Does nothing if the account is already registered.
    *
-   * @param secretKey - Secret key of the corresponding user master public key.
+   * The four privacy secret keys can be retrieved later with {@link getAccountSecretKeys}.
+   *
+   * @param keys - The account's privacy keys: four secret keys plus the message-signing and fallback public keys.
    * @param partialAddress - The partial address of the account contract corresponding to the account being registered.
    * @returns The complete address of the account.
-   */ async registerAccount(secretKey, partialAddress) {
+   */ async registerAccount(keys, partialAddress) {
         const accounts = await this.keyStore.getAccounts();
-        const accountCompleteAddress = await this.keyStore.addAccount(secretKey, partialAddress);
-        if (accounts.includes(accountCompleteAddress.address)) {
+        const accountCompleteAddress = await this.keyStore.addAccount(keys, partialAddress);
+        if (accounts.some((a)=>a.equals(accountCompleteAddress.address))) {
             this.log.info(`Account:\n "${accountCompleteAddress.address.toString()}"\n already registered.`);
             return accountCompleteAddress;
         } else {
@@ -300,44 +399,144 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         return accountCompleteAddress;
     }
     /**
-   * Registers a sender in this PXE.
+   * Retrieves the four privacy secret keys PXE holds for a registered account (nullifier-hiding, incoming-viewing,
+   * outgoing-viewing, tagging).
    *
-   * After registering a new sender, the PXE will sync private logs that are tagged with this sender's address.
-   * Will do nothing if the address is already registered.
+   * These do NOT grant control over an account's assets, e.g. they are insufficient to impersonate the account or to
+   * spend notes, but they _do_ guard the account's privacy. Parties that have knowledge of these keys can decrypt all
+   * messages sent to the account, discover all of their on-chain activity, including notes, events, etc.
    *
-   * @param sender - Address of the sender to register.
-   * @returns The address of the sender.
-   * TODO: It's strange that we return the address here and I (benesjan) think we should drop the return value.
-   */ async registerSender(sender) {
-        const accounts = await this.keyStore.getAccounts();
-        if (accounts.includes(sender)) {
-            this.log.info(`Sender:\n "${sender.toString()}"\n already registered.`);
-            return sender;
+   * Security is paramount when handling these keys, which should itself be a very rare occurrence. Other than exporting
+   * and then importing an account into a separate PXE/wallet, there is typically no need for a wallet to ever access
+   * these keys. Applications should NEVER be given access to them.
+   *
+   * @throws If the account is not registered.
+   */ getAccountSecretKeys(account) {
+        return this.keyStore.getAccountSecretKeys(account);
+    }
+    /**
+   * Registers a source from which this PXE derives the tagging secrets it scans for to discover incoming private logs.
+   * See {@link TaggingSecretSource} for the meaning of each variant. Does nothing if the source is already registered.
+   *
+   * After a new source is added we clear the cache tracking which contracts have finished syncing, so every contract
+   * re-syncs against the new source's logs (whose notes/events could belong to any contract). Already-discovered
+   * notes/events are not discarded.
+   */ async registerTaggingSecretSource(source) {
+        let wasAdded;
+        switch(source.kind){
+            case 'address-derived':
+                wasAdded = await this.#registerSender(source.sender);
+                break;
+            case 'arbitrary-secret':
+                wasAdded = await this.#registerSharedSecret(source.recipient, 'arbitrary-secret', source.secret);
+                break;
+            case 'handshake':
+                wasAdded = await this.#registerSharedSecret(source.recipient, 'handshake', await this.#deriveHandshakeSecret(source.recipient, source.ephPk));
+                break;
+            default:
+                {
+                    const _ = source;
+                    throw new Error('Unhandled tagging secret source kind');
+                }
         }
-        const wasAdded = await this.senderAddressBookStore.addSender(sender);
         if (wasAdded) {
-            this.log.info(`Added sender:\n ${sender.toString()}`);
-        } else {
-            this.log.info(`Sender:\n "${sender.toString()}"\n already registered.`);
+            // Queued to avoid wiping while a job is in flight.
+            await this.#putInJobQueue(()=>Promise.resolve(this.contractSyncService.wipe()));
         }
-        return sender;
     }
     /**
-   * Retrieves senders registered in this PXE.
-   * @returns Senders registered in this PXE.
-   */ getSenders() {
-        return this.senderAddressBookStore.getSenders();
+   * Removes a previously registered tagging secret source, identified by its registered form (see
+   * {@link getTaggingSecretSources}). Does nothing if it was not registered.
+   */ async removeTaggingSecretSource(source) {
+        switch(source.kind){
+            case 'address-derived':
+                {
+                    const { sender } = source;
+                    const wasRemoved = await this.taggingSecretSourcesStore.removeSender(sender);
+                    this.log.info(wasRemoved ? `Removed sender:\n ${sender.toString()}` : `Sender:\n "${sender.toString()}"\n not registered in PXE.`);
+                    break;
+                }
+            case 'arbitrary-secret':
+            case 'handshake':
+                {
+                    const { kind, recipient, secret } = source;
+                    const wasRemoved = await this.taggingSecretSourcesStore.removeSharedSecret(recipient, kind, secret);
+                    this.log.info(wasRemoved ? `Removed ${kind} shared secret for recipient:\n ${recipient.toString()}` : `No ${kind} shared secret registered for recipient:\n ${recipient.toString()}`);
+                    break;
+                }
+            default:
+                {
+                    const _ = source;
+                    throw new Error('Unhandled tagging secret source kind');
+                }
+        }
+    }
+    async getTaggingSecretSources(filter) {
+        const [senders, secrets] = await allToCompletion([
+            this.taggingSecretSourcesStore.getSenders(),
+            this.taggingSecretSourcesStore.getAllSharedSecrets()
+        ]);
+        const sources = [
+            ...senders.map((sender)=>({
+                    kind: 'address-derived',
+                    sender
+                })),
+            ...secrets.map(({ recipient, kind, secret })=>({
+                    kind,
+                    recipient,
+                    secret
+                }))
+        ];
+        return filter?.kind ? sources.filter((source)=>source.kind === filter.kind) : sources;
+    }
+    /** Registers a sender, skipping addresses that belong to a local account. Returns whether it was newly added. */ async #registerSender(address) {
+        if (!await address.isValid()) {
+            throw new Error(`Address ${address} 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.some((a)=>a.equals(address))) {
+            this.log.info(`Sender:\n "${address.toString()}"\n already registered.`);
+            return false;
+        }
+        const wasAdded = await this.taggingSecretSourcesStore.addSender(address);
+        this.log.info(wasAdded ? `Added sender:\n ${address.toString()}` : `Sender:\n "${address.toString()}"\n already registered.`);
+        return wasAdded;
     }
     /**
-   * Removes a sender registered in this PXE.
-   * @param sender - The address of the sender to remove.
-   */ async removeSender(sender) {
-        const wasRemoved = await this.senderAddressBookStore.removeSender(sender);
-        if (wasRemoved) {
-            this.log.info(`Removed sender:\n ${sender.toString()}`);
-        } else {
-            this.log.info(`Sender:\n "${sender.toString()}"\n not registered in PXE.`);
+   * Derives the shared secret of a handshake from its ephemeral public key: the raw ECDH secret
+   * `S = addressSecret(recipient) * ephPk` with the forgery protection applied,
+   * matching the protected secret the registry stores and the derivation the recipient-side scan uses for
+   * handshakes discovered onchain. The ephemeral key is reconstructed from its x-coordinate with a positive y,
+   * matching how the protocol generates it.
+   *
+   * @throws If `ephPk` is not the x-coordinate of a Grumpkin curve point, or if `recipient` is not an account of
+   * this PXE, since the derivation needs its keys.
+   */ async #deriveHandshakeSecret(recipient, ephPk) {
+        let ephPkPoint;
+        try {
+            ephPkPoint = await Point.fromXAndSign(ephPk, true);
+        } catch  {
+            throw new Error(`Ephemeral public key x-coordinate ${ephPk} does not correspond to a Grumpkin curve point.`);
+        }
+        const completeAddress = await this.addressStore.getCompleteAddress(recipient);
+        if (!completeAddress || !await this.keyStore.hasAccount(recipient)) {
+            throw new Error(`Recipient ${recipient} is not an account of this PXE. A handshake's shared secret can only be derived for an account whose keys are held.`);
+        }
+        const ivskM = await this.keyStore.getMasterIncomingViewingSecretKey(recipient);
+        const addressSecret = await computeAddressSecret(await completeAddress.getPreaddress(), ivskM);
+        const rawSecret = await deriveEcdhSharedSecretPoint(addressSecret, ephPkPoint);
+        return protectFromForgery(rawSecret, ephPkPoint, await recipient.toAddressPoint());
+    }
+    /** Registers a resolved shared secret scoped to a recipient. Returns whether it was newly added. */ async #registerSharedSecret(recipient, kind, secret) {
+        if (!await recipient.isValid()) {
+            throw new Error(`Recipient ${recipient} is not valid: it does not correspond to a point on the Grumpkin curve. Cannot register a shared secret for it.`);
         }
+        if (secret.isZero() || !secret.isOnCurve()) {
+            throw new Error(`Shared secret ${secret} is not a valid non-zero point on the Grumpkin curve.`);
+        }
+        const wasAdded = await this.taggingSecretSourcesStore.addSharedSecret(recipient, kind, secret);
+        this.log.info(wasAdded ? `Added ${kind} shared secret for recipient:\n ${recipient.toString()}` : `${kind} shared secret already registered for recipient:\n ${recipient.toString()}`);
+        return wasAdded;
     }
     /**
    * Retrieves the user accounts registered on this PXE.
@@ -354,73 +553,35 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    *
    * @param artifact - The build artifact for the contract class.
    */ async registerContractClass(artifact) {
-        const { id: contractClassId } = await getContractClassFromArtifact(artifact);
-        await this.contractStore.addContractArtifact(contractClassId, artifact);
+        const contractClassId = await this.contractStore.addContractArtifact(artifact);
+        // Publishing the artifact's public function signatures to the node is part of "registering a class", so that
+        // node-side debugging works regardless of which entrypoint (registerContractClass or registerContract) was used.
+        const publicFunctionSignatures = artifact.functions.filter((fn)=>fn.functionType === FunctionType.PUBLIC).map((fn)=>decodeFunctionSignature(fn.name, fn.parameters));
+        if (publicFunctionSignatures.length > 0) {
+            await this.nodeDebug?.registerContractFunctionSignatures(publicFunctionSignatures);
+        }
         this.log.info(`Added contract class ${artifact.name} with id ${contractClassId}`);
     }
     /**
-   * Adds deployed contracts to the PXE. Deployed contract information is used to access the
-   * contract code when simulating local transactions. This is automatically called by aztec.js when
-   * deploying a contract. Dapps that wish to interact with contracts already deployed should register
-   * these contracts in their users' PXE through this method.
+   * Registers a deployed contract instance so its private state can be synced and its functions simulated. The
+   * artifact for the class the instance runs must be registered separately via {@link registerContractClass}, before
+   * or after this call; registration performs no validation, so a missing or mismatched artifact only surfaces when
+   * the contract is later simulated. This is automatically called by aztec.js when deploying a contract.
    *
-   * @param contract - A contract instance to register, with an optional artifact which can be omitted if the contract class has already been registered.
-   */ async registerContract(contract) {
-        const { instance } = contract;
-        let { artifact } = contract;
-        if (artifact) {
-            // If the user provides an artifact, validate it against the expected class id and register it
-            const contractClass = await getContractClassFromArtifact(artifact);
-            const contractClassId = contractClass.id;
-            if (!contractClassId.equals(instance.currentContractClassId)) {
-                throw new Error(`Artifact does not match expected class id (computed ${contractClassId} but instance refers to ${instance.currentContractClassId})`);
-            }
-            const computedAddress = await computeContractAddressFromInstance(instance);
-            if (!computedAddress.equals(instance.address)) {
-                throw new Error('Added a contract in which the address does not match the contract instance.');
-            }
-            await this.contractStore.addContractArtifact(contractClass.id, artifact);
-            const publicFunctionSignatures = artifact.functions.filter((fn)=>fn.functionType === FunctionType.PUBLIC).map((fn)=>decodeFunctionSignature(fn.name, fn.parameters));
-            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);
-            if (!artifact) {
-                throw new Error(`Artifact not found when registering an instance. Contract class: ${instance.currentContractClassId}.`);
-            }
-        }
-        await this.contractStore.addContractInstance(instance);
-        this.log.info(`Added contract ${artifact.name} at ${instance.address.toString()} with class ${instance.currentContractClassId}`);
-    }
-    /**
-   * Updates a deployed contract in the PXE. This is used to update the contract artifact when
-   * an update has happened, so the new code can be used in the simulation of local transactions.
-   * This is called by aztec.js when instantiating a contract in a given address with a mismatching artifact.
-   * @param contractAddress - The address of the contract to update.
-   * @param artifact - The updated artifact for the contract.
-   * @throws If the artifact's contract class is not found in the PXE or if the contract class is different from
-   * the current one (current one from the point of view of the node to which the PXE is connected).
-   */ updateContract(contractAddress, artifact) {
-        // We disable concurrently updating contracts to avoid concurrently syncing with the node, or changing a contract's
-        // class while we're simulating it.
+   * @param instance - The address preimage of the contract instance to register. The address is derived from it.
+   * @returns The address of the registered instance.
+   */ registerContract(instance) {
+        // Run inside the job queue so we can't race a concurrent simulation while writing the instance to the store.
         return this.#putInJobQueue(async ()=>{
-            const currentInstance = await this.contractStore.getContractInstance(contractAddress);
-            if (!currentInstance) {
-                throw new Error(`Instance not found when updating a contract. Contract address: ${contractAddress}.`);
-            }
-            const contractClass = await getContractClassFromArtifact(artifact);
-            await this.blockStateSynchronizer.sync();
-            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.');
-            }
-            await this.contractStore.addContractArtifact(contractClass.id, artifact);
-            const publicFunctionSignatures = artifact.functions.filter((fn)=>fn.functionType === FunctionType.PUBLIC).map((fn)=>decodeFunctionSignature(fn.name, fn.parameters));
-            await this.node.registerContractFunctionSignatures(publicFunctionSignatures);
-            currentInstance.currentContractClassId = contractClass.id;
-            await this.contractStore.addContractInstance(currentInstance);
-            this.log.info(`Updated contract ${artifact.name} at ${contractAddress.toString()} to class ${contractClass.id}`);
+            const address = await computeContractAddressFromInstance(instance);
+            await this.contractStore.addContractInstance({
+                ...instance,
+                address
+            });
+            this.log.info(`Added contract at ${address}`, {
+                address
+            });
+            return address;
         });
     }
     /**
@@ -434,22 +595,32 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * (where validators prove the public portion).
    *
    * @param txRequest - An authenticated tx request ready for proving
+   * @param scopes - Addresses whose private state and keys are accessible during private execution.
    * @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) {
+   */ 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.
         return this.#putInJobQueue(async (jobId)=>{
             const totalTimer = new Timer();
+            const recording = this.node.startRecording();
             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, undefined, jobId);
-                const { publicInputs, chonkProof, executionSteps, timings: { proving } = {} } = await this.#prove(txRequest, this.proofCreator, privateExecutionResult, {
+                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,
                     profileMode: 'none'
@@ -472,42 +643,34 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                 });
                 const txProvingResult = new TxProvingResult(privateExecutionResult, publicInputs, chonkProof, {
                     timings,
-                    nodeRPCCalls: contractFunctionSimulator?.getStats().nodeRPCCalls
+                    nodeRPCCalls: recording.stop()
                 });
-                // 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 preTagsUsedInTheTx = privateExecutionResult.entrypoint.preTags;
-                if (preTagsUsedInTheTx.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(preTagsUsedInTheTx, txHash, jobId);
-                    this.log.debug(`Stored used pre-tags as sender for the tx`, {
-                        preTagsUsedInTheTx
-                    });
-                } else {
-                    this.log.debug(`No pre-tags 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));
+            } finally{
+                // Idempotent cleanup for the error and early-exit paths. The success path already stopped the recording.
+                recording.stop();
             }
         });
     }
     /**
    * Profiles a transaction, reporting gate counts (unless disabled) and returns an execution trace.
-   *
-   * @param txRequest - An authenticated tx request ready for simulation
-   * @param msgSender - (Optional) The message sender to use for the simulation.
-   * @param skipTxValidation - (Optional) If false, this function throws if the transaction is unable to be included in a block at the current state.
+   * @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) {
+   */ profileTx(txRequest, { profileMode, skipProofGeneration = true, scopes, senderForTags }) {
         // We disable concurrent profiles for consistency with simulateTx.
         return this.#putInJobQueue(async (jobId)=>{
             const totalTimer = new Timer();
+            const recording = this.node.startRecording();
             try {
                 const txInfo = {
                     origin: txRequest.origin,
@@ -519,11 +682,19 @@ 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, undefined, jobId);
-                const { executionSteps, timings: { proving } = {} } = await this.#prove(txRequest, this.proofCreator, privateExecutionResult, {
+                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,
                     profileMode
@@ -546,13 +717,15 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                     perFunction,
                     unaccounted: total - ((syncTime ?? 0) + (proving ?? 0) + perFunction.reduce((acc, { time })=>acc + time, 0))
                 };
-                const simulatorStats = contractFunctionSimulator.getStats();
                 return new TxProfileResult(executionSteps, {
                     timings,
-                    nodeRPCCalls: simulatorStats.nodeRPCCalls
+                    nodeRPCCalls: recording.stop()
                 });
             } catch (err) {
                 throw this.#contextualizeError(err, inspect(txRequest), `profileMode=${profileMode}`);
+            } finally{
+                // Idempotent cleanup for the error and early-exit paths. The success path already stopped the recording.
+                recording.stop();
             }
         });
     }
@@ -567,22 +740,18 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * In that case, the transaction returned is only potentially ready to be sent to the network for execution.
    *
    *
-   * @param txRequest - An authenticated tx request ready for simulation
-   * @param simulatePublic - Whether to simulate the public part of the transaction.
-   * @param skipTxValidation - (Optional) If false, this function throws if the transaction is unable to be included in a block at the current state.
-   * @param skipFeeEnforcement - (Optional) If false, fees are enforced.
-   * @param overrides - (Optional) State overrides for the simulation, such as msgSender, contract instances and artifacts.
-   * @param scopes - (Optional) The accounts whose notes we can access in this call. Currently optional and will default to all.
+   * @param txRequest - An authenticated tx request ready for simulation.
    * @returns A simulated transaction result object that includes public and private return values.
    * @throws If the code for the functions executed in this transaction have not been made available via `addContracts`.
    * 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, 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).
         return this.#putInJobQueue(async (jobId)=>{
+            const recording = this.node.startRecording();
             try {
                 const totalTimer = new Timer();
                 const txInfo = {
@@ -595,28 +764,29 @@ 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 contractFunctionSimulator = this.#getSimulatorForTx(overrides);
-                // Temporary: in case there are overrides, we have to skip the kernels or validations
-                // will fail. Consider handing control to the user/wallet on whether they want to run them
-                // or not.
-                const overriddenContracts = overrides?.contracts ? new Set(Object.keys(overrides.contracts)) : undefined;
-                const hasOverriddenContracts = overriddenContracts !== undefined && overriddenContracts.size > 0;
-                const skipKernels = hasOverriddenContracts;
-                // Set overridden contracts on the sync service so it knows to skip syncing them
-                if (hasOverriddenContracts) {
-                    this.contractSyncService.setOverriddenContracts(jobId, overriddenContracts);
+                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);
                 // Execution of private functions only; no proving, and no kernel logic.
-                const privateExecutionResult = await this.#executePrivate(contractFunctionSimulator, txRequest, scopes, jobId);
+                const privateExecutionResult = await this.#executePrivate({
+                    contractFunctionSimulator,
+                    txRequest,
+                    anchorBlockHeader,
+                    scopes,
+                    jobId,
+                    senderForTags
+                });
                 let publicInputs;
                 let executionSteps = [];
                 if (skipKernels) {
-                    ({ publicInputs, executionSteps } = await generateSimulatedProvingResult(privateExecutionResult, (addr, sel)=>this.contractStore.getDebugFunctionName(addr, sel)));
+                    ({ publicInputs, executionSteps } = await generateSimulatedProvingResult(privateExecutionResult, (addr, sel)=>this.#getDebugFunctionName(addr, sel, anchorBlockHeader), this.node));
                 } else {
                     // Kernel logic, plus proving of all private functions and kernels.
-                    ({ publicInputs, executionSteps } = await this.#prove(txRequest, this.proofCreator, privateExecutionResult, {
+                    ({ publicInputs, executionSteps } = await this.#prove(txRequest, this.proofCreator, privateExecutionResult, anchorBlockHeader, {
                         simulate: true,
                         skipFeeEnforcement,
                         profileMode: 'none'
@@ -628,8 +798,11 @@ 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.#getDebugContractName(addr, anchorBlockHeader));
+                    }
                 }
                 let validationTime;
                 if (!skipTxValidation) {
@@ -640,7 +813,8 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                     });
                     validationTime = validationTimer.ms();
                     if (validationResult.result === 'invalid') {
-                        throw new Error('The simulated transaction is unable to be added to state and is invalid.');
+                        const reason = validationResult.reason.length > 0 ? ` Reason: ${validationResult.reason.join(', ')}` : '';
+                        throw new Error(`The simulated transaction is unable to be added to state and is invalid.${reason}`);
                     }
                 }
                 const txHash = simulatedTx.getTxHash();
@@ -667,39 +841,39 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                         revertReason: publicOutput.revertReason
                     } : {}
                 });
-                const simulatorStats = contractFunctionSimulator.getStats();
                 return TxSimulationResult.fromPrivateSimulationResultAndPublicOutput(privateSimulationResult, publicOutput, {
                     timings,
-                    nodeRPCCalls: simulatorStats.nodeRPCCalls
+                    nodeRPCCalls: recording.stop()
                 });
             } catch (err) {
-                throw this.#contextualizeError(err, inspect(txRequest), `simulatePublic=${simulatePublic}`, `skipTxValidation=${skipTxValidation}`, `scopes=${scopes?.map((s)=>s.toString()).join(', ') ?? 'undefined'}`);
+                throw this.#contextualizeError(err, inspect(txRequest), `simulatePublic=${simulatePublic}`, `skipTxValidation=${skipTxValidation}`, `scopes=${scopes.map((s)=>s.toString()).join(', ')}`);
+            } finally{
+                // Idempotent cleanup for the error and early-exit paths. The success path already stopped the recording.
+                recording.stop();
             }
         });
     }
     /**
-   * Simulate the execution of a contract utility function.
-   *
+   * Executes a contract utility function.
    * @param call - The function call containing the function details, arguments, and target contract address.
-   * @param authwits - (Optional) The authentication witnesses required for the function call.
-   * @param scopes - (Optional) The accounts whose notes we can access in this call. Currently optional and will
-   * default to all.
-   * @returns The result of the utility function call, structured based on the function ABI.
-   */ simulateUtility(call, authwits, scopes) {
-        // We disable concurrent simulations since those might execute oracles which read and write to the PXE stores (e.g.
+   */ executeUtility(call, { authwits, scopes } = {
+        scopes: []
+    }) {
+        // We disable concurrent executions 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).
+        // delete the same read value, or reading values that another execution is currently modifying).
         return this.#putInJobQueue(async (jobId)=>{
+            const recording = this.node.startRecording();
             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();
                 const anchorBlockHeader = await this.anchorBlockStore.getBlockHeader();
-                await this.contractSyncService.ensureContractSynced(call.to, call.selector, (privateSyncCall)=>this.#simulateUtility(contractFunctionSimulator, privateSyncCall, [], undefined, jobId), anchorBlockHeader, jobId);
-                const executionResult = await this.#simulateUtility(contractFunctionSimulator, call, authwits ?? [], scopes, jobId);
+                await this.contractSyncService.ensureContractSynced(call.to, call.selector, (privateSyncCall, execScopes)=>this.#executeUtility(contractFunctionSimulator, privateSyncCall, [], execScopes, jobId), anchorBlockHeader, jobId, scopes);
+                const { result: executionResult, offchainEffects } = await this.#executeUtility(contractFunctionSimulator, call, authwits ?? [], scopes, jobId);
                 const functionTime = functionTimer.ms();
                 const totalTime = totalTimer.ms();
                 const perFunction = [
@@ -714,18 +888,22 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
                     perFunction,
                     unaccounted: totalTime - (syncTime + perFunction.reduce((acc, { time })=>acc + time, 0))
                 };
-                const simulationStats = contractFunctionSimulator.getStats();
                 return {
                     result: executionResult,
+                    offchainEffects,
+                    anchorBlockTimestamp: anchorBlockHeader.globalVariables.timestamp,
                     stats: {
                         timings,
-                        nodeRPCCalls: simulationStats.nodeRPCCalls
+                        nodeRPCCalls: recording.stop()
                     }
                 };
             } catch (err) {
                 const { to, name, args } = call;
                 const stringifiedArgs = args.map((arg)=>arg.toString()).join(', ');
-                throw this.#contextualizeError(err, `simulateUtility ${to}:${name}(${stringifiedArgs})`, `scopes=${scopes?.map((s)=>s.toString()).join(', ') ?? 'undefined'}`);
+                throw this.#contextualizeError(err, `executeUtility ${to}:${name}(${stringifiedArgs})`, `scopes=${scopes.map((s)=>s.toString()).join(', ')}`);
+            } finally{
+                // Idempotent cleanup for the error and early-exit paths. The success path already stopped the recording.
+                recording.stop();
             }
         });
     }
@@ -744,11 +922,11 @@ 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();
-            await this.contractSyncService.ensureContractSynced(filter.contractAddress, null, async (privateSyncCall)=>await this.#simulateUtility(contractFunctionSimulator, privateSyncCall, [], undefined, jobId), anchorBlockHeader, jobId);
+            await this.contractSyncService.ensureContractSynced(filter.contractAddress, null, async (privateSyncCall, execScopes)=>await this.#executeUtility(contractFunctionSimulator, privateSyncCall, [], execScopes, jobId), anchorBlockHeader, jobId, filter.scopes);
         });
         // anchorBlockNumber is set during the job and fixed to whatever it is after a block sync
         const sanitizedFilter = new PrivateEventFilterValidator(anchorBlockNumber).validate(filter);
@@ -756,8 +934,10 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         return this.privateEventStore.getPrivateEvents(eventSelector, sanitizedFilter);
     }
     /**
-   * Stops the PXE's job queue.
-   */ stop() {
-        return this.jobQueue.end();
+   * Stops the PXE's job queue and closes the backing store.
+   */ async stop() {
+        await this.jobQueue.end();
+        await this.blockStateSynchronizer.stop();
+        await this.db.close();
     }
 }