@aztec/simulator 0.0.1-commit.9593d84 → 0.0.1-commit.96bb3f7

package/src/public/fixtures/public_tx_simulation_tester.ts

@@ -1,6 +1,7 @@
 import { DEFAULT_TEARDOWN_DA_GAS_LIMIT, DEFAULT_TEARDOWN_L2_GAS_LIMIT } from '@aztec/constants';
 import { asyncMap } from '@aztec/foundation/async-map';
-import { Fr } from '@aztec/foundation/fields';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type ContractArtifact, encodeArguments } from '@aztec/stdlib/abi';
 import { PublicSimulatorConfig, type PublicTxResult } from '@aztec/stdlib/avm';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -19,7 +20,7 @@ import {
 } from '../avm/fixtures/utils.js';
 import { PublicContractsDB } from '../public_db_sources.js';
 import { MeasuredCppPublicTxSimulator } from '../public_tx_simulator/cpp_public_tx_simulator.js';
-import { MeasuredPublicTxSimulator } from '../public_tx_simulator/measured_public_tx_simulator.js';
+import { MeasuredCppVsTsPublicTxSimulator } from '../public_tx_simulator/cpp_vs_ts_public_tx_simulator.js';
 import type { MeasuredPublicTxSimulatorInterface } from '../public_tx_simulator/public_tx_simulator_interface.js';
 import { TestExecutorMetrics } from '../test_executor_metrics.js';
 import { SimpleContractDataSource } from './simple_contract_data_source.js';
