@aztec-labs/pxe 6.0.0-nightly.20260829

package/dest/entrypoints/client/lazy/utils.js

@@ -0,0 +1,77 @@
+import { BBLazyPrivateKernelProver } from '@aztec-labs/bb-prover/client/lazy';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { LazyProtocolContractsProvider } from '@aztec-labs/protocol-contracts/providers/lazy';
+import { WASMSimulator } from '@aztec-labs/simulator/client';
+import { getStandardAuthRegistry } from '@aztec-labs/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec-labs/standard-contracts/handshake-registry/lazy';
+import { getStandardMultiCallEntrypoint } from '@aztec-labs/standard-contracts/multi-call-entrypoint/lazy';
+import { PXE } from '../../../pxe.js';
+import { PXE_DATA_SCHEMA_VERSION } from '../../../storage/metadata.js';
+import { isPrivateKernelProver } from '../../pxe_creation_options.js';
+import { openBrowserStore } from '../store.js';
+/**
+ * Create and start an PXE instance with the given AztecNode.
+ * Returns a Promise that resolves to the started PXE instance.
+ *
+ * @param aztecNode - The AztecNode instance to be used by the server.
+ * @param config - The PXE Config to use
+ * @param options - (Optional) Optional information for creating an PXE.
+ * @returns A Promise that resolves to the started PXE instance.
+ */ export async function createPXE(aztecNode, config, options = {
+    loggers: {}
+}) {
+    const actor = options.loggerActorLabel;
+    const { l1ChainId, l1ContractAddresses, rollupVersion } = await aztecNode.getNodeInfo();
+    const configWithContracts = {
+        ...config,
+        ...l1ContractAddresses,
+        l1ChainId,
+        rollupVersion
+    };
+    const loggers = options.loggers ?? {};
+    const storeLogger = loggers.store ?? createLogger('pxe:data', {
+        actor
+    });
+    const store = options.store ?? await openBrowserStore('pxe_data', PXE_DATA_SCHEMA_VERSION, {
+        l1ChainId,
+        rollupAddress: l1ContractAddresses.rollupAddress,
+        dataStoreMapSizeKb: configWithContracts.dataStoreMapSizeKb
+    }, storeLogger);
+    const simulator = options.simulator ?? new WASMSimulator();
+    const proverLogger = loggers.prover ?? createLogger('pxe:bb:wasm:bundle', {
+        actor
+    });
+    let prover;
+    if (isPrivateKernelProver(options.proverOrOptions)) {
+        prover = options.proverOrOptions;
+    } else {
+        prover = new BBLazyPrivateKernelProver(simulator, {
+            ...options.proverOrOptions,
+            logger: proverLogger
+        });
+    }
+    const protocolContractsProvider = new LazyProtocolContractsProvider();
+    const preloadedContractsProvider = options.preloadedContractsProvider ?? {
+        getPreloadedContracts: async ()=>[
+                await getStandardMultiCallEntrypoint(),
+                await getStandardAuthRegistry(),
+                await getStandardHandshakeRegistry()
+            ]
+    };
+    const pxeLogger = loggers.pxe ?? createLogger('pxe:service', {
+        actor
+    });
+    const pxe = await PXE.create({
+        node: aztecNode,
+        nodeDebug: options.nodeDebug,
+        store,
+        proofCreator: prover,
+        simulator,
+        protocolContractsProvider,
+        preloadedContractsProvider,
+        config,
+        loggerOrSuffix: pxeLogger,
+        hooks: options.hooks
+    });
+    return pxe;
+}

package/dest/entrypoints/client/store.d.ts

@@ -0,0 +1,14 @@
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { type Logger } from '@aztec-labs/foundation/log';
+import { AztecSQLiteOPFSStore } from '@aztec-labs/kv-store/sqlite-opfs';
+/**
+ * Opens the persistent browser (sqlite-opfs) store selected by `name` and identity `(config.l1ChainId,
+ * config.rollupAddress, schemaVersion)` triple. A store exists per identity: reopening with the same identity returns
+ * the same data, a different identity selects a different (possibly fresh) store.
+ */
+export declare function openBrowserStore(name: string, schemaVersion: number, config: {
+    l1ChainId: number;
+    rollupAddress: EthAddress;
+    dataStoreMapSizeKb?: number;
+}, log?: Logger): Promise<AztecSQLiteOPFSStore>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9lbnRyeXBvaW50cy9jbGllbnQvc3RvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sb0NBQW9DLENBQUM7QUFDckUsT0FBTyxFQUFFLEtBQUssTUFBTSxFQUFnQixNQUFNLDRCQUE0QixDQUFDO0FBQ3ZFLE9BQU8sRUFDTCxvQkFBb0IsRUFJckIsTUFBTSxrQ0FBa0MsQ0FBQztBQUkxQzs7OztHQUlHO0FBQ0gsd0JBQXNCLGdCQUFnQixDQUNwQyxJQUFJLEVBQUUsTUFBTSxFQUNaLGFBQWEsRUFBRSxNQUFNLEVBQ3JCLE1BQU0sRUFBRTtJQUFFLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFBQyxhQUFhLEVBQUUsVUFBVSxDQUFDO0lBQUMsa0JBQWtCLENBQUMsRUFBRSxNQUFNLENBQUE7Q0FBRSxFQUNyRixHQUFHLEdBQUUsTUFBaUMsR0FDckMsT0FBTyxDQUFDLG9CQUFvQixDQUFDLENBZ0MvQiJ9

