@aztec-labs/txe 6.0.0-nightly.20260829

package/src/dispatcher_pool.ts

@@ -0,0 +1,319 @@
+import { BackendType, Barretenberg, BarretenbergSync } from '@aztec/bb.js';
+
+import { getSchnorrAccountContractArtifact } from '@aztec-labs/accounts/schnorr/lazy';
+import type { Logger } from '@aztec-labs/foundation/log';
+import { openEphemeralStore } from '@aztec-labs/kv-store/lmdb-v2';
+import { LazyProtocolContractsProvider } from '@aztec-labs/protocol-contracts/providers/lazy';
+import { ContractStore } from '@aztec-labs/pxe/client/lazy';
+import { getStandardAuthRegistry } from '@aztec-labs/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec-labs/standard-contracts/handshake-registry/lazy';
+import { getContractClassFromArtifact } from '@aztec-labs/stdlib/contract';
+import { existsSync } from 'node:fs';
+import { cpus } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+
+import { TXE_REQUIRED_PROTOCOL_CONTRACTS } from './index.js';
+import type { TXEForeignCallInput } from './index.js';
+import type { ForeignCallResult } from './utils/encoding.js';
+
+void Barretenberg.initSingleton({ backend: BackendType.Wasm, skipSrsInit: true, threads: 1 });
+void BarretenbergSync.initSingleton({ backend: BackendType.Wasm });
+
+/**
+ * Opens a fresh LMDB in a tmp dir and writes the protocol contracts in
+ * {@link TXE_REQUIRED_PROTOCOL_CONTRACTS} plus the standard AuthRegistry, HandshakeRegistry, and the SchnorrAccount artifact,
+ * returning the directory path and the SchnorrAccount class id (hex). The store handle is intentionally kept
+ * alive: closing it would trigger the ephemeral-store cleanup hook and remove the tmp
+ * directory, so any worker that has not yet cloned would find it missing.
+ */
+export async function buildSharedContractStore(): Promise<{ dataDir: string; schnorrClassId: string }> {
+  const kvStore = await openEphemeralStore('txe-shared-contracts', undefined, 2);
+  const dataDir = kvStore.dataDirectory;
+  const contractStore = new ContractStore(kvStore);
+  const provider = new LazyProtocolContractsProvider();
+  const [protocolContracts, standardContracts, schnorrArtifact] = await Promise.all([
+    Promise.all(TXE_REQUIRED_PROTOCOL_CONTRACTS.map(name => provider.getProtocolContractArtifact(name))),
+    Promise.all([getStandardAuthRegistry(), getStandardHandshakeRegistry()]),
+    getSchnorrAccountContractArtifact(),
+  ]);
+  const schnorrClass = await getContractClassFromArtifact(schnorrArtifact);
+  await Promise.all([
+    ...[...protocolContracts, ...standardContracts].flatMap(({ instance, artifact, contractClass }) => [
+      contractStore.addContractArtifact(artifact, contractClass),
+      contractStore.addContractInstance(instance),
+    ]),
+    contractStore.addContractArtifact(schnorrArtifact, schnorrClass),
+  ]);
+  return { dataDir, schnorrClassId: schnorrClass.id.toString() };
+}
+
+/**
+ * Resolves `worker.bundle.js` whether this code is running unbundled (next to dispatcher_pool.js
+ * inside `dest/`) or bundled into `dest/bin/index.js` (one directory deeper). `import.meta.url`
+ * refers to whichever module the calling code actually lives in; we try both relative locations
+ * and use whichever exists.
+ */
+// worker.bundle.js is esbuild's bundling of src/worker.ts (see esbuild.config.mjs).
+// @dependency ./worker.ts
+function resolveWorkerBundlePath(): URL {
+  const candidates = [new URL('./worker.bundle.js', import.meta.url), new URL('../worker.bundle.js', import.meta.url)];
+  return candidates.find(u => existsSync(fileURLToPath(u))) ?? candidates[0];
+}
+
+interface SerializedError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+
+type WorkerMessage =
+  | { type: 'result'; requestId: number; ok: true; value: ForeignCallResult }
+  | { type: 'result'; requestId: number; ok: false; error: SerializedError }
+  | {
+      type: 'memstat';
+      sessions: number;
+      rss: number;
+      heapTotal: number;
+      heapUsed: number;
+      external: number;
+      arrayBuffers: number;
+    };
+
+interface WorkerSlot {
+  worker: Worker;
+  sessions: Set<number>;
+  inFlightRequestIds: Set<number>;
+}
+
+interface PendingRequest {
+  resolve: (value: ForeignCallResult) => void;
+  reject: (err: Error) => void;
+  workerIdx: number;
+}
+
+function deserializeError(payload: SerializedError | undefined): Error {
+  if (!payload) {
+    return new Error('Worker returned an error with no payload');
+  }
+  const err = new Error(payload.message);
+  if (payload.name) {
+    err.name = payload.name;
+  }
+  if (payload.stack) {
+    err.stack = payload.stack;
+  }
+  return err;
+}
+
+export interface TXEDispatcherPoolOptions {
+  /** Number of worker threads */
+  workers?: number;
+}
+
+/**
+ * Main-thread router that owns a pool of TXE worker threads. Each worker runs its own
+ * {@link TXEDispatcher} and handles foreign-call requests for the sessions assigned to it.
+ *
+ * Routing is sticky by `session_id`: new sessions go to a freshly spawned worker (up to
+ * `maxWorkers`) or, once the cap is reached, to the existing worker with the fewest sessions.
+ * Each session's state — TXESession, native world state, KV stores — stays single-threaded
+ * within its worker; different sessions run in parallel across workers.
+ *
+ * The main thread builds a shared protocol-contracts LMDB once and passes its path via
+ * `workerData`. Workers clone the data file on demand instead of re-registering the contracts.
+ */
+export class TXEDispatcherPool {
+  private readonly workers: WorkerSlot[] = [];
+  private readonly sessionToWorker = new Map<number, number>();
+  private readonly pending = new Map<number, PendingRequest>();
+  private nextRequestId = 0;
+  private readonly maxWorkers: number;
+  private readonly readyPromise: Promise<void>;
+  private contractStoreSourceDir?: string;
+  private schnorrClassId?: string;
+  private workerPath?: URL;
+
+  constructor(
+    private readonly logger: Logger,
+    opts: TXEDispatcherPoolOptions = {},
+  ) {
+    // TXE still doesn't scale well beyond 16 workers due to contention
+    this.maxWorkers = Math.max(1, opts.workers ?? Math.min(cpus().length, 16));
+    this.readyPromise = this.init();
+  }
+
+  /** Resolves once the shared protocol-contracts store is built. Workers spawn lazily on demand. */
+  public ready(): Promise<void> {
+    return this.readyPromise;
+  }
+
+  private async init(): Promise<void> {
+    const t0 = Date.now();
+    const { dataDir, schnorrClassId } = await buildSharedContractStore();
+    this.contractStoreSourceDir = dataDir;
+    this.schnorrClassId = schnorrClassId;
+    this.workerPath = resolveWorkerBundlePath();
+    this.logger.debug(`TXE dispatcher pool ready (lazy spawn, cap=${this.maxWorkers})`, {
+      contractStoreSourceDir: dataDir,
+      schnorrClassId,
+      ms: Date.now() - t0,
+    });
+  }
+
+  /**
+   * Spawns a fresh worker and returns its index in `this.workers`. Caller must have awaited
+   * `init()` so the shared contract store path is set. Messages posted before the worker has
+   * finished loading are queued by Node's worker_threads transport.
+   */
+  private spawnWorker(): number {
+    const workerIdx = this.workers.length;
+    const w = new Worker(this.workerPath!, {
+      workerData: { contractStoreSourceDir: this.contractStoreSourceDir, schnorrClassId: this.schnorrClassId },
+    });
+    const slot: WorkerSlot = {
+      worker: w,
+      sessions: new Set(),
+      inFlightRequestIds: new Set(),
+    };
+    this.workers.push(slot);
+    w.on('message', (msg: WorkerMessage) => this.handleMessage(workerIdx, msg));
+    w.on('error', err => this.handleWorkerError(workerIdx, err));
+    w.on('exit', code => {
+      if (code !== 0) {
+        this.handleWorkerError(workerIdx, new Error(`Worker ${workerIdx} exited with code ${code}`));
+      }
+    });
+    this.logger.debug(`Spawning TXE worker ${workerIdx} on demand`, {
+      cap: this.maxWorkers,
+      poolSize: this.workers.length,
+    });
+    return workerIdx;
+  }
+
+  /** Routes a session-dispose request to the worker that owns the session. Fire-and-forget. */
+  disposeSession(sessionId: number): void {
+    const workerIdx = this.sessionToWorker.get(sessionId);
+    if (workerIdx === undefined) {
+      throw new Error(`disposeSession: no worker mapped for session ${sessionId}`);
+    }
+    this.sessionToWorker.delete(sessionId);
+    const slot = this.workers[workerIdx];
+    if (!slot) {
+      throw new Error(`disposeSession: worker ${workerIdx} (session ${sessionId}) missing from pool`);
+    }
+    slot.sessions.delete(sessionId);
+    slot.worker.postMessage({ type: 'dispose-session', sessionId });
+  }
+
+  // eslint-disable-next-line camelcase
+  async resolve_foreign_call(callData: TXEForeignCallInput): Promise<ForeignCallResult> {
+    // Make sure the shared contract store + worker bundle path are in place before we spawn.
+    await this.readyPromise;
+    const sessionId = callData.session_id;
+    let workerIdx = this.sessionToWorker.get(sessionId);
+    if (workerIdx === undefined) {
+      workerIdx = this.pickOrSpawnWorker();
+      this.sessionToWorker.set(sessionId, workerIdx);
+      this.workers[workerIdx].sessions.add(sessionId);
+      this.logger.debug(`Routing new session ${sessionId} to worker ${workerIdx}`);
+    }
+
+    const slot = this.workers[workerIdx];
+    const requestId = this.nextRequestId++;
+    return new Promise<ForeignCallResult>((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject, workerIdx: workerIdx! });
+      slot.inFlightRequestIds.add(requestId);
+      slot.worker.postMessage({ type: 'foreign-call', requestId, callData });
+    });
+  }
+
+  /** Terminates all workers. Used by tests; production TXE exits the process directly. */
+  async shutdown(): Promise<void> {
+    const slots = this.workers.splice(0, this.workers.length);
+    await Promise.all(slots.map(s => s.worker.terminate()));
+    for (const [requestId, pending] of this.pending) {
+      pending.reject(new Error('TXE dispatcher pool was shut down'));
+      this.pending.delete(requestId);
+    }
+  }
+
+  /**
+   * Returns the index of the worker that should handle a new session. Spawns a fresh worker if
+   * the pool hasn't reached its cap; otherwise picks the existing worker with the fewest
+   * assigned sessions. Always returns a valid index into `this.workers`.
+   */
+  private pickOrSpawnWorker(): number {
+    if (this.workers.length < this.maxWorkers) {
+      return this.spawnWorker();
+    }
+    let minIdx = 0;
+    let minCount = this.workers[0].sessions.size;
+    for (let i = 1; i < this.workers.length; i++) {
+      const count = this.workers[i].sessions.size;
+      if (count < minCount) {
+        minIdx = i;
+        minCount = count;
+      }
+    }
+    return minIdx;
+  }
+
+  private handleMessage(workerIdx: number, msg: WorkerMessage): void {
+    switch (msg.type) {
+      case 'result':
+        this.handleResult(workerIdx, msg);
+        return;
+      case 'memstat':
+        this.logger.debug(`worker ${workerIdx} memstat`, {
+          worker: workerIdx,
+          sessions: msg.sessions,
+          rssMiB: Math.round(msg.rss / 1024 / 1024),
+          heapTotalMiB: Math.round(msg.heapTotal / 1024 / 1024),
+          heapUsedMiB: Math.round(msg.heapUsed / 1024 / 1024),
+          externalMiB: Math.round(msg.external / 1024 / 1024),
+          arrayBuffersMiB: Math.round(msg.arrayBuffers / 1024 / 1024),
+        });
+        return;
+    }
+  }
+
+  private handleResult(workerIdx: number, msg: WorkerMessage & { type: 'result' }): void {
+    const pending = this.pending.get(msg.requestId);
+    if (!pending) {
+      throw new Error(`handleResult: request ${msg.requestId} (worker ${workerIdx}) not in pending map`);
+    }
+    this.pending.delete(msg.requestId);
+    const slot = this.workers[workerIdx];
+    if (!slot) {
+      throw new Error(`handleResult: worker ${workerIdx} (request ${msg.requestId}) missing from pool`);
+    }
+    slot.inFlightRequestIds.delete(msg.requestId);
+    if (msg.ok) {
+      pending.resolve(msg.value);
+    } else {
+      pending.reject(deserializeError(msg.error));
+    }
+  }
+
+  private handleWorkerError(workerIdx: number, err: Error): void {
+    this.logger.error(`TXE worker ${workerIdx} crashed; sessions assigned to it will fail`, err);
+    const slot = this.workers[workerIdx];
+    if (!slot) {
+      throw new Error(`handleWorkerError: worker ${workerIdx} missing from pool (orig err: ${err.message})`);
+    }
+    for (const requestId of slot.inFlightRequestIds) {
+      const pending = this.pending.get(requestId);
+      if (!pending) {
+        throw new Error(`handleWorkerError: in-flight request ${requestId} (worker ${workerIdx}) not in pending map`);
+      }
+      pending.reject(err);
+      this.pending.delete(requestId);
+    }
+    slot.inFlightRequestIds.clear();
+    for (const sessionId of slot.sessions) {
+      this.sessionToWorker.delete(sessionId);
+    }
+    slot.sessions.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,152 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { Logger } from '@aztec-labs/foundation/log';
+import { cloneEphemeralStoreFrom } from '@aztec-labs/kv-store/lmdb-v2';
+import type { ProtocolContractName } from '@aztec-labs/protocol-contracts';
+import { ContractStore } from '@aztec-labs/pxe/client/lazy';
+import type { ApiSchemaFor } from '@aztec-labs/stdlib/schemas';
+import { zodFor } from '@aztec-labs/stdlib/schemas';
+import { join } from 'path';
+import { z } from 'zod';
+
+// Side-effect import: registers the msgpackr Fr extension for the bundled `Fr` class. Must
+// be loaded before any `sendMessage` call. See msgpackr_fr_extension.ts for the why.
+import './msgpackr_fr_extension.js';
+import { type TXEOracleFunctionName, TXESession } from './txe_session.js';
+import {
+  type ForeignCallArgs,
+  ForeignCallArgsSchema,
+  type ForeignCallResult,
+  ForeignCallResultSchema,
+} from './utils/encoding.js';
+import { TXEArtifactResolver } from './utils/txe_artifact_resolver.js';
+
+export const TXE_REQUIRED_PROTOCOL_CONTRACTS: ProtocolContractName[] = [
+  'ContractClassRegistry',
+  'ContractInstanceRegistry',
+  'FeeJuice',
+];
+
+const sessions = new Map<number, TXESession>();
+
+export type TXEForeignCallInput = {
+  session_id: number;
+  function: TXEOracleFunctionName;
+  root_path: string;
+  package_name: string;
+  inputs: ForeignCallArgs;
+};
+
+export const TXEForeignCallInputSchema: z.ZodType<TXEForeignCallInput> = zodFor<TXEForeignCallInput>()(
+  z.object({
+    // Nargo generates session_id as a u64, which may exceed Number.MAX_SAFE_INTEGER.
+    // Zod 4's `.int()` enforces the safe-integer bound, so we drop it here and only require
+    // the value to be a non-negative number (it is used solely as a Map key).
+    // eslint-disable-next-line camelcase
+    session_id: z.number().nonnegative(),
+    function: z.string() as z.ZodType<TXEOracleFunctionName>,
+    // eslint-disable-next-line camelcase
+    root_path: z.string(),
+    // eslint-disable-next-line camelcase
+    package_name: z.string(),
+    inputs: ForeignCallArgsSchema,
+  }),
+);
+
+export interface TXEDispatcherOptions {
+  /**
+   * Path to an LMDB directory holding the required protocol contracts (see
+   * {@link TXE_REQUIRED_PROTOCOL_CONTRACTS}) and the SchnorrAccount artifact. When set, the
+   * dispatcher clones this directory into a fresh tmpdir on first use instead of registering
+   * the contracts itself.
+   */
+  contractStoreSourceDir: string;
+  /**
+   * Class id (hex) of the SchnorrAccount artifact pre-registered in the shared LMDB. The
+   * {@link TXEArtifactResolver} looks the artifact up from the cloned store via this class id
+   * instead of recomputing it via `getSchnorrAccountContractArtifact()` + `computeArtifactHash()`.
+   */
+  schnorrClassId: string;
+}
+
+export class TXEDispatcher {
+  private contractStore!: ContractStore;
+  private artifactResolver!: TXEArtifactResolver;
+  private readonly contractStoreSourceDir: string;
+  private readonly schnorrClassId: Fr;
+
+  constructor(
+    private logger: Logger,
+    opts: TXEDispatcherOptions,
+  ) {
+    this.contractStoreSourceDir = opts.contractStoreSourceDir;
+    this.schnorrClassId = Fr.fromString(opts.schnorrClassId);
+  }
+
+  /**
+   * Clones the pre-populated LMDB at `contractStoreSourceDir` into a fresh per-instance tmpdir
+   * on first use, so this dispatcher has a writable store already containing the required
+   * protocol contracts + SchnorrAccount. Idempotent — subsequent calls are no-ops.
+   */
+  private async warmUp(): Promise<void> {
+    if (this.contractStore) {
+      return;
+    }
+    const t0 = Date.now();
+    const kvStore = await cloneEphemeralStoreFrom(
+      join(this.contractStoreSourceDir, 'data.mdb'),
+      'txe-contracts',
+      undefined,
+      2,
+    );
+    this.contractStore = new ContractStore(kvStore);
+    this.artifactResolver = new TXEArtifactResolver(this.contractStore, this.schnorrClassId);
+    this.logger.debug('Cloned shared protocol-contracts store', { totalMs: Date.now() - t0 });
+  }
+
+  // eslint-disable-next-line camelcase
+  async resolve_foreign_call(callData: TXEForeignCallInput): Promise<ForeignCallResult> {
+    const {
+      session_id: sessionId,
+      function: functionName,
+      inputs,
+      root_path: rootPath,
+      package_name: packageName,
+    } = callData;
+    this.logger.debug(`Calling ${functionName} on session ${sessionId}`);
+
+    if (!sessions.has(sessionId)) {
+      this.logger.debug(`Creating new session ${sessionId}`);
+      await this.warmUp();
+      sessions.set(sessionId, await TXESession.init(this.contractStore, this.artifactResolver, rootPath, packageName));
+    }
+
+    return await sessions.get(sessionId)!.processFunction(functionName, inputs);
+  }
+
+  /**
+   * Releases a session and its resources (per-session LMDB + `NativeWorldStateService`).
+   * Called by the dispatcher pool when nargo closes its TCP connection for a test (see
+   * `rpc_server.ts`'s socket tracker). No-op if the session was never created — that happens
+   * when nargo opens a connection but errors before sending a request.
+   */
+  async disposeSession(sessionId: number): Promise<void> {
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+    sessions.delete(sessionId);
+    await session.dispose();
+  }
+}
+
+/** Diagnostic-only: number of sessions currently held by this worker. */
+export function activeSessionCount(): number {
+  return sessions.size;
+}
+
+export const TXEDispatcherApiSchema: ApiSchemaFor<TXEDispatcher> = {
+  // eslint-disable-next-line camelcase
+  resolve_foreign_call: z.function({ input: z.tuple([TXEForeignCallInputSchema]), output: ForeignCallResultSchema }),
+  // disposeSession is invoked over IPC from the worker, not via RPC; required by ApiSchemaFor.
+  disposeSession: z.function({ input: z.tuple([z.number().nonnegative()]), output: z.void() }),
+};

package/src/msgpackr_fr_extension.ts

@@ -0,0 +1,22 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { addExtension } from 'msgpackr';
+
+// `@aztec-labs/native/msgpack_channel` registers a msgpackr extension that packs `Fr` instances to
+// their raw 32-byte buffer for the C++ world-state side to deserialize. Because `@aztec-labs/native`
+// is externalized in TXE's esbuild config (it loads a `.node` binary that can't be bundled),
+// the `Fr` class the extension is keyed on belongs to the *external* `@aztec-labs/foundation`
+// module instance — a different class identity than the `Fr` bundled into the TXE worker /
+// bin. msgpackr's extension match uses `instanceof`, so bundled `Fr` instances slip through
+// and msgpackr falls back to `Fr.toJSON()` (returns `Fr.toString()` — a `0x...` hex string).
+// The C++ side then sees a string where a 32-byte binary was expected and throws
+// `msgpack::type_error` whose `what()` is literally `"std::bad_cast"`.
+//
+// Fix: register the same extension under the BUNDLED `Fr` class identity. msgpackr's extension
+// table holds an entry per `Class`, so both Fr classes now resolve to the same `write` callback
+// and produce the same wire format. Imported as a side-effect from `./index.js` so both the
+// worker (via `./worker.ts`) and the main-thread RPC server (via `./rpc_server.ts`) get the
+// registration before any `sendMessage` runs.
+addExtension({
+  Class: Fr,
+  write: (fr: Fr) => fr.toBuffer(),
+});

package/src/oracle/interfaces.ts

@@ -0,0 +1,125 @@
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { ChangeSetId, TaggingSecretStrategy } from '@aztec-labs/pxe/server';
+import type { Option } from '@aztec-labs/pxe/simulator';
+import type { EventSelector, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { CompleteAddress } from '@aztec-labs/stdlib/contract';
+import type { GasSettings } from '@aztec-labs/stdlib/gas';
+import type { UInt64 } from '@aztec-labs/stdlib/types';
+
+import type { TxEffectsData } from './noir-structs/tx_effects_data.js';
+
+// These interfaces complement the ones defined in PXE, and combined with those contain the full list of oracles used by
+// aztec-nr. In particular, these include the ones needed to run Brillig code associated to #[external("public")] functions that has
+// not been transpiled (e.g. in the context of a Noir test) as well as the ones associated with managing the state of
+// such a Noir test (deploying contracts, manipulating block time, making calls, etc) - the so called 'top level test
+// context'.
+
+/**
+ * Oracle methods associated with the execution of an Aztec #[external("public")] function.
+ *
+ * Note that real contracts have their Brillig calls to these be transpiled into opcodes, the oracles are only executed
+ * as such when running the original Brillig code, e.g. when invoking functions that interact with a PublicContext
+ * directly in a Noir test.
+ */
+export interface IAvmExecutionOracle {
+  isAvm: true;
+
+  address(): Promise<AztecAddress>;
+  sender(): Promise<AztecAddress>;
+  blockNumber(): Promise<BlockNumber>;
+  timestamp(): Promise<bigint>;
+  isStaticCall(): Promise<boolean>;
+  chainId(): Promise<Fr>;
+  version(): Promise<Fr>;
+  emitNullifier(nullifier: Fr): Promise<void>;
+  emitNoteHash(noteHash: Fr): Promise<void>;
+  nullifierExists(siloedNullifier: Fr): Promise<boolean>;
+  storageWrite(slot: Fr, value: Fr): Promise<void>;
+  storageRead(slot: Fr, contractAddress: AztecAddress): Promise<Fr>;
+  getContractInstanceDeployer(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]>;
+  getContractInstanceClassId(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]>;
+  getContractInstanceInitializationHash(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]>;
+  getContractInstanceImmutablesHash(address: AztecAddress): Promise<{ member: Fr; exists: boolean }[]>;
+  returndataSize(): Promise<number>;
+  returndataCopy(rdOffset: number, copySize: number): Promise<Fr[]>;
+  call(l2Gas: number, daGas: number, address: AztecAddress, argsLength: number, args: Fr[]): Promise<void>;
+  staticCall(l2Gas: number, daGas: number, address: AztecAddress, argsLength: number, args: Fr[]): Promise<void>;
+  successCopy(): Promise<boolean>;
+}
+
+/**
+ * Oracle methods associated with the execution of an Aztec Noir test.
+ */
+export interface ITxeExecutionOracle {
+  isTxe: true;
+
+  getDefaultAddress(): AztecAddress;
+  getNextBlockNumber(): Promise<BlockNumber>;
+  getNextBlockTimestamp(): Promise<UInt64>;
+  advanceBlocksBy(blocks: number): Promise<void>;
+  advanceTimestampBy(duration: UInt64): void;
+  deploy(
+    contractPath: string,
+    initializer: string,
+    args: Fr[],
+    secret: Fr,
+    salt: Fr,
+    deployer: AztecAddress,
+  ): Promise<Fr[]>;
+  createAccount(secret: Fr, partialAddress: Fr): Promise<CompleteAddress>;
+  addAccount(secret: Fr): Promise<CompleteAddress>;
+  addAuthWitness(address: AztecAddress, messageHash: Fr): Promise<void>;
+  sendL1ToL2Message(content: Fr, secretHash: Fr, sender: EthAddress, recipient: AztecAddress): Promise<Fr>;
+  /**
+   * Configures the tagging secret strategy the test's simulated wallet resolves for each delivery mode. A `none`
+   * clears that mode, so it falls back to the default strategy (or, when both modes end up unset, to no hook at all).
+   */
+  setTaggingSecretStrategies(
+    unconstrainedStrategy: Option<TaggingSecretStrategy>,
+    constrainedStrategy: Option<TaggingSecretStrategy>,
+  ): void;
+  /**
+   * Configures whether the test's simulated wallet authorizes every cross-contract utility call target.
+   */
+  setAuthorizeAllUtilityCallTargets(authorizeAll: boolean): void;
+  getLastBlockTimestamp(): Promise<bigint>;
+  getLastTxEffects(): Promise<TxEffectsData>;
+  getPrivateEvents(selector: EventSelector, contractAddress: AztecAddress, scope: AztecAddress): Promise<Fr[][]>;
+  privateCallNewFlow(
+    from: AztecAddress | undefined,
+    targetContractAddress: AztecAddress,
+    functionSelector: FunctionSelector,
+    args: Fr[],
+    argsHash: Fr,
+    isStaticCall: boolean,
+    additionalScopes: AztecAddress[],
+    changeSetId: ChangeSetId,
+    authorizedUtilityCallTargets: AztecAddress[],
+    gasSettings: GasSettings,
+  ): Promise<{ returnValues: Fr[]; offchainEffects: Fr[][] }>;
+  executeUtilityFunction(
+    from: AztecAddress | undefined,
+    targetContractAddress: AztecAddress,
+    functionSelector: FunctionSelector,
+    args: Fr[],
+    changeSetId: ChangeSetId,
+    authorizedUtilityCallTargets: AztecAddress[],
+  ): Promise<Fr[]>;
+  publicCallNewFlow(
+    from: AztecAddress | undefined,
+    targetContractAddress: AztecAddress,
+    calldata: Fr[],
+    isStaticCall: boolean,
+    gasSettings: GasSettings,
+  ): Promise<Fr[]>;
+  // TODO(F-335): Drop this from here as it's not a real oracle handler - it's only called from
+  // RPCTranslator::txeGetPrivateEvents and never from Noir.
+  syncContractNonOracleMethod(
+    contractAddress: AztecAddress,
+    scope: AztecAddress,
+    changeSetId: ChangeSetId,
+  ): Promise<void>;
+}

package/src/oracle/noir-structs/gas_settings_data.ts

@@ -0,0 +1,16 @@
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import type { Gas, GasFees } from '@aztec-labs/stdlib/gas';
+
+/** Wire form of {@link Gas}: the domain type's fields as decoded off the wire, before conversion. */
+export type GasData = FieldsOf<Gas>;
+
+/** Wire form of {@link GasFees}: the domain type's fields as decoded off the wire, before conversion. */
+export type GasFeesData = FieldsOf<GasFees>;
+
+/** Wire form of the gas usage and fee limits set by a transaction sender. */
+export type GasSettingsData = {
+  gasLimits: GasData;
+  teardownGasLimits: GasData;
+  maxFeesPerGas: GasFeesData;
+  maxPriorityFeesPerGas: GasFeesData;
+};

package/src/oracle/noir-structs/tx_effects_data.ts

@@ -0,0 +1,11 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { TxHash } from '@aztec-labs/stdlib/tx';
+
+type TxPrivateLog = Fr[];
+
+export type TxEffectsData = {
+  txHash: TxHash;
+  noteHashes: Fr[];
+  nullifiers: Fr[];
+  privateLogs: TxPrivateLog[];
+};

package/src/oracle/tagging_secret_strategy.ts

@@ -0,0 +1,25 @@
+import {
+  DEFAULT_TAGGING_SECRET_STRATEGY,
+  type ResolveTaggingSecretStrategy,
+  type TaggingSecretStrategy,
+} from '@aztec-labs/pxe/server';
+import type { AppTaggingSecretKind } from '@aztec-labs/stdlib/logs';
+
+/** The tagging secret strategies a TXE test has configured, keyed by delivery mode. Absence means "not configured". */
+export type TXETaggingSecretStrategies = Map<AppTaggingSecretKind, TaggingSecretStrategy>;
+
+/**
+ * Builds the `resolveTaggingSecretStrategy` hook backing the `aztec_txe_setTaggingSecretStrategies` oracle. Returns
+ * `undefined` when no strategy is configured, so PXE's own no-hook default path is exercised. When at least one mode
+ * is configured, modes without an entry resolve to {@link DEFAULT_TAGGING_SECRET_STRATEGY}, matching what PXE would
+ * apply without a hook.
+ */
+export function makeResolveTaggingSecretStrategyHook(
+  strategies: TXETaggingSecretStrategies,
+): ResolveTaggingSecretStrategy | undefined {
+  if (strategies.size === 0) {
+    return undefined;
+  }
+
+  return ({ deliveryMode }) => Promise.resolve(strategies.get(deliveryMode) ?? DEFAULT_TAGGING_SECRET_STRATEGY);
+}