@aztec/simulator 6.0.0-nightly.20260605 → 6.0.0-nightly.20260721

package/dest/public/public_tx_simulator/public_tx_simulator_base.d.ts

@@ -0,0 +1,24 @@
+import { type Logger, type LoggerBindings } from '@aztec/foundation/log';
+import { PublicSimulatorConfig } from '@aztec/stdlib/avm';
+import type { GlobalVariables, ProtocolContracts, Tx } from '@aztec/stdlib/tx';
+import type { AvmSimulator } from '../avm_simulator.js';
+import type { PublicContractsDB } from '../public_db_sources.js';
+/**
+ * Shared base for public tx simulators: holds the common configuration, the {@link AvmSimulator} used
+ * to run the transaction's public calls, the contracts DB and fork id that scope the simulation's
+ * contract-data lookups, the logger, and the tx-hash helper. Concrete simulators extend this and
+ * implement `simulate`.
+ */
+export declare abstract class PublicTxSimulatorBase {
+    protected avmSimulator: AvmSimulator;
+    protected globalVariables: GlobalVariables;
+    protected contractsDB: PublicContractsDB;
+    protected forkId: number;
+    protected protocolContracts: ProtocolContracts;
+    protected log: Logger;
+    protected readonly config: PublicSimulatorConfig;
+    protected readonly bindings?: LoggerBindings;
+    constructor(avmSimulator: AvmSimulator, globalVariables: GlobalVariables, contractsDB: PublicContractsDB, forkId: number, config?: Partial<PublicSimulatorConfig>, protocolContracts?: ProtocolContracts, bindings?: LoggerBindings);
+    protected computeTxHash(tx: Tx): import("@aztec/stdlib/tx").TxHash;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHVibGljX3R4X3NpbXVsYXRvcl9iYXNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcHVibGljL3B1YmxpY190eF9zaW11bGF0b3IvcHVibGljX3R4X3NpbXVsYXRvcl9iYXNlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBRSxLQUFLLGNBQWMsRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUV2RixPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssRUFBRSxlQUFlLEVBQUUsaUJBQWlCLEVBQUUsRUFBRSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFL0UsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDeEQsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUVqRTs7Ozs7R0FLRztBQUNILDhCQUFzQixxQkFBcUI7SUFNdkMsU0FBUyxDQUFDLFlBQVksRUFBRSxZQUFZO0lBQ3BDLFNBQVMsQ0FBQyxlQUFlLEVBQUUsZUFBZTtJQUMxQyxTQUFTLENBQUMsV0FBVyxFQUFFLGlCQUFpQjtJQUN4QyxTQUFTLENBQUMsTUFBTSxFQUFFLE1BQU07SUFFeEIsU0FBUyxDQUFDLGlCQUFpQixFQUFFLGlCQUFpQjtJQVZoRCxTQUFTLENBQUMsR0FBRyxFQUFFLE1BQU0sQ0FBQztJQUN0QixTQUFTLENBQUMsUUFBUSxDQUFDLE1BQU0sRUFBRSxxQkFBcUIsQ0FBQztJQUNqRCxTQUFTLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxFQUFFLGNBQWMsQ0FBQztJQUU3QyxZQUNZLFlBQVksRUFBRSxZQUFZLEVBQzFCLGVBQWUsRUFBRSxlQUFlLEVBQ2hDLFdBQVcsRUFBRSxpQkFBaUIsRUFDOUIsTUFBTSxFQUFFLE1BQU0sRUFDeEIsTUFBTSxDQUFDLEVBQUUsT0FBTyxDQUFDLHFCQUFxQixDQUFDLEVBQzdCLGlCQUFpQixHQUFFLGlCQUF5QyxFQUN0RSxRQUFRLENBQUMsRUFBRSxjQUFjLEVBSzFCO0lBRUQsU0FBUyxDQUFDLGFBQWEsQ0FBQyxFQUFFLEVBQUUsRUFBRSxxQ0FFN0I7Q0FDRiJ9

package/dest/public/public_tx_simulator/public_tx_simulator_base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public_tx_simulator_base.d.ts","sourceRoot":"","sources":["../../../src/public/public_tx_simulator/public_tx_simulator_base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AAEvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;GAKG;AACH,8BAAsB,qBAAqB;IAMvC,SAAS,CAAC,YAAY,EAAE,YAAY;IACpC,SAAS,CAAC,eAAe,EAAE,eAAe;IAC1C,SAAS,CAAC,WAAW,EAAE,iBAAiB;IACxC,SAAS,CAAC,MAAM,EAAE,MAAM;IAExB,SAAS,CAAC,iBAAiB,EAAE,iBAAiB;IAVhD,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACjD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE7C,YACY,YAAY,EAAE,YAAY,EAC1B,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,iBAAiB,EAC9B,MAAM,EAAE,MAAM,EACxB,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAC7B,iBAAiB,GAAE,iBAAyC,EACtE,QAAQ,CAAC,EAAE,cAAc,EAK1B;IAED,SAAS,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,qCAE7B;CACF"}

package/dest/public/public_tx_simulator/public_tx_simulator_base.js

@@ -0,0 +1,31 @@
+import { createLogger } from '@aztec/foundation/log';
+import { ProtocolContractsList } from '@aztec/protocol-contracts';
+import { PublicSimulatorConfig } from '@aztec/stdlib/avm';
+/**
+ * Shared base for public tx simulators: holds the common configuration, the {@link AvmSimulator} used
+ * to run the transaction's public calls, the contracts DB and fork id that scope the simulation's
+ * contract-data lookups, the logger, and the tx-hash helper. Concrete simulators extend this and
+ * implement `simulate`.
+ */ export class PublicTxSimulatorBase {
+    avmSimulator;
+    globalVariables;
+    contractsDB;
+    forkId;
+    protocolContracts;
+    log;
+    config;
+    bindings;
+    constructor(avmSimulator, globalVariables, contractsDB, forkId, config, protocolContracts = ProtocolContractsList, bindings){
+        this.avmSimulator = avmSimulator;
+        this.globalVariables = globalVariables;
+        this.contractsDB = contractsDB;
+        this.forkId = forkId;
+        this.protocolContracts = protocolContracts;
+        this.config = PublicSimulatorConfig.from(config ?? {});
+        this.bindings = bindings;
+        this.log = createLogger(`simulator:public_tx_simulator`, bindings);
+    }
+    computeTxHash(tx) {
+        return tx.getTxHash();
+    }
+}

package/dest/public/public_tx_simulator/public_tx_simulator_interface.d.ts

@@ -4,14 +4,14 @@ export interface PublicTxSimulatorInterface {
     simulate(tx: Tx): Promise<PublicTxResult>;
     /**
      * Cancel the current simulation if one is in progress.
-     * This signals the underlying simulator (e.g., C++) to stop at the next safe point.
+     * This signals the underlying simulator to stop at the next safe point.
      * Safe to call even if no simulation is in progress.
      * Optional - not all implementations support cancellation.
      *
      * @param waitTimeoutMs - If provided, wait up to this many ms for the simulation to actually stop.
-     *                        This is important because signaling cancellation doesn't immediately stop C++ -
-     *                        it only sets a flag that C++ checks at certain points. If C++ is in the middle
-     *                        of a slow operation (e.g., pad_trees), it won't stop until that completes.
+     *                        Cancellation is cooperative: signaling it only sets a flag the simulator
+     *                        checks at certain points, so if it's mid slow-operation it won't stop until
+     *                        that completes.
      * @returns Promise that resolves when cancellation is signaled (and optionally when simulation stops)
      */
     cancel?(waitTimeoutMs?: number): Promise<void>;
@@ -20,7 +20,7 @@ export interface MeasuredPublicTxSimulatorInterface {
     simulate(tx: Tx, txLabel: string): Promise<PublicTxResult>;
     /**
      * Cancel the current simulation if one is in progress.
-     * This signals the underlying simulator (e.g., C++) to stop at the next safe point.
+     * This signals the underlying simulator to stop at the next safe point.
      * Safe to call even if no simulation is in progress.
      * Optional - not all implementations support cancellation.
      *

package/dest/public/test_executor_metrics.d.ts

@@ -13,10 +13,6 @@ export interface PublicTxMetrics {
     totalDurationMs: number;
     manaUsed: number | undefined;
     totalInstructionsExecuted: number;
-    bytecodeSizes: {
-        contractName: string;
-        sizeBytes: number;
-    }[];
     nonRevertiblePrivateInsertionsUs: number | undefined;
     revertiblePrivateInsertionsUs: number | undefined;
     enqueuedCalls: PublicEnqueuedCallMetrics[];
@@ -51,11 +47,10 @@ export declare class TestExecutorMetrics implements ExecutorMetricsInterface {
     recordEnqueuedCallSimulation(fnName: string, durationMs: number, manaUsed: number, totalInstructionsExecuted: number): void;
     recordEnqueuedCallSimulationFailure(fnName: string, durationMs: number, manaUsed: number, totalInstructionsExecuted: number): void;
     recordPrivateEffectsInsertion(durationUs: number, type: 'revertible' | 'non-revertible'): void;
-    recordBytecodeSize(txLabel: string, contractName: string, sizeBytes: number): void;
     recordProverMetrics(txLabel: string, metrics: Partial<PublicTxMetrics>): void;
     prettyPrint(filter?: PublicTxMetricsFilter): void;
     toPrettyString(filter?: PublicTxMetricsFilter): string;
     toJSON(indent?: number): string;
     toGithubActionBenchmarkJSON(indent?: number): string;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVzdF9leGVjdXRvcl9tZXRyaWNzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcHVibGljL3Rlc3RfZXhlY3V0b3JfbWV0cmljcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQWUsS0FBSyxjQUFjLEVBQWdCLE1BQU0sdUJBQXVCLENBQUM7QUFFdkYsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFDcEQsT0FBTyxLQUFLLEVBQUUsT0FBTyxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFJakQsT0FBTyxLQUFLLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUVoRixNQUFNLFdBQVcseUJBQXlCO0lBQ3hDLE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZixVQUFVLEVBQUUsTUFBTSxDQUFDO0lBQ25CLFFBQVEsRUFBRSxNQUFNLENBQUM7SUFDakIseUJBQXlCLEVBQUUsTUFBTSxDQUFDO0lBQ2xDLFFBQVEsRUFBRSxPQUFPLENBQUM7Q0FDbkI7QUFFRCxNQUFNLFdBQVcsZUFBZTtJQUU5QixlQUFlLEVBQUUsTUFBTSxDQUFDO0lBQ3hCLFFBQVEsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQzdCLHlCQUF5QixFQUFFLE1BQU0sQ0FBQztJQUNsQyxhQUFhLEVBQUU7UUFBRSxZQUFZLEVBQUUsTUFBTSxDQUFDO1FBQUMsU0FBUyxFQUFFLE1BQU0sQ0FBQTtLQUFFLEVBQUUsQ0FBQztJQUM3RCxnQ0FBZ0MsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQ3JELDZCQUE2QixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFDbEQsYUFBYSxFQUFFLHlCQUF5QixFQUFFLENBQUM7SUFDM0MsWUFBWSxFQUFFLFVBQVUsR0FBRyxTQUFTLENBQUM7SUFFckMsc0JBQXNCLEVBQUUsTUFBTSxHQUFHLFNBQVMsQ0FBQztJQUMzQyxtQkFBbUIsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQ3hDLDJCQUEyQixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFFaEQsNkJBQTZCLEVBQUUsTUFBTSxHQUFHLFNBQVMsQ0FBQztJQUNsRCx1QkFBdUIsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQzVDLGlCQUFpQixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFDdEMsWUFBWSxFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFDakMsNkJBQTZCLEVBQUUsTUFBTSxHQUFHLFNBQVMsQ0FBQztJQUNsRCx3Q0FBd0MsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQzdELHdCQUF3QixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7Q0FDOUM7QUFXRCxvQkFBWSxxQkFBcUI7SUFDL0IsR0FBRyxJQUFBO0lBQ0gsTUFBTSxJQUFBO0lBQ04sU0FBUyxJQUFBO0lBQ1QsWUFBWSxJQUFBO0lBQ1osT0FBTyxJQUFBO0NBQ1I7QUE0QkQscUJBQWEsbUJBQW9CLFlBQVcsd0JBQXdCOztJQUNsRSxPQUFPLENBQUMsTUFBTSxDQUFTO0lBRXZCLE9BQU8sQ0FBQyxTQUFTLENBQTJDO0lBQzVELE9BQU8sQ0FBQyxjQUFjLENBQXFCO0lBQzNDLE9BQU8sQ0FBQyxPQUFPLENBQW9CO0lBRW5DLFlBQVksUUFBUSxDQUFDLEVBQUUsY0FBYyxFQUVwQztJQUVELDBCQUEwQixDQUFDLE9BQU8sRUFBRSxNQUFNLFFBTXpDO0lBRUQseUJBQXlCLENBQUMsT0FBTyxFQUFFLE1BQU0sRUFBRSxPQUFPLENBQUMsRUFBRSxPQUFPLEVBQUUsWUFBWSxDQUFDLEVBQUUsVUFBVSxRQWdCdEY7SUFFRCw0QkFBNEIsQ0FDMUIsTUFBTSxFQUFFLE1BQU0sRUFDZCxVQUFVLEVBQUUsTUFBTSxFQUNsQixRQUFRLEVBQUUsTUFBTSxFQUNoQix5QkFBeUIsRUFBRSxNQUFNLFFBR2xDO0lBRUQsbUNBQW1DLENBQ2pDLE1BQU0sRUFBRSxNQUFNLEVBQ2QsVUFBVSxFQUFFLE1BQU0sRUFDbEIsUUFBUSxFQUFFLE1BQU0sRUFDaEIseUJBQXlCLEVBQUUsTUFBTSxRQUdsQztJQW9CRCw2QkFBNkIsQ0FBQyxVQUFVLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxZQUFZLEdBQUcsZ0JBQWdCLFFBZ0J0RjtJQUVELGtCQUFrQixDQUFDLE9BQU8sRUFBRSxNQUFNLEVBQUUsWUFBWSxFQUFFLE1BQU0sRUFBRSxTQUFTLEVBQUUsTUFBTSxRQUkxRTtJQUVELG1CQUFtQixDQUFDLE9BQU8sRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLE9BQU8sQ0FBQyxlQUFlLENBQUMsUUFVckU7SUFFRCxXQUFXLENBQUMsTUFBTSxHQUFFLHFCQUFpRCxRQUVwRTtJQUVELGNBQWMsQ0FBQyxNQUFNLEdBQUUscUJBQWlELFVBd0Z2RTtJQTBCRCxNQUFNLENBQUMsTUFBTSxTQUFJLFVBRWhCO0lBRUQsMkJBQTJCLENBQUMsTUFBTSxTQUFJLFVBbUdyQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVzdF9leGVjdXRvcl9tZXRyaWNzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcHVibGljL3Rlc3RfZXhlY3V0b3JfbWV0cmljcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQWUsS0FBSyxjQUFjLEVBQWdCLE1BQU0sdUJBQXVCLENBQUM7QUFFdkYsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFDcEQsT0FBTyxLQUFLLEVBQUUsT0FBTyxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFJakQsT0FBTyxLQUFLLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUVoRixNQUFNLFdBQVcseUJBQXlCO0lBQ3hDLE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZixVQUFVLEVBQUUsTUFBTSxDQUFDO0lBQ25CLFFBQVEsRUFBRSxNQUFNLENBQUM7SUFDakIseUJBQXlCLEVBQUUsTUFBTSxDQUFDO0lBQ2xDLFFBQVEsRUFBRSxPQUFPLENBQUM7Q0FDbkI7QUFFRCxNQUFNLFdBQVcsZUFBZTtJQUU5QixlQUFlLEVBQUUsTUFBTSxDQUFDO0lBQ3hCLFFBQVEsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQzdCLHlCQUF5QixFQUFFLE1BQU0sQ0FBQztJQUNsQyxnQ0FBZ0MsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQ3JELDZCQUE2QixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFDbEQsYUFBYSxFQUFFLHlCQUF5QixFQUFFLENBQUM7SUFDM0MsWUFBWSxFQUFFLFVBQVUsR0FBRyxTQUFTLENBQUM7SUFFckMsc0JBQXNCLEVBQUUsTUFBTSxHQUFHLFNBQVMsQ0FBQztJQUMzQyxtQkFBbUIsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQ3hDLDJCQUEyQixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFFaEQsNkJBQTZCLEVBQUUsTUFBTSxHQUFHLFNBQVMsQ0FBQztJQUNsRCx1QkFBdUIsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQzVDLGlCQUFpQixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFDdEMsWUFBWSxFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7SUFDakMsNkJBQTZCLEVBQUUsTUFBTSxHQUFHLFNBQVMsQ0FBQztJQUNsRCx3Q0FBd0MsRUFBRSxNQUFNLEdBQUcsU0FBUyxDQUFDO0lBQzdELHdCQUF3QixFQUFFLE1BQU0sR0FBRyxTQUFTLENBQUM7Q0FDOUM7QUFXRCxvQkFBWSxxQkFBcUI7SUFDL0IsR0FBRyxJQUFBO0lBQ0gsTUFBTSxJQUFBO0lBQ04sU0FBUyxJQUFBO0lBQ1QsWUFBWSxJQUFBO0lBQ1osT0FBTyxJQUFBO0NBQ1I7QUEyQkQscUJBQWEsbUJBQW9CLFlBQVcsd0JBQXdCOztJQUNsRSxPQUFPLENBQUMsTUFBTSxDQUFTO0lBRXZCLE9BQU8sQ0FBQyxTQUFTLENBQTJDO0lBQzVELE9BQU8sQ0FBQyxjQUFjLENBQXFCO0lBQzNDLE9BQU8sQ0FBQyxPQUFPLENBQW9CO0lBRW5DLFlBQVksUUFBUSxDQUFDLEVBQUUsY0FBYyxFQUVwQztJQUVELDBCQUEwQixDQUFDLE9BQU8sRUFBRSxNQUFNLFFBTXpDO0lBRUQseUJBQXlCLENBQUMsT0FBTyxFQUFFLE1BQU0sRUFBRSxPQUFPLENBQUMsRUFBRSxPQUFPLEVBQUUsWUFBWSxDQUFDLEVBQUUsVUFBVSxRQWdCdEY7SUFFRCw0QkFBNEIsQ0FDMUIsTUFBTSxFQUFFLE1BQU0sRUFDZCxVQUFVLEVBQUUsTUFBTSxFQUNsQixRQUFRLEVBQUUsTUFBTSxFQUNoQix5QkFBeUIsRUFBRSxNQUFNLFFBR2xDO0lBRUQsbUNBQW1DLENBQ2pDLE1BQU0sRUFBRSxNQUFNLEVBQ2QsVUFBVSxFQUFFLE1BQU0sRUFDbEIsUUFBUSxFQUFFLE1BQU0sRUFDaEIseUJBQXlCLEVBQUUsTUFBTSxRQUdsQztJQW9CRCw2QkFBNkIsQ0FBQyxVQUFVLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxZQUFZLEdBQUcsZ0JBQWdCLFFBZ0J0RjtJQUVELG1CQUFtQixDQUFDLE9BQU8sRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLE9BQU8sQ0FBQyxlQUFlLENBQUMsUUFVckU7SUFFRCxXQUFXLENBQUMsTUFBTSxHQUFFLHFCQUFpRCxRQUVwRTtJQUVELGNBQWMsQ0FBQyxNQUFNLEdBQUUscUJBQWlELFVBK0V2RTtJQTBCRCxNQUFNLENBQUMsTUFBTSxTQUFJLFVBRWhCO0lBRUQsMkJBQTJCLENBQUMsTUFBTSxTQUFJLFVBNEZyQztDQUNGIn0=

package/dest/public/test_executor_metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test_executor_metrics.d.ts","sourceRoot":"","sources":["../../src/public/test_executor_metrics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"test_executor_metrics.d.ts","sourceRoot":"","sources":["../../src/public/test_executor_metrics.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AAEvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAIjD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAEhF,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB,EAAE,MAAM,CAAC;IAClC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAE9B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,yBAAyB,EAAE,MAAM,CAAC;IAClC,gCAAgC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrD,6BAA6B,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,aAAa,EAAE,yBAAyB,EAAE,CAAC;IAC3C,YAAY,EAAE,UAAU,GAAG,SAAS,CAAC;IAErC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,2BAA2B,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhD,6BAA6B,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6BAA6B,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,wCAAwC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7D,wBAAwB,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAWD,oBAAY,qBAAqB;IAC/B,GAAG,IAAA;IACH,MAAM,IAAA;IACN,SAAS,IAAA;IACT,YAAY,IAAA;IACZ,OAAO,IAAA;CACR;AA2BD,qBAAa,mBAAoB,YAAW,wBAAwB;;IAClE,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,SAAS,CAA2C;IAC5D,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,OAAO,CAAoB;IAEnC,YAAY,QAAQ,CAAC,EAAE,cAAc,EAEpC;IAED,0BAA0B,CAAC,OAAO,EAAE,MAAM,QAMzC;IAED,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,UAAU,QAgBtF;IAED,4BAA4B,CAC1B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,yBAAyB,EAAE,MAAM,QAGlC;IAED,mCAAmC,CACjC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,yBAAyB,EAAE,MAAM,QAGlC;IAoBD,6BAA6B,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,gBAAgB,QAgBtF;IAED,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,QAUrE;IAED,WAAW,CAAC,MAAM,GAAE,qBAAiD,QAEpE;IAED,cAAc,CAAC,MAAM,GAAE,qBAAiD,UA+EvE;IA0BD,MAAM,CAAC,MAAM,SAAI,UAEhB;IAED,2BAA2B,CAAC,MAAM,SAAI,UA4FrC;CACF"}

package/dest/public/test_executor_metrics.js

@@ -24,7 +24,6 @@ function createEmptyTxMetrics() {
         totalDurationMs: 0,
         manaUsed: 0,
         totalInstructionsExecuted: 0,
-        bytecodeSizes: [],
         nonRevertiblePrivateInsertionsUs: undefined,
         revertiblePrivateInsertionsUs: undefined,
         enqueuedCalls: [],
@@ -100,14 +99,6 @@ export class TestExecutorMetrics {
             txMetrics.nonRevertiblePrivateInsertionsUs = durationUs;
         }
     }
-    recordBytecodeSize(txLabel, contractName, sizeBytes) {
-        const txMetrics = this.txMetrics.get(txLabel);
-        assert(txMetrics, `Cannot record bytecode size for unknown tx label: ${txLabel}`);
-        txMetrics.bytecodeSizes.push({
-            contractName,
-            sizeBytes
-        });
-    }
     recordProverMetrics(txLabel, metrics) {
         if (!this.txMetrics.has(txLabel)) {
             this.txMetrics.set(txLabel, createEmptyTxMetrics());
@@ -141,12 +132,6 @@ export class TestExecutorMetrics {
             if (filter === 3 || filter === 1 || filter === 0) {
                 pretty += `${INDENT0}Total instructions executed: ${fmtNum(txMetrics.totalInstructionsExecuted)}\n`;
             }
-            if ((filter === 1 || filter === 0) && txMetrics.bytecodeSizes.length > 0) {
-                pretty += `${INDENT0}Bytecode sizes:\n`;
-                for (const { contractName, sizeBytes } of txMetrics.bytecodeSizes){
-                    pretty += `${INDENT1}${contractName}: ${fmtNum(sizeBytes, 'bytes')}\n`;
-                }
-            }
             if (filter === 2 || filter === 0) {
                 pretty += `${INDENT0}Private insertions:\n`;
                 pretty += `${INDENT1}Non-revertible: ${fmtNum(txMetrics.nonRevertiblePrivateInsertionsUs / 1_000, 'ms')}\n`;
@@ -313,13 +298,6 @@ export class TestExecutorMetrics {
                     });
                 }
             }
-            for (const { contractName, sizeBytes } of txMetrics.bytecodeSizes){
-                data.push({
-                    name: `${txLabel}/bytecodeSizeBytes/${contractName}`,
-                    value: sizeBytes,
-                    unit: 'bytes'
-                });
-            }
         }
         return JSON.stringify(data, null, indent);
     }

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@aztec/simulator",
-  "version": "6.0.0-nightly.20260605",
+  "version": "6.0.0-nightly.20260721",
   "type": "module",
   "exports": {
     "./server": "./dest/server.js",
     "./client": "./dest/client.js",
     "./testing": "./dest/testing.js",
-    "./public/fixtures": "./dest/public/fixtures/index.js",
-    "./public/avm/opcodes": "./dest/public/avm/opcodes/index.js"
+    "./public/fixtures": "./dest/public/fixtures/index.js"
   },
   "typedocOptions": {
     "entryPoints": [
@@ -20,8 +19,9 @@
     "build": "yarn clean && ../scripts/tsc.sh",
     "build:dev": "../scripts/tsc.sh --watch",
     "clean": "rm -rf ./dest .tsbuildinfo",
+    "generate": "node --experimental-strip-types --experimental-transform-types --no-warnings ../../ipc-codegen/src/generate.ts --schema ../../barretenberg/cpp/src/barretenberg/cdb/cdb_schema.json --lang ts --server --out src/public/cdb/generated",
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}",
-    "build:fuzzer": "yarn clean && ../scripts/tsc.sh"
+    "build:fuzzer": "yarn clean && yarn generate && ../scripts/tsc.sh"
   },
   "inherits": [
     "../package.common.json"
@@ -64,26 +64,29 @@
     ]
   },
   "dependencies": {
-    "@aztec/constants": "6.0.0-nightly.20260605",
-    "@aztec/foundation": "6.0.0-nightly.20260605",
-    "@aztec/native": "6.0.0-nightly.20260605",
-    "@aztec/noir-acvm_js": "6.0.0-nightly.20260605",
-    "@aztec/noir-noirc_abi": "6.0.0-nightly.20260605",
-    "@aztec/noir-protocol-circuits-types": "6.0.0-nightly.20260605",
-    "@aztec/noir-types": "6.0.0-nightly.20260605",
-    "@aztec/protocol-contracts": "6.0.0-nightly.20260605",
-    "@aztec/standard-contracts": "6.0.0-nightly.20260605",
-    "@aztec/stdlib": "6.0.0-nightly.20260605",
-    "@aztec/telemetry-client": "6.0.0-nightly.20260605",
-    "@aztec/world-state": "6.0.0-nightly.20260605",
+    "@aztec/bb-avm-sim": "6.0.0-nightly.20260721",
+    "@aztec/constants": "6.0.0-nightly.20260721",
+    "@aztec/foundation": "6.0.0-nightly.20260721",
+    "@aztec/ipc-runtime": "6.0.0-nightly.20260721",
+    "@aztec/native": "6.0.0-nightly.20260721",
+    "@aztec/noir-acvm_js": "6.0.0-nightly.20260721",
+    "@aztec/noir-noirc_abi": "6.0.0-nightly.20260721",
+    "@aztec/noir-protocol-circuits-types": "6.0.0-nightly.20260721",
+    "@aztec/noir-types": "6.0.0-nightly.20260721",
+    "@aztec/protocol-contracts": "6.0.0-nightly.20260721",
+    "@aztec/standard-contracts": "6.0.0-nightly.20260721",
+    "@aztec/stdlib": "6.0.0-nightly.20260721",
+    "@aztec/telemetry-client": "6.0.0-nightly.20260721",
+    "@aztec/world-state": "6.0.0-nightly.20260721",
     "lodash.clonedeep": "^4.5.0",
     "lodash.merge": "^4.6.2",
+    "msgpackr": "^1.11.2",
     "tslib": "^2.4.0"
   },
   "devDependencies": {
-    "@aztec/kv-store": "6.0.0-nightly.20260605",
-    "@aztec/noir-contracts.js": "6.0.0-nightly.20260605",
-    "@aztec/noir-test-contracts.js": "6.0.0-nightly.20260605",
+    "@aztec/kv-store": "6.0.0-nightly.20260721",
+    "@aztec/noir-contracts.js": "6.0.0-nightly.20260721",
+    "@aztec/noir-test-contracts.js": "6.0.0-nightly.20260721",
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/lodash.clonedeep": "^4.5.7",

package/src/client.ts

@@ -1,6 +1,4 @@
 export * from './private/acvm/index.js';
 export { WASMSimulator } from './private/acvm_wasm.js';
-export { SimulatorRecorderWrapper } from './private/circuit_recording/simulator_recorder_wrapper.js';
-export { MemoryCircuitRecorder } from './private/circuit_recording/memory_circuit_recorder.js';
 export { type CircuitSimulator, type DecodedError } from './private/circuit_simulator.js';
 export * from './common/index.js';

package/src/private/circuit_recording/circuit_recorder.ts

@@ -3,6 +3,8 @@ import { type Logger, type LoggerBindings, resolveLogger } from '@aztec/foundati
 import { Timer } from '@aztec/foundation/timer';
 import type { ForeignCallHandler, ForeignCallInput, ForeignCallOutput } from '@aztec/noir-acvm_js';
 
+import { AsyncLocalStorage } from 'node:async_hooks';
+
 import type { ACIRCallback } from '../acvm/acvm.js';
 import type { ACVMWitness } from '../acvm/acvm_types.js';
 
@@ -43,10 +45,23 @@ export class CircuitRecording {
   }
 }
 
+/** 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
  * {
@@ -91,37 +106,44 @@ export class CircuitRecording {
 export class CircuitRecorder {
   protected readonly logger: Logger;
 
-  protected recording?: CircuitRecording;
-
-  private stackDepth: number = 0;
-  private newCircuit: boolean = true;
+  readonly #recordings = new AsyncLocalStorage<CircuitRecording>();
 
   protected constructor(loggerOrBindings?: Logger | LoggerBindings) {
     this.logger = resolveLogger('simulator:acvm:recording', loggerOrBindings);
   }
 
   /**
-   * Initializes a new circuit recording session.
-   * @param recordDir - Directory to store the recording
-   * @param input - Circuit input witness
-   * @param circuitBytecode - Compiled circuit bytecode
-   * @param circuitName - Name of the circuit
-   * @param functionName - Name of the circuit function (defaults to 'main'). This is meaningful only for
-   * contracts as protocol circuits artifacts always contain a single entrypoint function called 'main'.
+   * 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.
    */
-  start(input: ACVMWitness, circuitBytecode: Buffer, circuitName: string, functionName: string): Promise<void> {
-    if (this.newCircuit) {
-      const parentRef = this.recording;
-      this.recording = new CircuitRecording(
-        circuitName,
-        functionName,
-        sha512(circuitBytecode).toString('hex'),
-        Object.fromEntries(input),
-      );
-      this.recording.setParent(parentRef);
-    }
+  record<T>(metadata: RecordingMetadata, fn: () => Promise<T>): Promise<{ result: T; recording: CircuitRecording }> {
+    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 Promise.resolve();
+    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;
+      }
+    });
   }
 
   /**
@@ -147,7 +169,9 @@ export class CircuitRecorder {
   }
 
   /**
-   * Wraps a user circuit callback to record all oracle calls.
+   * 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.
    */
@@ -161,38 +185,16 @@ export class CircuitRecorder {
         throw new Error(`Oracle method ${name} not found when setting up recording callback`);
       }
 
-      const isExternalCall = (name as keyof ACIRCallback) === 'aztec_prv_callPrivateFunction';
-
       recordingCallback[name as keyof ACIRCallback] = (...args: ForeignCallInput[]): ReturnType<typeof fn> => {
         const timer = new Timer();
-        // If we're entering another circuit via `aztec_prv_callPrivateFunction`, we increase the stack depth and set the
-        // newCircuit variable to ensure we are creating a new recording object.
-        if (isExternalCall) {
-          this.stackDepth++;
-          this.newCircuit = true;
-        }
         const result = fn.call(callback, ...args);
         if (result instanceof Promise) {
           return result.then(async r => {
-            // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-            // so that the parent circuit continues with its existing recording
-            // Note: recording restoration is handled by finish()
-            if (isExternalCall) {
-              this.stackDepth--;
-              this.newCircuit = false;
-            }
-            await this.recordCall(name, args, r, timer.ms(), this.stackDepth);
+            await this.recordCall(name, args, r, timer.ms());
             return r;
           }) as ReturnType<typeof fn>;
         }
-        // Once we leave the nested circuit, we decrease the stack depth and set newCircuit to false
-        // so that the parent circuit continues with its existing recording
-        // Note: recording restoration is handled by finish()
-        if (isExternalCall) {
-          this.stackDepth--;
-          this.newCircuit = false;
-        }
-        void this.recordCall(name, args, result, timer.ms(), this.stackDepth);
+        void this.recordCall(name, args, result, timer.ms());
         return result;
       };
     }