package/dest/entrypoints/client/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/client/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,4BAA4B,CAAC;AACvE,OAAO,EACL,oBAAoB,EAIrB,MAAM,kCAAkC,CAAC;AAI1C;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,UAAU,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,EACrF,GAAG,GAAE,MAAiC,GACrC,OAAO,CAAC,oBAAoB,CAAC,CAgC/B"}

package/dest/entrypoints/client/store.js

@@ -0,0 +1,42 @@
+import { createLogger } from '@aztec-labs/foundation/log';
+import { AztecSQLiteOPFSStore, SqliteCorruptionError, deleteStore, storePoolDirectory } from '@aztec-labs/kv-store/sqlite-opfs';
+import { assertStoreIdentity, effectiveStoreName } from '../../storage/store_identity.js';
+/**
+ * Opens the persistent browser (sqlite-opfs) store selected by `name` and identity `(config.l1ChainId,
+ * config.rollupAddress, schemaVersion)` triple. A store exists per identity: reopening with the same identity returns
+ * the same data, a different identity selects a different (possibly fresh) store.
+ */ export async function openBrowserStore(name, schemaVersion, config, log = createLogger('pxe:data')) {
+    const identity = {
+        l1ChainId: config.l1ChainId,
+        rollupAddress: config.rollupAddress,
+        schemaVersion
+    };
+    const storeName = effectiveStoreName(name, identity);
+    log.info(`Creating ${storeName} SQLite-OPFS data store`, {
+        storeName,
+        dataStoreMapSizeKb: config.dataStoreMapSizeKb
+    });
+    const openStore = ()=>AztecSQLiteOPFSStore.open(createLogger('kv-store:sqlite-opfs'), storeName, false, storePoolDirectory(storeName));
+    let store;
+    try {
+        store = await openStore();
+    } catch (err) {
+        if (!(err instanceof SqliteCorruptionError)) {
+            throw err;
+        }
+        // A corrupt image is unrecoverable — no retry against the same bytes helps. Wipe the store's OPFS directory
+        // (safe: the failed open left no SAH-pool lock behind) and reopen a fresh, empty one, so the browser self-heals
+        // into a normal first-run rather than dead-ending on "database disk image is malformed" every load.
+        log.warn(`${storeName} store is corrupt (${err.message}); wiping and reopening fresh`);
+        await deleteStore(storeName);
+        store = await openStore();
+    }
+    try {
+        await assertStoreIdentity(store, storeName, identity);
+    } catch (err) {
+        // The store handle owns a worker and OPFS locks; release them before surfacing the refusal.
+        await store.close().catch(()=>{});
+        throw err;
+    }
+    return store;
+}

package/dest/entrypoints/pxe_creation_options.d.ts

