@aztec/simulator 2.1.0-rc.9 → 3.0.0-devnet.2

package/src/public/fixtures/custom_bytecode_tests.ts

@@ -0,0 +1,135 @@
+import { strict as assert } from 'assert';
+
+import { TypeTag } from '../avm/avm_memory_types.js';
+import { Addressing, AddressingMode } from '../avm/opcodes/addressing_mode.js';
+import { CalldataCopy, Jump, Return, Set } from '../avm/opcodes/index.js';
+import { encodeToBytecode } from '../avm/serialization/bytecode_serialization.js';
+import {
+  MAX_OPCODE_VALUE,
+  Opcode,
+  OperandType,
+  getOperandSize,
+} from '../avm/serialization/instruction_serialization.js';
+import { testCustomBytecode } from './custom_bytecode_tester.js';
+import { PublicTxSimulationTester } from './public_tx_simulation_tester.js';
+
+// First instruction resolved a base address (offset 0) which is uninitialized and therefore
+// of invalid tag (FF). This will trigger an exceptional halt.
+export async function addressingWithBaseTagIssueTest(isIndirect: boolean, tester: PublicTxSimulationTester) {
+  const addressingMode = Addressing.fromModes([
+    isIndirect ? AddressingMode.INDIRECT_RELATIVE : AddressingMode.RELATIVE,
+    AddressingMode.DIRECT,
+    AddressingMode.DIRECT,
+  ]);
+
+  const bytecode = encodeToBytecode([
+    new CalldataCopy(/*indirect=*/ addressingMode.toWire(), /*copySize=*/ 1, /*cdOffset=*/ 0, /*dstOffset=*/ 0),
+    new Return(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*returnOffset=*/ 0),
+  ]);
+
+  const txLabel = isIndirect ? 'AddressingWithBaseTagInvalidIndirect' : 'AddressingWithBaseTagInvalidDirect';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+export async function pcOutOfRangeTest(tester: PublicTxSimulationTester) {
+  const bytecode = encodeToBytecode([
+    new Jump(/*jumpOffset=*/ 123), // Jump to out-of-range pc offset.
+    new Return(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*returnOffset=*/ 0),
+  ]);
+
+  const txLabel = 'PcOutOfRange';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+export async function invalidOpcodeTest(tester: PublicTxSimulationTester) {
+  let bytecode = encodeToBytecode([
+    new Set(/*indirect=*/ 0, /*dstOffset=*/ 0, TypeTag.UINT32, /*value=*/ 0).as(Opcode.SET_8, Set.wireFormat8),
+  ]);
+
+  const offsetReturnOpcodeByte = bytecode.length;
+
+  bytecode = Buffer.concat([
+    bytecode,
+    encodeToBytecode([new Return(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*returnOffset=*/ 0)]),
+  ]);
+
+  // Manipulate the Return opcode to make the opcode invalid (out of range).
+  bytecode[offsetReturnOpcodeByte] = MAX_OPCODE_VALUE + 1; // opcode is invalid.
+
+  const txLabel = 'InvalidOpcode';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+// Single invalid byte in the bytecode.
+export async function invalidByteTest(tester: PublicTxSimulationTester) {
+  const invalidOpcode = MAX_OPCODE_VALUE + 7;
+  assert(invalidOpcode < 256, 'Invalid opcode must fit in a single byte');
+  const bytecode = Buffer.from([invalidOpcode]);
+
+  const txLabel = 'InvalidByte';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+// Truncate the last instruction in the bytecode.
+export async function instructionTruncatedTest(tester: PublicTxSimulationTester) {
+  let bytecode = encodeToBytecode([
+    new Set(/*indirect=*/ 0, /*dstOffset=*/ 0, TypeTag.UINT32, /*value=*/ 0).as(Opcode.SET_8, Set.wireFormat8),
+  ]);
+
+  // Truncate the bytecode.
+  bytecode = bytecode.subarray(0, -1);
+
+  const txLabel = 'InstructionTruncated';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+// Invalid tag value byte in an instruction.
+export async function invalidTagValueTest(tester: PublicTxSimulationTester) {
+  const bytecode = encodeToBytecode([
+    new Set(/*indirect=*/ 0, /*dstOffset=*/ 0, TypeTag.UINT32, /*value=*/ 0).as(Opcode.SET_8, Set.wireFormat8),
+    new Return(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*returnOffset=*/ 0),
+  ]);
+
+  const tagOffset = getTagOffsetInInstruction(Set.wireFormat8);
+  assert(bytecode[tagOffset].valueOf() == TypeTag.UINT32.valueOf(), 'Set instruction tag should be UINT32 in test');
+  bytecode[tagOffset] = TypeTag.INVALID;
+
+  const txLabel = 'InvalidTagValue';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+// Combine an invalid tag in the last instruction that is truncated.
+export async function invalidTagValueAndInstructionTruncatedTest(tester: PublicTxSimulationTester) {
+  let bytecode = encodeToBytecode([
+    // Important: value argument must be a bigint otherwise a type error will be thrown.
+    new Set(/*indirect=*/ 0, /*dstOffset=*/ 0, TypeTag.UINT128, /*value=*/ 0n).as(Opcode.SET_128, Set.wireFormat128),
+  ]);
+
+  // Truncate the bytecode.
+  bytecode = bytecode.subarray(0, -5);
+  const tagOffset = getTagOffsetInInstruction(Set.wireFormat128);
+  assert(bytecode[tagOffset].valueOf() == TypeTag.UINT128.valueOf(), 'Set instruction tag should be UINT128 in test');
+  bytecode[tagOffset] = 0x6f; // Invalid tag value.
+
+  const txLabel = 'InvalidTagValueAndInstructionTruncated';
+  return await testCustomBytecode(bytecode, tester, txLabel);
+}
+
+/**
+ * Returns the offset of the tag in an instruction.
+ * @details Loops over the wire format operand type entries until it finds the tag.
+ * Returns the byte offset of the tag based on each operand size that is passed.
+ *
+ * @param wireFormat array of operand types
+ * @returns byte offset of the tag
+ */
+function getTagOffsetInInstruction(wireFormat: OperandType[]): number {
+  let offset = 0;
+  for (const operand of wireFormat) {
+    if (operand === OperandType.TAG) {
+      break;
+    }
+    offset += getOperandSize(operand);
+  }
+  return offset;
+}

package/src/public/fixtures/index.ts

@@ -1,8 +1,9 @@
 export * from './public_tx_simulation_tester.js';
 export * from './utils.js';
 export * from './simple_contract_data_source.js';
-export { readAvmMinimalPublicTxInputsFromFile, createAvmMinimalPublicTx } from './minimal_public_tx.js';
+export { readAvmMinimalPublicTxInputsFromFile, executeAvmMinimalPublicTx } from './minimal_public_tx.js';
 export { TestExecutorMetrics } from '../test_executor_metrics.js';
 export { ammTest } from './amm_test.js';
 export { bulkTest, megaBulkTest } from './bulk_test.js';
 export { tokenTest } from './token_test.js';
+export * from './custom_bytecode_tests.js';

package/src/public/fixtures/minimal_public_tx.ts

@@ -1,6 +1,5 @@
-import { FunctionType, emptyContractArtifact, emptyFunctionArtifact } from '@aztec/stdlib/abi';
 import { AvmCircuitInputs } from '@aztec/stdlib/avm';
-import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { ProtocolContracts } from '@aztec/stdlib/tx';
 
 import avmMinimalCircuitInputsJson from '../../../artifacts/avm_minimal_inputs.json' with { type: 'json' };
 import { TypeTag } from '../avm/avm_memory_types.js';
@@ -8,13 +7,10 @@ import { Add, Return, Set } from '../avm/opcodes/index.js';
 import { encodeToBytecode } from '../avm/serialization/bytecode_serialization.js';
 import { Opcode } from '../avm/serialization/instruction_serialization.js';
 import type { PublicTxResult } from '../public_tx_simulator/public_tx_simulator.js';
+import { testCustomBytecode } from './custom_bytecode_tester.js';
 import { PublicTxSimulationTester } from './public_tx_simulation_tester.js';
 
-export async function createAvmMinimalPublicTx(): Promise<PublicTxResult> {
-  const deployer = AztecAddress.fromNumber(42);
-
-  const simTester = await PublicTxSimulationTester.create();
-
+export async function executeAvmMinimalPublicTx(tester: PublicTxSimulationTester): Promise<PublicTxResult> {
   const minimalBytecode = encodeToBytecode([
     new Set(/*indirect*/ 0, /*dstOffset*/ 0, TypeTag.UINT32, /*value*/ 1).as(Opcode.SET_8, Set.wireFormat8),
     new Set(/*indirect*/ 0, /*dstOffset*/ 1, TypeTag.UINT32, /*value*/ 2).as(Opcode.SET_8, Set.wireFormat8),
@@ -22,32 +18,13 @@ export async function createAvmMinimalPublicTx(): Promise<PublicTxResult> {
     new Return(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*returnOffset=*/ 2),
   ]);
 
-  const minimalContractArtifact = emptyContractArtifact();
-  minimalContractArtifact.name = 'MinimalContract';
-  minimalContractArtifact.functions = [emptyFunctionArtifact()];
-  minimalContractArtifact.functions[0].name = 'public_dispatch';
-  minimalContractArtifact.functions[0].functionType = FunctionType.PUBLIC;
-  minimalContractArtifact.functions[0].bytecode = minimalBytecode;
+  const result = await testCustomBytecode(minimalBytecode, tester, 'MinimalTx', 'AvmMinimalContract');
 
-  const minimalTestContract = await simTester.registerAndDeployContract(
-    /*constructorArgs=*/ [],
-    deployer,
-    /*contractArtifact=*/ minimalContractArtifact,
-  );
+  // Modify the protocol contracts to be all zeros
+  result.avmProvingRequest.inputs.hints.protocolContracts = ProtocolContracts.empty();
+  result.avmProvingRequest.inputs.publicInputs.protocolContracts = ProtocolContracts.empty();
 
-  return await simTester.simulateTx(
-    /*sender=*/ deployer,
-    /*setupCalls=*/ [],
-    /*appCalls=*/ [
-      {
-        address: minimalTestContract.address,
-        fnName: 'public_dispatch',
-        args: [],
-      },
-    ],
-    /*teardownCall=*/ undefined,
-    /*feePayer=*/ deployer,
-  );
+  return result;
 }
 
 /**

package/src/public/fixtures/public_tx_simulation_tester.ts

@@ -16,8 +16,10 @@ import {
   getFunctionSelector,
 } from '../avm/fixtures/utils.js';
 import { PublicContractsDB } from '../public_db_sources.js';
+import { MeasuredCppPublicTxSimulatorHintedDbs } from '../public_tx_simulator/cpp_public_tx_simulator.js';
 import { MeasuredPublicTxSimulator } from '../public_tx_simulator/measured_public_tx_simulator.js';
 import type { PublicTxResult } from '../public_tx_simulator/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';
 import { type TestPrivateInsertions, createTxForPublicCalls } from './utils.js';
@@ -40,7 +42,7 @@ export type TestEnqueuedCall = {
  */
 export class PublicTxSimulationTester extends BaseAvmSimulationTester {
   protected txCount: number = 0;
-  private simulator: MeasuredPublicTxSimulator;
+  private simulator: MeasuredPublicTxSimulatorInterface;
   private metricsPrefix?: string;
 
   constructor(
@@ -48,28 +50,30 @@ export class PublicTxSimulationTester extends BaseAvmSimulationTester {
     contractDataSource: SimpleContractDataSource,
     globals: GlobalVariables = defaultGlobals(),
     private metrics: TestExecutorMetrics = new TestExecutorMetrics(),
+    useCppSimulator: boolean = false,
   ) {
     super(contractDataSource, merkleTree);
 
     const contractsDB = new PublicContractsDB(contractDataSource);
-    this.simulator = new MeasuredPublicTxSimulator(
-      merkleTree,
-      contractsDB,
-      globals,
-      /*doMerkleOperations=*/ true,
-      /*skipFeeEnforcement=*/ false,
-      /*clientInitiatedSimulation=*/ true,
-      this.metrics,
-    );
+    const config = {
+      doMerkleOperations: true,
+      skipFeeEnforcement: false,
+      clientInitiatedSimulation: true,
+    };
+    this.simulator = useCppSimulator
+      ? new MeasuredCppPublicTxSimulatorHintedDbs(merkleTree, contractsDB, globals, this.metrics, config)
+      : new MeasuredPublicTxSimulator(merkleTree, contractsDB, globals, this.metrics, config);
   }
 
   public static async create(
+    worldStateService: NativeWorldStateService, // make sure to close this later
     globals: GlobalVariables = defaultGlobals(),
     metrics: TestExecutorMetrics = new TestExecutorMetrics(),
+    useCppSimulator = false,
   ): Promise<PublicTxSimulationTester> {
     const contractDataSource = new SimpleContractDataSource();
-    const merkleTree = await (await NativeWorldStateService.tmp()).fork();
-    return new PublicTxSimulationTester(merkleTree, contractDataSource, globals, metrics);
+    const merkleTree = await worldStateService.fork();
+    return new PublicTxSimulationTester(merkleTree, contractDataSource, globals, metrics, useCppSimulator);
   }
 
   public setMetricsPrefix(prefix: string) {

package/src/public/fixtures/utils.ts

@@ -153,7 +153,7 @@ export async function createTxForPublicCalls(
 
   return await Tx.create({
     data: txData,
-    clientIvcProof: ClientIvcProof.empty(),
+    clientIvcProof: ClientIvcProof.random(),
     contractClassLogFields: [],
     publicFunctionCalldata: calldata,
   });

package/src/public/hinting_db_sources.ts

@@ -40,6 +40,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';
 
@@ -449,6 +450,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);
   }

package/src/public/index.ts

@@ -1,5 +1,10 @@
 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 {
+  PublicTxSimulator,
+  type PublicTxSimulatorConfig,
+  TelemetryPublicTxSimulator,
+  type PublicTxResult,
+} from './public_tx_simulator/index.js';
 export { getCallRequestsWithCalldataByPhase } from './utils.js';

package/src/public/public_db_sources.ts

@@ -1,4 +1,9 @@
-import { NULLIFIER_SUBTREE_HEIGHT, PUBLIC_DATA_SUBTREE_HEIGHT } from '@aztec/constants';
+import {
+  L1_TO_L2_MSG_TREE_LEAF_COUNT,
+  NOTE_HASH_TREE_LEAF_COUNT,
+  NULLIFIER_SUBTREE_HEIGHT,
+  PUBLIC_DATA_SUBTREE_HEIGHT,
+} from '@aztec/constants';
 import { Fr } from '@aztec/foundation/fields';
 import { createLogger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
@@ -27,7 +32,10 @@ import {
 import { TreeSnapshots, type Tx } from '@aztec/stdlib/tx';
 import type { UInt64 } from '@aztec/stdlib/types';
 
+import { strict as assert } from 'assert';
+
 import type { PublicContractsDBInterface, PublicStateDBInterface } from './db_interfaces.js';
+import { L1ToL2MessageIndexOutOfRangeError, NoteHashIndexOutOfRangeError } from './side_effect_errors.js';
 import { TxContractCache } from './tx_contract_cache.js';
 
 /**
@@ -323,9 +331,13 @@ export class PublicTreesDB implements PublicStateDBInterface {
     } satisfies PublicDBAccessStats);
   }
 
-  public async getL1ToL2LeafValue(leafIndex: bigint): Promise<Fr | undefined> {
+  public async getL1ToL2LeafValue(leafIndex: bigint): Promise<Fr> {
     const timer = new Timer();
+    if (leafIndex > L1_TO_L2_MSG_TREE_LEAF_COUNT) {
+      throw new L1ToL2MessageIndexOutOfRangeError(Number(leafIndex));
+    }
     const leafValue = await this.db.getLeafValue(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, leafIndex);
+    assert(leafValue !== undefined, 'Unexpected null response from l1 to l2 message tree');
     // TODO: We need this for the hints. See class comment for more details.
     await this.db.getSiblingPath(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, leafIndex);
 
@@ -337,9 +349,13 @@ export class PublicTreesDB implements PublicStateDBInterface {
     return leafValue;
   }
 
-  public async getNoteHash(leafIndex: bigint): Promise<Fr | undefined> {
+  public async getNoteHash(leafIndex: bigint): Promise<Fr> {
     const timer = new Timer();
+    if (leafIndex > NOTE_HASH_TREE_LEAF_COUNT) {
+      throw new NoteHashIndexOutOfRangeError(Number(leafIndex));
+    }
     const leafValue = await this.db.getLeafValue(MerkleTreeId.NOTE_HASH_TREE, leafIndex);
+    assert(leafValue !== undefined, 'Unexpected null response from note hash tree');
     // TODO: We need this for the hints. See class comment for more details.
     await this.db.getSiblingPath(MerkleTreeId.NOTE_HASH_TREE, leafIndex);
 

package/src/public/public_errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Any known (and checked) error that can be thrown during public execution.
+ * Includes AvmExecutionErrors and SideEffectErrors.
+ *
+ * AvmSimulator catches any checked errors before returning a boolean "reverted".
+ * Unchecked errors are generally the result of a bug. They are propagated and
+ * ultimately will be the resonsibility of PublicProcessor to handle.
+ */
+export abstract class CheckedPublicExecutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CheckedPublicExecutionError';
+  }
+}

package/src/public/public_processor/guarded_merkle_tree.ts

@@ -11,6 +11,7 @@ import type {
   TreeInfo,
 } from '@aztec/stdlib/trees';
 import type { BlockHeader, StateReference } from '@aztec/stdlib/tx';
+import type { WorldStateRevision } from '@aztec/stdlib/world-state';
 
 /**
  * Wraps an instance of `MerkleTreeWriteOperations` to allow the sequencer to gate access.
@@ -88,6 +89,9 @@ export class GuardedMerkleTreeOperations implements MerkleTreeWriteOperations {
   getInitialHeader(): BlockHeader {
     return this.target.getInitialHeader();
   }
+  public getRevision(): WorldStateRevision {
+    return this.target.getRevision();
+  }
   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

@@ -40,8 +40,14 @@ import {
 } from '@aztec/telemetry-client';
 import { ForkCheckpoint } from '@aztec/world-state/native';
 
+import { AssertionError } from 'assert';
+
 import { PublicContractsDB, PublicTreesDB } from '../public_db_sources.js';
-import { type PublicTxSimulator, TelemetryPublicTxSimulator } from '../public_tx_simulator/index.js';
+import {
+  type PublicTxSimulator,
+  type PublicTxSimulatorConfig,
+  TelemetryPublicTxSimulator,
+} from '../public_tx_simulator/index.js';
 import { GuardedMerkleTreeOperations } from './guarded_merkle_tree.js';
 import { PublicProcessorMetrics } from './public_processor_metrics.js';
 
@@ -57,7 +63,6 @@ export class PublicProcessorFactory {
 
   /**
    * Creates a new instance of a PublicProcessor.
-   * @param historicalHeader - The header of a block previous to the one in which the tx is included.
    * @param globalVariables - The global variables for the block being processed.
    * @param skipFeeEnforcement - Allows disabling balance checks for fee estimations.
    * @returns A new instance of a PublicProcessor.
@@ -65,20 +70,23 @@ export class PublicProcessorFactory {
   public create(
     merkleTree: MerkleTreeWriteOperations,
     globalVariables: GlobalVariables,
-    skipFeeEnforcement: boolean,
-    clientInitiatedSimulation: boolean = false,
+    config: {
+      skipFeeEnforcement: boolean;
+      clientInitiatedSimulation: boolean;
+      proverId?: Fr;
+      maxDebugLogMemoryReads?: number;
+    },
   ): PublicProcessor {
     const contractsDB = new PublicContractsDB(this.contractDataSource);
 
     const guardedFork = new GuardedMerkleTreeOperations(merkleTree);
-    const publicTxSimulator = this.createPublicTxSimulator(
-      guardedFork,
-      contractsDB,
-      globalVariables,
-      /*doMerkleOperations=*/ true,
-      skipFeeEnforcement,
-      clientInitiatedSimulation,
-    );
+    const publicTxSimulator = this.createPublicTxSimulator(guardedFork, contractsDB, globalVariables, {
+      proverId: config.proverId,
+      doMerkleOperations: true,
+      skipFeeEnforcement: config.skipFeeEnforcement,
+      clientInitiatedSimulation: config.clientInitiatedSimulation,
+      maxDebugLogMemoryReads: config.maxDebugLogMemoryReads,
+    });
 
     return new PublicProcessor(
       globalVariables,
@@ -94,19 +102,9 @@ export class PublicProcessorFactory {
     merkleTree: MerkleTreeWriteOperations,
     contractsDB: PublicContractsDB,
     globalVariables: GlobalVariables,
-    doMerkleOperations: boolean,
-    skipFeeEnforcement: boolean,
-    clientInitiatedSimulation: boolean,
+    config?: Partial<PublicTxSimulatorConfig>,
   ): PublicTxSimulator {
-    return new TelemetryPublicTxSimulator(
-      merkleTree,
-      contractsDB,
-      globalVariables,
-      doMerkleOperations,
-      skipFeeEnforcement,
-      clientInitiatedSimulation,
-      this.telemetryClient,
-    );
+    return new TelemetryPublicTxSimulator(merkleTree, contractsDB, globalVariables, this.telemetryClient, config);
   }
 }
 
@@ -310,7 +308,7 @@ export class PublicProcessor implements Traceable {
         // Roll back state to start of TX before proceeding to next TX
         await checkpoint.revert();
         await this.guardedMerkleTree.getUnderlyingFork().revertAllCheckpoints();
-        const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+        const errorMessage = err instanceof Error || err instanceof AssertionError ? err.message : 'Unknown error';
         this.log.warn(`Failed to process tx ${txHash.toString()}: ${errorMessage} ${err?.stack}`);
         failed.push({ tx, error: err instanceof Error ? err : new Error(errorMessage) });
         returns.push(new NestedProcessReturnValues([]));

package/src/public/public_tx_simulator/cpp_public_tx_simulator.ts

@@ -0,0 +1,128 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { avmSimulateWithHintedDbs } from '@aztec/native';
+import { deserializeFromMessagePack } from '@aztec/stdlib/avm';
+import { SimulationError } from '@aztec/stdlib/errors';
+import type { MerkleTreeWriteOperations } from '@aztec/stdlib/trees';
+import type { GlobalVariables, Tx } from '@aztec/stdlib/tx';
+
+import type { ExecutorMetricsInterface } from '../executor_metrics_interface.js';
+import type { PublicContractsDB } from '../public_db_sources.js';
+import { type PublicTxResult, PublicTxSimulator, type PublicTxSimulatorConfig } from './public_tx_simulator.js';
+import type {
+  MeasuredPublicTxSimulatorInterface,
+  PublicTxSimulatorInterface,
+} from './public_tx_simulator_interface.js';
+
+/**
+ * C++ implementation of PublicTxSimulator using pre-collected hints.
+ * This implementation runs TS simulation first to collect all hints,
+ * then passes the complete AvmCircuitInputs (hints + public inputs)
+ * to C++ to run hinted simulation.
+ */
+export class CppPublicTxSimulatorHintedDbs extends PublicTxSimulator implements PublicTxSimulatorInterface {
+  protected override log: Logger;
+
+  constructor(
+    merkleTree: MerkleTreeWriteOperations,
+    contractsDB: PublicContractsDB,
+    globalVariables: GlobalVariables,
+    config?: Partial<PublicTxSimulatorConfig>,
+  ) {
+    super(merkleTree, contractsDB, globalVariables, config);
+    this.log = createLogger(`simulator:cpp_public_tx_simulator_hinted_dbs`);
+  }
+
+  /**
+   * Simulate a transaction's public portion using the C++ vm2 simulator with hinted DBs.
+   *
+   * This implementation:
+   * 1. Runs the full TypeScript simulation to generate AvmCircuitInputs (hints + public inputs)
+   * 2. Passes the complete AvmCircuitInputs to C++ to run hinted simulation
+   *
+   * @param tx - The transaction to simulate.
+   * @returns The result of the transaction's public execution.
+   */
+  public override async simulate(tx: Tx): Promise<PublicTxResult> {
+    const txHash = this.computeTxHash(tx);
+    this.log.debug(`C++ hinted DB simulation of ${tx.publicFunctionCalldata.length} public calls for tx ${txHash}`, {
+      txHash,
+    });
+
+    // First, run TS simulation to generate hints and public inputs
+    this.log.debug(`Running TS simulation for tx ${txHash}`);
+
+    let tsResult: PublicTxResult;
+    try {
+      // Run the full TypeScript simulation using the parent class
+      // This will modify the merkle tree with the transaction's state changes
+      tsResult = await super.simulate(tx);
+      this.log.debug(`TS simulation succeeded for tx ${txHash}`);
+    } catch (error: any) {
+      // If TS simulation fails, clear any partial contract additions and re-throw the error
+      this.contractsDB.clearContractsForTx();
+      throw error;
+    }
+
+    // Extract the full AvmCircuitInputs from the TS result
+    const avmCircuitInputs = tsResult.avmProvingRequest.inputs;
+
+    // Second, run C++ simulation with hinted DBs
+    this.log.debug(`Running C++ simulation with hinted DBs for tx ${txHash}`);
+
+    // Serialize to msgpack and call the C++ simulator
+    const inputBuffer = avmCircuitInputs.serializeWithMessagePack();
+
+    let resultBuffer: Buffer;
+    try {
+      resultBuffer = await avmSimulateWithHintedDbs(inputBuffer);
+    } catch (error: any) {
+      throw new SimulationError(`C++ hinted simulation failed: ${error.message}`, []);
+    }
+
+    // Deserialize the msgpack result
+    const _success = deserializeFromMessagePack<boolean>(resultBuffer);
+
+    this.log.debug(`C++ hinted simulation completed for tx ${txHash}`, {
+      txHash,
+      reverted: !tsResult.revertCode.isOK(),
+      tsGasUsed: tsResult.gasUsed.totalGas.l2Gas,
+      cppGasUsed: tsResult.gasUsed.totalGas.l2Gas,
+    });
+
+    // TODO(dbanks12): C++ should return PublicTxResult (or something similar)
+    return tsResult;
+  }
+}
+
+/**
+ * Class to record metrics for simulation.
+ *
+ * Note(dbanks12): We might not be able to collect all the same metrics in C++ as we do in TS!
+ * Unless we move some of the metrics collection to C++, we don't have inner functions exposed
+ * to TS for tracking.
+ */
+export class MeasuredCppPublicTxSimulatorHintedDbs
+  extends CppPublicTxSimulatorHintedDbs
+  implements MeasuredPublicTxSimulatorInterface
+{
+  constructor(
+    merkleTree: MerkleTreeWriteOperations,
+    contractsDB: PublicContractsDB,
+    globalVariables: GlobalVariables,
+    protected readonly metrics: ExecutorMetricsInterface,
+    config?: Partial<PublicTxSimulatorConfig>,
+  ) {
+    super(merkleTree, contractsDB, globalVariables, config);
+  }
+
+  public override async simulate(tx: Tx, txLabel: string = 'unlabeledTx'): Promise<PublicTxResult> {
+    this.metrics.startRecordingTxSimulation(txLabel);
+    let result: PublicTxResult | undefined;
+    try {
+      result = await super.simulate(tx);
+    } finally {
+      this.metrics.stopRecordingTxSimulation(txLabel, result?.revertCode);
+    }
+    return result;
+  }
+}

package/src/public/public_tx_simulator/index.ts

@@ -1,2 +1,3 @@
 export * from './public_tx_simulator.js';
+export type { PublicTxSimulatorInterface } from './public_tx_simulator_interface.js';
 export { TelemetryPublicTxSimulator } from './telemetry_public_tx_simulator.js';

package/src/public/public_tx_simulator/measured_public_tx_simulator.ts

@@ -10,22 +10,26 @@ import type { ExecutorMetricsInterface } from '../executor_metrics_interface.js'
 import type { PublicContractsDB } from '../public_db_sources.js';
 import type { PublicPersistableStateManager } from '../state_manager/state_manager.js';
 import { PublicTxContext } from './public_tx_context.js';
-import { type ProcessedPhase, type PublicTxResult, PublicTxSimulator } from './public_tx_simulator.js';
+import {
+  type ProcessedPhase,
+  type PublicTxResult,
+  PublicTxSimulator,
+  type PublicTxSimulatorConfig,
+} from './public_tx_simulator.js';
+import type { MeasuredPublicTxSimulatorInterface } from './public_tx_simulator_interface.js';
 
 /**
  * A public tx simulator that tracks miscellaneous simulation metrics without telemetry.
  */
-export class MeasuredPublicTxSimulator extends PublicTxSimulator {
+export class MeasuredPublicTxSimulator extends PublicTxSimulator implements MeasuredPublicTxSimulatorInterface {
   constructor(
     merkleTree: MerkleTreeWriteOperations,
     contractsDB: PublicContractsDB,
     globalVariables: GlobalVariables,
-    doMerkleOperations: boolean = false,
-    skipFeeEnforcement: boolean = false,
-    clientInitiatedSimulation: boolean = false,
     protected readonly metrics: ExecutorMetricsInterface,
+    config?: Partial<PublicTxSimulatorConfig>,
   ) {
-    super(merkleTree, contractsDB, globalVariables, doMerkleOperations, skipFeeEnforcement, clientInitiatedSimulation);
+    super(merkleTree, contractsDB, globalVariables, config);
   }
 
   public override async simulate(tx: Tx, txLabel: string = 'unlabeledTx'): Promise<PublicTxResult> {
@@ -45,11 +49,10 @@ export class MeasuredPublicTxSimulator extends PublicTxSimulator {
     this.metrics.recordPrivateEffectsInsertion(timer.us(), 'non-revertible');
   }
 
-  protected override async insertRevertiblesFromPrivate(context: PublicTxContext, tx: Tx): Promise<boolean> {
+  protected override async insertRevertiblesFromPrivate(context: PublicTxContext, tx: Tx) {
     const timer = new Timer();
-    const result = await super.insertRevertiblesFromPrivate(context, tx);
+    await super.insertRevertiblesFromPrivate(context, tx);
     this.metrics.recordPrivateEffectsInsertion(timer.us(), 'revertible');
-    return result;
   }
 
   protected override async simulatePhase(phase: TxExecutionPhase, context: PublicTxContext): Promise<ProcessedPhase> {