@@ -30,7 +31,7 @@ const DEFAULT_GAS_FEES = new GasFees(2, 3);
 export type TestEnqueuedCall = {
   sender?: AztecAddress;
   address: AztecAddress;
-  fnName: string;
+  fnName?: string;
   args: any[];
   isStaticCall?: boolean;
   contractArtifact?: ContractArtifact;
@@ -41,9 +42,21 @@ const defaultConfig: PublicSimulatorConfig = PublicSimulatorConfig.from({
   collectCallMetadata: true,
   collectDebugLogs: true,
   collectHints: false,
+  collectPublicInputs: false,
   collectStatistics: false,
 });
 
+/**
+ * Factory type for creating a MeasuredPublicTxSimulatorInterface.
+ */
+export type MeasuredSimulatorFactory = (
+  merkleTree: MerkleTreeWriteOperations,
+  contractsDB: PublicContractsDB,
+  globals: GlobalVariables,
+  metrics: TestExecutorMetrics,
+  config: PublicSimulatorConfig,
+) => MeasuredPublicTxSimulatorInterface;
+
 /**
  * A test class that extends the BaseAvmSimulationTester to enable real-app testing of the PublicTxSimulator.
  * It provides an interface for simulating one transaction at a time and maintains state between subsequent
@@ -59,15 +72,17 @@ export class PublicTxSimulationTester extends BaseAvmSimulationTester {
     contractDataSource: SimpleContractDataSource,
     globals: GlobalVariables = defaultGlobals(),
     private metrics: TestExecutorMetrics = new TestExecutorMetrics(),
-    useCppSimulator: boolean = false,
+    simulatorFactory?: MeasuredSimulatorFactory,
     config: PublicSimulatorConfig = defaultConfig,
   ) {
     super(contractDataSource, merkleTree);
 
     const contractsDB = new PublicContractsDB(contractDataSource);
-    this.simulator = useCppSimulator
-      ? new MeasuredCppPublicTxSimulator(merkleTree, contractsDB, globals, this.metrics, config)
-      : new MeasuredPublicTxSimulator(merkleTree, contractsDB, globals, this.metrics, config);
+    if (simulatorFactory) {
+      this.simulator = simulatorFactory(merkleTree, contractsDB, globals, this.metrics, config);
+    } else {
+      this.simulator = new MeasuredCppPublicTxSimulator(merkleTree, contractsDB, globals, this.metrics, config);
+    }
   }
 
   public static async create(
@@ -79,7 +94,10 @@ export class PublicTxSimulationTester extends BaseAvmSimulationTester {
   ): Promise<PublicTxSimulationTester> {
     const contractDataSource = new SimpleContractDataSource();
     const merkleTree = await worldStateService.fork();
-    return new PublicTxSimulationTester(merkleTree, contractDataSource, globals, metrics, useCppSimulator, config);
+    const simulatorFactory: MeasuredSimulatorFactory = useCppSimulator
+      ? (mt, cdb, g, m, c) => new MeasuredCppPublicTxSimulator(mt, cdb, g, m, c)
+      : (mt, cdb, g, m, c) => new MeasuredCppVsTsPublicTxSimulator(mt, cdb, g, m, c);
+    return new PublicTxSimulationTester(merkleTree, contractDataSource, globals, metrics, simulatorFactory, config);
   }
 
   public setMetricsPrefix(prefix: string) {
@@ -136,6 +154,11 @@ export class PublicTxSimulationTester extends BaseAvmSimulationTester {
     const txLabelWithCount = `${txLabel}/${this.txCount - 1}`;
     const fullTxLabel = this.metricsPrefix ? `${this.metricsPrefix}/${txLabelWithCount}` : txLabelWithCount;
 
+    if (!this.simulator) {
+      throw new Error(
+        'No simulator configured. Pass a simulatorFactory to the constructor or use PublicTxSimulationTester.create()',
+      );
+    }
     const avmResult = await this.simulator.simulate(tx, fullTxLabel);
 
     // Something like this is often useful for debugging:
@@ -202,6 +225,25 @@ export class PublicTxSimulationTester extends BaseAvmSimulationTester {
     this.metrics.prettyPrint();
   }
 
+  /**
+   * Cancel the current simulation if one is in progress.
+   * This signals the underlying simulator (e.g., C++) to stop at the next safe point.
+   * Safe to call even if no simulation is in progress.
+   *
+   * @param waitTimeoutMs - If provided, wait up to this many ms for the simulation to actually stop.
+   */
+  public async cancel(waitTimeoutMs?: number): Promise<void> {
+    await this.simulator.cancel?.(waitTimeoutMs);
+  }
+
+  /**
+   * Get the underlying simulator for advanced test scenarios.
+   * Use this when you need direct control over simulation (e.g., for testing cancellation).
+   */
+  public getSimulator(): MeasuredPublicTxSimulatorInterface {
+    return this.simulator;
+  }
+
   async #createPubicCallRequestForCall(
     call: TestEnqueuedCall,
     sender: AztecAddress,
@@ -212,10 +254,24 @@ export class PublicTxSimulationTester extends BaseAvmSimulationTester {
       throw new Error(`Contract artifact not found for address: ${address}`);
     }
 
-    const fnSelector = await getFunctionSelector(call.fnName, contractArtifact);
-    const fnAbi = getContractFunctionAbi(call.fnName, contractArtifact)!;
-    const encodedArgs = encodeArguments(fnAbi, call.args);
-    const calldata = [fnSelector.toField(), ...encodedArgs];
+    let calldata: Fr[] = [];
+    if (!call.fnName) {
+      this.logger.debug(
+        `No function name specified for call to contract ${call.address.toString()}. Assuming this is a custom bytecode with no public_dispatch function.`,
+      );
+      this.logger.debug(`Not using ABI to encode arguments. Not prepending fn selector to calldata.`);
+      try {
+        calldata = call.args.map(arg => new Fr(arg));
+      } catch (error) {
+        this.logger.warn(`Tried assuming that all arguments are Field-like. Failed. Error: ${error}`);
+        throw error;
+      }
+    } else {
+      const fnSelector = await getFunctionSelector(call.fnName, contractArtifact);
+      const fnAbi = getContractFunctionAbi(call.fnName, contractArtifact)!;
+      const encodedArgs = encodeArguments(fnAbi, call.args);
+      calldata = [fnSelector.toField(), ...encodedArgs];
+    }
     const isStaticCall = call.isStaticCall ?? false;
     const request = await PublicCallRequest.fromCalldata(sender, address, isStaticCall, calldata);
 
@@ -227,6 +283,6 @@ export function defaultGlobals() {
   const globals = GlobalVariables.empty();
   globals.timestamp = DEFAULT_TIMESTAMP;
   globals.gasFees = DEFAULT_GAS_FEES; // apply some nonzero default gas fees
-  globals.blockNumber = DEFAULT_BLOCK_NUMBER;
+  globals.blockNumber = BlockNumber(DEFAULT_BLOCK_NUMBER);
   return globals;
 }

package/src/public/fixtures/simple_contract_data_source.ts

@@ -1,4 +1,5 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import type { ContractArtifact, FunctionSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -59,7 +60,7 @@ export class SimpleContractDataSource implements ContractDataSource {
 
   /////////////////////////////////////////////////////////////
   // ContractDataSource function implementations
-  getBlockNumber(): Promise<number> {
+  getBlockNumber(): Promise<BlockNumber> {
     throw new Error('Method not implemented.');
   }
 
@@ -90,19 +91,17 @@ export class SimpleContractDataSource implements ContractDataSource {
     return this.contractArtifacts.get(contractInstance!.currentContractClassId.toString());
   }
 
-  async getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string> {
+  async getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined> {
     const contractInstance = await this.getContract(address);
     if (!contractInstance) {
-      this.logger.warn(
-        `Couldn't get fn name for debugging. Contract not in tester's ContractDataSource. Using selector:${selector} instead...`,
-      );
-      return `selector:${selector.toString()}`;
+      this.logger.warn(`Couldn't get fn name for debugging. Contract not in tester's ContractDataSource.`);
+      return undefined;
     }
     const key = `${contractInstance.currentContractClassId.toString()}:${selector.toString()}`;
     const fnName = this.debugFunctionName.get(key);
     if (!fnName) {
-      this.logger.warn(`Couldn't get fn name for debugging. Using selector:${selector} instead...`);
-      return selector.toString();
+      this.logger.warn(`Couldn't get fn name for debugging...`);
+      return undefined;
     }
     return fnName;
   }

package/src/public/fixtures/token_test.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { Logger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
 import type { ContractArtifact } from '@aztec/stdlib/abi';
@@ -7,11 +7,17 @@ import type { ContractInstanceWithAddress } from '@aztec/stdlib/contract';
 
 import { PublicTxSimulationTester } from './public_tx_simulation_tester.js';
 
+export type TokenTestOptions = {
+  /** Skip return value assertions in balance checks (useful for benchmarking with collectCallMetadata=false) */
+  skipReturnValueAssertions?: boolean;
+};
+
 export async function tokenTest(
   tester: PublicTxSimulationTester,
   logger: Logger,
   tokenArtifact: ContractArtifact,
   expectToBeTrue: (x: boolean) => void,
+  options: TokenTestOptions = {},
 ) {
   const timer = new Timer();
 
@@ -36,7 +42,7 @@ export async function tokenTest(
     ],
   );
   expectToBeTrue(mintResult.revertCode.isOK());
-  await checkBalance(tester, token, sender, sender, mintAmount, expectToBeTrue);
+  await checkBalance(tester, token, sender, sender, mintAmount, expectToBeTrue, options);
 
   const authwitNonce = new Fr(0);
   const transferAmount = 50n;
@@ -54,8 +60,8 @@ export async function tokenTest(
     ],
   );
   expectToBeTrue(transferResult.revertCode.isOK());
-  await checkBalance(tester, token, sender, receiver, mintAmount - transferAmount, expectToBeTrue);
-  await checkBalance(tester, token, sender, receiver, transferAmount, expectToBeTrue);
+  await checkBalance(tester, token, sender, sender, mintAmount - transferAmount, expectToBeTrue, options);
+  await checkBalance(tester, token, sender, receiver, transferAmount, expectToBeTrue, options);
 
   // EXECUTE! This means that if using AvmProvingTester subclass, it will PROVE the transaction!
   const burnResult = await tester.executeTxWithLabel(
@@ -71,7 +77,7 @@ export async function tokenTest(
     ],
   );
   expectToBeTrue(burnResult.revertCode.isOK());
-  await checkBalance(tester, token, sender, receiver, 0n, expectToBeTrue);
+  await checkBalance(tester, token, sender, receiver, 0n, expectToBeTrue, options);
 
   logger.info(`TokenContract test took ${timer.ms()}ms\n`);
 }
@@ -116,6 +122,7 @@ async function checkBalance(
   account: AztecAddress,
   expectedBalance: bigint,
   expectToBeTrue: (x: boolean) => void,
+  options: TokenTestOptions = {},
 ) {
   // Strictly simulate this! No need to "execute" (aka prove if using AvmProvingTester subclass).
   const balResult = await tester.simulateTxWithLabel(
@@ -132,8 +139,10 @@ async function checkBalance(
     ],
   );
   expectToBeTrue(balResult.revertCode.isOK());
-  // should be 1 call with 1 return value that is expectedBalance
-  expectToBeTrue(balResult.appLogicReturnValues.length == 1);
-  expectToBeTrue(balResult.appLogicReturnValues[0].values!.length == 1);
-  expectToBeTrue(balResult.appLogicReturnValues[0].values![0].toBigInt() == expectedBalance);
+  if (!options.skipReturnValueAssertions) {
+    // should be 1 call with 1 return value that is expectedBalance
+    const appLogicReturnValues = balResult.getAppLogicReturnValues();
+    expectToBeTrue(appLogicReturnValues.length === 1);
+    expectToBeTrue(appLogicReturnValues[0].values?.[0]?.toBigInt() === expectedBalance);
+  }
 }

package/src/public/fixtures/utils.ts

@@ -9,7 +9,7 @@ import {
   PRIVATE_LOG_SIZE_IN_FIELDS,
 } from '@aztec/constants';
 import { padArrayEnd } from '@aztec/foundation/collection';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { CONTRACT_INSTANCE_PUBLISHED_EVENT_TAG } from '@aztec/protocol-contracts';
 import { bufferAsFields } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -132,8 +132,7 @@ export async function createTxForPublicCalls(
     : Gas.empty();
   const gasSettings = new GasSettings(gasLimits, teardownGasLimits, maxFeesPerGas, GasFees.empty());
   const txContext = new TxContext(Fr.zero(), Fr.zero(), gasSettings);
-  const header = BlockHeader.empty();
-  header.globalVariables = globals;
+  const header = BlockHeader.empty({ globalVariables: globals });
   const constantData = new TxConstantData(header, txContext, Fr.zero(), Fr.zero());
   const includeByTimestamp = 0n; // Not used in the simulator.
 

package/src/public/fuzzing/avm_fuzzer_simulator.ts

@@ -0,0 +1,240 @@
+import {
+  MAX_ENQUEUED_CALLS_PER_TX,
+  MAX_L2_TO_L1_MSGS_PER_TX,
+  MAX_NOTE_HASHES_PER_TX,
+  MAX_NULLIFIERS_PER_TX,
+  MAX_PRIVATE_LOGS_PER_TX,
+} from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { AvmTxHint, type PublicTxResult } from '@aztec/stdlib/avm';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { contractClassPublicFromPlainObject, contractInstanceWithAddressFromPlainObject } from '@aztec/stdlib/contract';
+import {
+  PartialPrivateTailPublicInputsForPublic,
+  PrivateKernelTailCircuitPublicInputs,
+  PrivateToPublicAccumulatedData,
+  PublicCallRequest,
+} from '@aztec/stdlib/kernel';
+import { PrivateLog } from '@aztec/stdlib/logs';
+import { ScopedL2ToL1Message } from '@aztec/stdlib/messaging';
+import { ChonkProof } from '@aztec/stdlib/proofs';
+import type { MerkleTreeWriteOperations } from '@aztec/stdlib/trees';
+import { BlockHeader, GlobalVariables, HashedValues, Tx, TxConstantData, TxContext, TxHash } from '@aztec/stdlib/tx';
+import type { NativeWorldStateService } from '@aztec/world-state';
+
+import { BaseAvmSimulationTester } from '../avm/fixtures/base_avm_simulation_tester.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';
+
+/**
+ * Request structure for fuzzer simulation communication from C++.
+ * Matches the C++ FuzzerSimulationRequest struct
+ */
+export class FuzzerSimulationRequest {
+  constructor(
+    public readonly wsDataDir: string,
+    public readonly wsMapSizeKb: number,
+    public readonly tx: AvmTxHint,
+    public readonly globals: GlobalVariables,
+    public readonly contractClasses: any[], // Raw, processed by addContractClassFromCpp
+    public readonly contractInstances: [any, any][], // Raw pairs [address, instance]
+  ) {}
+
+  static fromPlainObject(obj: any): FuzzerSimulationRequest {
+    if (obj instanceof FuzzerSimulationRequest) {
+      return obj;
+    }
+    return new FuzzerSimulationRequest(
+      obj.wsDataDir,
+      obj.wsMapSizeKb,
+      AvmTxHint.fromPlainObject(obj.tx),
+      GlobalVariables.fromPlainObject(obj.globals),
+      obj.contractClasses,
+      obj.contractInstances,
+    );
+  }
+}
+
+/**
+ * Creates a TypeScript Tx object from a deserialized C++ Tx (AvmTxHint-like structure).
+ * This allows using PublicTxSimulator.simulate() with fuzzer-generated transactions.
+ */
+async function createTxFromHint(cppTx: AvmTxHint): Promise<Tx> {
+  // Create TxHash from the C++ tx hash string
+  if (!cppTx.hash) {
+    throw new Error(`cppTx.hash is undefined. Keys: ${Object.keys(cppTx || {}).join(', ')}`);
+  }
+  const txHash = TxHash.fromString(cppTx.hash);
+
+  // Extract PublicCallRequest instances from enqueued calls
+  const setupCallRequests = cppTx.setupEnqueuedCalls.map(call => call.request);
+  const paddedSetupCalls = padArrayEnd(setupCallRequests, PublicCallRequest.empty(), MAX_ENQUEUED_CALLS_PER_TX);
+
+  const appLogicCallRequests = cppTx.appLogicEnqueuedCalls.map(call => call.request);
+  const paddedAppLogicCalls = padArrayEnd(appLogicCallRequests, PublicCallRequest.empty(), MAX_ENQUEUED_CALLS_PER_TX);
+
+  // Build non-revertible accumulated data from C++ tx
+  const emptyNonRevertible = PrivateToPublicAccumulatedData.empty();
+  const nonRevertibleAccumulatedData = new PrivateToPublicAccumulatedData(
+    padArrayEnd(cppTx.nonRevertibleAccumulatedData.noteHashes, Fr.ZERO, MAX_NOTE_HASHES_PER_TX),
+    padArrayEnd(cppTx.nonRevertibleAccumulatedData.nullifiers, Fr.ZERO, MAX_NULLIFIERS_PER_TX),
+    padArrayEnd(
+      cppTx.nonRevertibleAccumulatedData.l2ToL1Messages,
+      ScopedL2ToL1Message.empty(),
+      MAX_L2_TO_L1_MSGS_PER_TX,
+    ),
+    padArrayEnd(cppTx.nonRevertibleContractDeploymentData.privateLogs, PrivateLog.empty(), MAX_PRIVATE_LOGS_PER_TX),
+    emptyNonRevertible.contractClassLogsHashes,
+    paddedSetupCalls,
+  );
+
+  // Build revertible accumulated data from C++ tx
+  const emptyRevertible = PrivateToPublicAccumulatedData.empty();
+  const revertibleAccumulatedData = new PrivateToPublicAccumulatedData(
+    padArrayEnd(cppTx.revertibleAccumulatedData.noteHashes, Fr.ZERO, MAX_NOTE_HASHES_PER_TX),
+    padArrayEnd(cppTx.revertibleAccumulatedData.nullifiers, Fr.ZERO, MAX_NULLIFIERS_PER_TX),
+    padArrayEnd(cppTx.revertibleAccumulatedData.l2ToL1Messages, ScopedL2ToL1Message.empty(), MAX_L2_TO_L1_MSGS_PER_TX),
+    padArrayEnd(cppTx.revertibleContractDeploymentData.privateLogs, PrivateLog.empty(), MAX_PRIVATE_LOGS_PER_TX),
+    emptyRevertible.contractClassLogsHashes,
+    paddedAppLogicCalls,
+  );
+
+  // Build teardown call request (if exists)
+  const teardownCallRequest = cppTx.teardownEnqueuedCall?.request ?? PublicCallRequest.empty();
+
+  // Create forPublic structure
+  const forPublic = new PartialPrivateTailPublicInputsForPublic(
+    nonRevertibleAccumulatedData,
+    revertibleAccumulatedData,
+    teardownCallRequest,
+  );
+
+  // Build TxContext - gasSettings is already a proper GasSettings after AvmTxHint.fromPlainObject
+  const txContext = new TxContext(
+    Fr.ZERO, // chainId - this is fine because simulation actually reads from globalVariables not here
+    Fr.ZERO, // version - this is fine because simulation actually reads from globalVariables not here
+    cppTx.gasSettings,
+  );
+
+  // Build TxConstantData
+  const constants = new TxConstantData(
+    BlockHeader.empty(), // anchorBlockHeader (unused in simulation)
+    txContext,
+    Fr.ZERO, // vkTreeRoot - not needed for public simulation
+    Fr.ZERO, // protocolContractsHash - not needed for public simulation
+  );
+
+  const data = new PrivateKernelTailCircuitPublicInputs(
+    constants,
+    cppTx.gasUsedByPrivate,
+    cppTx.feePayer,
+    0n, // includeByTimestamp
+    forPublic,
+    undefined, // forRollup - not needed for public simulation
+  );
+
+  // Build publicFunctionCalldata from all enqueued calls
+  // Calldata is already Fr[] after AvmTxHint.fromPlainObject
+  const publicFunctionCalldata: HashedValues[] = [];
+
+  // Add setup calls
+  for (const call of cppTx.setupEnqueuedCalls || []) {
+    publicFunctionCalldata.push(await HashedValues.fromCalldata(call.calldata));
+  }
+
+  // Add app logic calls
+  for (const call of cppTx.appLogicEnqueuedCalls || []) {
+    publicFunctionCalldata.push(await HashedValues.fromCalldata(call.calldata));
+  }
+
+  // Add teardown call if present
+  if (cppTx.teardownEnqueuedCall) {
+    publicFunctionCalldata.push(await HashedValues.fromCalldata(cppTx.teardownEnqueuedCall.calldata));
+  }
+
+  // Extract contract class log fields from ContractDeploymentData
+  const contractClassLogFields = [
+    ...cppTx.nonRevertibleContractDeploymentData.contractClassLogs.map(log => log.fields),
+    ...cppTx.revertibleContractDeploymentData.contractClassLogs.map(log => log.fields),
+  ];
+
+  // Create the Tx
+  return new Tx(
+    txHash,
+    data,
+    ChonkProof.empty(), // No real proof needed for simulation
+    contractClassLogFields,
+    publicFunctionCalldata,
+  );
+}
+
+/**
+ * A simulator class for the AVM fuzzer that extends BaseAvmSimulationTester.
+ * It provides methods for registering contracts from C++ msgpack data and simulating transactions.
+ */
+export class AvmFuzzerSimulator extends BaseAvmSimulationTester {
+  private simulator: PublicTxSimulator;
+
+  constructor(
+    merkleTrees: MerkleTreeWriteOperations,
+    contractDataSource: SimpleContractDataSource,
+    globals: GlobalVariables,
+  ) {
+    super(contractDataSource, merkleTrees);
+    const contractsDb = new PublicContractsDB(contractDataSource);
+    this.simulator = new PublicTxSimulator(merkleTrees, contractsDb, globals, {
+      skipFeeEnforcement: false,
+      collectDebugLogs: false,
+      collectHints: false,
+      collectStatistics: false,
+      collectCallMetadata: false,
+    });
+  }
+
+  /**
+   * Static factory method to create an AvmFuzzerSimulator.
+   */
+  public static async create(
+    worldStateService: NativeWorldStateService,
+    globals: GlobalVariables,
+  ): Promise<AvmFuzzerSimulator> {
+    const contractDataSource = new SimpleContractDataSource();
+    const merkleTrees = await worldStateService.fork();
+    return new AvmFuzzerSimulator(merkleTrees, contractDataSource, globals);
+  }
+
+  /**
+   * Simulate a transaction from a C++ AvmTxHint.
+   */
+  public async simulate(txHint: AvmTxHint): Promise<PublicTxResult> {
+    // Compute fee from gas limits and max fees per gas (upper bound on fee)
+    const totalFee =
+      BigInt(txHint.gasSettings.gasLimits.daGas) * txHint.gasSettings.maxFeesPerGas.feePerDaGas +
+      BigInt(txHint.gasSettings.gasLimits.l2Gas) * txHint.gasSettings.maxFeesPerGas.feePerL2Gas;
+
+    await this.setFeePayerBalance(txHint.feePayer, new Fr(totalFee));
+
+    const tx = await createTxFromHint(txHint);
+    return await this.simulator.simulate(tx);
+  }
+
+  /**
+   * Add a contract class from C++ raw msgpack data.
+   */
+  public async addContractClassFromCpp(rawClass: any): Promise<void> {
+    const contractClass = contractClassPublicFromPlainObject(rawClass);
+    await this.contractDataSource.addContractClass(contractClass);
+  }
+
+  /**
+   * Add a contract instance from C++ raw msgpack data.
+   * This also inserts the contract address nullifier into the nullifier tree.
+   */
+  public async addContractInstanceFromCpp(rawAddress: any, rawInstance: any): Promise<void> {
+    const address = AztecAddress.fromPlainObject(rawAddress);
+    const instance = contractInstanceWithAddressFromPlainObject(address, rawInstance);
+    await this.addContractInstance(instance);
+  }
+}

package/src/public/fuzzing/avm_simulator_bin.ts

@@ -0,0 +1,153 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import {
+  AvmCircuitPublicInputs,
+  type AvmTxHint,
+  deserializeFromMessagePack,
+  serializeWithMessagePack,
+} from '@aztec/stdlib/avm';
+import { GlobalVariables, TreeSnapshots } from '@aztec/stdlib/tx';
+import { NativeWorldStateService } from '@aztec/world-state';
+
+import { createInterface } from 'readline';
+
+import { AvmFuzzerSimulator, FuzzerSimulationRequest } from './avm_fuzzer_simulator.js';
+
+/** Write data to stdout, letting Node handle buffering. */
+function writeOutput(data: string): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    process.stdout.write(data, err => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+// This cache holds opened world states to avoid reopening them for each invocation.
+// It's a map so that in the future we could support multiple world states (if we had multiple fuzzers).
+const worldStateCache = new Map<string, NativeWorldStateService>();
+
+async function openExistingWorldState(dataDir: string, mapSizeKb: number): Promise<NativeWorldStateService> {
+  const cached = worldStateCache.get(dataDir);
+  if (cached) {
+    return cached;
+  }
+
+  const ws = await NativeWorldStateService.new(EthAddress.ZERO, dataDir, {
+    archiveTreeMapSizeKb: mapSizeKb,
+    nullifierTreeMapSizeKb: mapSizeKb,
+    noteHashTreeMapSizeKb: mapSizeKb,
+    messageTreeMapSizeKb: mapSizeKb,
+    publicDataTreeMapSizeKb: mapSizeKb,
+  });
+
+  worldStateCache.set(dataDir, ws);
+  return ws;
+}
+
+async function simulateWithFuzzer(
+  dataDir: string,
+  mapSizeKb: number,
+  txHint: AvmTxHint,
+  globals: GlobalVariables,
+  rawContractClasses: any[], // Replace these when we are moving contract classes to TS
+  rawContractInstances: [any, any][], // Replace these when we are moving contract instances to TS
+): Promise<{ reverted: boolean; output: Fr[]; revertReason?: string; publicInputs: AvmCircuitPublicInputs }> {
+  const worldStateService = await openExistingWorldState(dataDir, mapSizeKb);
+
+  const simulator = await AvmFuzzerSimulator.create(worldStateService, globals);
+
+  // Register contract classes from C++
+  for (const rawClass of rawContractClasses) {
+    await simulator.addContractClassFromCpp(rawClass);
+  }
+
+  // Register contract instances from C++
+  for (const [rawAddress, rawInstance] of rawContractInstances) {
+    await simulator.addContractInstanceFromCpp(rawAddress, rawInstance);
+  }
+
+  const result = await simulator.simulate(txHint);
+
+  const output = result
+    .getAppLogicReturnValues()
+    .flatMap((rv: { values?: Fr[] } | undefined) => rv?.values?.filter((v: Fr | null | undefined) => v != null) ?? []);
+
+  return {
+    reverted: !result.revertCode.isOK(),
+    output,
+    revertReason: result.findRevertReason()?.message,
+    publicInputs: result.publicInputs!,
+  };
+}
+
+async function execute(base64Line: string): Promise<void> {
+  try {
+    // Decode base64 and deserialize the entire request from msgpack
+    const buffer = Buffer.from(base64Line.trim(), 'base64');
+    const rawRequest = deserializeFromMessagePack(buffer);
+    const request = FuzzerSimulationRequest.fromPlainObject(rawRequest);
+
+    // Run the TS simulation
+    const result = await simulateWithFuzzer(
+      request.wsDataDir,
+      request.wsMapSizeKb,
+      request.tx,
+      request.globals,
+      request.contractClasses,
+      request.contractInstances,
+    );
+
+    // Serialize the result to msgpack and encode it in base64 for output
+    const resultBuffer = serializeWithMessagePack({
+      reverted: result.reverted,
+      output: result.output,
+      revertReason: result.revertReason ?? '',
+      endTreeSnapshots: result.publicInputs.endTreeSnapshots,
+    });
+    const base64Response = resultBuffer.toString('base64') + '\n';
+    await writeOutput(base64Response);
+  } catch (error: any) {
+    // If we error, treat as reverted
+    const errorResult = serializeWithMessagePack({
+      reverted: true,
+      output: [] as Fr[],
+      revertReason: `Unexpected Error ${error.message}`,
+      endTreeSnapshots: TreeSnapshots.empty(),
+    });
+    await writeOutput(errorResult.toString('base64') + '\n');
+  }
+}
+
+function mainLoop() {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  // Process lines sequentially to avoid race conditions in responses
+  const lineQueue: string[] = [];
+  let processing = false;
+
+  async function processQueue() {
+    if (processing || lineQueue.length === 0) {
+      return;
+    }
+    processing = true;
+    while (lineQueue.length > 0) {
+      const line = lineQueue.shift()!;
+      await execute(line);
+    }
+    processing = false;
+  }
+
+  rl.on('line', (line: string) => {
+    if (line.trim()) {
+      lineQueue.push(line);
+      void processQueue();
+    }
+  });
+  rl.on('close', () => process.exit(0));
+}
+
+void mainLoop();