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

package/dest/constants.d.ts

@@ -1,3 +1,7 @@
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 export declare const DEFAULT_ADDRESS: AztecAddress;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY29uc3RhbnRzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUUzRCxlQUFPLE1BQU0sZUFBZSxjQUE4QixDQUFDIn0=
+export declare const MAX_PRIVATE_EVENT_LEN = 10;
+export declare const MAX_PRIVATE_EVENTS_PER_TXE_QUERY = 5;
+export declare const MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY = 64;
+export declare const MAX_OFFCHAIN_EFFECT_LEN: number;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY29uc3RhbnRzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUUzRCxlQUFPLE1BQU0sZUFBZSxjQUE4QixDQUFDO0FBRzNELGVBQU8sTUFBTSxxQkFBcUIsS0FBSyxDQUFDO0FBQ3hDLGVBQU8sTUFBTSxnQ0FBZ0MsSUFBSSxDQUFDO0FBR2xELGVBQU8sTUFBTSxrQ0FBa0MsS0FBSyxDQUFDO0FBRXJELGVBQU8sTUFBTSx1QkFBdUIsUUFBaUMsQ0FBQyJ9

package/dest/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,eAAO,MAAM,eAAe,cAA8B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,eAAO,MAAM,eAAe,cAA8B,CAAC;AAG3D,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAGlD,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD,eAAO,MAAM,uBAAuB,QAAiC,CAAC"}

package/dest/constants.js

@@ -1,2 +1,10 @@
+import { PRIVATE_LOG_CIPHERTEXT_LEN } from '@aztec/constants';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 export const DEFAULT_ADDRESS = AztecAddress.fromNumber(42);
+// This is MAX_MESSAGE_CONTENT_LEN - PRIVATE_EVENT_MSG_PLAINTEXT_RESERVED_FIELDS_LEN
+export const MAX_PRIVATE_EVENT_LEN = 10;
+export const MAX_PRIVATE_EVENTS_PER_TXE_QUERY = 5;
+// Arbitrarily set at 64 because we need a bound. Nothing inherent about it.
+export const MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY = 64;
+// Must match MAX_OFFCHAIN_EFFECT_LEN in noir-projects/aztec-nr/aztec/src/test/helpers/txe_oracles.nr.
+export const MAX_OFFCHAIN_EFFECT_LEN = 2 + PRIVATE_LOG_CIPHERTEXT_LEN;

package/dest/dispatcher_pool.d.ts

