@aztec/pxe 0.0.1-commit.b9865e97 → 0.0.1-commit.be03c316

package/dest/pxe.js

@@ -1,26 +1,28 @@
 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 { protocolContractNames } from '@aztec/protocol-contracts';
 import { FunctionType, decodeFunctionSignature } from '@aztec/stdlib/abi';
 import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/stdlib/block';
-import { computeContractAddressFromInstance, getContractClassFromArtifact } from '@aztec/stdlib/contract';
+import { 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 { openPxeStores } from './storage/open_pxe_stores.js';
@@ -30,20 +32,23 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
  * 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;
@@ -56,22 +61,25 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
     jobCoordinator;
     debug;
     hooks;
-    constructor(node, db, blockStateSynchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, messageContextService, l2TipsStore, simulator, proverEnabled, autoSync, proofCreator, protocolContractsProvider, preloadedContractsProvider, log, jobQueue, jobCoordinator, debug, hooks){
+    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;
@@ -91,7 +99,7 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
    * can be contacted.
    *
    * @returns A promise that resolves PXE is ready to be used.
-   */ static async create({ node, store, proofCreator, simulator, protocolContractsProvider, preloadedContractsProvider, config, loggerOrSuffix, hooks }) {
+   */ 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;
@@ -104,10 +112,11 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
         // 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, senderAddressBookStore, recipientTaggingStore, capsuleStore, keyStore, l2TipsStore } = openPxeStores(store, initialBlockHash);
-        const contractSyncService = new ContractSyncService(node, contractStore, noteStore, createLogger('pxe:contract_sync', bindings));
-        const messageContextService = new MessageContextService(node);
-        const synchronizer = new BlockSynchronizer(node, store, anchorBlockStore, noteStore, privateEventStore, l2TipsStore, 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,
@@ -115,11 +124,12 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
             recipientTaggingStore,
             privateEventStore,
             noteStore,
+            factStore,
             contractSyncService
         ]);
         const debugUtils = new PXEDebugUtils(contractSyncService, noteStore, synchronizer, anchorBlockStore);
         const jobQueue = new SerialQueue();
-        const pxe = new PXE(node, store, synchronizer, keyStore, contractStore, noteStore, capsuleStore, anchorBlockStore, senderTaggingStore, senderAddressBookStore, recipientTaggingStore, addressStore, privateEventStore, contractSyncService, messageContextService, l2TipsStore, simulator, proverEnabled, config.autoSync, proofCreator, protocolContractsProvider, preloadedContractsProvider, log, jobQueue, jobCoordinator, debugUtils, hooks);
+        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 Promise.all([
@@ -131,9 +141,10 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
     }
     // 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,
@@ -141,15 +152,32 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
             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) {
@@ -202,10 +230,12 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
     }
     async #registerPreloadedContracts() {
         const contracts = await this.preloadedContractsProvider.getPreloadedContracts();
-        await Promise.all(contracts.map(({ instance, artifact })=>this.registerContract({
-                instance,
-                artifact
-            })));
+        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())
         });
@@ -217,8 +247,6 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
         try {
             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,
@@ -228,7 +256,7 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
             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;
         }
@@ -252,7 +280,8 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
             };
         } 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;
         }
@@ -274,7 +303,8 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
         } 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}`);
                 }
@@ -293,7 +323,7 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
    * @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, anchorBlockHeader, config) {
-        const kernelOracle = new PrivateKernelOracle(this.contractStore, this.keyStore, this.node, anchorBlockHeader);
+        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);
@@ -324,9 +354,9 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
         });
     }
     /**
-   * 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);
     }
@@ -338,17 +368,21 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
         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);
+        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;
@@ -360,50 +394,144 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
         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.some((a)=>a.equals(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. Queued to avoid wiping while a job is in flight.
+            // Queued to avoid wiping while a job is in flight.
             await this.#putInJobQueue(()=>Promise.resolve(this.contractSyncService.wipe()));
-        } else {
-            this.log.info(`Sender:\n "${sender.toString()}"\n already registered.`);
         }
-        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.
@@ -421,76 +549,34 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
    * @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));
-            if (publicFunctionSignatures.length > 0) {
-                await this.node.registerContractFunctionSignatures(publicFunctionSignatures);
-            }
-        } else {
-            // Otherwise, make sure there is an artifact already registered for that class id
-            artifact = await this.contractStore.getContractArtifact(instance.currentContractClassId);
-            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.#maybeSync();
-            const header = await this.anchorBlockStore.getBlockHeader();
-            const currentClassId = await readCurrentClassId(contractAddress, currentInstance, this.node, header);
-            if (!contractClass.id.equals(currentClassId)) {
-                throw new Error('Could not update contract to a class different from the current one.');
-            }
-            const publicFunctionSignatures = artifact.functions.filter((fn)=>fn.functionType === FunctionType.PUBLIC).map((fn)=>decodeFunctionSignature(fn.name, fn.parameters));
-            if (publicFunctionSignatures.length > 0) {
-                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;
         });
     }
     /**
@@ -684,7 +770,7 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
                 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, anchorBlockHeader, {
@@ -702,7 +788,7 @@ import { persistSenderTaggingIndexRangesForTx } from './tagging/index.js';
                     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;

package/dest/storage/allowed_scopes.d.ts

@@ -0,0 +1,6 @@
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+/**
+ * Asserts that `scope` is one of `allowedScopes`, throwing otherwise.
+ */
+export declare function assertAllowedScope(scope: AztecAddress, allowedScopes: AztecAddress[]): void;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWxsb3dlZF9zY29wZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zdG9yYWdlL2FsbG93ZWRfc2NvcGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUUzRDs7R0FFRztBQUNILHdCQUFnQixrQkFBa0IsQ0FBQyxLQUFLLEVBQUUsWUFBWSxFQUFFLGFBQWEsRUFBRSxZQUFZLEVBQUUsR0FBRyxJQUFJLENBUTNGIn0=

package/dest/storage/allowed_scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed_scopes.d.ts","sourceRoot":"","sources":["../../src/storage/allowed_scopes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,IAAI,CAQ3F"}

package/dest/storage/allowed_scopes.js

@@ -0,0 +1,7 @@
+/**
+ * Asserts that `scope` is one of `allowedScopes`, throwing otherwise.
+ */ export function assertAllowedScope(scope, allowedScopes) {
+    if (!allowedScopes.some((allowed)=>allowed.equals(scope))) {
+        throw new Error(`Scope ${scope.toString()} is not in the allowed scopes list: [${allowedScopes.map((s)=>s.toString()).join(', ')}]. See https://docs.aztec.network/errors/10`);
+    }
+}