@@ -0,0 +1,32 @@
+import type { BBPrivateKernelProverOptions } from '@aztec-labs/bb-prover/client';
+import type { Logger } from '@aztec-labs/foundation/log';
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+import type { CircuitSimulator } from '@aztec-labs/simulator/client';
+import type { AztecNodeDebug, PrivateKernelProver } from '@aztec-labs/stdlib/interfaces/client';
+import type { ExecutionHooks } from '../hooks/index.js';
+import type { PreloadedContractsProvider } from '../pxe.js';
+export type PXECreationOptions = {
+    loggers?: {
+        store?: Logger;
+        pxe?: Logger;
+        prover?: Logger;
+    };
+    /** Actor label to include in log output (e.g., 'pxe-0', 'pxe-test'). */
+    loggerActorLabel?: string;
+    proverOrOptions?: PrivateKernelProver | BBPrivateKernelProverOptions;
+    store?: AztecAsyncKVStore;
+    simulator?: CircuitSimulator;
+    /** Optional hooks to observe and influence contract execution. */
+    hooks?: ExecutionHooks;
+    /** Contracts to preload on startup. Replaces the default when set. */
+    preloadedContractsProvider?: PreloadedContractsProvider;
+    /**
+     * Optional debug API client for the same node. When provided, public function signatures are registered so the
+     * node can produce named public-execution stack traces. Only available on nodes started with debug endpoints
+     * enabled; omitted in prod-like setups.
+     */
+    nodeDebug?: AztecNodeDebug;
+};
+/** Checks if the given value implements the PrivateKernelProver interface via duck-typing. */
+export declare function isPrivateKernelProver(value: unknown): value is PrivateKernelProver;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHhlX2NyZWF0aW9uX29wdGlvbnMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9lbnRyeXBvaW50cy9weGVfY3JlYXRpb25fb3B0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSw0QkFBNEIsRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBQ2pGLE9BQU8sS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBQ3pELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDOUQsT0FBTyxLQUFLLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSw4QkFBOEIsQ0FBQztBQUNyRSxPQUFPLEtBQUssRUFBRSxjQUFjLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxzQ0FBc0MsQ0FBQztBQUVoRyxPQUFPLEtBQUssRUFBRSxjQUFjLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUN4RCxPQUFPLEtBQUssRUFBRSwwQkFBMEIsRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUU1RCxNQUFNLE1BQU0sa0JBQWtCLEdBQUc7SUFDL0IsT0FBTyxDQUFDLEVBQUU7UUFBRSxLQUFLLENBQUMsRUFBRSxNQUFNLENBQUM7UUFBQyxHQUFHLENBQUMsRUFBRSxNQUFNLENBQUM7UUFBQyxNQUFNLENBQUMsRUFBRSxNQUFNLENBQUE7S0FBRSxDQUFDO0lBQzVELHdFQUF3RTtJQUN4RSxnQkFBZ0IsQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUMxQixlQUFlLENBQUMsRUFBRSxtQkFBbUIsR0FBRyw0QkFBNEIsQ0FBQztJQUNyRSxLQUFLLENBQUMsRUFBRSxpQkFBaUIsQ0FBQztJQUMxQixTQUFTLENBQUMsRUFBRSxnQkFBZ0IsQ0FBQztJQUM3QixrRUFBa0U7SUFDbEUsS0FBSyxDQUFDLEVBQUUsY0FBYyxDQUFDO0lBQ3ZCLHNFQUFzRTtJQUN0RSwwQkFBMEIsQ0FBQyxFQUFFLDBCQUEwQixDQUFDO0lBQ3hEOzs7O09BSUc7SUFDSCxTQUFTLENBQUMsRUFBRSxjQUFjLENBQUM7Q0FDNUIsQ0FBQztBQUVGLDhGQUE4RjtBQUM5Rix3QkFBZ0IscUJBQXFCLENBQUMsS0FBSyxFQUFFLE9BQU8sR0FBRyxLQUFLLElBQUksbUJBQW1CLENBSWxGIn0=

package/dest/entrypoints/pxe_creation_options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pxe_creation_options.d.ts","sourceRoot":"","sources":["../../src/entrypoints/pxe_creation_options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEhG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAE5D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,mBAAmB,GAAG,4BAA4B,CAAC;IACrE,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,kEAAkE;IAClE,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,sEAAsE;IACtE,0BAA0B,CAAC,EAAE,0BAA0B,CAAC;IACxD;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B,CAAC;AAEF,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAIlF"}

package/dest/entrypoints/pxe_creation_options.js

@@ -0,0 +1,3 @@
+/** Checks if the given value implements the PrivateKernelProver interface via duck-typing. */ export function isPrivateKernelProver(value) {
+    return typeof value === 'object' && value !== null && typeof value.createChonkProof === 'function';
+}

package/dest/entrypoints/server/circuit_recording/circuit_recorder.d.ts