@@ -0,0 +1,67 @@
+import type { Logger } from '@aztec/foundation/log';
+import type { TXEForeignCallInput } from './index.js';
+import type { ForeignCallResult } from './utils/encoding.js';
+/**
+ * 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 declare function buildSharedContractStore(): Promise<{
+    dataDir: string;
+    schnorrClassId: string;
+}>;
+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 declare class TXEDispatcherPool {
+    private readonly logger;
+    private readonly workers;
+    private readonly sessionToWorker;
+    private readonly pending;
+    private nextRequestId;
+    private readonly maxWorkers;
+    private readonly readyPromise;
+    private contractStoreSourceDir?;
+    private schnorrClassId?;
+    private workerPath?;
+    constructor(logger: Logger, opts?: TXEDispatcherPoolOptions);
+    /** Resolves once the shared protocol-contracts store is built. Workers spawn lazily on demand. */
+    ready(): Promise<void>;
+    private init;
+    /**
+     * 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;
+    /** Routes a session-dispose request to the worker that owns the session. Fire-and-forget. */
+    disposeSession(sessionId: number): void;
+    resolve_foreign_call(callData: TXEForeignCallInput): Promise<ForeignCallResult>;
+    /** Terminates all workers. Used by tests; production TXE exits the process directly. */
+    shutdown(): Promise<void>;
+    /**
+     * 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;
+    private handleMessage;
+    private handleResult;
+    private handleWorkerError;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGlzcGF0Y2hlcl9wb29sLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvZGlzcGF0Y2hlcl9wb29sLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE9BQU8sS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBY3BELE9BQU8sS0FBSyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sWUFBWSxDQUFDO0FBQ3RELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFLN0Q7Ozs7OztHQU1HO0FBQ0gsd0JBQXNCLHdCQUF3QixJQUFJLE9BQU8sQ0FBQztJQUFFLE9BQU8sRUFBRSxNQUFNLENBQUM7SUFBQyxjQUFjLEVBQUUsTUFBTSxDQUFBO0NBQUUsQ0FBQyxDQW1Cckc7QUEwREQsTUFBTSxXQUFXLHdCQUF3QjtJQUN2QywrQkFBK0I7SUFDL0IsT0FBTyxDQUFDLEVBQUUsTUFBTSxDQUFDO0NBQ2xCO0FBRUQ7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCxxQkFBYSxpQkFBaUI7SUFZMUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxNQUFNO0lBWHpCLE9BQU8sQ0FBQyxRQUFRLENBQUMsT0FBTyxDQUFvQjtJQUM1QyxPQUFPLENBQUMsUUFBUSxDQUFDLGVBQWUsQ0FBNkI7SUFDN0QsT0FBTyxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQXFDO0lBQzdELE9BQU8sQ0FBQyxhQUFhLENBQUs7SUFDMUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQVM7SUFDcEMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQWdCO0lBQzdDLE9BQU8sQ0FBQyxzQkFBc0IsQ0FBQyxDQUFTO0lBQ3hDLE9BQU8sQ0FBQyxjQUFjLENBQUMsQ0FBUztJQUNoQyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQU07SUFFekIsWUFDbUIsTUFBTSxFQUFFLE1BQU0sRUFDL0IsSUFBSSxHQUFFLHdCQUE2QixFQUtwQztJQUVELGtHQUFrRztJQUMzRixLQUFLLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUU1QjtZQUVhLElBQUk7SUFhbEI7Ozs7T0FJRztJQUNILE9BQU8sQ0FBQyxXQUFXO0lBeUJuQiw2RkFBNkY7SUFDN0YsY0FBYyxDQUFDLFNBQVMsRUFBRSxNQUFNLEdBQUcsSUFBSSxDQVl0QztJQUdLLG9CQUFvQixDQUFDLFFBQVEsRUFBRSxtQkFBbUIsR0FBRyxPQUFPLENBQUMsaUJBQWlCLENBQUMsQ0FtQnBGO0lBRUQsd0ZBQXdGO0lBQ2xGLFFBQVEsSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBTzlCO0lBRUQ7Ozs7T0FJRztJQUNILE9BQU8sQ0FBQyxpQkFBaUI7SUFnQnpCLE9BQU8sQ0FBQyxhQUFhO0lBbUJyQixPQUFPLENBQUMsWUFBWTtJQWtCcEIsT0FBTyxDQUFDLGlCQUFpQjtDQW9CMUIifQ==

package/dest/dispatcher_pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher_pool.d.ts","sourceRoot":"","sources":["../src/dispatcher_pool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAcpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAK7D;;;;;;GAMG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBrG;AA0DD,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAiB;IAY1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAXzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,sBAAsB,CAAC,CAAS;IACxC,OAAO,CAAC,cAAc,CAAC,CAAS;IAChC,OAAO,CAAC,UAAU,CAAC,CAAM;IAEzB,YACmB,MAAM,EAAE,MAAM,EAC/B,IAAI,GAAE,wBAA6B,EAKpC;IAED,kGAAkG;IAC3F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE5B;YAEa,IAAI;IAalB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAyBnB,6FAA6F;IAC7F,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAYtC;IAGK,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmBpF;IAED,wFAAwF;IAClF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAO9B;IAED;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,iBAAiB;CAoB1B"}

package/dest/dispatcher_pool.js

@@ -0,0 +1,286 @@
+import { getSchnorrAccountContractArtifact } from '@aztec/accounts/schnorr/lazy';
+import { BackendType, Barretenberg, BarretenbergSync } from '@aztec/bb.js';
+import { openEphemeralStore } from '@aztec/kv-store/lmdb-v2';
+import { LazyProtocolContractsProvider } from '@aztec/protocol-contracts/providers/lazy';
+import { ContractStore } from '@aztec/pxe/client/lazy';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry/lazy';
+import { getContractClassFromArtifact } from '@aztec/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';
+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() {
+    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.
+ */ function resolveWorkerBundlePath() {
+    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];
+}
+function deserializeError(payload) {
+    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;
+}
+/**
+ * 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 {
+    logger;
+    workers;
+    sessionToWorker;
+    pending;
+    nextRequestId;
+    maxWorkers;
+    readyPromise;
+    contractStoreSourceDir;
+    schnorrClassId;
+    workerPath;
+    constructor(logger, opts = {}){
+        this.logger = logger;
+        this.workers = [];
+        this.sessionToWorker = new Map();
+        this.pending = new Map();
+        this.nextRequestId = 0;
+        // 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. */ ready() {
+        return this.readyPromise;
+    }
+    async init() {
+        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.
+   */ spawnWorker() {
+        const workerIdx = this.workers.length;
+        const w = new Worker(this.workerPath, {
+            workerData: {
+                contractStoreSourceDir: this.contractStoreSourceDir,
+                schnorrClassId: this.schnorrClassId
+            }
+        });
+        const slot = {
+            worker: w,
+            sessions: new Set(),
+            inFlightRequestIds: new Set()
+        };
+        this.workers.push(slot);
+        w.on('message', (msg)=>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) {
+        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) {
+        // 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((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() {
+        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`.
+   */ pickOrSpawnWorker() {
+        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;
+    }
+    handleMessage(workerIdx, msg) {
+        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;
+        }
+    }
+    handleResult(workerIdx, msg) {
+        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));
+        }
+    }
+    handleWorkerError(workerIdx, err) {
+        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/dest/index.d.ts

@@ -1,8 +1,52 @@
 import type { Logger } from '@aztec/foundation/log';
-/**
- * Creates an RPC server that forwards calls to the TXE.
- * @param logger - Logger to output to
- * @returns A TXE RPC server.
- */
-export declare function createTXERpcServer(logger: Logger): import("@aztec/foundation/json-rpc/server").SafeJsonRpcServer;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFVQSxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQXFRcEQ7Ozs7R0FJRztBQUNILHdCQUFnQixrQkFBa0IsQ0FBQyxNQUFNLEVBQUUsTUFBTSxpRUFJaEQifQ==
+import type { ProtocolContractName } from '@aztec/protocol-contracts';
+import type { ApiSchemaFor } from '@aztec/stdlib/schemas';
+import { z } from 'zod';
+import './msgpackr_fr_extension.js';
+import { type TXEOracleFunctionName } from './txe_session.js';
+import { type ForeignCallArgs, type ForeignCallResult } from './utils/encoding.js';
+export declare const TXE_REQUIRED_PROTOCOL_CONTRACTS: ProtocolContractName[];
+export type TXEForeignCallInput = {
+    session_id: number;
+    function: TXEOracleFunctionName;
+    root_path: string;
+    package_name: string;
+    inputs: ForeignCallArgs;
+};
+export declare const TXEForeignCallInputSchema: z.ZodType<TXEForeignCallInput>;
+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 declare class TXEDispatcher {
+    private logger;
+    private contractStore;
+    private artifactResolver;
+    private readonly contractStoreSourceDir;
+    private readonly schnorrClassId;
+    constructor(logger: Logger, opts: TXEDispatcherOptions);
+    private warmUp;
+    resolve_foreign_call(callData: TXEForeignCallInput): Promise<ForeignCallResult>;
+    /**
+     * 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.
+     */
+    disposeSession(sessionId: number): Promise<void>;
+}
+/** Diagnostic-only: number of sessions currently held by this worker. */
+export declare function activeSessionCount(): number;
+export declare const TXEDispatcherApiSchema: ApiSchemaFor<TXEDispatcher>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUVwRCxPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBRXRFLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBSTFELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFJeEIsT0FBTyw0QkFBNEIsQ0FBQztBQUNwQyxPQUFPLEVBQUUsS0FBSyxxQkFBcUIsRUFBYyxNQUFNLGtCQUFrQixDQUFDO0FBQzFFLE9BQU8sRUFDTCxLQUFLLGVBQWUsRUFFcEIsS0FBSyxpQkFBaUIsRUFFdkIsTUFBTSxxQkFBcUIsQ0FBQztBQUs3QixlQUFPLE1BQU0sK0JBQStCLEVBQUUsb0JBQW9CLEVBQU8sQ0FBQztBQUkxRSxNQUFNLE1BQU0sbUJBQW1CLEdBQUc7SUFDaEMsVUFBVSxFQUFFLE1BQU0sQ0FBQztJQUNuQixRQUFRLEVBQUUscUJBQXFCLENBQUM7SUFDaEMsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQixZQUFZLEVBQUUsTUFBTSxDQUFDO0lBQ3JCLE1BQU0sRUFBRSxlQUFlLENBQUM7Q0FDekIsQ0FBQztBQUVGLGVBQU8sTUFBTSx5QkFBeUIsRUFBRSxDQUFDLENBQUMsT0FBTyxDQUFDLG1CQUFtQixDQWNwRSxDQUFDO0FBRUYsTUFBTSxXQUFXLG9CQUFvQjtJQUNuQzs7Ozs7T0FLRztJQUNILHNCQUFzQixFQUFFLE1BQU0sQ0FBQztJQUMvQjs7OztPQUlHO0lBQ0gsY0FBYyxFQUFFLE1BQU0sQ0FBQztDQUN4QjtBQUVELHFCQUFhLGFBQWE7SUFPdEIsT0FBTyxDQUFDLE1BQU07SUFOaEIsT0FBTyxDQUFDLGFBQWEsQ0FBaUI7SUFDdEMsT0FBTyxDQUFDLGdCQUFnQixDQUF1QjtJQUMvQyxPQUFPLENBQUMsUUFBUSxDQUFDLHNCQUFzQixDQUFTO0lBQ2hELE9BQU8sQ0FBQyxRQUFRLENBQUMsY0FBYyxDQUFLO0lBRXBDLFlBQ1UsTUFBTSxFQUFFLE1BQU0sRUFDdEIsSUFBSSxFQUFFLG9CQUFvQixFQUkzQjtZQU9hLE1BQU07SUFpQmQsb0JBQW9CLENBQUMsUUFBUSxFQUFFLG1CQUFtQixHQUFHLE9BQU8sQ0FBQyxpQkFBaUIsQ0FBQyxDQWlCcEY7SUFFRDs7Ozs7T0FLRztJQUNHLGNBQWMsQ0FBQyxTQUFTLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FPckQ7Q0FDRjtBQUVELHlFQUF5RTtBQUN6RSx3QkFBZ0Isa0JBQWtCLElBQUksTUFBTSxDQUUzQztBQUVELGVBQU8sTUFBTSxzQkFBc0IsRUFBRSxZQUFZLENBQUMsYUFBYSxDQUs5RCxDQUFDIn0=

package/dest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAqQpD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,iEAIhD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,qBAAqB,EAAc,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,iBAAiB,EAEvB,MAAM,qBAAqB,CAAC;AAK7B,eAAO,MAAM,+BAA+B,EAAE,oBAAoB,EAAO,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAcpE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,aAAa;IAOtB,OAAO,CAAC,MAAM;IANhB,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAK;IAEpC,YACU,MAAM,EAAE,MAAM,EACtB,IAAI,EAAE,oBAAoB,EAI3B;YAOa,MAAM;IAiBd,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiBpF;IAED;;;;;OAKG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrD;CACF;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,eAAO,MAAM,sBAAsB,EAAE,YAAY,CAAC,aAAa,CAK9D,CAAC"}