@aztec/txe 5.0.0-private.20260318 → 5.0.0-rc.1

package/dest/oracle/txe_oracle_top_level_context.js

@@ -1,11 +1,11 @@
-import { CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS, DEFAULT_DA_GAS_LIMIT, DEFAULT_L2_GAS_LIMIT, DEFAULT_TEARDOWN_DA_GAS_LIMIT, DEFAULT_TEARDOWN_L2_GAS_LIMIT, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
+import { CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS, MAX_PRIVATE_LOGS_PER_TX, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Schnorr } from '@aztec/foundation/crypto/schnorr';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { LogLevels, applyStringFormatting, createLogger } from '@aztec/foundation/log';
 import { TestDateProvider } from '@aztec/foundation/timer';
-import { ORACLE_VERSION, enrichPublicSimulationError } from '@aztec/pxe/server';
-import { ExecutionNoteCache, ExecutionTaggingIndexCache, HashedValuesCache, Oracle, PrivateExecutionOracle, UtilityExecutionOracle, executePrivateFunction, generateSimulatedProvingResult } from '@aztec/pxe/simulator';
+import { CapsuleService, ORACLE_VERSION_MAJOR, composeHooks, enrichPublicSimulationError } from '@aztec/pxe/server';
+import { ExecutionNoteCache, ExecutionTaggingIndexCache, HashedValuesCache, PrivateExecutionOracle, TransientArrayService, UtilityExecutionOracle, buildACIRCallback, executePrivateFunction, generateSimulatedProvingResult } from '@aztec/pxe/simulator';
 import { ExecutionError, WASMSimulator, createSimulationError, extractCallStack, resolveAssertionMessageFromError, toACVMWitness, witnessMapToFields } from '@aztec/simulator/client';
 import { CppPublicTxSimulator, GuardedMerkleTreeOperations, PublicContractsDB, PublicProcessor } from '@aztec/simulator/server';
 import { FunctionCall, FunctionSelector, FunctionType } from '@aztec/stdlib/abi';
@@ -13,17 +13,18 @@ import { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { PublicSimulatorConfig } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { computePartialAddress } from '@aztec/stdlib/contract';
-import { Gas, GasFees, GasSettings } from '@aztec/stdlib/gas';
+import { Gas, GasFees } from '@aztec/stdlib/gas';
 import { computeCalldataHash, computeProtocolNullifier, siloNullifier } from '@aztec/stdlib/hash';
 import { PartialPrivateTailPublicInputsForPublic, PrivateKernelTailCircuitPublicInputs, PrivateToPublicAccumulatedData, PublicCallRequest } from '@aztec/stdlib/kernel';
+import { hashPublicKey } from '@aztec/stdlib/keys';
 import { ChonkProof } from '@aztec/stdlib/proofs';
 import { makeGlobalVariables } from '@aztec/stdlib/testing';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
 import { CallContext, HashedValues, PrivateExecutionResult, Tx, TxConstantData, TxContext, TxEffect, TxHash, collectNested } from '@aztec/stdlib/tx';
-import { ForkCheckpoint } from '@aztec/world-state';
-import { DEFAULT_ADDRESS } from '../constants.js';
-import { TXEPublicContractDataSource } from '../util/txe_public_contract_data_source.js';
+import { ForkCheckpoint } from '@aztec/world-state/native';
+import { DEFAULT_ADDRESS, MAX_PRIVATE_EVENTS_PER_TXE_QUERY, MAX_PRIVATE_EVENT_LEN } from '../constants.js';
 import { getSingleTxBlockRequestHash, insertTxEffectIntoWorldTrees, makeTXEBlock } from '../utils/block_creation.js';
+import { TXEPublicContractDataSource } from '../utils/txe_public_contract_data_source.js';
 export class TXEOracleTopLevelContext {
     stateMachine;
     contractStore;
@@ -40,10 +41,13 @@ export class TXEOracleTopLevelContext {
     version;
     chainId;
     authwits;
+    artifactResolver;
+    rootPath;
+    packageName;
     isMisc;
     isTxe;
     logger;
-    constructor(stateMachine, contractStore, noteStore, keyStore, addressStore, accountStore, senderTaggingStore, recipientTaggingStore, senderAddressBookStore, capsuleStore, privateEventStore, nextBlockTimestamp, version, chainId, authwits){
+    constructor(stateMachine, contractStore, noteStore, keyStore, addressStore, accountStore, senderTaggingStore, recipientTaggingStore, senderAddressBookStore, capsuleStore, privateEventStore, nextBlockTimestamp, version, chainId, authwits, artifactResolver, rootPath, packageName){
         this.stateMachine = stateMachine;
         this.contractStore = contractStore;
         this.noteStore = noteStore;
@@ -59,15 +63,28 @@ export class TXEOracleTopLevelContext {
         this.version = version;
         this.chainId = chainId;
         this.authwits = authwits;
+        this.artifactResolver = artifactResolver;
+        this.rootPath = rootPath;
+        this.packageName = packageName;
         this.isMisc = true;
         this.isTxe = true;
         this.logger = createLogger('txe:top_level_context');
         this.logger.debug('Entering Top Level Context');
     }
-    assertCompatibleOracleVersion(version) {
-        if (version !== ORACLE_VERSION) {
-            throw new Error(`Incompatible oracle version. TXE is using version '${ORACLE_VERSION}', but got a request for '${version}'.`);
+    contractOracleVersion;
+    assertCompatibleOracleVersion(major, minor) {
+        if (major !== ORACLE_VERSION_MAJOR) {
+            const hint = major > ORACLE_VERSION_MAJOR ? 'The contract was compiled with a newer version of Aztec.nr than this aztec cli version supports. Upgrade your aztec cli version to a compatible version.' : 'The contract was compiled with an older version of Aztec.nr than this aztec cli version supports. Recompile the contract with a compatible version of Aztec.nr.';
+            throw new Error(`Incompatible aztec cli version: ${hint} See https://docs.aztec.network/errors/8 (expected oracle major version ${ORACLE_VERSION_MAJOR}, got ${major})`);
         }
+        this.contractOracleVersion = {
+            major,
+            minor
+        };
+    }
+    // Prefixed with "nonOracleFunction" as it is not used as an oracle handler.
+    nonOracleFunctionGetContractOracleVersion() {
+        return this.contractOracleVersion;
     }
     // This is typically only invoked in private contexts, but it is convenient to also have it in top-level for testing
     // setup.
@@ -75,7 +92,7 @@ export class TXEOracleTopLevelContext {
         return Fr.random();
     }
     // We instruct users to debug contracts via this oracle, so it makes sense that they'd expect it to also work in tests
-    log(level, message, fields) {
+    log(level, message, _fieldsSize, fields) {
         if (!LogLevels[level]) {
             throw new Error(`Invalid log level: ${level}`);
         }
@@ -95,20 +112,27 @@ export class TXEOracleTopLevelContext {
         return Promise.resolve(this.nextBlockTimestamp);
     }
     async getLastBlockTimestamp() {
-        return (await this.stateMachine.node.getBlockHeader('latest')).globalVariables.timestamp;
+        return (await this.stateMachine.node.getBlockData('latest')).header.globalVariables.timestamp;
     }
     async getLastTxEffects() {
         const latestBlockNumber = await this.stateMachine.archiver.getBlockNumber();
-        const block = await this.stateMachine.archiver.getBlock(latestBlockNumber);
+        const block = await this.stateMachine.archiver.getBlock({
+            number: latestBlockNumber
+        });
         if (block.body.txEffects.length != 1) {
             // Note that calls like env.mine() will result in blocks with no transactions, hitting this
             throw new Error(`Expected a single transaction in the last block, found ${block.body.txEffects.length}`);
         }
         const txEffects = block.body.txEffects[0];
+        const privateLogs = txEffects.privateLogs;
+        if (privateLogs.length > MAX_PRIVATE_LOGS_PER_TX) {
+            throw new Error(`${privateLogs.length} private logs exceed max ${MAX_PRIVATE_LOGS_PER_TX}`);
+        }
         return {
             txHash: txEffects.txHash,
             noteHashes: txEffects.noteHashes,
-            nullifiers: txEffects.nullifiers
+            nullifiers: txEffects.nullifiers,
+            privateLogs
         };
     }
     async syncContractNonOracleMethod(contractAddress, scope, jobId) {
@@ -124,7 +148,7 @@ export class TXEOracleTopLevelContext {
         ]);
     }
     async getPrivateEvents(selector, contractAddress, scope) {
-        return (await this.privateEventStore.getPrivateEvents(selector, {
+        const events = (await this.privateEventStore.getPrivateEvents(selector, {
             contractAddress,
             scopes: [
                 scope
@@ -132,6 +156,13 @@ export class TXEOracleTopLevelContext {
             fromBlock: 0,
             toBlock: await this.getLastBlockNumber() + 1
         })).map((e)=>e.packedEvent);
+        if (events.length > MAX_PRIVATE_EVENTS_PER_TXE_QUERY) {
+            throw new Error(`Array of length ${events.length} larger than maxLen ${MAX_PRIVATE_EVENTS_PER_TXE_QUERY}`);
+        }
+        if (events.some((e)=>e.length > MAX_PRIVATE_EVENT_LEN)) {
+            throw new Error(`Some private event has length larger than maxLen ${MAX_PRIVATE_EVENT_LEN}`);
+        }
+        return events;
     }
     async advanceBlocksBy(blocks) {
         this.logger.debug(`time traveling ${blocks} blocks`);
@@ -143,22 +174,54 @@ export class TXEOracleTopLevelContext {
         this.logger.debug(`time traveling ${duration} seconds`);
         this.nextBlockTimestamp += duration;
     }
-    async deploy(artifact, instance, secret) {
+    deploymentNullifier(address) {
+        return siloNullifier(AztecAddress.fromNumber(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS), address.toField());
+    }
+    async deploy(contractPath, initializer, args, secret, salt, deployer) {
+        const { artifact, instance } = await this.artifactResolver.resolveDeployArtifact({
+            rootPath: this.rootPath,
+            packageName: this.packageName,
+            contractPath,
+            initializer,
+            args,
+            secret,
+            salt,
+            deployer
+        });
         // Emit deployment nullifier
         await this.mineBlock({
             nullifiers: [
-                await siloNullifier(AztecAddress.fromNumber(CONTRACT_INSTANCE_REGISTRY_CONTRACT_ADDRESS), instance.address.toField())
+                await this.deploymentNullifier(instance.address)
             ]
         });
         if (!secret.equals(Fr.ZERO)) {
-            await this.addAccount(artifact, instance, secret);
+            await this.registerContractAndAddAccount(artifact, instance, secret);
         } else {
             await this.contractStore.addContractInstance(instance);
             await this.contractStore.addContractArtifact(artifact);
             this.logger.debug(`Deployed ${artifact.name} at ${instance.address}`);
         }
+        return [
+            instance.salt,
+            instance.deployer.toField(),
+            instance.currentContractClassId,
+            instance.initializationHash,
+            instance.immutablesHash,
+            ...instance.publicKeys.toFields()
+        ];
     }
-    async addAccount(artifact, instance, secret) {
+    /**
+   * Mines a single block containing only the deployment nullifiers for the contracts at the given addresses.
+   */ async mineDeploymentNullifiers(addresses) {
+        await this.mineBlock({
+            nullifiers: await Promise.all(addresses.map((address)=>this.deploymentNullifier(address)))
+        });
+    }
+    async addAccount(secret) {
+        const { artifact, instance } = await this.artifactResolver.resolveAccountArtifact(secret);
+        return this.registerContractAndAddAccount(artifact, instance, secret);
+    }
+    async registerContractAndAddAccount(artifact, instance, secret) {
         const partialAddress = await computePartialAddress(instance);
         this.logger.debug(`Deployed ${artifact.name} at ${instance.address}`);
         await this.contractStore.addContractInstance(instance);
@@ -179,12 +242,11 @@ export class TXEOracleTopLevelContext {
     }
     async addAuthWitness(address, messageHash) {
         const account = await this.accountStore.getAccount(address);
-        const privateKey = await this.keyStore.getMasterSecretKey(account.publicKeys.masterIncomingViewingPublicKey);
+        const ivpkMHash = await hashPublicKey(account.publicKeys.ivpkM);
+        const privateKey = await this.keyStore.getMasterSecretKey(ivpkMHash);
         const schnorr = new Schnorr();
-        const signature = await schnorr.constructSignature(messageHash.toBuffer(), privateKey);
-        const authWitness = new AuthWitness(messageHash, [
-            ...signature.toBuffer()
-        ]);
+        const signature = await schnorr.constructSignature(messageHash, privateKey);
+        const authWitness = new AuthWitness(messageHash, signature.toLimbFields());
         this.authwits.set(authWitness.requestHash.toString(), authWitness);
     }
     async mineBlock(options = {}) {
@@ -210,29 +272,26 @@ export class TXEOracleTopLevelContext {
         this.logger.info(`Created block ${blockNumber} with timestamp ${block.header.globalVariables.timestamp}`);
         await this.stateMachine.handleL2Block(block);
     }
-    async privateCallNewFlow(from, targetContractAddress = AztecAddress.zero(), functionSelector = FunctionSelector.empty(), args, argsHash = Fr.zero(), isStaticCall = false, jobId) {
+    async privateCallNewFlow(from, targetContractAddress = AztecAddress.zero(), functionSelector = FunctionSelector.empty(), args, argsHash = Fr.zero(), isStaticCall = false, additionalScopes = [], jobId, authorizedUtilityCallTargets, gasSettings) {
         this.logger.verbose(`Executing external function ${await this.contractStore.getDebugFunctionName(targetContractAddress, functionSelector)}@${targetContractAddress} isStaticCall=${isStaticCall}`);
         const artifact = await this.contractStore.getFunctionArtifact(targetContractAddress, functionSelector);
         if (!artifact) {
             const message = functionSelector.equals(await FunctionSelector.fromSignature('verify_private_authwit(Field)')) ? 'Found no account contract artifact for a private authwit check - use `create_contract_account` instead of `create_light_account` for authwit support.' : 'Function Artifact does not exist';
             throw new Error(message);
         }
-        // When `from` is the zero address (e.g. when deploying a new account contract), we return an
-        // empty scope list which acts as deny-all: no notes are visible and no keys are accessible.
-        const effectiveScopes = from.isZero() ? [] : [
-            from
+        const scopes = from === undefined ? additionalScopes : [
+            from,
+            ...additionalScopes
         ];
         // Sync notes before executing private function to discover notes from previous transactions
         const utilityExecutor = async (call, execScopes)=>{
             await this.executeUtilityCall(call, execScopes, jobId);
         };
         const blockHeader = await this.stateMachine.anchorBlockStore.getBlockHeader();
-        await this.stateMachine.contractSyncService.ensureContractSynced(targetContractAddress, functionSelector, utilityExecutor, blockHeader, jobId, effectiveScopes);
+        await this.stateMachine.contractSyncService.ensureContractSynced(targetContractAddress, functionSelector, utilityExecutor, blockHeader, jobId, scopes);
         const blockNumber = await this.getNextBlockNumber();
-        const callContext = new CallContext(from, targetContractAddress, functionSelector, isStaticCall);
-        const gasLimits = new Gas(DEFAULT_DA_GAS_LIMIT, DEFAULT_L2_GAS_LIMIT);
-        const teardownGasLimits = new Gas(DEFAULT_TEARDOWN_DA_GAS_LIMIT, DEFAULT_TEARDOWN_L2_GAS_LIMIT);
-        const gasSettings = new GasSettings(gasLimits, teardownGasLimits, GasFees.empty(), GasFees.empty());
+        const msgSender = from ?? AztecAddress.NULL_MSG_SENDER;
+        const callContext = new CallContext(msgSender, targetContractAddress, functionSelector, isStaticCall);
         const txContext = new TxContext(this.chainId, this.version, gasSettings);
         const protocolNullifier = await computeProtocolNullifier(getSingleTxBlockRequestHash(blockNumber));
         const noteCache = new ExecutionNoteCache(protocolNullifier);
@@ -243,6 +302,7 @@ export class TXEOracleTopLevelContext {
         await noteCache.setMinRevertibleSideEffectCounter(minRevertibleSideEffectCounter);
         const taggingIndexCache = new ExecutionTaggingIndexCache();
         const simulator = new WASMSimulator();
+        const transientArrayService = new TransientArrayService();
         const privateExecutionOracle = new PrivateExecutionOracle({
             argsHash,
             txContext,
@@ -264,18 +324,23 @@ export class TXEOracleTopLevelContext {
             senderTaggingStore: this.senderTaggingStore,
             recipientTaggingStore: this.recipientTaggingStore,
             senderAddressBookStore: this.senderAddressBookStore,
-            capsuleStore: this.capsuleStore,
+            capsuleService: new CapsuleService(this.capsuleStore, scopes),
             privateEventStore: this.privateEventStore,
             contractSyncService: this.stateMachine.contractSyncService,
             jobId,
             totalPublicCalldataCount: 0,
             sideEffectCounter: minRevertibleSideEffectCounter,
-            scopes: effectiveScopes,
+            scopes,
             // In TXE, the typical transaction entrypoint is skipped, so we need to simulate the actions that such a
             // contract would perform, including setting senderForTags.
             senderForTags: from,
             simulator,
-            messageContextService: this.stateMachine.messageContextService
+            messageContextService: this.stateMachine.messageContextService,
+            l2TipsStore: this.stateMachine.l2TipsProvider,
+            hooks: composeHooks({
+                authorizeUtilityCall: this.buildAuthorizeUtilityCallHook(isStaticCall ? 'private view' : 'private', authorizedUtilityCallTargets)
+            }),
+            transientArrayService
         });
         // Note: This is a slight modification of simulator.run without any of the checks. Maybe we should modify simulator.run with a boolean value to skip checks.
         let result;
@@ -288,7 +353,7 @@ export class TXEOracleTopLevelContext {
                     r.publicInputs.publicTeardownCallRequest
                 ]));
             const publicFunctionsCalldata = await Promise.all(publicCallRequests.map(async (r)=>{
-                const calldata = await privateExecutionOracle.loadFromExecutionCache(r.calldataHash);
+                const calldata = await privateExecutionOracle.getHashPreimage(r.calldataHash);
                 return new HashedValues(calldata, r.calldataHash);
             }));
             noteCache.finish();
@@ -347,10 +412,20 @@ export class TXEOracleTopLevelContext {
                 throw new Error('Contract execution has reverted');
             }
         }
+        // Walk the nested private-call tree and collect every offchain effect the transaction emitted.
+        // PXE stores these on each `PrivateCallExecutionResult` and they never reach TXE via the
+        // `aztec_utl_emitOffchainEffect` foreign-call path (that path only fires at the top-level), so
+        // we pull them out here and the RPC wrapper will hand them to `TXESession` for buffering.
+        const offchainEffects = collectNested([
+            executionResult
+        ], (r)=>r.offchainEffects.map((e)=>e.data));
         if (isStaticCall) {
             await checkpoint.revert();
             await forkedWorldTrees.close();
-            return executionResult.returnValues ?? [];
+            return {
+                returnValues: executionResult.returnValues ?? [],
+                offchainEffects
+            };
         }
         const txEffect = TxEffect.empty();
         txEffect.noteHashes = processedTx.txEffect.noteHashes;
@@ -366,14 +441,14 @@ export class TXEOracleTopLevelContext {
         ]);
         await this.stateMachine.handleL2Block(l2Block);
         await forkedWorldTrees.close();
-        return executionResult.returnValues ?? [];
+        return {
+            returnValues: executionResult.returnValues ?? [],
+            offchainEffects
+        };
     }
-    async publicCallNewFlow(from, targetContractAddress, calldata, isStaticCall) {
+    async publicCallNewFlow(from, targetContractAddress, calldata, isStaticCall, gasSettings) {
         this.logger.verbose(`Executing public function ${await this.contractStore.getDebugFunctionName(targetContractAddress, FunctionSelector.fromField(calldata[0]))}@${targetContractAddress} isStaticCall=${isStaticCall}`);
         const blockNumber = await this.getNextBlockNumber();
-        const gasLimits = new Gas(DEFAULT_DA_GAS_LIMIT, DEFAULT_L2_GAS_LIMIT);
-        const teardownGasLimits = new Gas(DEFAULT_TEARDOWN_DA_GAS_LIMIT, DEFAULT_TEARDOWN_L2_GAS_LIMIT);
-        const gasSettings = new GasSettings(gasLimits, teardownGasLimits, GasFees.empty(), GasFees.empty());
         const txContext = new TxContext(this.chainId, this.version, gasSettings);
         const anchorBlockHeader = await this.stateMachine.anchorBlockStore.getBlockHeader();
         const calldataHash = await computeCalldataHash(calldata);
@@ -406,7 +481,7 @@ export class TXEOracleTopLevelContext {
         // The enqueued public call itself we make be revertible so that the public execution is itself revertible, as tests
         // may require producing reverts.
         const revertibleAccumulatedData = PrivateToPublicAccumulatedData.empty();
-        revertibleAccumulatedData.publicCallRequests[0] = new PublicCallRequest(from, targetContractAddress, isStaticCall, calldataHash);
+        revertibleAccumulatedData.publicCallRequests[0] = new PublicCallRequest(from ?? AztecAddress.NULL_MSG_SENDER, targetContractAddress, isStaticCall, calldataHash);
         const inputsForPublic = new PartialPrivateTailPublicInputsForPublic(nonRevertibleAccumulatedData, revertibleAccumulatedData, PublicCallRequest.empty());
         const constantData = new TxConstantData(anchorBlockHeader, txContext, Fr.zero(), Fr.zero());
         const txData = new PrivateKernelTailCircuitPublicInputs(constantData, /*gasUsed=*/ new Gas(0, 0), /*feePayer=*/ AztecAddress.zero(), /*expirationTimestamp=*/ 0n, inputsForPublic, undefined);
@@ -462,7 +537,7 @@ export class TXEOracleTopLevelContext {
         await forkedWorldTrees.close();
         return returnValues ?? [];
     }
-    async executeUtilityFunction(targetContractAddress, functionSelector, args, jobId) {
+    async executeUtilityFunction(targetContractAddress, functionSelector, args, jobId, authorizedUtilityCallTargets) {
         const artifact = await this.contractStore.getFunctionArtifact(targetContractAddress, functionSelector);
         if (!artifact) {
             throw new Error(`Cannot call ${functionSelector} as there is no artifact found at ${targetContractAddress}.`);
@@ -471,7 +546,7 @@ export class TXEOracleTopLevelContext {
         const blockHeader = await this.stateMachine.anchorBlockStore.getBlockHeader();
         await this.stateMachine.contractSyncService.ensureContractSynced(targetContractAddress, functionSelector, async (call, execScopes)=>{
             await this.executeUtilityCall(call, execScopes, jobId);
-        }, blockHeader, jobId, 'ALL_SCOPES');
+        }, blockHeader, jobId, await this.keyStore.getAccounts());
         const call = FunctionCall.from({
             name: artifact.name,
             to: targetContractAddress,
@@ -482,9 +557,9 @@ export class TXEOracleTopLevelContext {
             args,
             returnTypes: []
         });
-        return this.executeUtilityCall(call, 'ALL_SCOPES', jobId);
+        return this.executeUtilityCall(call, await this.keyStore.getAccounts(), jobId, authorizedUtilityCallTargets);
     }
-    async executeUtilityCall(call, scopes, jobId) {
+    async executeUtilityCall(call, scopes, jobId, authorizedUtilityCallTargets = []) {
         const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(call.to, call.selector);
         if (entryPointArtifact.functionType !== FunctionType.UTILITY) {
             throw new Error(`Cannot run ${entryPointArtifact.functionType} function as utility`);
@@ -495,6 +570,10 @@ export class TXEOracleTopLevelContext {
         });
         try {
             const anchorBlockHeader = await this.stateMachine.anchorBlockStore.getBlockHeader();
+            const simulator = new WASMSimulator();
+            const utilityExecutor = async (syncCall, execScopes)=>{
+                await this.executeUtilityCall(syncCall, execScopes, jobId);
+            };
             const oracle = new UtilityExecutionOracle({
                 contractAddress: call.to,
                 authWitnesses: [],
@@ -507,13 +586,22 @@ export class TXEOracleTopLevelContext {
                 aztecNode: this.stateMachine.node,
                 recipientTaggingStore: this.recipientTaggingStore,
                 senderAddressBookStore: this.senderAddressBookStore,
-                capsuleStore: this.capsuleStore,
+                capsuleService: new CapsuleService(this.capsuleStore, scopes),
                 privateEventStore: this.privateEventStore,
                 messageContextService: this.stateMachine.messageContextService,
+                contractSyncService: this.stateMachine.contractSyncService,
+                l2TipsStore: this.stateMachine.l2TipsProvider,
                 jobId,
-                scopes
+                scopes,
+                simulator,
+                hooks: composeHooks({
+                    authorizeUtilityCall: this.buildAuthorizeUtilityCallHook('utility', authorizedUtilityCallTargets)
+                }),
+                utilityExecutor,
+                // Execution-tree root (top-level utility run or contract sync): own store; nested frames inherit it.
+                transientArrayService: new TransientArrayService()
             });
-            const acirExecutionResult = await new WASMSimulator().executeUserCircuit(toACVMWitness(0, call.args), entryPointArtifact, new Oracle(oracle).toACIRCallback()).catch((err)=>{
+            const acirExecutionResult = await simulator.executeUserCircuit(toACVMWitness(0, call.args), entryPointArtifact, buildACIRCallback(oracle)).catch((err)=>{
                 err.message = resolveAssertionMessageFromError(err, entryPointArtifact);
                 throw new ExecutionError(err.message, {
                     contractAddress: call.to,
@@ -536,7 +624,15 @@ export class TXEOracleTopLevelContext {
         ];
     }
     async getLastBlockNumber() {
-        const header = await this.stateMachine.node.getBlockHeader('latest');
-        return header ? header.globalVariables.blockNumber : BlockNumber.ZERO;
+        const block = await this.stateMachine.node.getBlock('latest');
+        return block ? block.header.globalVariables.blockNumber : BlockNumber.ZERO;
+    }
+    buildAuthorizeUtilityCallHook(callerContext, authorizedTargets) {
+        if (authorizedTargets.length === 0) {
+            return undefined;
+        }
+        return (req)=>Promise.resolve({
+                authorized: req.callerContext === callerContext && authorizedTargets.some((t)=>t.equals(req.target))
+            });
     }
 }

package/dest/oracle/txe_oracle_version.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The TXE oracle version constants are used to check that the oracle interface used for tests is in sync between
+ * TXE and Aztec.nr. This is separate from the contract oracle version in `pxe/src/oracle_version.ts`, which covers
+ * oracles used during contract execution by PXE.
+ *
+ * The Noir counterparts are in `noir-projects/aztec-nr/aztec/src/test/helpers/txe_oracles.nr`.
+ */
+export declare const TXE_ORACLE_VERSION_MAJOR = 1;
+export declare const TXE_ORACLE_VERSION_MINOR = 2;
+/**
+ * This hash is computed from the TXE oracle interfaces (IAvmExecutionOracle and ITxeExecutionOracle) and is used to
+ * detect when those interfaces change. When it does, bump:
+ *   - TXE_ORACLE_VERSION_MAJOR (and reset MINOR to 0) for breaking changes, or
+ *   - TXE_ORACLE_VERSION_MINOR for additive changes (new oracle method added).
+ */
+export declare const TXE_ORACLE_INTERFACE_HASH = "9e5f6ad5fd170d1de5ddd417f19cce47b17382567e08360dc6a783154828e218";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhlX29yYWNsZV92ZXJzaW9uLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvb3JhY2xlL3R4ZV9vcmFjbGVfdmVyc2lvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7O0dBTUc7QUFDSCxlQUFPLE1BQU0sd0JBQXdCLElBQUksQ0FBQztBQUMxQyxlQUFPLE1BQU0sd0JBQXdCLElBQUksQ0FBQztBQUUxQzs7Ozs7R0FLRztBQUNILGVBQU8sTUFBTSx5QkFBeUIscUVBQXFFLENBQUMifQ==

package/dest/oracle/txe_oracle_version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txe_oracle_version.d.ts","sourceRoot":"","sources":["../../src/oracle/txe_oracle_version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,qEAAqE,CAAC"}

package/dest/oracle/txe_oracle_version.js

@@ -0,0 +1,14 @@
+/**
+ * The TXE oracle version constants are used to check that the oracle interface used for tests is in sync between
+ * TXE and Aztec.nr. This is separate from the contract oracle version in `pxe/src/oracle_version.ts`, which covers
+ * oracles used during contract execution by PXE.
+ *
+ * The Noir counterparts are in `noir-projects/aztec-nr/aztec/src/test/helpers/txe_oracles.nr`.
+ */ export const TXE_ORACLE_VERSION_MAJOR = 1;
+export const TXE_ORACLE_VERSION_MINOR = 2;
+/**
+ * This hash is computed from the TXE oracle interfaces (IAvmExecutionOracle and ITxeExecutionOracle) and is used to
+ * detect when those interfaces change. When it does, bump:
+ *   - TXE_ORACLE_VERSION_MAJOR (and reset MINOR to 0) for breaking changes, or
+ *   - TXE_ORACLE_VERSION_MINOR for additive changes (new oracle method added).
+ */ export const TXE_ORACLE_INTERFACE_HASH = '9e5f6ad5fd170d1de5ddd417f19cce47b17382567e08360dc6a783154828e218';

package/dest/oracle/txe_private_execution_oracle.d.ts

@@ -0,0 +1,17 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { PrivateExecutionOracle } from '@aztec/pxe/simulator';
+import type { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+/**
+ * TXE-specific subclass of PrivateExecutionOracle that forbids operations not supported in
+ * TestEnvironment::private_context. TXE uses dedicated oracle flows (e.g. private_call) instead.
+ */
+export declare class TXEPrivateExecutionOracle extends PrivateExecutionOracle {
+    callPrivateFunction(_targetContractAddress: AztecAddress, _functionSelector: FunctionSelector, _argsHash: Fr, _sideEffectCounter: number, _isStaticCall: boolean): Promise<{
+        endSideEffectCounter: Fr;
+        returnsHash: Fr;
+    }>;
+    assertValidPublicCalldata(_calldataHash: Fr): Promise<void>;
+    notifyRevertiblePhaseStart(_minRevertibleSideEffectCounter: number): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHhlX3ByaXZhdGVfZXhlY3V0aW9uX29yYWNsZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL29yYWNsZS90eGVfcHJpdmF0ZV9leGVjdXRpb25fb3JhY2xlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ3pELE9BQU8sRUFBRSxzQkFBc0IsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBQzlELE9BQU8sS0FBSyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFDMUQsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFFaEU7OztHQUdHO0FBQ0gscUJBQWEseUJBQTBCLFNBQVEsc0JBQXNCO0lBQzFELG1CQUFtQixDQUMxQixzQkFBc0IsRUFBRSxZQUFZLEVBQ3BDLGlCQUFpQixFQUFFLGdCQUFnQixFQUNuQyxTQUFTLEVBQUUsRUFBRSxFQUNiLGtCQUFrQixFQUFFLE1BQU0sRUFDMUIsYUFBYSxFQUFFLE9BQU8sR0FDckIsT0FBTyxDQUFDO1FBQUUsb0JBQW9CLEVBQUUsRUFBRSxDQUFDO1FBQUMsV0FBVyxFQUFFLEVBQUUsQ0FBQTtLQUFFLENBQUMsQ0FJeEQ7SUFFUSx5QkFBeUIsQ0FBQyxhQUFhLEVBQUUsRUFBRSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFbkU7SUFFUSwwQkFBMEIsQ0FBQywrQkFBK0IsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUUxRjtDQUNGIn0=

package/dest/oracle/txe_private_execution_oracle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txe_private_execution_oracle.d.ts","sourceRoot":"","sources":["../../src/oracle/txe_private_execution_oracle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,sBAAsB;IAC1D,mBAAmB,CAC1B,sBAAsB,EAAE,YAAY,EACpC,iBAAiB,EAAE,gBAAgB,EACnC,SAAS,EAAE,EAAE,EACb,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,OAAO,GACrB,OAAO,CAAC;QAAE,oBAAoB,EAAE,EAAE,CAAC;QAAC,WAAW,EAAE,EAAE,CAAA;KAAE,CAAC,CAIxD;IAEQ,yBAAyB,CAAC,aAAa,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;IAEQ,0BAA0B,CAAC,+BAA+B,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1F;CACF"}

package/dest/oracle/txe_private_execution_oracle.js

@@ -0,0 +1,15 @@
+import { PrivateExecutionOracle } from '@aztec/pxe/simulator';
+/**
+ * TXE-specific subclass of PrivateExecutionOracle that forbids operations not supported in
+ * TestEnvironment::private_context. TXE uses dedicated oracle flows (e.g. private_call) instead.
+ */ export class TXEPrivateExecutionOracle extends PrivateExecutionOracle {
+    callPrivateFunction(_targetContractAddress, _functionSelector, _argsHash, _sideEffectCounter, _isStaticCall) {
+        throw new Error('Contract calls are forbidden inside a `TestEnvironment::private_context`, use `private_call` instead');
+    }
+    assertValidPublicCalldata(_calldataHash) {
+        throw new Error('Enqueueing public calls is not supported in TestEnvironment::private_context');
+    }
+    notifyRevertiblePhaseStart(_minRevertibleSideEffectCounter) {
+        throw new Error('Enqueueing public calls is not supported in TestEnvironment::private_context');
+    }
+}

package/dest/rpc_server.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from '@aztec/foundation/log';
+/**
+ * Creates the TXE RPC server. With `TXE_WORKERS=1` oracle calls run on the main thread (no
+ * worker_threads, no IPC overhead). With any other value oracle calls are
+ * routed to a pool of worker threads sized to that value, sticky by `session_id`.
+ *
+ * Each incoming TCP socket is tagged with the `session_id` of the first oracle call it carries —
+ * nargo uses one HTTP client per test, so the socket-to-session mapping is 1:1. When the socket
+ * closes (end of test), the dispatcher disposes the session and frees its world state + LMDB.
+ *
+ * Lives in its own module so the worker bundle does not pull in the HTTP server stack.
+ */
+export declare function createTXERpcServer(logger: Logger): Promise<import("@aztec/foundation/json-rpc/server").SafeJsonRpcServer>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnBjX3NlcnZlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3JwY19zZXJ2ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFlcEQ7Ozs7Ozs7Ozs7R0FVRztBQUNILHdCQUFzQixrQkFBa0IsQ0FBQyxNQUFNLEVBQUUsTUFBTSwwRUE0Q3REIn0=

package/dest/rpc_server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc_server.d.ts","sourceRoot":"","sources":["../src/rpc_server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAepD;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,0EA4CtD"}

package/dest/rpc_server.js

@@ -0,0 +1,78 @@
+import { createSafeJsonRpcServer } from '@aztec/foundation/json-rpc/server';
+import { TXEDispatcherPool, buildSharedContractStore } from './dispatcher_pool.js';
+import { TXEDispatcher, TXEDispatcherApiSchema } from './index.js';
+/**
+ * Symbol used to tag an incoming TCP socket with the `session_id` it has been associated with.
+ * Hidden under a Symbol so we don't risk colliding with anything koa or http core adds.
+ */ const SESSION_SYMBOL = Symbol('txeSessionId');
+/**
+ * Creates the TXE RPC server. With `TXE_WORKERS=1` oracle calls run on the main thread (no
+ * worker_threads, no IPC overhead). With any other value oracle calls are
+ * routed to a pool of worker threads sized to that value, sticky by `session_id`.
+ *
+ * Each incoming TCP socket is tagged with the `session_id` of the first oracle call it carries —
+ * nargo uses one HTTP client per test, so the socket-to-session mapping is 1:1. When the socket
+ * closes (end of test), the dispatcher disposes the session and frees its world state + LMDB.
+ *
+ * Lives in its own module so the worker bundle does not pull in the HTTP server stack.
+ */ export async function createTXERpcServer(logger) {
+    const workerCount = Number(process.env.TXE_WORKERS);
+    let dispatcher;
+    if (workerCount === 1) {
+        const { dataDir, schnorrClassId } = await buildSharedContractStore();
+        dispatcher = new TXEDispatcher(logger, {
+            contractStoreSourceDir: dataDir,
+            schnorrClassId
+        });
+    } else {
+        dispatcher = new TXEDispatcherPool(logger, {
+            workers: Number.isFinite(workerCount) && workerCount > 1 ? workerCount : undefined
+        });
+    }
+    const server = createSafeJsonRpcServer(dispatcher, TXEDispatcherApiSchema, {
+        http200OnError: true,
+        middlewares: [
+            async (ctx, next)=>{
+                // The body parser runs further down the chain, so `ctx.request.body` is populated only
+                // after `next()` resolves.
+                await next();
+                const socket = ctx.req.socket;
+                if (socket[SESSION_SYMBOL] !== undefined) {
+                    return;
+                }
+                const body = ctx.request.body;
+                const sessionId = body && typeof body === 'object' && 'params' in body ? extractSessionId(body.params) : undefined;
+                if (sessionId === undefined) {
+                    return;
+                }
+                socket[SESSION_SYMBOL] = sessionId;
+                logger.debug(`Tagged socket with session`, {
+                    sessionId,
+                    remoteAddress: socket.remoteAddress,
+                    remotePort: socket.remotePort
+                });
+                socket.once('close', ()=>{
+                    logger.debug(`Disposing session on socket close`, {
+                        sessionId
+                    });
+                    void dispatcher.disposeSession(sessionId);
+                });
+            }
+        ]
+    });
+    return server;
+}
+// Extracts `session_id` from a JSON-RPC `params` array. Always a `number` because session_id
+// comes off `JSON.parse`, which never produces BigInt; values above MAX_SAFE_INTEGER lose
+// precision but still work as a Map key.
+function extractSessionId(params) {
+    if (!Array.isArray(params) || params.length === 0) {
+        return undefined;
+    }
+    const first = params[0];
+    if (first && typeof first === 'object' && 'session_id' in first) {
+        const sid = first.session_id;
+        return typeof sid === 'number' ? sid : undefined;
+    }
+    return undefined;
+}