@@ -0,0 +1,121 @@
+import type { ForeignCallHandler } from '@aztec/noir-acvm_js';
+import { type Logger, type LoggerBindings } from '@aztec-labs/foundation/log';
+import type { ACIRCallback, ACVMWitness } from '@aztec-labs/simulator/client';
+export type OracleCall = {
+    name: string;
+    inputs: unknown[];
+    outputs: unknown;
+    time: number;
+    stackDepth: number;
+};
+export declare class CircuitRecording {
+    circuitName: string;
+    functionName: string;
+    bytecodeSHA512Hash: string;
+    timestamp: number;
+    inputs: Record<string, string>;
+    oracleCalls: OracleCall[];
+    error?: string;
+    parent?: CircuitRecording;
+    constructor(circuitName: string, functionName: string, bytecodeSHA512Hash: string, inputs: Record<string, string>);
+    setParent(recording?: CircuitRecording): void;
+}
+/** Inputs needed to open a recording for a single circuit execution. */
+export type RecordingMetadata = {
+    input: ACVMWitness;
+    bytecode: Buffer;
+    circuitName: string;
+    functionName: string;
+};
+/**
+ * Class responsible for recording circuit inputs necessary to replay the circuit. These inputs are the initial witness
+ * map and the oracle calls made during the circuit execution/witness generation.
+ *
+ * The active recording for an execution lives in `AsyncLocalStorage`, so each (possibly nested) circuit execution owns
+ * its own recording and concurrent or re-entrant executions cannot corrupt one another's state. Nested executions
+ * (`aztec_prv_callPrivateFunction`, utility calls) re-enter {@link record}, which links the child to the recording
+ * active in the enclosing async context and lets ALS restore the parent automatically when the child completes.
+ *
+ * Example recording object:
+ * ```json
+ * {
+ *   "circuitName": "AMM",
+ *   "functionName": "add_liquidity",
+ *   "bytecodeSHA512Hash": "b46c640ed38f20eac5f61a5e41d8dd1e",
+ *   "timestamp": 1740691464360,
+ *   "inputs": {
+ *     "0": "0x1e89de1f0ad5204263733b7ddf65bec45b8f44714a4da85a46474dad677679ef",
+ *     "1": "0x00f4d59c0ff773427bb0fed5b422557ca4dc5655abe53d31fa9408cb3c5a672f",
+ *     "5": "0x000000000000000000000000000000000000000000000000000000000000000f"
+ *   },
+ *   "oracleCalls": [
+ *     {
+ *       "name": "loadCapsule",
+ *       "inputs": [
+ *         [
+ *           "0x102422483bad6abd385948435667e144ac4c272576e325e7563608876cd446fd"
+ *         ],
+ *         [
+ *           "0x000000000000000000000000000000000000000000000000000000000000004d"
+ *         ],
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000001"
+ *         ]
+ *       ],
+ *       "outputs": [
+ *         "0x0000000000000000000000000000000000000000000000000000000000000000",
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000000"
+ *         ]
+ *       ]
+ *     },
+ *     {
+ *       "name": "fetchTaggedLogs",
+ *       "inputs": []
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export declare class CircuitRecorder {
+    #private;
+    protected readonly logger: Logger;
+    protected constructor(loggerOrBindings?: Logger | LoggerBindings);
+    /**
+     * Records a single circuit execution. Opens a recording for the circuit (linked as a child of the recording active
+     * in the current async context, if any), runs `fn` within that recording's context, and finalizes it. The recording
+     * is returned alongside the result so callers can derive per-circuit stats (e.g. oracle timings).
+     *
+     * Recorder bookkeeping never alters execution: if `fn` throws, the error is attached to the recording and re-thrown
+     * unchanged.
+     * @param metadata - Identifies the circuit and its initial witness.
+     * @param fn - Runs the circuit execution; its oracle calls are recorded into this recording.
+     */
+    record<T>(metadata: RecordingMetadata, fn: () => Promise<T>): Promise<{
+        result: T;
+        recording: CircuitRecording;
+    }>;
+    /**
+     * Wraps a callback to record all oracle/foreign calls.
+     * @param callback - The original callback to wrap, either a user circuit callback or protocol circuit callback.
+     * @returns A wrapped callback that records all oracle interactions.
+     */
+    wrapCallback(callback: ACIRCallback | ForeignCallHandler | undefined): ACIRCallback | ForeignCallHandler | undefined;
+    /**
+     * Records a single oracle/foreign call with its inputs and outputs against the recording active in the current
+     * async context.
+     * @param name - Name of the call
+     * @param inputs - Input arguments
+     * @param outputs - Output results
+     */
+    recordCall(name: string, inputs: unknown[], outputs: unknown, time: number): Promise<OracleCall>;
+    /** The recording active in the current async context, if any. */
+    protected currentRecording(): CircuitRecording | undefined;
+    /** Hook invoked when a recording opens, within the recording's context. Overridden to persist recordings. */
+    protected onStart(_recording: CircuitRecording): Promise<void>;
+    /** Hook invoked when a recording completes successfully, within the recording's context. */
+    protected onFinish(_recording: CircuitRecording): Promise<void>;
+    /** Hook invoked when a recording's execution throws, within the recording's context. */
+    protected onError(_recording: CircuitRecording, _error: unknown): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2lyY3VpdF9yZWNvcmRlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2VudHJ5cG9pbnRzL3NlcnZlci9jaXJjdWl0X3JlY29yZGluZy9jaXJjdWl0X3JlY29yZGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUF1QyxNQUFNLHFCQUFxQixDQUFDO0FBR25HLE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBRSxLQUFLLGNBQWMsRUFBaUIsTUFBTSw0QkFBNEIsQ0FBQztBQUU3RixPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsV0FBVyxFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFHOUUsTUFBTSxNQUFNLFVBQVUsR0FBRztJQUN2QixJQUFJLEVBQUUsTUFBTSxDQUFDO0lBQ2IsTUFBTSxFQUFFLE9BQU8sRUFBRSxDQUFDO0lBQ2xCLE9BQU8sRUFBRSxPQUFPLENBQUM7SUFDakIsSUFBSSxFQUFFLE1BQU0sQ0FBQztJQU1iLFVBQVUsRUFBRSxNQUFNLENBQUM7Q0FDcEIsQ0FBQztBQUVGLHFCQUFhLGdCQUFnQjtJQUMzQixXQUFXLEVBQUUsTUFBTSxDQUFDO0lBQ3BCLFlBQVksRUFBRSxNQUFNLENBQUM7SUFDckIsa0JBQWtCLEVBQUUsTUFBTSxDQUFDO0lBQzNCLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFDbEIsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDL0IsV0FBVyxFQUFFLFVBQVUsRUFBRSxDQUFDO0lBQzFCLEtBQUssQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNmLE1BQU0sQ0FBQyxFQUFFLGdCQUFnQixDQUFDO0lBRTFCLFlBQVksV0FBVyxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsTUFBTSxFQUFFLGtCQUFrQixFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsTUFBTSxDQUFDLE1BQU0sRUFBRSxNQUFNLENBQUMsRUFPaEg7SUFFRCxTQUFTLENBQUMsU0FBUyxDQUFDLEVBQUUsZ0JBQWdCLEdBQUcsSUFBSSxDQUU1QztDQUNGO0FBRUQsd0VBQXdFO0FBQ3hFLE1BQU0sTUFBTSxpQkFBaUIsR0FBRztJQUM5QixLQUFLLEVBQUUsV0FBVyxDQUFDO0lBQ25CLFFBQVEsRUFBRSxNQUFNLENBQUM7SUFDakIsV0FBVyxFQUFFLE1BQU0sQ0FBQztJQUNwQixZQUFZLEVBQUUsTUFBTSxDQUFDO0NBQ3RCLENBQUM7QUFFRjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQWlERztBQUNILHFCQUFhLGVBQWU7O0lBQzFCLFNBQVMsQ0FBQyxRQUFRLENBQUMsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUlsQyxTQUFTLGFBQWEsZ0JBQWdCLENBQUMsRUFBRSxNQUFNLEdBQUcsY0FBYyxFQUUvRDtJQUVEOzs7Ozs7Ozs7T0FTRztJQUNILE1BQU0sQ0FBQyxDQUFDLEVBQUUsUUFBUSxFQUFFLGlCQUFpQixFQUFFLEVBQUUsRUFBRSxNQUFNLE9BQU8sQ0FBQyxDQUFDLENBQUMsR0FBRyxPQUFPLENBQUM7UUFBRSxNQUFNLEVBQUUsQ0FBQyxDQUFDO1FBQUMsU0FBUyxFQUFFLGdCQUFnQixDQUFBO0tBQUUsQ0FBQyxDQXNCaEg7SUFFRDs7OztPQUlHO0lBQ0gsWUFBWSxDQUFDLFFBQVEsRUFBRSxZQUFZLEdBQUcsa0JBQWtCLEdBQUcsU0FBUyxHQUFHLFlBQVksR0FBRyxrQkFBa0IsR0FBRyxTQUFTLENBUW5IO0lBeUREOzs7Ozs7T0FNRztJQUNILFVBQVUsQ0FBQyxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUUsRUFBRSxPQUFPLEVBQUUsT0FBTyxFQUFFLElBQUksRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLFVBQVUsQ0FBQyxDQWEvRjtJQUVELGlFQUFpRTtJQUNqRSxTQUFTLENBQUMsZ0JBQWdCLElBQUksZ0JBQWdCLEdBQUcsU0FBUyxDQUV6RDtJQUVELDZHQUE2RztJQUM3RyxTQUFTLENBQUMsT0FBTyxDQUFDLFVBQVUsRUFBRSxnQkFBZ0IsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBRTdEO0lBRUQsNEZBQTRGO0lBQzVGLFNBQVMsQ0FBQyxRQUFRLENBQUMsVUFBVSxFQUFFLGdCQUFnQixHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFOUQ7SUFFRCx3RkFBd0Y7SUFDeEYsU0FBUyxDQUFDLE9BQU8sQ0FBQyxVQUFVLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBRTlFO0NBQ0YifQ==

