@aztec/simulator 3.0.0-rc.5 → 4.0.0-nightly.20260107

package/src/public/fixtures/public_tx_simulation_tester.ts

@@ -31,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;
@@ -225,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,
@@ -235,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);
 

package/src/public/fixtures/utils.ts

@@ -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

@@ -185,7 +185,7 @@ export class AvmFuzzerSimulator extends BaseAvmSimulationTester {
     super(contractDataSource, merkleTrees);
     const contractsDb = new PublicContractsDB(contractDataSource);
     this.simulator = new PublicTxSimulator(merkleTrees, contractsDb, globals, {
-      skipFeeEnforcement: true,
+      skipFeeEnforcement: false,
       collectDebugLogs: false,
       collectHints: false,
       collectStatistics: false,
@@ -209,6 +209,13 @@ export class AvmFuzzerSimulator extends BaseAvmSimulationTester {
    * 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);
   }

package/src/public/fuzzing/avm_simulator_bin.ts

@@ -98,6 +98,7 @@ async function execute(base64Line: string): Promise<void> {
     });
     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[],
@@ -110,12 +111,30 @@ async function execute(base64Line: string): Promise<void> {
 
 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()) {
-      void execute(line);
+      lineQueue.push(line);
+      void processQueue();
     }
   });
   rl.on('close', () => process.exit(0));
 }
 
-mainLoop();
+void mainLoop();

package/src/public/hinting_db_sources.ts

@@ -572,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>[],

package/src/public/public_processor/guarded_merkle_tree.ts

