@aztec/simulator 4.0.0-nightly.20250907 → 4.0.0-nightly.20260107

package/src/public/fuzzing/avm_simulator_bin.ts

@@ -0,0 +1,140 @@
+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 { writeSync } from 'fs';
+import { createInterface } from 'readline';
+
+import { AvmFuzzerSimulator, FuzzerSimulationRequest } from './avm_fuzzer_simulator.js';
+
+// 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,
+    });
+    writeSync(process.stdout.fd, resultBuffer.toString('base64') + '\n');
+  } catch (error: any) {
+    // If we error, treat as reverted
+    const errorResult = serializeWithMessagePack({
+      reverted: true,
+      output: [] as string[],
+      revertReason: `Unexpected Error ${error.message}`,
+      endTreeSnapshots: TreeSnapshots.empty(),
+    });
+    writeSync(process.stdout.fd, 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();

package/src/public/hinting_db_sources.ts

@@ -1,5 +1,6 @@
-import { sha256Trunc } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import { sha256Trunc } from '@aztec/foundation/crypto/sha256';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { IndexedTreeLeafPreimage, SiblingPath } from '@aztec/foundation/trees';
 import type { FunctionSelector } from '@aztec/stdlib/abi';
@@ -8,8 +9,12 @@ import {
   AvmBytecodeCommitmentHint,
   AvmCommitCheckpointHint,
   AvmContractClassHint,
+  AvmContractDbCommitCheckpointHint,
+  AvmContractDbCreateCheckpointHint,
+  AvmContractDbRevertCheckpointHint,
   AvmContractInstanceHint,
   AvmCreateCheckpointHint,
+  AvmDebugFunctionNameHint,
   type AvmExecutionHints,
   AvmGetLeafPreimageHintNullifierTree,
   AvmGetLeafPreimageHintPublicDataTree,
@@ -40,6 +45,7 @@ import {
 } from '@aztec/stdlib/trees';
 import { TreeSnapshots } from '@aztec/stdlib/tx';
 import type { UInt64 } from '@aztec/stdlib/types';
+import type { WorldStateRevision } from '@aztec/stdlib/world-state';
 
 import { strict as assert } from 'assert';
 
@@ -49,8 +55,11 @@ import type { PublicContractsDBInterface } from './db_interfaces.js';
  * A public contracts database that forwards requests and collects AVM hints.
  */
 export class HintingPublicContractsDB implements PublicContractsDBInterface {
-  // We deduplicate contract classes because they include the whole bytecode.
-  private contractClassIds: Set<bigint> = new Set();
+  private static readonly log: Logger = createLogger('simulator:hinting-public-contracts-db');
+
+  private checkpointActionCounter: number = 0;
+  private nextCheckpointId: number = 1;
+  private checkpointStack: number[] = [0];
 
   constructor(
     private readonly db: PublicContractsDBInterface,
@@ -63,9 +72,11 @@ export class HintingPublicContractsDB implements PublicContractsDBInterface {
   ): Promise<ContractInstanceWithAddress | undefined> {
     const instance = await this.db.getContractInstance(address, timestamp);
     if (instance) {
-      // We don't need to hint the block number because it doesn't change.
+      const hintKey = this.getHintKey();
+
       this.hints.contractInstances.push(
         new AvmContractInstanceHint(
+          hintKey,
           instance.address,
           instance.salt,
           instance.deployer,
@@ -75,22 +86,31 @@ export class HintingPublicContractsDB implements PublicContractsDBInterface {
           instance.publicKeys,
         ),
       );
+
+      HintingPublicContractsDB.log.trace(
+        `[getContractInstance:${hintKey}] Added contract instance ${instance.address.toString()} to hints.`,
+      );
     }
     return instance;
   }
 
   public async getContractClass(contractClassId: Fr): Promise<ContractClassPublic | undefined> {
     const contractClass = await this.db.getContractClass(contractClassId);
-    if (contractClass && !this.contractClassIds.has(contractClassId.toBigInt())) {
-      this.contractClassIds.add(contractClassId.toBigInt());
+    if (contractClass) {
+      const hintKey = this.getHintKey();
       this.hints.contractClasses.push(
         new AvmContractClassHint(
+          hintKey,
           contractClass.id,
           contractClass.artifactHash,
           contractClass.privateFunctionsRoot,
           contractClass.packedBytecode,
         ),
       );
+
+      HintingPublicContractsDB.log.trace(
+        `[getContractClass:${hintKey}] Added contract class ${contractClassId.toString()} to hints.`,
+      );
     }
     return contractClass;
   }
@@ -98,7 +118,12 @@ export class HintingPublicContractsDB implements PublicContractsDBInterface {
   public async getBytecodeCommitment(contractClassId: Fr): Promise<Fr | undefined> {
     const commitment = await this.db.getBytecodeCommitment(contractClassId);
     if (commitment) {
-      this.hints.bytecodeCommitments.push(new AvmBytecodeCommitmentHint(contractClassId, commitment));
+      const hintKey = this.getHintKey();
+      this.hints.bytecodeCommitments.push(new AvmBytecodeCommitmentHint(hintKey, contractClassId, commitment));
+
+      HintingPublicContractsDB.log.trace(
+        `[getBytecodeCommitment:${hintKey}] Added bytecode commitment ${commitment.toString()} to hints for contract class ${contractClassId.toString()}.`,
+      );
     }
     return commitment;
   }
@@ -107,7 +132,81 @@ export class HintingPublicContractsDB implements PublicContractsDBInterface {
     contractAddress: AztecAddress,
     selector: FunctionSelector,
   ): Promise<string | undefined> {
-    return await this.db.getDebugFunctionName(contractAddress, selector);
+    const name = await this.db.getDebugFunctionName(contractAddress, selector);
+    if (name) {
+      HintingPublicContractsDB.log.debug(
+        `[getDebugFunctionName] Adding debug function name ${name} to hints for contract ${contractAddress.toString()} and selector ${selector.toString()}.`,
+      );
+      // We hint selector as a field to make things way simpler in C++.
+      this.hints.debugFunctionNames.push(new AvmDebugFunctionNameHint(contractAddress, selector.toField(), name));
+    }
+    return name;
+  }
+
+  public createCheckpoint(): void {
+    const hintKey = this.getHintKey();
+    this.checkpointActionCounter++;
+    const oldCheckpointId = this.getCurrentCheckpointId();
+
+    this.db.createCheckpoint();
+
+    const newCheckpointId = this.nextCheckpointId++;
+    this.checkpointStack.push(newCheckpointId);
+
+    this.hints.contractDbCreateCheckpointHints.push(
+      new AvmContractDbCreateCheckpointHint(hintKey, oldCheckpointId, newCheckpointId),
+    );
+
+    HintingPublicContractsDB.log.trace(
+      `[createCheckpoint:${hintKey}] Checkpoint evolved ${oldCheckpointId} -> ${newCheckpointId}.`,
+    );
+  }
+
+  public commitCheckpoint(): void {
+    const hintKey = this.getHintKey();
+    this.checkpointActionCounter++;
+    const oldCheckpointId = this.getCurrentCheckpointId();
+
+    this.db.commitCheckpoint();
+
+    this.checkpointStack.pop();
+    const newCheckpointId = this.getCurrentCheckpointId();
+
+    this.hints.contractDbCommitCheckpointHints.push(
+      new AvmContractDbCommitCheckpointHint(hintKey, oldCheckpointId, newCheckpointId),
+    );
+
+    HintingPublicContractsDB.log.trace(
+      `[commitCheckpoint:${hintKey}] Checkpoint evolved ${oldCheckpointId} -> ${newCheckpointId}.`,
+    );
+  }
+
+  public revertCheckpoint(): void {
+    const hintKey = this.getHintKey();
+    this.checkpointActionCounter++;
+    const oldCheckpointId = this.getCurrentCheckpointId();
+
+    this.db.revertCheckpoint();
+
+    this.checkpointStack.pop();
+    const newCheckpointId = this.getCurrentCheckpointId();
+
+    this.hints.contractDbRevertCheckpointHints.push(
+      new AvmContractDbRevertCheckpointHint(hintKey, oldCheckpointId, newCheckpointId),
+    );
+
+    HintingPublicContractsDB.log.trace(
+      `[revertCheckpoint:${hintKey}] Checkpoint evolved ${oldCheckpointId} -> ${newCheckpointId}.`,
+    );
+  }
+
+  // Private methods.
+  private getHintKey(): number {
+    return this.checkpointActionCounter;
+  }
+
+  private getCurrentCheckpointId(): number {
+    return this.checkpointStack[this.checkpointStack.length - 1];
   }
 }
 
@@ -449,6 +548,10 @@ export class HintingMerkleWriteOperations implements MerkleTreeWriteOperations {
     return this.db.getInitialHeader();
   }
 
+  public getRevision(): WorldStateRevision {
+    return this.db.getRevision();
+  }
+
   public async updateArchive(header: any): Promise<void> {
     return await this.db.updateArchive(header);
   }
@@ -469,6 +572,10 @@ export class HintingMerkleWriteOperations implements MerkleTreeWriteOperations {
     return await this.db.close();
   }
 
+  async [Symbol.dispose](): Promise<void> {
+    await this.close();
+  }
+
   public async findLeafIndices<ID extends MerkleTreeId>(
     treeId: ID,
     values: MerkleTreeLeafType<ID>[],
@@ -494,7 +601,7 @@ export class HintingMerkleWriteOperations implements MerkleTreeWriteOperations {
   public async getBlockNumbersForLeafIndices<ID extends MerkleTreeId>(
     treeId: ID,
     leafIndices: bigint[],
-  ): Promise<(bigint | undefined)[]> {
+  ): Promise<(BlockNumber | undefined)[]> {
     return await this.db.getBlockNumbersForLeafIndices(treeId, leafIndices);
   }
 }

package/src/public/index.ts

@@ -1,5 +1,12 @@
 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 { PublicTxSimulator, TelemetryPublicTxSimulator, type PublicTxResult } from './public_tx_simulator/index.js';
+export {
+  CppPublicTxSimulator,
+  createPublicTxSimulatorForBlockBuilding,
+  DumpingCppPublicTxSimulator,
+  type PublicTxSimulatorInterface,
+  TelemetryCppPublicTxSimulator,
+} from './public_tx_simulator/index.js';
+export type { PublicTxResult, PublicSimulatorConfig as PublicTxSimulatorConfig } from '@aztec/stdlib/avm';
 export { getCallRequestsWithCalldataByPhase } from './utils.js';