package/dest/entrypoints/server/circuit_recording/circuit_recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit_recorder.d.ts","sourceRoot":"","sources":["../../../../src/entrypoints/server/circuit_recording/circuit_recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAuC,MAAM,qBAAqB,CAAC;AAGnG,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAiB,MAAM,4BAA4B,CAAC;AAE7F,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAG9E,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IAMb,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,gBAAgB;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAE1B,YAAY,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAOhH;IAED,SAAS,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAE5C;CACF;AAED,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,eAAe;;IAC1B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlC,SAAS,aAAa,gBAAgB,CAAC,EAAE,MAAM,GAAG,cAAc,EAE/D;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAsBhH;IAED;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,GAAG,SAAS,GAAG,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAQnH;IAyDD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAa/F;IAED,iEAAiE;IACjE,SAAS,CAAC,gBAAgB,IAAI,gBAAgB,GAAG,SAAS,CAEzD;IAED,6GAA6G;IAC7G,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D;IAED,4FAA4F;IAC5F,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;IAED,wFAAwF;IACxF,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9E;CACF"}

package/dest/entrypoints/server/circuit_recording/circuit_recorder.js

@@ -0,0 +1,208 @@
+import { sha512 } from '@aztec-labs/foundation/crypto/sha512';
+import { resolveLogger } from '@aztec-labs/foundation/log';
+import { Timer } from '@aztec-labs/foundation/timer';
+import { AsyncLocalStorage } from 'node:async_hooks';
+export class CircuitRecording {
+    circuitName;
+    functionName;
+    bytecodeSHA512Hash;
+    timestamp;
+    inputs;
+    oracleCalls;
+    error;
+    parent;
+    constructor(circuitName, functionName, bytecodeSHA512Hash, inputs){
+        this.circuitName = circuitName;
+        this.functionName = functionName;
+        this.bytecodeSHA512Hash = bytecodeSHA512Hash;
+        this.timestamp = Date.now();
+        this.inputs = inputs;
+        this.oracleCalls = [];
+    }
+    setParent(recording) {
+        this.parent = recording;
+    }
+}
+/**
+ * Class responsible for recording circuit inputs necessary to replay the circuit. These inputs are the initial witness
+ * map and the oracle calls made during the circuit execution/witness generation.
+ *
+ * The active recording for an execution lives in `AsyncLocalStorage`, so each (possibly nested) circuit execution owns
+ * its own recording and concurrent or re-entrant executions cannot corrupt one another's state. Nested executions
+ * (`aztec_prv_callPrivateFunction`, utility calls) re-enter {@link record}, which links the child to the recording
+ * active in the enclosing async context and lets ALS restore the parent automatically when the child completes.
+ *
+ * Example recording object:
+ * ```json
+ * {
+ *   "circuitName": "AMM",
+ *   "functionName": "add_liquidity",
+ *   "bytecodeSHA512Hash": "b46c640ed38f20eac5f61a5e41d8dd1e",
+ *   "timestamp": 1740691464360,
+ *   "inputs": {
+ *     "0": "0x1e89de1f0ad5204263733b7ddf65bec45b8f44714a4da85a46474dad677679ef",
+ *     "1": "0x00f4d59c0ff773427bb0fed5b422557ca4dc5655abe53d31fa9408cb3c5a672f",
+ *     "5": "0x000000000000000000000000000000000000000000000000000000000000000f"
+ *   },
+ *   "oracleCalls": [
+ *     {
+ *       "name": "loadCapsule",
+ *       "inputs": [
+ *         [
+ *           "0x102422483bad6abd385948435667e144ac4c272576e325e7563608876cd446fd"
+ *         ],
+ *         [
+ *           "0x000000000000000000000000000000000000000000000000000000000000004d"
+ *         ],
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000001"
+ *         ]
+ *       ],
+ *       "outputs": [
+ *         "0x0000000000000000000000000000000000000000000000000000000000000000",
+ *         [
+ *           "0x0000000000000000000000000000000000000000000000000000000000000000"
+ *         ]
+ *       ]
+ *     },
+ *     {
+ *       "name": "fetchTaggedLogs",
+ *       "inputs": []
+ *     }
+ *   ]
+ * }
+ * ```
+ */ export class CircuitRecorder {
+    logger;
+    #recordings = new AsyncLocalStorage();
+    constructor(loggerOrBindings){
+        this.logger = resolveLogger('simulator:acvm:recording', loggerOrBindings);
+    }
+    /**
+   * Records a single circuit execution. Opens a recording for the circuit (linked as a child of the recording active
+   * in the current async context, if any), runs `fn` within that recording's context, and finalizes it. The recording
+   * is returned alongside the result so callers can derive per-circuit stats (e.g. oracle timings).
+   *
+   * Recorder bookkeeping never alters execution: if `fn` throws, the error is attached to the recording and re-thrown
+   * unchanged.
+   * @param metadata - Identifies the circuit and its initial witness.
+   * @param fn - Runs the circuit execution; its oracle calls are recorded into this recording.
+   */ record(metadata, fn) {
+        const parent = this.#recordings.getStore();
+        const recording = new CircuitRecording(metadata.circuitName, metadata.functionName, sha512(metadata.bytecode).toString('hex'), Object.fromEntries(metadata.input));
+        recording.setParent(parent);
+        return this.#recordings.run(recording, async ()=>{
+            await this.onStart(recording);
+            try {
+                const result = await fn();
+                await this.onFinish(recording);
+                return {
+                    result,
+                    recording
+                };
+            } catch (error) {
+                recording.error = JSON.stringify(error);
+                await this.onError(recording, error);
+                throw error;
+            }
+        });
+    }
+    /**
+   * Wraps a callback to record all oracle/foreign calls.
+   * @param callback - The original callback to wrap, either a user circuit callback or protocol circuit callback.
+   * @returns A wrapped callback that records all oracle interactions.
+   */ wrapCallback(callback) {
+        if (!callback) {
+            return undefined;
+        }
+        if (this.#isACIRCallback(callback)) {
+            return this.#wrapUserCircuitCallback(callback);
+        }
+        return this.#wrapProtocolCircuitCallback(callback);
+    }
+    /**
+   * Type guard to check if a callback is an ACIRCallback.
+   */ #isACIRCallback(callback) {
+        return typeof callback === 'object' && callback !== null && !('call' in callback);
+    }
+    /**
+   * Wraps a user circuit callback to record all oracle calls. A nested circuit entered via an oracle (e.g.
+   * `aztec_prv_callPrivateFunction`) re-enters {@link record}, so its own oracle calls land on the child recording and
+   * this circuit's calls (including the entering oracle call itself) land on this recording once the child completes.
+   * @param callback - The original circuit callback.
+   * @returns A wrapped callback that records all oracle interactions which is to be provided to the ACVM.
+   */ #wrapUserCircuitCallback(callback) {
+        const recordingCallback = {};
+        const oracleMethods = Object.keys(callback);
+        for (const name of oracleMethods){
+            const fn = callback[name];
+            if (!fn || typeof fn !== 'function') {
+                throw new Error(`Oracle method ${name} not found when setting up recording callback`);
+            }
+            recordingCallback[name] = (...args)=>{
+                const timer = new Timer();
+                const result = fn.call(callback, ...args);
+                if (result instanceof Promise) {
+                    return result.then(async (r)=>{
+                        await this.recordCall(name, args, r, timer.ms());
+                        return r;
+                    });
+                }
+                void this.recordCall(name, args, result, timer.ms());
+                return result;
+            };
+        }
+        return recordingCallback;
+    }
+    /**
+   * Wraps a protocol circuit callback to record all oracle calls.
+   * @param callback - The original oracle circuit callback.
+   * @returns A wrapped handler that records all oracle interactions which is to be provided to the ACVM.
+   */ #wrapProtocolCircuitCallback(callback) {
+        return async (name, inputs)=>{
+            const timer = new Timer();
+            const result = await callback(name, inputs);
+            await this.recordCall(name, inputs, result, timer.ms());
+            return result;
+        };
+    }
+    /**
+   * Records a single oracle/foreign call with its inputs and outputs against the recording active in the current
+   * async context.
+   * @param name - Name of the call
+   * @param inputs - Input arguments
+   * @param outputs - Output results
+   */ recordCall(name, inputs, outputs, time) {
+        const recording = this.#recordings.getStore();
+        const entry = {
+            name,
+            inputs,
+            outputs,
+            time,
+            stackDepth: depthOf(recording)
+        };
+        // Outside any active recording context (e.g. a stray call after the scope closed, or a direct unit-test call)
+        // there is nowhere to record; return the entry without throwing into the execution path.
+        recording?.oracleCalls.push(entry);
+        return Promise.resolve(entry);
+    }
+    /** The recording active in the current async context, if any. */ currentRecording() {
+        return this.#recordings.getStore();
+    }
+    /** Hook invoked when a recording opens, within the recording's context. Overridden to persist recordings. */ onStart(_recording) {
+        return Promise.resolve();
+    }
+    /** Hook invoked when a recording completes successfully, within the recording's context. */ onFinish(_recording) {
+        return Promise.resolve();
+    }
+    /** Hook invoked when a recording's execution throws, within the recording's context. */ onError(_recording, _error) {
+        return Promise.resolve();
+    }
+}
+/** Depth of a recording in the call tree: 0 for a top-level circuit, incremented per nested circuit. */ function depthOf(recording) {
+    let depth = 0;
+    for(let ancestor = recording?.parent; ancestor; ancestor = ancestor.parent){
+        depth++;
+    }
+    return depth;
+}

