@aztec/txe 0.0.1-commit.7b97ef96e → 0.0.1-commit.7cbc774

package/src/txe_session.ts

@@ -2,11 +2,12 @@ import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import { KeyStore } from '@aztec/key-store';
-import { openTmpStore } from '@aztec/kv-store/lmdb-v2';
-import type { AccessScopes } from '@aztec/pxe/client/lazy';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import { openEphemeralStore } from '@aztec/kv-store/lmdb-v2';
 import {
   AddressStore,
   AnchorBlockStore,
+  CapsuleService,
   CapsuleStore,
   ContractStore,
   JobCoordinator,
@@ -24,7 +25,6 @@ import {
   type IPrivateExecutionOracle,
   type IUtilityExecutionOracle,
   Oracle,
-  PrivateExecutionOracle,
   UtilityExecutionOracle,
 } from '@aztec/pxe/simulator';
 import {
@@ -35,28 +35,31 @@ import {
   resolveAssertionMessageFromError,
   toACVMWitness,
 } from '@aztec/simulator/client';
+import { STANDARD_AUTH_REGISTRY_ADDRESS } from '@aztec/standard-contracts/auth-registry/constants';
 import { FunctionCall, FunctionSelector, FunctionType } from '@aztec/stdlib/abi';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { GasSettings } from '@aztec/stdlib/gas';
+import type { GasSettings } from '@aztec/stdlib/gas';
 import { computeProtocolNullifier } from '@aztec/stdlib/hash';
 import { PrivateContextInputs } from '@aztec/stdlib/kernel';
 import { makeGlobalVariables } from '@aztec/stdlib/testing';
-import { CallContext, GlobalVariables, TxContext } from '@aztec/stdlib/tx';
+import { CallContext, GlobalVariables, OFFCHAIN_MESSAGE_IDENTIFIER, TxContext } from '@aztec/stdlib/tx';
 
 import { z } from 'zod';
 
-import { DEFAULT_ADDRESS } from './constants.js';
+import { DEFAULT_ADDRESS, MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY, MAX_OFFCHAIN_EFFECT_LEN } from './constants.js';
 import type { IAvmExecutionOracle, ITxeExecutionOracle } from './oracle/interfaces.js';
 import { TXEOraclePublicContext } from './oracle/txe_oracle_public_context.js';
 import { TXEOracleTopLevelContext } from './oracle/txe_oracle_top_level_context.js';
+import { TXEPrivateExecutionOracle } from './oracle/txe_private_execution_oracle.js';
 import { RPCTranslator } from './rpc_translator.js';
 import { TXEArchiver } from './state_machine/archiver.js';
 import { TXEStateMachine } from './state_machine/index.js';
-import type { ForeignCallArgs, ForeignCallResult } from './util/encoding.js';
-import { TXEAccountStore } from './util/txe_account_store.js';
+import { TXE_ORACLE_VERSION_MAJOR, TXE_ORACLE_VERSION_MINOR } from './txe_oracle_version.js';
 import { getSingleTxBlockRequestHash, insertTxEffectIntoWorldTrees, makeTXEBlock } from './utils/block_creation.js';
+import type { ForeignCallArgs, ForeignCallResult } from './utils/encoding.js';
 import { makeTxEffect } from './utils/tx_effect_creation.js';
+import { TXEAccountStore } from './utils/txe_account_store.js';
 
 /**
  * A TXE Session can be in one of four states, which change as the test progresses and different oracles are called.
@@ -109,10 +112,80 @@ export type TXEOracleFunctionName = Exclude<
 >;
 
 export interface TXESessionStateHandler {
+  /** Records the TXE oracle version reported by the Noir test code for diagnostics. */
+  setTxeOracleVersion(major: number, minor: number): void;
+
   enterTopLevelState(): Promise<void>;
   enterPublicState(contractAddress?: AztecAddress): Promise<void>;
-  enterPrivateState(contractAddress?: AztecAddress, anchorBlockNumber?: BlockNumber): Promise<PrivateContextInputs>;
+  enterPrivateState(
+    contractAddress: AztecAddress | undefined,
+    anchorBlockNumber: BlockNumber | undefined,
+    gasSettings: GasSettings,
+  ): Promise<PrivateContextInputs>;
   enterUtilityState(contractAddress?: AztecAddress): Promise<void>;
+
+  // TODO(F-335): Exposing the job info is abstraction breakage - drop the following 2 functions.
+  cycleJob(): Promise<string>;
+  getCurrentJob(): string;
+
+  /**
+   * Runs an executor-style top-level call (private/public call, utility execution) with last-call tracking.
+   */
+  withTopLevelCallTracking<T>(work: () => Promise<{ result: T; txHash?: Fr }>): Promise<T>;
+
+  /**
+   * Captures a raw offchain effect payload for consumption from test environment. Called by the `emit_offchain_effect`
+   * oracle handler whenever a contract function emits an offchain message, at any call depth.
+   */
+  recordOffchainEffect(data: Fr[]): void;
+
+  /**
+   * Returns the raw offchain effect payloads emitted by the last top-level call. Each payload follows the protocol
+   * convention documented on `OFFCHAIN_MESSAGE_IDENTIFIER`, i.e. `[identifier, recipient, ...ciphertext]`. Decoding into
+   * `OffchainMessage` structs happens on the Noir side of the test helper. Marks the buffer as queried so the
+   * unqueried-messages warning doesn't fire on the next reset.
+   */
+  getLastCallOffchainEffects(): { effects: Fr[][] };
+
+  /**
+   * Returns the context of the last top-level call: its tx hash (`Fr.ZERO` if the call was tx-less) and the anchor
+   * block timestamp captured at the start of the call. Does *not* mark the buffer as queried — context reads are
+   * metadata, not effect consumption.
+   */
+  getLastCallContext(): { txHash: Fr; anchorBlockTimestamp: bigint };
+}
+
+/**
+ * Session state tracking the most recently completed top-level call: the offchain effect buffer it produced, and the
+ * call's context (tx hash + anchor block timestamp). The context is refreshed on every top-level call, independently
+ * of whether the call produced offchain effects.
+ */
+interface LastCallState {
+  /**
+   * Raw offchain effect payloads emitted by the currently-executing (or most recently completed) top-level call. Wiped
+   * at the start of every top-level entry point, appended to on every `emit_offchain_effect` oracle invocation.
+   */
+  offchainEffects: Fr[][];
+  /**
+   * Tracks whether the test has queried `effects` since the last reset. If a new top-level call clobbers the buffer
+   * without it being queried first, any accumulated messages are lost and we emit a warning so tests don't silently
+   * drop delivery.
+   */
+  queried: boolean;
+  /**
+   * Tx hash of the most recently completed top-level call, or `Fr.ZERO` if the call was tx-less (context setters,
+   * utility execution). Populated by call executor handlers after execution completes.
+   */
+  txHash: Fr;
+  /**
+   * Anchor block timestamp of the most recently completed top-level call, captured from the anchor block header that
+   * was active when the call started. Populated by call executor handlers after execution completes.
+   */
+  anchorBlockTimestamp: bigint;
+}
+
+function emptyLastCallState(): LastCallState {
+  return { offchainEffects: [], queried: false, txHash: Fr.ZERO, anchorBlockTimestamp: 0n };
 }
 
 /**
@@ -122,9 +195,14 @@ export interface TXESessionStateHandler {
 export class TXESession implements TXESessionStateHandler {
   private state: SessionState = { name: 'TOP_LEVEL' };
   private authwits: Map<string, AuthWitness> = new Map();
+  private lastCallInfo: LastCallState = emptyLastCallState();
+  private txeOracleVersion: { major: number; minor: number } | undefined;
+
+  private disposed = false;
 
   constructor(
     private logger: Logger,
+    private sessionStore: AztecAsyncKVStore,
     private stateMachine: TXEStateMachine,
     private oracleHandler:
       | IUtilityExecutionOracle
@@ -148,8 +226,33 @@ export class TXESession implements TXESessionStateHandler {
     private nextBlockTimestamp: bigint,
   ) {}
 
+  /**
+   * Closes the per-session `txe-session` LMDB and the `NativeWorldStateService` .
+   * Called via IPC when the dispatcher detects the end of a test. Idempotent.
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    try {
+      await this.stateMachine.synchronizer.nativeWorldStateService.close();
+    } catch (err) {
+      this.logger.warn(`Error closing native world state during session dispose`, err);
+    }
+    try {
+      await this.sessionStore.close();
+    } catch (err) {
+      this.logger.warn(`Error closing session LMDB during dispose`, err);
+    }
+  }
+
   static async init(contractStore: ContractStore) {
-    const store = await openTmpStore('txe-session');
+    // Size LMDB's reader slots to the libuv pool (capped to 2 in bin/index.ts via
+    // HARDWARE_CONCURRENCY): each native LMDB read needs a libuv worker thread to run, so any
+    // slot beyond the pool size would sit idle while still consuming a semaphore + reader-table
+    // entry per session.
+    const store = await openEphemeralStore('txe-session', undefined, 2);
 
     const addressStore = new AddressStore(store);
     const privateEventStore = new PrivateEventStore(store);
@@ -161,7 +264,6 @@ export class TXESession implements TXESessionStateHandler {
     const keyStore = new KeyStore(store);
     const accountStore = new TXEAccountStore(store);
 
-    // Create job coordinator and register staged stores
     const jobCoordinator = new JobCoordinator(store);
     jobCoordinator.registerStores([
       capsuleStore,
@@ -181,6 +283,8 @@ export class TXESession implements TXESessionStateHandler {
 
     const initialJobId = jobCoordinator.beginJob();
 
+    const logger = createLogger('txe:session');
+
     const topLevelOracleHandler = new TXEOracleTopLevelContext(
       stateMachine,
       contractStore,
@@ -193,16 +297,17 @@ export class TXESession implements TXESessionStateHandler {
       senderAddressBookStore,
       capsuleStore,
       privateEventStore,
-      initialJobId,
       nextBlockTimestamp,
       version,
       chainId,
       new Map(),
     );
-    await topLevelOracleHandler.txeAdvanceBlocksBy(1);
+
+    await topLevelOracleHandler.mineDeploymentNullifiers([STANDARD_AUTH_REGISTRY_ADDRESS]);
 
     return new TXESession(
-      createLogger('txe:session'),
+      logger,
+      store,
       stateMachine,
       topLevelOracleHandler,
       contractStore,
@@ -241,7 +346,28 @@ export class TXESession implements TXESessionStateHandler {
       return translator[validatedFunctionName](...inputs);
     } catch (error) {
       if (error instanceof z.ZodError) {
-        throw new Error(`${functionName} does not correspond to any oracle handler available on RPCTranslator`);
+        let versionHint: string;
+        if (!this.txeOracleVersion) {
+          versionHint =
+            ' The test appears to use an older version of Aztec.nr that does not' +
+            ' support test environment oracle versioning. Update Aztec.nr to a compatible version.' +
+            ' See https://docs.aztec.network/errors/12';
+        } else if (this.txeOracleVersion.minor > TXE_ORACLE_VERSION_MINOR) {
+          versionHint =
+            ` The test uses Aztec.nr test oracle version` +
+            ` ${this.txeOracleVersion.major}.${this.txeOracleVersion.minor}, but this test environment` +
+            ` only supports up to ${TXE_ORACLE_VERSION_MAJOR}.${TXE_ORACLE_VERSION_MINOR}.` +
+            ` Upgrade the Aztec CLI to a compatible version.` +
+            ` See https://docs.aztec.network/errors/12`;
+        } else {
+          versionHint =
+            ` The test's oracle version (${this.txeOracleVersion.major}.${this.txeOracleVersion.minor})` +
+            ` is compatible with this test environment` +
+            ` (${TXE_ORACLE_VERSION_MAJOR}.${TXE_ORACLE_VERSION_MINOR}), so this oracle should be` +
+            ` available. This is an unexpected error, please report it.` +
+            ` See https://docs.aztec.network/errors/13`;
+        }
+        throw new Error(`Unknown oracle '${functionName}'.${versionHint}`);
       } else if (error instanceof Error) {
         throw new Error(
           `Execution error while processing function ${functionName} in state ${this.state.name}: ${error.message}`,
@@ -254,6 +380,86 @@ export class TXESession implements TXESessionStateHandler {
     }
   }
 
+  getCurrentJob(): string {
+    return this.currentJobId;
+  }
+
+  /** Commits the current job and begins a new one. Returns the new job ID. */
+  async cycleJob(): Promise<string> {
+    await this.jobCoordinator.commitJob(this.currentJobId);
+    this.currentJobId = this.jobCoordinator.beginJob();
+    return this.currentJobId;
+  }
+
+  private resetLastCall(): void {
+    const notQueriedMessageCount = this.lastCallInfo.queried
+      ? 0
+      : this.lastCallInfo.offchainEffects.filter(payload => payload[0]?.equals(OFFCHAIN_MESSAGE_IDENTIFIER)).length;
+    if (notQueriedMessageCount > 0) {
+      this.logger.warn(
+        `Dropping ${notQueriedMessageCount} unqueried offchain message(s) from the previous top-level call. ` +
+          `To deliver them, call \`env.offchain_messages()\` and forward the result to the recipient contract's ` +
+          `\`offchain_receive\` utility before issuing another top-level call. To intentionally discard, assign ` +
+          `to \`let _ = env.offchain_messages()\` to silence this warning.`,
+      );
+    }
+    this.lastCallInfo = emptyLastCallState();
+  }
+
+  recordOffchainEffect(data: Fr[]): void {
+    this.lastCallInfo.offchainEffects.push(data);
+  }
+
+  private setLastCallContext(txHash: Fr, anchorBlockTimestamp: bigint): void {
+    this.lastCallInfo.txHash = txHash;
+    this.lastCallInfo.anchorBlockTimestamp = anchorBlockTimestamp;
+  }
+
+  async withTopLevelCallTracking<T>(work: () => Promise<{ result: T; txHash?: Fr }>): Promise<T> {
+    this.resetLastCall();
+    // Capture the anchor *before* `work` runs: private/public executor calls mine a new block as a
+    // side effect, and that block's timestamp should not be attributed to this call's anchor.
+    const anchorBlockTimestamp = (await this.stateMachine.node.getBlockData('latest'))!.header.globalVariables
+      .timestamp;
+    const { result, txHash } = await work();
+    this.setLastCallContext(txHash ?? Fr.ZERO, anchorBlockTimestamp);
+    return result;
+  }
+
+  getLastCallOffchainEffects(): { effects: Fr[][] } {
+    this.lastCallInfo.queried = true;
+    const effects = this.lastCallInfo.offchainEffects;
+
+    if (effects.length > MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY) {
+      throw new Error(`${effects.length} offchain effects exceed max ${MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY}`);
+    }
+    if (effects.some(e => e.length > MAX_OFFCHAIN_EFFECT_LEN)) {
+      throw new Error(`Some offchain effect has length larger than max ${MAX_OFFCHAIN_EFFECT_LEN}`);
+    }
+
+    return { effects };
+  }
+
+  getLastCallContext(): { txHash: Fr; anchorBlockTimestamp: bigint } {
+    const { txHash, anchorBlockTimestamp } = this.lastCallInfo;
+    return { txHash, anchorBlockTimestamp };
+  }
+
+  setTxeOracleVersion(major: number, minor: number): void {
+    if (major !== TXE_ORACLE_VERSION_MAJOR) {
+      const hint =
+        major > TXE_ORACLE_VERSION_MAJOR
+          ? 'The test was compiled with a newer version of Aztec.nr than your test environment supports. Upgrade your test environment to a compatible version.'
+          : 'The test was compiled with an older version of Aztec.nr than your test environment supports. Recompile the test with a compatible version of Aztec.nr.';
+      throw new Error(
+        `Incompatible test environment version: ${hint} See https://docs.aztec.network/errors/12 (expected test oracle major version ${TXE_ORACLE_VERSION_MAJOR}, got ${major})`,
+      );
+    }
+
+    this.txeOracleVersion = { major, minor };
+    this.logger.debug(`Test compiled with test oracle version ${major}.${minor}`);
+  }
+
   async enterTopLevelState() {
     switch (this.state.name) {
       case 'PRIVATE': {
@@ -277,8 +483,7 @@ export class TXESession implements TXESessionStateHandler {
     }
 
     // Commit all staged stores from the job that was just completed, then begin a new job
-    await this.jobCoordinator.commitJob(this.currentJobId);
-    this.currentJobId = this.jobCoordinator.beginJob();
+    await this.cycleJob();
 
     this.oracleHandler = new TXEOracleTopLevelContext(
       this.stateMachine,
@@ -292,7 +497,6 @@ export class TXESession implements TXESessionStateHandler {
       this.senderAddressBookStore,
       this.capsuleStore,
       this.privateEventStore,
-      this.currentJobId,
       this.nextBlockTimestamp,
       this.version,
       this.chainId,
@@ -305,20 +509,22 @@ export class TXESession implements TXESessionStateHandler {
 
   async enterPrivateState(
     contractAddress: AztecAddress = DEFAULT_ADDRESS,
-    anchorBlockNumber?: BlockNumber,
+    anchorBlockNumber: BlockNumber | undefined,
+    gasSettings: GasSettings,
   ): Promise<PrivateContextInputs> {
     this.exitTopLevelState();
+    this.resetLastCall();
 
     // Private execution has two associated block numbers: the anchor block (i.e. the historical block that is used to
     // build the proof), and the *next* block, i.e. the one we'll create once the execution ends, and which will contain
     // a single transaction with the effects of what was done in the test.
-    const anchorBlock = await this.stateMachine.node.getBlockHeader(anchorBlockNumber ?? 'latest');
+    const anchorBlock = await this.stateMachine.node.getBlock(anchorBlockNumber ?? 'latest').then(b => b?.header);
 
     await new NoteService(this.noteStore, this.stateMachine.node, anchorBlock!, this.currentJobId).syncNoteNullifiers(
       contractAddress,
-      'ALL_SCOPES',
+      await this.keyStore.getAccounts(),
     );
-    const latestBlock = await this.stateMachine.node.getBlockHeader('latest');
+    const latestBlock = await this.stateMachine.node.getBlock('latest').then(b => b?.header);
 
     const nextBlockGlobalVariables = makeGlobalVariables(undefined, {
       blockNumber: BlockNumber(latestBlock!.globalVariables.blockNumber + 1),
@@ -333,9 +539,9 @@ export class TXESession implements TXESessionStateHandler {
     const taggingIndexCache = new ExecutionTaggingIndexCache();
 
     const utilityExecutor = this.utilityExecutorForContractSync(anchorBlock);
-    this.oracleHandler = new PrivateExecutionOracle({
+    this.oracleHandler = new TXEPrivateExecutionOracle({
       argsHash: Fr.ZERO,
-      txContext: new TxContext(this.chainId, this.version, GasSettings.empty()),
+      txContext: new TxContext(this.chainId, this.version, gasSettings),
       callContext: new CallContext(AztecAddress.ZERO, contractAddress, FunctionSelector.empty(), false),
       anchorBlockHeader: anchorBlock!,
       utilityExecutor,
@@ -352,11 +558,14 @@ export class TXESession implements TXESessionStateHandler {
       senderTaggingStore: this.senderTaggingStore,
       recipientTaggingStore: this.recipientTaggingStore,
       senderAddressBookStore: this.senderAddressBookStore,
-      capsuleStore: this.capsuleStore,
+      capsuleService: new CapsuleService(this.capsuleStore, await this.keyStore.getAccounts()),
       privateEventStore: this.privateEventStore,
       contractSyncService: this.stateMachine.contractSyncService,
+      l2TipsStore: this.stateMachine.l2TipsProvider,
       jobId: this.currentJobId,
-      scopes: 'ALL_SCOPES',
+      scopes: await this.keyStore.getAccounts(),
+      messageContextService: this.stateMachine.messageContextService,
+      simulator: new WASMSimulator(),
     });
 
     // We store the note and tagging index caches fed into the PrivateExecutionOracle (along with some other auxiliary
@@ -367,17 +576,22 @@ export class TXESession implements TXESessionStateHandler {
     this.state = { name: 'PRIVATE', nextBlockGlobalVariables, noteCache, taggingIndexCache };
     this.logger.debug(`Entered state ${this.state.name}`);
 
-    return (this.oracleHandler as PrivateExecutionOracle).getPrivateContextInputs();
+    // Record the *resolved* anchor's timestamp — if the caller pinned the anchor to a past block
+    // via `anchorBlockNumber`, "latest" would be the wrong anchor for offchain-message semantics.
+    this.setLastCallContext(Fr.ZERO, anchorBlock!.globalVariables.timestamp);
+
+    return (this.oracleHandler as TXEPrivateExecutionOracle).getPrivateContextInputs();
   }
 
   async enterPublicState(contractAddress?: AztecAddress) {
     this.exitTopLevelState();
+    this.resetLastCall();
 
     // The PublicContext will create a block with a single transaction in it, containing the effects of what was done in
     // the test. The block therefore gets the *next* block number and timestamp.
-    const latestBlockNumber = (await this.stateMachine.node.getBlockHeader('latest'))!.globalVariables.blockNumber;
+    const latestHeader = (await this.stateMachine.node.getBlockData('latest'))!.header;
     const globalVariables = makeGlobalVariables(undefined, {
-      blockNumber: BlockNumber(latestBlockNumber + 1),
+      blockNumber: BlockNumber(latestHeader.globalVariables.blockNumber + 1),
       timestamp: this.nextBlockTimestamp,
       version: this.version,
       chainId: this.chainId,
@@ -392,10 +606,14 @@ export class TXESession implements TXESessionStateHandler {
 
     this.state = { name: 'PUBLIC' };
     this.logger.debug(`Entered state ${this.state.name}`);
+
+    // Public state is anchored at the latest block.
+    this.setLastCallContext(Fr.ZERO, latestHeader.globalVariables.timestamp);
   }
 
   async enterUtilityState(contractAddress: AztecAddress = DEFAULT_ADDRESS) {
     this.exitTopLevelState();
+    this.resetLastCall();
 
     const anchorBlockHeader = await this.stateMachine.anchorBlockStore.getBlockHeader();
 
@@ -409,7 +627,7 @@ export class TXESession implements TXESessionStateHandler {
       this.stateMachine.node,
       anchorBlockHeader,
       this.currentJobId,
-    ).syncNoteNullifiers(contractAddress, 'ALL_SCOPES');
+    ).syncNoteNullifiers(contractAddress, await this.keyStore.getAccounts());
 
     this.oracleHandler = new UtilityExecutionOracle({
       contractAddress,
@@ -423,14 +641,22 @@ export class TXESession implements TXESessionStateHandler {
       aztecNode: this.stateMachine.node,
       recipientTaggingStore: this.recipientTaggingStore,
       senderAddressBookStore: this.senderAddressBookStore,
-      capsuleStore: this.capsuleStore,
+      capsuleService: new CapsuleService(this.capsuleStore, await this.keyStore.getAccounts()),
       privateEventStore: this.privateEventStore,
+      messageContextService: this.stateMachine.messageContextService,
+      contractSyncService: this.stateMachine.contractSyncService,
+      l2TipsStore: this.stateMachine.l2TipsProvider,
       jobId: this.currentJobId,
-      scopes: 'ALL_SCOPES',
+      scopes: await this.keyStore.getAccounts(),
+      simulator: new WASMSimulator(),
+      utilityExecutor: this.utilityExecutorForContractSync(anchorBlockHeader),
     });
 
     this.state = { name: 'UTILITY' };
     this.logger.debug(`Entered state ${this.state.name}`);
+
+    // Utility state anchors at whatever the anchor block store is pointing to (tracked as latest).
+    this.setLastCallContext(Fr.ZERO, anchorBlockHeader.globalVariables.timestamp);
   }
 
   private exitTopLevelState() {
@@ -440,8 +666,8 @@ export class TXESession implements TXESessionStateHandler {
 
     // Note that while all public and private contexts do is build a single block that we then process when exiting
     // those, the top level context performs a large number of actions not captured in the following 'close' call. Among
-    // others, it will create empty blocks (via `txeAdvanceBlocksBy` and `deploy`), create blocks with transactions via
-    // `txePrivateCallNewFlow` and `txePublicCallNewFlow`, add accounts to PXE via `txeAddAccount`, etc. This is a
+    // others, it will create empty blocks (via `advanceBlocksBy` and `deploy`), create blocks with transactions via
+    // `privateCallNewFlow` and `publicCallNewFlow`, add accounts to PXE via `addAccount`, etc. This is a
     // slight inconsistency in the working model of this class, but is not too bad.
     // TODO: it's quite unfortunate that we need to capture the authwits created to later pass them again when the top
     // level context is re-created. This is because authwits create a temporary utility context that'd otherwise reset
@@ -495,13 +721,14 @@ export class TXESession implements TXESessionStateHandler {
   }
 
   private utilityExecutorForContractSync(anchorBlock: any) {
-    return async (call: FunctionCall, scopes: AccessScopes) => {
+    return async (call: FunctionCall, scopes: AztecAddress[]) => {
       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`);
       }
 
       try {
+        const simulator = new WASMSimulator();
         const oracle = new UtilityExecutionOracle({
           contractAddress: call.to,
           authWitnesses: [],
@@ -514,12 +741,17 @@ export class TXESession implements TXESessionStateHandler {
           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: this.currentJobId,
           scopes,
+          simulator,
+          utilityExecutor: this.utilityExecutorForContractSync(anchorBlock),
         });
-        await new WASMSimulator()
+        await simulator
           .executeUserCircuit(toACVMWitness(0, call.args), entryPointArtifact, new Oracle(oracle).toACIRCallback())
           .catch((err: Error) => {
             err.message = resolveAssertionMessageFromError(err, entryPointArtifact);

package/src/{util → utils}/encoding.ts

@@ -3,6 +3,7 @@ import type { EthAddress } from '@aztec/foundation/eth-address';
 import { hexToBuffer } from '@aztec/foundation/string';
 import { type ContractArtifact, ContractArtifactSchema } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { BlockHash } from '@aztec/stdlib/block';
 import { type ContractInstanceWithAddress, ContractInstanceWithAddressSchema } from '@aztec/stdlib/contract';
 
 import { z } from 'zod';
@@ -25,6 +26,10 @@ export function addressFromSingle(obj: ForeignCallSingle) {
   return new AztecAddress(fromSingle(obj));
 }
 
+export function blockHashFromSingle(obj: ForeignCallSingle) {
+  return new BlockHash(fromSingle(obj));
+}
+
 export function fromArray(obj: ForeignCallArray) {
   return obj.map(str => Fr.fromBuffer(hexToBuffer(str)));
 }
@@ -142,9 +147,10 @@ export function arrayOfArraysToBoundedVecOfArrays(
 
   const numFieldsToPad = maxLen * nestedArrayLength - flattenedStorage.length;
 
-  const flattenedStorageWithPadding = flattenedStorage.concat(Array(numFieldsToPad).fill(new Fr(0)));
+  // Pad with hex-encoded zeros so the result is uniformly `ForeignCallSingle` (string); raw Fr
+  // instances would JSON-serialize as `{ asBigInt: "0" }` and nargo would reject the response.
+  const flattenedStorageWithPadding = flattenedStorage.concat(toArray(Array(numFieldsToPad).fill(new Fr(0))));
 
-  // At last we get the actual length of the BoundedVec and return the values.
   const len = toSingle(new Fr(bVecStorage.length));
   return [flattenedStorageWithPadding, len];
 }

package/src/{util → utils}/txe_public_contract_data_source.ts

@@ -26,8 +26,6 @@ export class TXEPublicContractDataSource implements ContractDataSource {
       packedBytecode: contractClass.packedBytecode,
       privateFunctionsRoot: contractClass.privateFunctionsRoot,
       version: contractClass.version,
-      privateFunctions: [],
-      utilityFunctions: [],
     };
   }
 

package/src/worker.ts

@@ -0,0 +1,98 @@
+import { BackendType, Barretenberg, BarretenbergSync } from '@aztec/bb.js';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+import { parentPort, workerData } from 'node:worker_threads';
+
+// Importing `./index.js` registers the msgpackr Fr extension transitively (via
+// ./msgpackr_fr_extension.js); this must happen before any `sendMessage` call.
+import { TXEDispatcher, type TXEDispatcherOptions, type TXEForeignCallInput, activeSessionCount } from './index.js';
+
+// Seed both bb.js singletons with the WASM backend before any crypto call. `initSingleton`
+// binds the singleton to whichever backend the first call requests, so this pre-empts the
+// implicit `Barretenberg.initSingleton()` inside `poseidon2Hash` from `@aztec/foundation/crypto`.
+// TXE only needs hashing (no proving, no verification), so WASM is sufficient and
+// `skipSrsInit: true` skips the CRS load. `threads: 1` keeps the WASM backend on a single
+// thread — additional threads would each spawn a nested worker_thread, multiplying memory cost
+// per pool worker.
+void Barretenberg.initSingleton({ backend: BackendType.Wasm, skipSrsInit: true, threads: 1 });
+void BarretenbergSync.initSingleton({ backend: BackendType.Wasm });
+
+if (!parentPort) {
+  throw new Error('worker.ts must be loaded as a worker_thread');
+}
+
+const port = parentPort;
+const logger: Logger = createLogger('txe:worker');
+
+// The pool builds a template LMDB containing the protocol contracts + the SchnorrAccount
+// artifact on the main thread and passes its data dir via `workerData`. The dispatcher clones
+// that LMDB into a per-worker store on first use, so this worker gets a writable copy already
+// populated.
+const dispatcherOpts: TXEDispatcherOptions = {
+  contractStoreSourceDir: workerData.contractStoreSourceDir,
+  schnorrClassId: workerData.schnorrClassId,
+};
+const dispatcher = new TXEDispatcher(logger, dispatcherOpts);
+
+interface ForeignCallRequest {
+  type: 'foreign-call';
+  requestId: number;
+  callData: TXEForeignCallInput;
+}
+
+interface DisposeSessionMessage {
+  type: 'dispose-session';
+  sessionId: number;
+}
+
+type IncomingMessage = ForeignCallRequest | DisposeSessionMessage;
+
+interface SerializedError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+
+function serializeError(err: unknown): SerializedError {
+  if (err instanceof Error) {
+    return { message: err.message, name: err.name, stack: err.stack };
+  }
+  return { message: String(err) };
+}
+
+// Periodic memstat for diagnostic builds — set TXE_WORKER_MEMSTAT=1 to enable. Posts JS-heap
+// breakdown + active-session count back to the dispatcher so we can attribute RSS growth
+// between V8 heap (would show in heapUsed) and native (LMDB / world-state / WASM).
+if (process.env.TXE_WORKER_MEMSTAT === '1') {
+  setInterval(() => {
+    const m = process.memoryUsage();
+    port.postMessage({
+      type: 'memstat',
+      sessions: activeSessionCount(),
+      rss: m.rss,
+      heapTotal: m.heapTotal,
+      heapUsed: m.heapUsed,
+      external: m.external,
+      arrayBuffers: m.arrayBuffers,
+    });
+  }, 2000).unref();
+}
+
+port.on('message', (msg: IncomingMessage) => {
+  switch (msg.type) {
+    case 'foreign-call':
+      void (async () => {
+        try {
+          const value = await dispatcher.resolve_foreign_call(msg.callData);
+          port.postMessage({ type: 'result', requestId: msg.requestId, ok: true, value });
+        } catch (err) {
+          port.postMessage({ type: 'result', requestId: msg.requestId, ok: false, error: serializeError(err) });
+        }
+      })();
+      return;
+    case 'dispose-session':
+      // Fire-and-forget; the main thread does not wait for confirmation.
+      void dispatcher.disposeSession(msg.sessionId).catch(err => logger.warn(`disposeSession failed`, err));
+      return;
+  }
+});