package/dest/storage/anchor_block_store/anchor_block_store.d.ts

@@ -1,17 +1,20 @@
 import type { AztecAsyncKVStore } from '@aztec/kv-store';
 import { BlockHeader } from '@aztec/stdlib/tx';
+/**
+ * Holds the block header that PXE's private execution is anchored to. Updated by the BlockSynchronizer as the chain
+ * advances or reorgs.
+ */
 export declare class AnchorBlockStore {
     #private;
     constructor(store: AztecAsyncKVStore);
     /**
-     * Sets the currently synchronized block
-     *
-     * Important: this method is only called from BlockSynchronizer, and since we need it to run atomically with other
-     * stores in the case of a reorg, it MUST NOT be wrapped in a `transactionAsync` call. Doing so would result in a
-     * deadlock when the backend is IndexedDB, because `transactionAsync` is not designed to support reentrancy.
+     * Sets the currently synchronized block header.
      *
+     * Important: only called from BlockSynchronizer, and since it must run atomically with other stores in a reorg, it
+     * MUST NOT be wrapped in `transactionAsync`: doing so deadlocks when the kv-store backend is IndexedDB (no
+     * support for reentrancy).
      */
     setHeader(header: BlockHeader): Promise<void>;
     getBlockHeader(): Promise<BlockHeader>;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYW5jaG9yX2Jsb2NrX3N0b3JlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9hbmNob3JfYmxvY2tfc3RvcmUvYW5jaG9yX2Jsb2NrX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUF1QixNQUFNLGlCQUFpQixDQUFDO0FBQzlFLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUUvQyxxQkFBYSxnQkFBZ0I7O0lBSTNCLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQUduQztJQUVEOzs7Ozs7O09BT0c7SUFDRyxTQUFTLENBQUMsTUFBTSxFQUFFLFdBQVcsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBRWxEO0lBRUssY0FBYyxJQUFJLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FPM0M7Q0FDRiJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYW5jaG9yX2Jsb2NrX3N0b3JlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9hbmNob3JfYmxvY2tfc3RvcmUvYW5jaG9yX2Jsb2NrX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUF1QixNQUFNLGlCQUFpQixDQUFDO0FBQzlFLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUUvQzs7O0dBR0c7QUFDSCxxQkFBYSxnQkFBZ0I7O0lBSTNCLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQUduQztJQUVEOzs7Ozs7T0FNRztJQUNHLFNBQVMsQ0FBQyxNQUFNLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFbEQ7SUFFSyxjQUFjLElBQUksT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQU0zQztDQUNGIn0=

package/dest/storage/anchor_block_store/anchor_block_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor_block_store.d.ts","sourceRoot":"","sources":["../../../src/storage/anchor_block_store/anchor_block_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAuB,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,qBAAa,gBAAgB;;IAI3B,YAAY,KAAK,EAAE,iBAAiB,EAGnC;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;IAEK,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAO3C;CACF"}
+{"version":3,"file":"anchor_block_store.d.ts","sourceRoot":"","sources":["../../../src/storage/anchor_block_store/anchor_block_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAuB,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;GAGG;AACH,qBAAa,gBAAgB;;IAI3B,YAAY,KAAK,EAAE,iBAAiB,EAGnC;IAED;;;;;;OAMG;IACG,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;IAEK,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAM3C;CACF"}