package/dest/entrypoints/server/circuit_recording/file_circuit_recorder.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from '@aztec-labs/foundation/log';
+import { CircuitRecorder, type CircuitRecording } from './circuit_recorder.js';
+export declare class FileCircuitRecorder extends CircuitRecorder {
+    #private;
+    private readonly recordDir;
+    constructor(recordDir: string, logger?: Logger);
+    protected onStart(recording: CircuitRecording): Promise<void>;
+    /**
+     * Records a single oracle/foreign call with its inputs and outputs.
+     * @param name - Name of the call
+     * @param inputs - Input arguments
+     * @param outputs - Output results
+     */
+    recordCall(name: string, inputs: unknown[], outputs: unknown, time: number): Promise<import("./circuit_recorder.js").OracleCall>;
+    /** Closes the recording file with the trailing brackets so the JSON parses. */
+    protected onFinish(recording: CircuitRecording): Promise<void>;
+    /** Closes the recording file with the execution error and trailing brackets so the JSON parses. */
+    protected onError(recording: CircuitRecording, error: unknown): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZV9jaXJjdWl0X3JlY29yZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvZW50cnlwb2ludHMvc2VydmVyL2NpcmN1aXRfcmVjb3JkaW5nL2ZpbGVfY2lyY3VpdF9yZWNvcmRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUl6RCxPQUFPLEVBQUUsZUFBZSxFQUFFLEtBQUssZ0JBQWdCLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUsvRSxxQkFBYSxtQkFBb0IsU0FBUSxlQUFlOztJQUlwRCxPQUFPLENBQUMsUUFBUSxDQUFDLFNBQVM7SUFENUIsWUFDbUIsU0FBUyxFQUFFLE1BQU0sRUFDbEMsTUFBTSxDQUFDLEVBQUUsTUFBTSxFQUdoQjtJQUVELFVBQXlCLE9BQU8sQ0FBQyxTQUFTLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQTZCM0U7SUFxQ0Q7Ozs7O09BS0c7SUFDWSxVQUFVLENBQUMsSUFBSSxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLEVBQUUsT0FBTyxFQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsTUFBTSx1REFjeEY7SUFFRCwrRUFBK0U7SUFDL0UsVUFBeUIsUUFBUSxDQUFDLFNBQVMsRUFBRSxnQkFBZ0IsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBVTVFO0lBRUQsbUdBQW1HO0lBQ25HLFVBQXlCLE9BQU8sQ0FBQyxTQUFTLEVBQUUsZ0JBQWdCLEVBQUUsS0FBSyxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBWTNGO0NBQ0YifQ==

package/dest/entrypoints/server/circuit_recording/file_circuit_recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file_circuit_recorder.d.ts","sourceRoot":"","sources":["../../../../src/entrypoints/server/circuit_recording/file_circuit_recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIzD,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK/E,qBAAa,mBAAoB,SAAQ,eAAe;;IAIpD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAD5B,YACmB,SAAS,EAAE,MAAM,EAClC,MAAM,CAAC,EAAE,MAAM,EAGhB;IAED,UAAyB,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B3E;IAqCD;;;;;OAKG;IACY,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,uDAcxF;IAED,+EAA+E;IAC/E,UAAyB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E;IAED,mGAAmG;IACnG,UAAyB,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAY3F;CACF"}