@@ -81,6 +81,10 @@ export class GuardedMerkleTreeOperations implements MerkleTreeWriteOperations {
   close(): Promise<void> {
     return this.guardAndPush(() => this.target.close());
   }
+
+  async [Symbol.dispose](): Promise<void> {
+    await this.close();
+  }
   getTreeInfo(treeId: MerkleTreeId): Promise<TreeInfo> {
     return this.guardAndPush(() => this.target.getTreeInfo(treeId));
   }

package/src/public/public_processor/public_processor.ts

@@ -126,7 +126,7 @@ export class PublicProcessor implements Traceable {
     private dateProvider: DateProvider,
     telemetryClient: TelemetryClient = getTelemetryClient(),
     private log = createLogger('simulator:public-processor'),
-    private opts: Pick<SequencerConfig, 'fakeProcessingDelayPerTxMs'> = {},
+    private opts: Pick<SequencerConfig, 'fakeProcessingDelayPerTxMs' | 'fakeThrowAfterProcessingTxCount'> = {},
   ) {
     this.metrics = new PublicProcessorMetrics(telemetryClient, 'PublicProcessor');
   }
@@ -160,7 +160,7 @@ export class PublicProcessor implements Traceable {
     let totalBlockGas = new Gas(0, 0);
     let totalBlobFields = 0;
 
-    for await (const origTx of txs) {
+    for await (const tx of txs) {
       // Only process up to the max tx limit
       if (maxTransactions !== undefined && result.length >= maxTransactions) {
         this.log.debug(`Stopping tx processing due to reaching the max tx limit.`);
@@ -174,8 +174,8 @@ export class PublicProcessor implements Traceable {
       }
 
       // Skip this tx if it'd exceed max block size
-      const txHash = origTx.getTxHash().toString();
-      const preTxSizeInBytes = origTx.getEstimatedPrivateTxEffectsSize();
+      const txHash = tx.getTxHash().toString();
+      const preTxSizeInBytes = tx.getEstimatedPrivateTxEffectsSize();
       if (maxBlockSize !== undefined && totalSizeInBytes + preTxSizeInBytes > maxBlockSize) {
         this.log.warn(`Skipping processing of tx ${txHash} sized ${preTxSizeInBytes} bytes due to block size limit`, {
           txHash,
@@ -187,7 +187,7 @@ export class PublicProcessor implements Traceable {
       }
 
       // Skip this tx if its gas limit would exceed the block gas limit
-      const txGasLimit = origTx.data.constants.txContext.gasSettings.gasLimits;
+      const txGasLimit = tx.data.constants.txContext.gasSettings.gasLimits;
       if (maxBlockGas !== undefined && totalBlockGas.add(txGasLimit).gtAny(maxBlockGas)) {
         this.log.warn(`Skipping processing of tx ${txHash} due to block gas limit`, {
           txHash,
@@ -198,9 +198,6 @@ export class PublicProcessor implements Traceable {
         continue;
       }
 
-      // The processor modifies the tx objects in place, so we need to clone them.
-      const tx = Tx.clone(origTx);
-
       // We validate the tx before processing it, to avoid unnecessary work.
       if (preprocessValidator) {
         const result = await preprocessValidator.validateTx(tx);
@@ -233,6 +230,12 @@ export class PublicProcessor implements Traceable {
       try {
         const [processedTx, returnValues] = await this.processTx(tx, deadline);
 
+        // Inject a fake processing failure after N txs if requested
+        const fakeThrowAfter = this.opts.fakeThrowAfterProcessingTxCount;
+        if (fakeThrowAfter !== undefined && result.length + failed.length + 1 >= fakeThrowAfter) {
+          throw new Error(`Fake error after processing ${fakeThrowAfter} txs`);
+        }
+
         const txBlobFields = processedTx.txEffect.getNumBlobFields();
 
         // If the actual size of this tx would exceed block size, skip it
@@ -282,7 +285,15 @@ export class PublicProcessor implements Traceable {
         if (err?.name === 'PublicProcessorTimeoutError') {
           this.log.warn(`Stopping tx processing due to timeout.`);
           // We hit the transaction execution deadline.
-          // There may still be a transaction executing. We stop the guarded fork to prevent any further access to the world state.
+          // There may still be a transaction executing on a worker thread (C++ via NAPI).
+          // Signal cancellation AND WAIT for the simulation to actually stop.
+          // This is critical because C++ might be in the middle of a slow operation (e.g., pad_trees)
+          // and won't check the cancellation flag until that operation completes.
+          // Without waiting, we'd proceed to revert checkpoints while C++ is still writing to state.
+          // Wait for C++ to stop gracefully.
+          await this.publicTxSimulator.cancel?.();
+
+          // Now stop the guarded fork to prevent any further TS-side access to the world state.
           await this.guardedMerkleTree.stop();
 
           // We now know there can't be any further access to world state. The fork is in a state where there is:

package/src/public/public_tx_simulator/contract_provider_for_cpp.ts

@@ -18,7 +18,7 @@ export class ContractProviderForCpp implements ContractProvider {
   ) {}
 
   public getContractInstance = async (address: string): Promise<Buffer | undefined> => {
-    this.log.debug(`Contract provider callback: getContractInstance(${address})`);
+    this.log.trace(`Contract provider callback: getContractInstance(${address})`);
 
     const aztecAddr = AztecAddress.fromString(address);
 
@@ -33,7 +33,7 @@ export class ContractProviderForCpp implements ContractProvider {
   };
 
   public getContractClass = async (classId: string): Promise<Buffer | undefined> => {
-    this.log.debug(`Contract provider callback: getContractClass(${classId})`);
+    this.log.trace(`Contract provider callback: getContractClass(${classId})`);
 
     // Parse classId string to Fr
     const classIdFr = Fr.fromString(classId);
@@ -50,7 +50,7 @@ export class ContractProviderForCpp implements ContractProvider {
   };
 
   public addContracts = async (contractDeploymentDataBuffer: Buffer): Promise<void> => {
-    this.log.debug(`Contract provider callback: addContracts`);
+    this.log.trace(`Contract provider callback: addContracts`);
 
     const rawData: any = deserializeFromMessagePack(contractDeploymentDataBuffer);
 
@@ -58,12 +58,12 @@ export class ContractProviderForCpp implements ContractProvider {
     const contractDeploymentData = ContractDeploymentData.fromPlainObject(rawData);
 
     // Add contracts to the contracts DB
-    this.log.debug(`Calling contractsDB.addContracts`);
+    this.log.trace(`Calling contractsDB.addContracts`);
     await this.contractsDB.addContracts(contractDeploymentData);
   };
 
   public getBytecodeCommitment = async (classId: string): Promise<Buffer | undefined> => {
-    this.log.debug(`Contract provider callback: getBytecodeCommitment(${classId})`);
+    this.log.trace(`Contract provider callback: getBytecodeCommitment(${classId})`);
 
     // Parse classId string to Fr
     const classIdFr = Fr.fromString(classId);
@@ -81,18 +81,23 @@ export class ContractProviderForCpp implements ContractProvider {
   };
 
   public getDebugFunctionName = async (address: string, selector: string): Promise<string | undefined> => {
-    this.log.debug(`Contract provider callback: getDebugFunctionName(${address}, ${selector})`);
+    this.log.trace(`Contract provider callback: getDebugFunctionName(${address}, ${selector})`);
 
     // Parse address and selector strings
     const aztecAddr = AztecAddress.fromString(address);
     const selectorFr = Fr.fromString(selector);
-    const functionSelector = FunctionSelector.fromField(selectorFr);
+    const functionSelector = FunctionSelector.fromFieldOrUndefined(selectorFr);
+
+    if (!functionSelector) {
+      this.log.trace(`calldata[0] is not a function selector: ${selector}`);
+      return undefined;
+    }
 
     // Fetch debug function name from the contracts DB
     const name = await this.contractsDB.getDebugFunctionName(aztecAddr, functionSelector);
 
     if (!name) {
-      this.log.debug(`Debug function name not found for ${address}:${selector}`);
+      this.log.trace(`Debug function name not found for ${address}:${selector}`);
       return undefined;
     }
 
@@ -100,17 +105,17 @@ export class ContractProviderForCpp implements ContractProvider {
   };
 
   public createCheckpoint = (): Promise<void> => {
-    this.log.debug(`Contract provider callback: createCheckpoint`);
+    this.log.trace(`Contract provider callback: createCheckpoint`);
     return Promise.resolve(this.contractsDB.createCheckpoint());
   };
 
   public commitCheckpoint = (): Promise<void> => {
-    this.log.debug(`Contract provider callback: commitCheckpoint`);
+    this.log.trace(`Contract provider callback: commitCheckpoint`);
     return Promise.resolve(this.contractsDB.commitCheckpoint());
   };
 
   public revertCheckpoint = (): Promise<void> => {
-    this.log.debug(`Contract provider callback: revertCheckpoint`);
+    this.log.trace(`Contract provider callback: revertCheckpoint`);
     return Promise.resolve(this.contractsDB.revertCheckpoint());
   };
 }

package/src/public/public_tx_simulator/cpp_public_tx_simulator.ts

@@ -1,5 +1,6 @@
 import { type Logger, createLogger, logLevel } from '@aztec/foundation/log';
-import { avmSimulate } from '@aztec/native';
+import { sleep } from '@aztec/foundation/sleep';
+import { type CancellationToken, avmSimulate, cancelSimulation, createCancellationToken } from '@aztec/native';
 import { ProtocolContractsList } from '@aztec/protocol-contracts';
 import {
   AvmFastSimulationInputs,
@@ -33,6 +34,10 @@ import type {
  */
 export class CppPublicTxSimulator extends PublicTxSimulator implements PublicTxSimulatorInterface {
   protected override log: Logger;
+  /** Current cancellation token for in-flight simulation. */
+  private cancellationToken?: CancellationToken;
+  /** Current simulation promise, used to wait for completion after cancellation. */
+  private simulationPromise?: Promise<Buffer>;
 
   constructor(
     merkleTree: MerkleTreeWriteOperations,
@@ -85,12 +90,25 @@ export class CppPublicTxSimulator extends PublicTxSimulator implements PublicTxS
     this.log.trace(`Serializing fast simulation inputs to msgpack...`);
     const inputBuffer = fastSimInputs.serializeWithMessagePack();
 
+    // Create cancellation token for this simulation
+    this.cancellationToken = createCancellationToken();
+
+    // Store the promise so cancel() can wait for it
+    this.log.debug(`Calling C++ simulator for tx ${txHash}`);
+    this.simulationPromise = avmSimulate(inputBuffer, contractProvider, wsCppHandle, logLevel, this.cancellationToken);
+
     let resultBuffer: Buffer;
     try {
-      this.log.debug(`Calling C++ simulator for tx ${txHash}`);
-      resultBuffer = await avmSimulate(inputBuffer, contractProvider, wsCppHandle, logLevel);
+      resultBuffer = await this.simulationPromise;
     } catch (error: any) {
+      // Check if this was a cancellation
+      if (error.message?.includes('Simulation cancelled')) {
+        throw new SimulationError(`C++ simulation cancelled`, []);
+      }
       throw new SimulationError(`C++ simulation failed: ${error.message}`, []);
+    } finally {
+      this.cancellationToken = undefined;
+      this.simulationPromise = undefined;
     }
 
     // If we've reached this point, C++ succeeded during simulation,
@@ -109,6 +127,33 @@ export class CppPublicTxSimulator extends PublicTxSimulator implements PublicTxS
 
     return cppResult;
   }
+
+  /**
+   * Cancel the current simulation if one is in progress.
+   * This signals the C++ simulator to stop at the next opcode or before the next WorldState write.
+   * 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.
+   *                        This is important because C++ might be in the middle of a slow operation
+   *                        (e.g., pad_trees) and won't check the cancellation flag until it completes.
+   *                        Default timeout of 100ms after cancellation.
+   */
+  public async cancel(waitTimeoutMs: number = 100): Promise<void> {
+    if (this.cancellationToken) {
+      this.log.debug('Cancelling C++ simulation');
+      cancelSimulation(this.cancellationToken);
+    }
+
+    // Wait for the simulation to actually complete if not already done
+    if (this.simulationPromise) {
+      this.log.debug(`Waiting up to ${waitTimeoutMs}ms for C++ simulation to stop`);
+      await Promise.race([
+        this.simulationPromise.catch(() => {}), // Ignore rejection, just wait for completion
+        sleep(waitTimeoutMs),
+      ]);
+      this.log.debug('C++ simulation stopped or wait timed out');
+    }
+  }
 }
 
 export class MeasuredCppPublicTxSimulator extends CppPublicTxSimulator implements MeasuredPublicTxSimulatorInterface {

package/src/public/public_tx_simulator/cpp_vs_ts_public_tx_simulator.ts

@@ -39,7 +39,7 @@ export class CppVsTsPublicTxSimulator extends PublicTxSimulator implements Publi
     config?: Partial<PublicSimulatorConfig>,
   ) {
     super(merkleTree, contractsDB, globalVariables, config);
-    this.log = createLogger(`simulator:cpp_public_tx_simulator`);
+    this.log = createLogger(`simulator:cpp_vs_public_tx_simulator`);
   }
 
   /**
@@ -205,7 +205,8 @@ export class CppVsTsPublicTxSimulator extends PublicTxSimulator implements Publi
       cppGasUsed: cppResult.gasUsed.totalGas.l2Gas,
     });
 
-    return tsResult;
+    // Return cpp result as it has more detailed metadata / revert reasons
+    return cppResult;
   }
 }
 

package/src/public/public_tx_simulator/public_tx_simulator_interface.ts

@@ -3,8 +3,31 @@ import type { Tx } from '@aztec/stdlib/tx';
 
 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.
+   * 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.
+   * @returns Promise that resolves when cancellation is signaled (and optionally when simulation stops)
+   */
+  cancel?(waitTimeoutMs?: number): Promise<void>;
 }
 
 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.
+   * 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.
+   * @returns Promise that resolves when cancellation is signaled (and optionally when simulation stops)
+   */
+  cancel?(waitTimeoutMs?: number): Promise<void>;
 }