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

package/src/public/fuzzing/avm_fuzzer_simulator.ts

@@ -33,7 +33,8 @@ import {
 } from '@aztec/stdlib/tx';
 import type { NativeWorldStateService } from '@aztec/world-state';
 
-import { BaseAvmSimulationTester } from '../avm/fixtures/base_avm_simulation_tester.js';
+import { BaseAvmSimulationTester } from '../avm/testing/base_avm_simulation_tester.js';
+import { AvmSimulatorPool } from '../avm_simulator_pool.js';
 import { SimpleContractDataSource } from '../fixtures/simple_contract_data_source.js';
 import { PublicContractsDB } from '../public_db_sources.js';
 import { PublicTxSimulator } from '../public_tx_simulator/public_tx_simulator.js';
@@ -75,7 +76,7 @@ export class FuzzerSimulationRequest {
 
 /**
  * Creates a TypeScript Tx object from a deserialized C++ Tx (AvmTxHint-like structure).
- * This allows using PublicTxSimulator.simulate() with fuzzer-generated transactions.
+ * This allows simulating fuzzer-generated transactions with the C++ public tx simulator.
  */
 async function createTxFromHint(cppTx: AvmTxHint): Promise<Tx> {
   // Create TxHash from the C++ tx hash string
@@ -189,6 +190,8 @@ async function createTxFromHint(cppTx: AvmTxHint): Promise<Tx> {
 /**
  * A simulator class for the AVM fuzzer that extends BaseAvmSimulationTester.
  * It provides methods for registering contracts from C++ msgpack data and simulating transactions.
+ * The simulation itself runs on the production C++ AVM simulator, so the fuzzer compares brillig
+ * execution against the real AVM rather than a TS reference.
  */
 export class AvmFuzzerSimulator extends BaseAvmSimulationTester {
   private simulator: PublicTxSimulator;
@@ -197,22 +200,27 @@ export class AvmFuzzerSimulator extends BaseAvmSimulationTester {
     merkleTrees: MerkleTreeWriteOperations,
     contractDataSource: SimpleContractDataSource,
     globals: GlobalVariables,
-    protocolContracts: ProtocolContracts,
+    private avmSimulator: AvmSimulatorPool,
+    contractsDB: PublicContractsDB,
+    forkId: number,
   ) {
     super(contractDataSource, merkleTrees);
-    const contractsDb = new PublicContractsDB(contractDataSource);
+    // collectPublicInputs and collectCallMetadata are required so the C++ result carries the end
+    // tree snapshots and app-logic return values that the fuzzer bin reports back to the harness.
     this.simulator = new PublicTxSimulator(
-      merkleTrees,
-      contractsDb,
+      avmSimulator,
       globals,
+      contractsDB,
+      forkId,
       {
         skipFeeEnforcement: false,
         collectDebugLogs: false,
         collectHints: false,
+        collectPublicInputs: true,
         collectStatistics: false,
-        collectCallMetadata: false,
+        collectCallMetadata: true,
       },
-      protocolContracts,
+      undefined,
     );
   }
 
@@ -222,11 +230,18 @@ export class AvmFuzzerSimulator extends BaseAvmSimulationTester {
   public static async create(
     worldStateService: NativeWorldStateService,
     globals: GlobalVariables,
-    protocolContracts: ProtocolContracts,
   ): Promise<AvmFuzzerSimulator> {
     const contractDataSource = new SimpleContractDataSource();
     const merkleTrees = await worldStateService.fork();
-    return new AvmFuzzerSimulator(merkleTrees, contractDataSource, globals, protocolContracts);
+    const forkId = merkleTrees.getRevision().forkId;
+    const avmSimulator = await AvmSimulatorPool.spawn({ wsdbIpcPath: worldStateService.getIpcPath() });
+    const contractsDB = new PublicContractsDB(contractDataSource);
+    return new AvmFuzzerSimulator(merkleTrees, contractDataSource, globals, avmSimulator, contractsDB, forkId);
+  }
+
+  /** Tear down the AVM simulator pool (AVM processes and CDB server). */
+  public async close(): Promise<void> {
+    await this.avmSimulator[Symbol.asyncDispose]();
   }
 
   /**

package/src/public/fuzzing/avm_simulator_bin.ts

@@ -7,7 +7,7 @@ import {
   deserializeFromMessagePack,
   serializeWithMessagePack,
 } from '@aztec/stdlib/avm';
-import { GlobalVariables, ProtocolContracts, TreeSnapshots } from '@aztec/stdlib/tx';
+import { GlobalVariables, TreeSnapshots } from '@aztec/stdlib/tx';
 import { NativeWorldStateService } from '@aztec/world-state';
 
 import { createInterface } from 'readline';
@@ -58,7 +58,6 @@ async function simulateWithFuzzer(
   rawContractInstances: [any, any][], // Replace these when we are moving contract instances to TS
   rawPublicDataWrites: any[], // Public data tree writes to apply before simulation
   rawNoteHashes: any[], // Note hashes to apply before simulation
-  protocolContracts: ProtocolContracts, // Protocol contracts mapping from C++
 ): Promise<{
   reverted: boolean;
   output: Fr[];
@@ -68,7 +67,7 @@ async function simulateWithFuzzer(
 }> {
   const worldStateService = await openExistingWorldState(dataDir, mapSizeKb);
 
-  const simulator = await AvmFuzzerSimulator.create(worldStateService, globals, protocolContracts);
+  const simulator = await AvmFuzzerSimulator.create(worldStateService, globals);
 
   await simulator.applyNoteHashes(rawNoteHashes);
 
@@ -108,7 +107,7 @@ async function execute(base64Line: string): Promise<void> {
     const rawRequest = deserializeFromMessagePack(buffer);
     const request = FuzzerSimulationRequest.fromPlainObject(rawRequest);
 
-    // Run the TS simulation
+    // Run the simulation on the C++ AVM simulator
     const result = await simulateWithFuzzer(
       request.wsDataDir,
       request.wsMapSizeKb,
@@ -118,7 +117,6 @@ async function execute(base64Line: string): Promise<void> {
       request.contractInstances,
       request.publicDataWrites,
       request.noteHashes,
-      request.protocolContracts,
     );
 
     // Serialize the result to msgpack and encode it in base64 for output

package/src/public/index.ts

@@ -1,12 +1,16 @@
+export { AvmSimulatorPool, type AvmSimulatorPoolOptions } from './avm_simulator_pool.js';
+export type { PublicContractsDBInterface } from './db_interfaces.js';
 export { PublicContractsDB } from './public_db_sources.js';
 export { GuardedMerkleTreeOperations } from './public_processor/guarded_merkle_tree.js';
 export { PublicProcessor, PublicProcessorFactory } from './public_processor/public_processor.js';
+export type { AvmContractsDBContext, AvmSimulator } from './avm_simulator.js';
 export {
-  CppPublicTxSimulator,
+  PublicTxSimulator,
+  MeasuredPublicTxSimulator,
   createPublicTxSimulatorForBlockBuilding,
-  DumpingCppPublicTxSimulator,
+  DumpingPublicTxSimulator,
   type PublicTxSimulatorInterface,
-  TelemetryCppPublicTxSimulator,
+  TelemetryPublicTxSimulator,
 } from './public_tx_simulator/index.js';
 export type { PublicTxResult, PublicSimulatorConfig as PublicTxSimulatorConfig } from '@aztec/stdlib/avm';
 export { getCallRequestsWithCalldataByPhase } from './utils.js';

package/src/public/public_db_sources.ts

@@ -55,7 +55,7 @@ export class PublicContractsDB implements PublicContractsDBInterface {
     this.log = createLogger('simulator:contracts-data-source', bindings);
   }
 
-  /** Parses raw log data from the C++/NAPI bridge and inserts the resulting contracts into the current checkpoint. */
+  /** Parses raw contract deployment data and inserts the resulting contracts into the current checkpoint. */
   public addContractsFromLogs(contractDeploymentData: ContractDeploymentData): void {
     const currentState = this.getCurrentState();
 

package/src/public/public_processor/guarded_merkle_tree.ts

@@ -12,7 +12,7 @@ import type {
   TreeInfo,
 } from '@aztec/stdlib/trees';
 import type { BlockHeader, StateReference } from '@aztec/stdlib/tx';
-import type { WorldStateRevision, WorldStateRevisionWithHandle } from '@aztec/stdlib/world-state';
+import type { WorldStateRevision } from '@aztec/stdlib/world-state';
 
 /**
  * Wraps an instance of `MerkleTreeWriteOperations` to allow the sequencer to gate access.
@@ -94,9 +94,12 @@ export class GuardedMerkleTreeOperations implements MerkleTreeWriteOperations {
   getInitialHeader(): BlockHeader {
     return this.target.getInitialHeader();
   }
-  public getRevision(): WorldStateRevision | WorldStateRevisionWithHandle {
+  public getRevision(): WorldStateRevision {
     return this.target.getRevision();
   }
+  public getIpcPath(): string {
+    return this.target.getIpcPath();
+  }
   getSiblingPath<ID extends MerkleTreeId>(treeId: ID, index: bigint): Promise<SiblingPath<TreeHeights[ID]>> {
     return this.guardAndPush(() => this.target.getSiblingPath(treeId, index));
   }

package/src/public/public_processor/public_processor.ts

@@ -50,11 +50,12 @@ import { ForkCheckpoint } from '@aztec/world-state/native';
 
 import { AssertionError } from 'assert';
 
+import type { AvmSimulator } from '../avm_simulator.js';
 import { PublicContractsDB, PublicTreesDB } from '../public_db_sources.js';
 import {
   type PublicTxSimulatorConfig,
   type PublicTxSimulatorInterface,
-  TelemetryCppPublicTxSimulator,
+  TelemetryPublicTxSimulator,
 } from '../public_tx_simulator/index.js';
 import { GuardedMerkleTreeOperations } from './guarded_merkle_tree.js';
 import { PublicProcessorMetrics } from './public_processor_metrics.js';
@@ -66,6 +67,7 @@ export class PublicProcessorFactory {
   private log: Logger;
   constructor(
     private contractDataSource: ContractDataSource,
+    private avmSimulator: AvmSimulator,
     private dateProvider: DateProvider = new DateProvider(),
     protected telemetryClient: TelemetryClient = getTelemetryClient(),
     bindings?: LoggerBindings,
@@ -74,7 +76,9 @@ export class PublicProcessorFactory {
   }
 
   /**
-   * Creates a new instance of a PublicProcessor.
+   * Creates a new instance of a PublicProcessor. The simulator it drives reads contract data from the fork's
+   * contracts DB, scoped by the fork id so AVM requests route to the right state.
+   *
    * @param globalVariables - The global variables for the block being processed.
    * @param contractsDB - Optional pre-populated contracts DB; a fresh one is constructed if omitted.
    * @returns A new instance of a PublicProcessor.
@@ -85,8 +89,10 @@ export class PublicProcessorFactory {
     config: PublicSimulatorConfig,
     contractsDB: PublicContractsDB = new PublicContractsDB(this.contractDataSource, this.log.getBindings()),
   ): PublicProcessor {
+    const forkId = merkleTree.getRevision().forkId;
+
     const guardedFork = new GuardedMerkleTreeOperations(merkleTree);
-    const publicTxSimulator = this.createPublicTxSimulator(guardedFork, contractsDB, globalVariables, config);
+    const publicTxSimulator = this.createPublicTxSimulator(forkId, globalVariables, contractsDB, config);
 
     return new PublicProcessor(
       globalVariables,
@@ -100,15 +106,16 @@ export class PublicProcessorFactory {
   }
 
   protected createPublicTxSimulator(
-    merkleTree: MerkleTreeWriteOperations,
-    contractsDB: PublicContractsDB,
+    forkId: number,
     globalVariables: GlobalVariables,
+    contractsDB: PublicContractsDB,
     config?: Partial<PublicTxSimulatorConfig>,
   ): PublicTxSimulatorInterface {
-    return new TelemetryCppPublicTxSimulator(
-      merkleTree,
-      contractsDB,
+    return new TelemetryPublicTxSimulator(
+      this.avmSimulator,
       globalVariables,
+      contractsDB,
+      forkId,
       this.telemetryClient,
       config,
       this.log.getBindings(),
@@ -130,10 +137,6 @@ class PublicProcessorAbortError extends Error {
   }
 }
 
-function isPublicProcessorInterruptError(err: any) {
-  return err?.name === 'PublicProcessorTimeoutError' || err?.name === 'PublicProcessorAbortError';
-}
-
 /**
  * Converts Txs lifted from the P2P module into ProcessedTx objects by executing
  * any public function calls in them. Txs with private calls only are unaffected.
@@ -326,11 +329,15 @@ export class PublicProcessor implements Traceable {
         // Commit the tx-level contracts checkpoint on success
         this.contractsDB.commitCheckpoint();
       } catch (err: any) {
-        if (isPublicProcessorInterruptError(err)) {
-          const interruptReason = err.name === 'PublicProcessorTimeoutError' ? 'timeout' : 'abort signal';
-          this.log.warn(`Stopping tx processing due to ${interruptReason}.`);
-          // The tx may still be executing on a worker thread (C++ via NAPI).
-          // Signal cancellation AND WAIT for the simulation to actually stop before touching fork checkpoints.
+        if (err?.name === 'PublicProcessorTimeoutError' || err?.name === 'PublicProcessorAbortError') {
+          this.log.warn(
+            `Stopping tx processing due to ${err.name === 'PublicProcessorTimeoutError' ? 'timeout' : 'abort'}.`,
+          );
+          // We hit the transaction execution deadline or an external abort signal.
+          // There may still be a simulation in progress.
+          // Signal cancellation AND WAIT for the simulation to actually stop. Cancellation is
+          // cooperative: the simulator may be mid slow-operation and won't observe the flag until it
+          // completes, and without waiting we'd revert checkpoints while it's still writing to state.
           await this.publicTxSimulator.cancel?.();
 
           // Now stop the guarded fork to prevent any further TS-side access to the world state.

package/src/public/public_tx_simulator/{dumping_cpp_public_tx_simulator.ts → dumping_public_tx_simulator.ts}

@@ -4,35 +4,36 @@ import {
   AvmCircuitPublicInputs,
   AvmExecutionHints,
   type PublicSimulatorConfig,
-  PublicTxResult,
+  type PublicTxResult,
   serializeWithMessagePack,
 } from '@aztec/stdlib/avm';
-import type { MerkleTreeWriteOperations } from '@aztec/stdlib/trees';
-import type { GlobalVariables, Tx, TxHash } from '@aztec/stdlib/tx';
+import type { GlobalVariables, Tx } from '@aztec/stdlib/tx';
 
 import { strict as assert } from 'assert';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
+import type { AvmSimulator } from '../avm_simulator.js';
 import type { PublicContractsDB } from '../public_db_sources.js';
-import { CppPublicTxSimulator } from './cpp_public_tx_simulator.js';
+import { PublicTxSimulator } from './public_tx_simulator.js';
 
 /**
- * A C++ public tx simulator that dumps AVM circuit inputs to disk after simulation.
- * Used during nightly CI runs to collect circuit inputs for benchmarking.
+ * A {@link PublicTxSimulator} that dumps AVM circuit inputs to disk after simulation.
+ * Used during nightly CI runs to collect circuit inputs for AVM proving benchmarks.
  */
-export class DumpingCppPublicTxSimulator extends CppPublicTxSimulator {
+export class DumpingPublicTxSimulator extends PublicTxSimulator {
   private readonly outputDir: string;
 
   constructor(
-    merkleTree: MerkleTreeWriteOperations,
-    contractsDB: PublicContractsDB,
+    avmSimulator: AvmSimulator,
     globalVariables: GlobalVariables,
+    contractsDB: PublicContractsDB,
+    forkId: number,
     config: Partial<PublicSimulatorConfig>,
     outputDir: string,
     bindings?: LoggerBindings,
   ) {
-    super(merkleTree, contractsDB, globalVariables, config, bindings);
+    super(avmSimulator, globalVariables, contractsDB, forkId, config, bindings);
     assert(config.collectHints === true, 'collectHints must be enabled to dump AVM circuit inputs');
     assert(config.collectPublicInputs === true, 'collectPublicInputs must be enabled to dump AVM circuit inputs');
     this.outputDir = outputDir;
@@ -40,44 +41,27 @@ export class DumpingCppPublicTxSimulator extends CppPublicTxSimulator {
 
   public override async simulate(tx: Tx): Promise<PublicTxResult> {
     const result = await super.simulate(tx);
-
-    // Dump the circuit inputs after successful simulation
-    const txHash = this.computeTxHash(tx);
-    this.dumpAvmCircuitInputs(result, txHash);
-
+    this.dumpAvmCircuitInputs(result, tx.getTxHash().toString());
     return result;
   }
 
-  /**
-   * Dumps AVM circuit inputs to disk.
-   *
-   * @param result - The simulation result containing hints and public inputs
-   * @param txHash - The transaction hash to use in the filename
-   */
-  private dumpAvmCircuitInputs(result: PublicTxResult, txHash: TxHash): void {
+  private dumpAvmCircuitInputs(result: PublicTxResult, txHash: string): void {
     try {
-      // Ensure the output directory exists
       mkdirSync(this.outputDir, { recursive: true });
 
-      // Generate filename using transaction hash
-      const filename = `avm-circuit-inputs-tx-${txHash.toString()}.bin`;
+      const filename = `avm-circuit-inputs-tx-${txHash}.bin`;
       const filepath = join(this.outputDir, filename);
 
-      // Create circuit inputs from the result
       const hints = result.hints ?? AvmExecutionHints.empty();
       const publicInputs = result.publicInputs ?? AvmCircuitPublicInputs.empty();
       const avmCircuitInputs = new AvmCircuitInputs(hints, publicInputs);
 
-      // Serialize the circuit inputs using MessagePack
       const serialized = serializeWithMessagePack(avmCircuitInputs);
-
-      // Write to disk
       writeFileSync(filepath, serialized);
 
       this.log.debug(`Dumped AVM circuit inputs to ${filepath}`);
     } catch (error) {
-      // Non-blocking error handling - log but don't interrupt processing
-      this.log.warn(`Failed to dump AVM circuit inputs for tx ${txHash.toString()}: ${error}`);
+      this.log.warn(`Failed to dump AVM circuit inputs for tx ${txHash}: ${error}`);
     }
   }
 }

package/src/public/public_tx_simulator/factories.ts

@@ -1,22 +1,23 @@
 import type { LoggerBindings } from '@aztec/foundation/log';
 import { PublicSimulatorConfig } from '@aztec/stdlib/avm';
-import type { MerkleTreeWriteOperations } from '@aztec/stdlib/trees';
 import type { GlobalVariables } from '@aztec/stdlib/tx';
 import type { TelemetryClient } from '@aztec/telemetry-client';
 
+import type { AvmSimulator } from '../avm_simulator.js';
 import type { PublicContractsDB } from '../public_db_sources.js';
-import { TelemetryCppPublicTxSimulator } from './cpp_public_tx_simulator.js';
-import { DumpingCppPublicTxSimulator } from './dumping_cpp_public_tx_simulator.js';
+import { DumpingPublicTxSimulator } from './dumping_public_tx_simulator.js';
+import { TelemetryPublicTxSimulator } from './public_tx_simulator.js';
 
 /**
- * Creates a public tx simulator for block building.
- * Uses DumpingCppPublicTxSimulator if DUMP_AVM_INPUTS_TO_DIR env var is set (for CI/testing avm circuit),
- * otherwise uses TelemetryCppPublicTxSimulator (for production).
+ * Creates an IPC-based public tx simulator for block building.
+ * Uses DumpingPublicTxSimulator if DUMP_AVM_INPUTS_TO_DIR env var is set (for CI/testing the AVM circuit),
+ * otherwise uses TelemetryPublicTxSimulator (for production).
  */
 export function createPublicTxSimulatorForBlockBuilding(
-  merkleTree: MerkleTreeWriteOperations,
-  contractsDB: PublicContractsDB,
+  avmSimulator: AvmSimulator,
   globalVariables: GlobalVariables,
+  contractsDB: PublicContractsDB,
+  forkId: number,
   telemetryClient: TelemetryClient,
   bindings?: LoggerBindings,
   collectDebugLogs = false,
@@ -38,7 +39,23 @@ export function createPublicTxSimulatorForBlockBuilding(
       collectHints: true,
       collectPublicInputs: true,
     };
-    return new DumpingCppPublicTxSimulator(merkleTree, contractsDB, globalVariables, dumpingConfig, dumpDir, bindings);
+    return new DumpingPublicTxSimulator(
+      avmSimulator,
+      globalVariables,
+      contractsDB,
+      forkId,
+      dumpingConfig,
+      dumpDir,
+      bindings,
+    );
   }
-  return new TelemetryCppPublicTxSimulator(merkleTree, contractsDB, globalVariables, telemetryClient, config, bindings);
+  return new TelemetryPublicTxSimulator(
+    avmSimulator,
+    globalVariables,
+    contractsDB,
+    forkId,
+    telemetryClient,
+    config,
+    bindings,
+  );
 }

package/src/public/public_tx_simulator/index.ts

@@ -1,7 +1,8 @@
-export * from './public_tx_simulator.js';
-export { CppPublicTxSimulator, TelemetryCppPublicTxSimulator } from './cpp_public_tx_simulator.js';
-export { DumpingCppPublicTxSimulator } from './dumping_cpp_public_tx_simulator.js';
+export { PublicTxSimulator, MeasuredPublicTxSimulator, TelemetryPublicTxSimulator } from './public_tx_simulator.js';
+export { DumpingPublicTxSimulator } from './dumping_public_tx_simulator.js';
 export { createPublicTxSimulatorForBlockBuilding } from './factories.js';
-export type { PublicTxSimulatorInterface } from './public_tx_simulator_interface.js';
-export { TelemetryPublicTxSimulator } from './telemetry_public_tx_simulator.js';
+export type {
+  PublicTxSimulatorInterface,
+  MeasuredPublicTxSimulatorInterface,
+} from './public_tx_simulator_interface.js';
 export type { PublicTxResult, PublicSimulatorConfig as PublicTxSimulatorConfig } from '@aztec/stdlib/avm';