@@ -209,55 +211,59 @@ export class CircuitRecorder {
     return async (name: string, inputs: ForeignCallInput[]): Promise<ForeignCallOutput[]> => {
       const timer = new Timer();
       const result = await callback(name, inputs);
-      await this.recordCall(name, inputs, result, timer.ms(), 0);
+      await this.recordCall(name, inputs, result, timer.ms());
       return result;
     };
   }
 
   /**
-   * Records a single oracle/foreign call with its inputs and outputs.
+   * 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, stackDepth: number): Promise<OracleCall> {
+  recordCall(name: string, inputs: unknown[], outputs: unknown, time: number): Promise<OracleCall> {
+    const recording = this.#recordings.getStore();
     const entry = {
       name,
       inputs,
       outputs,
       time,
-      stackDepth,
+      stackDepth: depthOf(recording),
     };
-    this.recording!.oracleCalls.push(entry);
+    // 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);
   }
 
-  /**
-   * Finalizes the recording by resetting the state and returning the recording object.
-   */
-  finish(): Promise<CircuitRecording> {
-    const result = this.recording;
-    // If this is the top-level circuit recording, we reset the state for the next simulator call
-    if (!result!.parent) {
-      this.newCircuit = true;
-      this.recording = undefined;
-    } else {
-      // For nested circuits (utility calls, nested contract calls), restore to parent recording
-      // Note: we don't set newCircuit=false here because:
-      // - For privateCallPrivateFunction, the callback wrapper will set it to false
-      // - For utility calls, we want newCircuit to remain true so the next circuit creates its own recording
-      this.recording = result!.parent;
-    }
-    return Promise.resolve(result!);
+  /** The recording active in the current async context, if any. */
+  protected currentRecording(): CircuitRecording | undefined {
+    return this.#recordings.getStore();
   }
 
-  /**
-   * Finalizes the recording by resetting the state and returning the recording object with an attached error.
-   * @param error - The error that occurred during circuit execution
-   */
-  async finishWithError(error: unknown): Promise<CircuitRecording> {
-    const result = await this.finish();
-    result.error = JSON.stringify(error);
-    return result;
+  /** Hook invoked when a recording opens, within the recording's context. Overridden to persist recordings. */
+  protected onStart(_recording: CircuitRecording): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** Hook invoked when a recording completes successfully, within the recording's context. */
+  protected onFinish(_recording: CircuitRecording): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /** Hook invoked when a recording's execution throws, within the recording's context. */
+  protected onError(_recording: CircuitRecording, _error: unknown): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+/** Depth of a recording in the call tree: 0 for a top-level circuit, incremented per nested circuit. */
+function depthOf(recording: CircuitRecording | undefined): number {
+  let depth = 0;
+  for (let ancestor = recording?.parent; ancestor; ancestor = ancestor.parent) {
+    depth++;
   }
+  return depth;
 }