@aztec/pxe 0.0.1-commit.a89ec08 → 0.0.1-commit.aa0c64f

package/dest/pxe.js

@@ -1,88 +1,97 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Point } from '@aztec/foundation/curves/grumpkin';
 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 { 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 { ContractClassService } from './contract/contract_class_service.js';
+import { ContractSyncService } from './contract/contract_sync_service.js';
 import { BenchmarkedNodeFactory } from './contract_function_simulator/benchmarked_node.js';
 import { ContractFunctionSimulator, generateSimulatedProvingResult } from './contract_function_simulator/contract_function_simulator.js';
-import { ProxiedContractStoreFactory } from './contract_function_simulator/proxied_contract_data_source.js';
 import { displayDebugLogs } from './contract_logging.js';
-import { ContractSyncService } from './contract_sync/contract_sync_service.js';
-import { readCurrentClassId } from './contract_sync/helpers.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 { MessageContextService } from './messages/message_context_service.js';
+import { TxResolverService } from './messages/tx_resolver_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.
  */ export class PXE {
     node;
+    nodeDebug;
+    db;
     blockStateSynchronizer;
     keyStore;
     contractStore;
     noteStore;
     capsuleStore;
+    factStore;
     anchorBlockStore;
     senderTaggingStore;
-    senderAddressBookStore;
+    taggingSecretSourcesStore;
     recipientTaggingStore;
     addressStore;
     privateEventStore;
     contractSyncService;
-    messageContextService;
+    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, messageContextService, l2TipsStore, 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.messageContextService = messageContextService;
+        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.
@@ -90,26 +99,24 @@ 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 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 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 { addressStore, privateEventStore, contractStore, noteStore, anchorBlockStore, senderTaggingStore, taggingSecretSourcesStore, recipientTaggingStore, capsuleStore, keyStore, l2TipsStore, factStore } = openPxeStores(store, initialBlockHash);
+        const contractClassService = new ContractClassService(node, contractStore);
+        const contractSyncService = new ContractSyncService(node, contractStore, contractClassService, noteStore, createLogger('pxe:contract_sync', bindings));
+        const txResolver = new TxResolverService(node);
+        const synchronizer = new BlockSynchronizer(node, store, anchorBlockStore, noteStore, privateEventStore, factStore, l2TipsStore, contractSyncService, contractClassService, config, bindings);
         const jobCoordinator = new JobCoordinator(store, bindings);
         jobCoordinator.registerStores([
             capsuleStore,
@@ -117,22 +124,27 @@ 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, messageContextService, tipsStore, simulator, proverEnabled, proofCreator, protocolContractsProvider, log, jobQueue, jobCoordinator, debugUtils);
+        const pxe = new PXE(node, 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();
+        await Promise.all([
+            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({
-            contractStore: proxyContractStore,
+            contractStore: this.contractStore,
+            contractClassService: this.contractClassService,
+            overrides: overrides?.contracts,
             noteStore: this.noteStore,
             keyStore: this.keyStore,
             addressStore: this.addressStore,
@@ -140,14 +152,32 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             l2TipsStore: this.l2TipsStore,
             senderTaggingStore: this.senderTaggingStore,
             recipientTaggingStore: this.recipientTaggingStore,
-            senderAddressBookStore: this.senderAddressBookStore,
+            taggingSecretSourcesStore: this.taggingSecretSourcesStore,
             capsuleStore: this.capsuleStore,
+            factStore: this.factStore,
             privateEventStore: this.privateEventStore,
             simulator: this.simulator,
             contractSyncService: this.contractSyncService,
-            messageContextService: this.messageContextService
+            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 = '';
         if (context.length > 0) {
@@ -187,34 +217,46 @@ 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(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, execScopes)=>this.#executeUtility(contractFunctionSimulator, privateSyncCall, [], execScopes, jobId), anchorBlockHeader, jobId, scopes);
             const result = await contractFunctionSimulator.run(txRequest, {
-                contractAddress,
-                selector: functionSelector,
                 anchorBlockHeader,
                 scopes,
-                jobId
+                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;
         }
@@ -238,7 +280,8 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
             };
         } 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;
         }
@@ -248,11 +291,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;
             }
@@ -260,7 +303,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}`);
                 }
@@ -278,16 +322,30 @@ 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() {
@@ -296,9 +354,9 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
         });
     }
     /**
-   * 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);
     }
@@ -310,18 +368,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 {
@@ -332,50 +394,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) {
-        if (!await sender.isValid()) {
-            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)) {
-            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()}`);
-            // Wipe the entire sync cache: the new sender's tagged logs could contain notes/events for any contract, so
-            // all contracts must re-sync to discover them.
-            this.contractSyncService.wipe();
-        } 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 Promise.all([
+            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.
@@ -393,72 +549,34 @@ import { SenderTaggingStore } from './storage/tagging_store/sender_tagging_store
    * @param artifact - The build artifact for the contract class.
    */ async registerContractClass(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);
-            if (!contractClass.id.equals(instance.currentContractClassId)) {
-                throw new Error(`Artifact does not match expected class id (computed ${contractClass.id} 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(artifact, contractClass);
-            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.');
-            }
-            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 Promise.all([
-                this.contractStore.addContractArtifact(artifact, contractClass),
-                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;
         });
     }
     /**
@@ -476,7 +594,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.
@@ -484,11 +602,19 @@ 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, scopes, 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'
@@ -513,22 +639,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 +657,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 +672,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, scopes, 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
@@ -609,7 +734,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).
@@ -626,28 +751,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 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, 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), this.node));
+                    ({ 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'
@@ -659,10 +785,10 @@ 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));
+                        await displayDebugLogs(publicOutput.debugLogs, (addr)=>this.#getDebugContractName(addr, anchorBlockHeader));
                     }
                 }
                 let validationTime;
@@ -725,7 +851,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();
@@ -778,7 +904,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();
@@ -790,8 +916,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();
     }
 }