@aztec/simulator 0.40.1 → 0.42.0

package/src/public/execution.ts

@@ -1,16 +1,17 @@
 import { type SimulationError, type UnencryptedFunctionL2Logs } from '@aztec/circuit-types';
 import {
+  type AvmExecutionHints,
   type ContractStorageRead,
   type ContractStorageUpdateRequest,
   type Fr,
   type L2ToL1Message,
+  type LogHash,
   type NoteHash,
   type Nullifier,
   type PublicCallRequest,
   PublicDataRead,
   PublicDataUpdateRequest,
   type ReadRequest,
-  type SideEffect,
 } from '@aztec/circuits.js';
 import { computePublicDataTreeLeafSlot, computePublicDataTreeValue } from '@aztec/circuits.js/hash';
 
@@ -34,10 +35,14 @@ export interface PublicExecutionResult {
   endSideEffectCounter: Fr;
   /** The new nullifiers to be inserted into the nullifier tree. */
   newNullifiers: Nullifier[];
+  /** The note hash read requests emitted in this call. */
+  noteHashReadRequests: ReadRequest[];
   /** The nullifier read requests emitted in this call. */
   nullifierReadRequests: ReadRequest[];
   /** The nullifier non existent read requests emitted in this call. */
   nullifierNonExistentReadRequests: ReadRequest[];
+  /** L1 to L2 message read requests emitted in this call. */
+  l1ToL2MsgReadRequests: ReadRequest[];
   /** The contract storage reads performed by the function. */
   contractStorageReads: ContractStorageRead[];
   /** The contract storage update requests performed by the function. */
@@ -48,41 +53,39 @@ export interface PublicExecutionResult {
    * The hashed logs with side effect counter.
    * Note: required as we don't track the counter anywhere else.
    */
-  unencryptedLogsHashes: SideEffect[];
+  unencryptedLogsHashes: LogHash[];
   /**
    * Unencrypted logs emitted during execution of this function call.
    * Note: These are preimages to `unencryptedLogsHashes`.
    */
   unencryptedLogs: UnencryptedFunctionL2Logs;
-  /**
-   * Length of the unencrypted log preimages emitted in this function call.
-   */
-  unencryptedLogPreimagesLength: Fr;
   /**
    * Unencrypted logs emitted during this call AND any nested calls.
    * Useful for maintaining correct ordering in ts.
    */
   allUnencryptedLogs: UnencryptedFunctionL2Logs;
-  /**
-   * Whether the execution reverted.
-   */
+  /** Whether the execution reverted. */
   reverted: boolean;
-  /**
-   * The revert reason if the execution reverted.
-   */
-  revertReason: SimulationError | undefined;
+  /** The revert reason if the execution reverted. */
+  revertReason?: SimulationError;
   /** How much gas was available for this public execution. */
   startGasLeft: Gas;
   /** How much gas was left after this public execution. */
   endGasLeft: Gas;
   /** Transaction fee set for this tx. */
   transactionFee: Fr;
+  /** Bytecode used for this execution. */
+  bytecode?: Buffer;
+  /** Calldata used for this execution. */
+  calldata: Fr[];
+  /** Hints for proving AVM execution. */
+  avmHints: AvmExecutionHints;
 }
 
 /**
  * The execution of a public function.
  */
-export type PublicExecution = Pick<PublicCallRequest, 'contractAddress' | 'functionData' | 'callContext' | 'args'>;
+export type PublicExecution = Pick<PublicCallRequest, 'contractAddress' | 'functionSelector' | 'callContext' | 'args'>;
 
 /**
  * Returns if the input is a public execution result and not just a public execution.

package/src/public/executor.ts

@@ -1,270 +1,14 @@
-import { UnencryptedFunctionL2Logs } from '@aztec/circuit-types';
-import {
-  Fr,
-  Gas,
-  type GlobalVariables,
-  type Header,
-  type Nullifier,
-  PublicCircuitPublicInputs,
-  type TxContext,
-} from '@aztec/circuits.js';
+import { Fr, type Gas, type GlobalVariables, type Header, type Nullifier, type TxContext } from '@aztec/circuits.js';
 import { createDebugLogger } from '@aztec/foundation/log';
 
-import { spawn } from 'child_process';
-import fs from 'fs/promises';
-import path from 'path';
-
-import { Oracle, acvm, extractCallStack, witnessMapToFields } from '../acvm/index.js';
 import { AvmContext } from '../avm/avm_context.js';
 import { AvmMachineState } from '../avm/avm_machine_state.js';
 import { AvmSimulator } from '../avm/avm_simulator.js';
 import { HostStorage } from '../avm/journal/host_storage.js';
 import { AvmPersistableStateManager } from '../avm/journal/index.js';
-import { AcirSimulator } from '../client/simulator.js';
-import { ExecutionError, createSimulationError } from '../common/errors.js';
-import { SideEffectCounter } from '../common/index.js';
-import { PackedValuesCache } from '../common/packed_values_cache.js';
-import { type CommitmentsDB, type PublicContractsDB, type PublicStateDB } from './db.js';
+import { type CommitmentsDB, type PublicContractsDB, type PublicStateDB } from './db_interfaces.js';
 import { type PublicExecution, type PublicExecutionResult, checkValidStaticCall } from './execution.js';
-import { PublicExecutionContext } from './public_execution_context.js';
-import { convertAvmResultsToPxResult, createAvmExecutionEnvironment, isAvmBytecode } from './transitional_adaptors.js';
-
-/**
- * Execute a public function and return the execution result.
- */
-export async function executePublicFunction(
-  context: PublicExecutionContext,
-  nested: boolean,
-): Promise<PublicExecutionResult> {
-  const bytecode = await context.contractsDb.getBytecode(
-    context.execution.contractAddress,
-    context.execution.functionData.selector,
-  );
-  if (!bytecode) {
-    throw new Error(
-      `Bytecode not found for ${context.execution.contractAddress}:${context.execution.functionData.selector}`,
-    );
-  }
-
-  if (isAvmBytecode(bytecode)) {
-    return await executeTopLevelPublicFunctionAvm(context, bytecode);
-  } else {
-    return await executePublicFunctionAcvm(context, bytecode, nested);
-  }
-}
-
-/**
- * Execute a top-level public function call (the first call in an enqueued-call/execution-request) in the AVM.
- * Translate the results back to the PublicExecutionResult format.
- */
-async function executeTopLevelPublicFunctionAvm(
-  executionContext: PublicExecutionContext,
-  bytecode: Buffer,
-): Promise<PublicExecutionResult> {
-  const address = executionContext.execution.contractAddress;
-  const selector = executionContext.execution.functionData.selector;
-  const startGas = executionContext.availableGas;
-  const log = createDebugLogger('aztec:simulator:public_execution');
-  log.verbose(`[AVM] Executing public external function ${address.toString()}:${selector}.`);
-
-  // Temporary code to construct the AVM context
-  // These data structures will permeate across the simulator when the public executor is phased out
-  const hostStorage = new HostStorage(
-    executionContext.stateDb,
-    executionContext.contractsDb,
-    executionContext.commitmentsDb,
-  );
-
-  // TODO(6207): add sideEffectCounter to persistableState construction
-  // or modify the PersistableStateManager to manage rollbacks across enqueued-calls and transactions.
-  const worldStateJournal = new AvmPersistableStateManager(hostStorage);
-  const startSideEffectCounter = executionContext.execution.callContext.sideEffectCounter;
-  for (const nullifier of executionContext.pendingNullifiers) {
-    worldStateJournal.nullifiers.cache.appendSiloed(nullifier.value);
-  }
-  worldStateJournal.trace.accessCounter = startSideEffectCounter;
-
-  const executionEnv = createAvmExecutionEnvironment(
-    executionContext.execution,
-    executionContext.header,
-    executionContext.globalVariables,
-    executionContext.gasSettings,
-    executionContext.transactionFee,
-  );
-
-  const machineState = new AvmMachineState(startGas);
-  const avmContext = new AvmContext(worldStateJournal, executionEnv, machineState);
-  const simulator = new AvmSimulator(avmContext);
-
-  const avmResult = await simulator.executeBytecode(bytecode);
-
-  // Commit the journals state to the DBs since this is a top-level execution.
-  // Observe that this will write all the state changes to the DBs, not only the latest for each slot.
-  // However, the underlying DB keep a cache and will only write the latest state to disk.
-  await avmContext.persistableState.publicStorage.commitToDB();
-
-  log.verbose(
-    `[AVM] ${address.toString()}:${selector} returned, reverted: ${avmResult.reverted}, reason: ${
-      avmResult.revertReason
-    }.`,
-  );
-
-  return convertAvmResultsToPxResult(
-    avmResult,
-    startSideEffectCounter,
-    executionContext.execution,
-    startGas,
-    avmContext,
-  );
-}
-
-async function executePublicFunctionAcvm(
-  context: PublicExecutionContext,
-  acir: Buffer,
-  nested: boolean,
-): Promise<PublicExecutionResult> {
-  const execution = context.execution;
-  const { contractAddress, functionData } = execution;
-  const selector = functionData.selector;
-  const log = createDebugLogger('aztec:simulator:public_execution');
-  log.verbose(`[ACVM] Executing public external function ${contractAddress.toString()}:${selector}.`);
-
-  const initialWitness = context.getInitialWitness();
-  const acvmCallback = new Oracle(context);
-
-  const { partialWitness, returnWitnessMap, reverted, revertReason } = await (async () => {
-    try {
-      const result = await acvm(await AcirSimulator.getSolver(), acir, initialWitness, acvmCallback);
-      return {
-        partialWitness: result.partialWitness,
-        returnWitnessMap: result.returnWitness,
-        reverted: false,
-        revertReason: undefined,
-      };
-    } catch (err_) {
-      const err = err_ as Error;
-      const ee = new ExecutionError(
-        err.message,
-        {
-          contractAddress,
-          functionSelector: selector,
-        },
-        extractCallStack(err),
-        { cause: err },
-      );
-
-      if (nested) {
-        // If we're nested, throw the error so the parent can handle it
-        throw ee;
-      } else {
-        return {
-          partialWitness: undefined,
-          returnWitnessMap: undefined,
-          reverted: true,
-          revertReason: createSimulationError(ee),
-        };
-      }
-    }
-  })();
-
-  if (reverted) {
-    return {
-      execution,
-      returnValues: [],
-      newNoteHashes: [],
-      newL2ToL1Messages: [],
-      // TODO (side effects) get these values in the revert case from the vm
-      startSideEffectCounter: Fr.ZERO,
-      endSideEffectCounter: Fr.ZERO,
-      newNullifiers: [],
-      nullifierReadRequests: [],
-      nullifierNonExistentReadRequests: [],
-      contractStorageReads: [],
-      contractStorageUpdateRequests: [],
-      nestedExecutions: [],
-      unencryptedLogsHashes: [],
-      unencryptedLogs: UnencryptedFunctionL2Logs.empty(),
-      unencryptedLogPreimagesLength: new Fr(4n), // empty logs have len 4
-      allUnencryptedLogs: UnencryptedFunctionL2Logs.empty(),
-      reverted,
-      revertReason,
-      startGasLeft: context.availableGas,
-      endGasLeft: Gas.empty(),
-      transactionFee: context.transactionFee,
-    };
-  }
-
-  if (!partialWitness) {
-    throw new Error('No partial witness returned from ACVM');
-  }
-
-  const returnWitness = witnessMapToFields(returnWitnessMap);
-  const {
-    returnsHash,
-    nullifierReadRequests: nullifierReadRequestsPadded,
-    nullifierNonExistentReadRequests: nullifierNonExistentReadRequestsPadded,
-    newL2ToL1Msgs,
-    newNoteHashes: newNoteHashesPadded,
-    newNullifiers: newNullifiersPadded,
-    startSideEffectCounter,
-    endSideEffectCounter,
-    unencryptedLogsHashes: unencryptedLogsHashesPadded,
-    unencryptedLogPreimagesLength,
-  } = PublicCircuitPublicInputs.fromFields(returnWitness);
-  const returnValues = await context.unpackReturns(returnsHash);
-
-  const nullifierReadRequests = nullifierReadRequestsPadded.filter(v => !v.isEmpty());
-  const nullifierNonExistentReadRequests = nullifierNonExistentReadRequestsPadded.filter(v => !v.isEmpty());
-  const newL2ToL1Messages = newL2ToL1Msgs.filter(v => !v.isEmpty());
-  const newNoteHashes = newNoteHashesPadded.filter(v => !v.isEmpty());
-  const newNullifiers = newNullifiersPadded.filter(v => !v.isEmpty());
-  const unencryptedLogsHashes = unencryptedLogsHashesPadded.filter(v => !v.isEmpty());
-
-  const { contractStorageReads, contractStorageUpdateRequests } = context.getStorageActionData();
-
-  log.debug(
-    `Contract storage reads: ${contractStorageReads
-      .map(r => r.toFriendlyJSON() + ` - sec: ${r.sideEffectCounter}`)
-      .join(', ')}`,
-  );
-  log.debug(
-    `Contract storage update requests: ${contractStorageUpdateRequests
-      .map(r => r.toFriendlyJSON() + ` - sec: ${r.sideEffectCounter}`)
-      .join(', ')}`,
-  );
-
-  const nestedExecutions = context.getNestedExecutions();
-  const unencryptedLogs = context.getUnencryptedLogs();
-  const allUnencryptedLogs = context.getAllUnencryptedLogs();
-
-  // TODO(palla/gas): We should be loading these values from the returned PublicCircuitPublicInputs
-  const startGasLeft = context.availableGas;
-  const endGasLeft = context.availableGas; // No gas consumption in non-AVM
-
-  return {
-    execution,
-    newNoteHashes,
-    newL2ToL1Messages,
-    newNullifiers,
-    startSideEffectCounter,
-    endSideEffectCounter,
-    nullifierReadRequests,
-    nullifierNonExistentReadRequests,
-    contractStorageReads,
-    contractStorageUpdateRequests,
-    returnValues,
-    nestedExecutions,
-    unencryptedLogsHashes,
-    unencryptedLogs,
-    unencryptedLogPreimagesLength,
-    allUnencryptedLogs,
-    reverted: false,
-    revertReason: undefined,
-    startGasLeft,
-    endGasLeft,
-    transactionFee: context.transactionFee,
-  };
-}
+import { convertAvmResultsToPxResult, createAvmExecutionEnvironment } from './transitional_adaptors.js';
 
 /**
  * Handles execution of public functions.
@@ -277,7 +21,8 @@ export class PublicExecutor {
     private readonly header: Header,
   ) {}
 
-  private readonly log = createDebugLogger('aztec:simulator:public_executor');
+  static readonly log = createDebugLogger('aztec:simulator:public_executor');
+
   /**
    * Executes a public execution request.
    * @param execution - The execution to run.
@@ -293,28 +38,60 @@ export class PublicExecutor {
     transactionFee: Fr = Fr.ZERO,
     sideEffectCounter: number = 0,
   ): Promise<PublicExecutionResult> {
-    // Functions can request to pack arguments before calling other functions.
-    // We use this cache to hold the packed arguments.
-    const packedArgs = PackedValuesCache.create([]);
+    const address = execution.contractAddress;
+    const selector = execution.functionSelector;
+    const startGas = availableGas;
+
+    PublicExecutor.log.verbose(`[AVM] Executing public external function ${address.toString()}:${selector}.`);
+
+    // Temporary code to construct the AVM context
+    // These data structures will permeate across the simulator when the public executor is phased out
+    const hostStorage = new HostStorage(this.stateDb, this.contractsDb, this.commitmentsDb);
+
+    const startSideEffectCounter = sideEffectCounter;
+    const worldStateJournal = new AvmPersistableStateManager(hostStorage);
+    for (const nullifier of pendingNullifiers) {
+      worldStateJournal.nullifiers.cache.appendSiloed(nullifier.value);
+    }
+    // All the subsequent side effects will have a counter larger than the call's start counter.
+    worldStateJournal.trace.accessCounter = startSideEffectCounter + 1;
 
-    const context = new PublicExecutionContext(
+    const executionEnv = createAvmExecutionEnvironment(
       execution,
       this.header,
       globalVariables,
-      packedArgs,
-      new SideEffectCounter(sideEffectCounter),
-      this.stateDb,
-      this.contractsDb,
-      this.commitmentsDb,
-      availableGas,
-      transactionFee,
       txContext.gasSettings,
-      pendingNullifiers,
+      transactionFee,
+    );
+
+    const machineState = new AvmMachineState(startGas);
+    const avmContext = new AvmContext(worldStateJournal, executionEnv, machineState);
+    const simulator = new AvmSimulator(avmContext);
+    const avmResult = await simulator.execute();
+
+    // Commit the journals state to the DBs since this is a top-level execution.
+    // Observe that this will write all the state changes to the DBs, not only the latest for each slot.
+    // However, the underlying DB keep a cache and will only write the latest state to disk.
+    await avmContext.persistableState.publicStorage.commitToDB();
+
+    PublicExecutor.log.verbose(
+      `[AVM] ${address.toString()}:${selector} returned, reverted: ${avmResult.reverted}, reason: ${
+        avmResult.revertReason
+      }.`,
     );
 
-    const executionResult = await executePublicFunction(context, /*nested=*/ false);
+    const executionResult = convertAvmResultsToPxResult(
+      avmResult,
+      startSideEffectCounter,
+      execution,
+      startGas,
+      avmContext,
+      simulator.getBytecode(),
+    );
 
-    if (executionResult.execution.callContext.isStaticCall) {
+    // TODO(https://github.com/AztecProtocol/aztec-packages/issues/5818): is this really needed?
+    // should already be handled in simulation.
+    if (execution.callContext.isStaticCall) {
       checkValidStaticCall(
         executionResult.newNoteHashes,
         executionResult.newNullifiers,
@@ -326,121 +103,4 @@ export class PublicExecutor {
 
     return executionResult;
   }
-
-  /**
-   * These functions are currently housed in the temporary executor as it relies on access to
-   * oracles like the contractsDB and this is the least intrusive way to achieve this.
-   * When we remove this executor(tracking issue #4792) and have an interface that is compatible with the kernel circuits,
-   * this will be moved to sequencer-client/prover.
-   */
-
-  /**
-   * Generates a proof for an associated avm execution. This is currently only used for testing purposes,
-   * as proof generation is not fully complete in the AVM yet.
-   * @param execution - The execution to run.
-   * @returns An AVM proof and the verification key.
-   */
-  public async getAvmProof(avmExecution: PublicExecution): Promise<Buffer[]> {
-    // The paths for the barretenberg binary and the write path are hardcoded for now.
-    const bbPath = path.resolve('../../barretenberg/cpp');
-    const artifactsPath = path.resolve('target');
-
-    // Create the directory if it does not exist
-    await fs.rm(artifactsPath, { recursive: true, force: true });
-    await fs.mkdir(artifactsPath, { recursive: true });
-
-    const calldataPath = path.join(artifactsPath, 'calldata.bin');
-    const bytecodePath = path.join(artifactsPath, 'avm_bytecode.bin');
-    const proofPath = path.join(artifactsPath, 'proof');
-
-    const { args, functionData, contractAddress } = avmExecution;
-    const bytecode = await this.contractsDb.getBytecode(contractAddress, functionData.selector);
-    // Write call data and bytecode to files.
-    await fs.writeFile(
-      calldataPath,
-      args.map(c => c.toBuffer()),
-    );
-    await fs.writeFile(bytecodePath, bytecode!);
-
-    const bbExec = path.join(bbPath, 'build', 'bin', 'bb');
-    const bbArgs = ['avm_prove', '-b', bytecodePath, '-d', calldataPath, '-o', proofPath];
-    this.log.debug(`calling '${bbExec} ${bbArgs.join(' ')}'`);
-    const bbBinary = spawn(bbExec, bbArgs);
-
-    // The binary writes the proof and the verification key to the write path.
-    return new Promise((resolve, reject) => {
-      let stdout: string = '';
-      let stderr: string = '';
-
-      bbBinary.on('close', () => {
-        this.log.verbose(`Proof generation complete. Reading proof and vk from ${proofPath}.`);
-        return resolve(Promise.all([fs.readFile(proofPath), fs.readFile(path.join(artifactsPath, 'vk'))]));
-      });
-
-      // Catch stdout.
-      bbBinary.stdout.on('data', (data: Buffer) => {
-        stdout += data.toString();
-      });
-      bbBinary.stdout.on('end', () => {
-        if (stdout.length > 0) {
-          this.log.debug(`stdout: ${stdout}`);
-        }
-      });
-
-      // Catch stderr.
-      bbBinary.stderr.on('data', (data: Buffer) => {
-        stderr += data.toString();
-      });
-      bbBinary.stderr.on('end', () => {
-        if (stderr.length > 0) {
-          this.log.warn(`stderr: ${stderr}`);
-        }
-      });
-
-      // Catch and propagate errors from spawning
-      bbBinary.on('error', err => {
-        reject(err);
-      });
-    });
-  }
-
-  /**
-   * Verifies an AVM proof. This function is currently only used for testing purposes, as verification
-   * is not fully complete in the AVM yet.
-   * @param vk - The verification key to use.
-   * @param proof - The proof to verify.
-   * @returns True if the proof is valid, false otherwise.
-   */
-  async verifyAvmProof(vk: Buffer, proof: Buffer): Promise<boolean> {
-    // The relative paths for the barretenberg binary and the write path are hardcoded for now.
-    const bbPath = path.resolve('../../barretenberg/cpp');
-    const artifactsPath = path.resolve('./target');
-
-    const vkPath = path.join(artifactsPath, 'vk');
-    const proofPath = path.join(artifactsPath, 'proof');
-
-    // Write the verification key and the proof to files.
-    await fs.writeFile(vkPath, vk);
-    await fs.writeFile(proofPath, proof);
-
-    const bbExec = path.join(bbPath, 'build', 'bin', 'bb');
-    const bbArgs = ['avm_verify', '-p', proofPath];
-    this.log.debug(`calling '${bbPath} ${bbArgs.join(' ')}'`);
-    const bbBinary = spawn(bbExec, bbArgs);
-
-    // The binary prints to stdout 1 if the proof is valid and 0 if it is not.
-    return new Promise((resolve, reject) => {
-      let result = Buffer.alloc(0);
-      bbBinary.stdout.on('data', data => {
-        result += data;
-      });
-      bbBinary.on('close', () => {
-        resolve(result.toString() === '1');
-      });
-      // Catch and propagate errors from spawning
-      bbBinary.on('error', err => {
-        reject(err);
-      });
-    });
-  }
 }

package/src/public/fee_payment.ts

@@ -0,0 +1,26 @@
+import { GAS_TOKEN_ADDRESS } from '@aztec/circuits.js';
+import { computePublicDataTreeLeafSlot } from '@aztec/circuits.js/hash';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+import { GasTokenArtifact } from '@aztec/protocol-contracts/gas-token';
+
+import { computeSlotForMapping } from '../utils.js';
+
+/**
+ * Computes the storage slot within the gas token contract for the balance of the fee payer.
+ */
+export function computeFeePayerBalanceStorageSlot(feePayer: AztecAddress) {
+  return computeSlotForMapping(GasTokenArtifact.storageLayout.balances.slot, feePayer);
+}
+
+/**
+ * Computes the leaf slot in the public data tree for the balance of the fee payer in the gas token.
+ */
+export function computeFeePayerBalanceLeafSlot(feePayer: AztecAddress): Fr {
+  if (feePayer.isZero()) {
+    return Fr.ZERO;
+  }
+  const gasToken = AztecAddress.fromBigInt(GAS_TOKEN_ADDRESS);
+  const balanceSlot = computeFeePayerBalanceStorageSlot(feePayer);
+  return computePublicDataTreeLeafSlot(gasToken, balanceSlot);
+}

package/src/public/hints_builder.ts

@@ -3,7 +3,7 @@ import {
   type Fr,
   type MAX_NEW_NULLIFIERS_PER_TX,
   type MAX_NULLIFIER_NON_EXISTENT_READ_REQUESTS_PER_TX,
-  type MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+  MAX_NULLIFIER_READ_REQUESTS_PER_TX,
   type MAX_PUBLIC_DATA_HINTS,
   type MAX_PUBLIC_DATA_READS_PER_TX,
   type MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
@@ -17,6 +17,7 @@ import {
   type PublicDataUpdateRequest,
   type ScopedReadRequest,
   buildNullifierNonExistentReadRequestHints,
+  buildPublicDataHint,
   buildPublicDataHints,
   buildPublicDataReadRequestHints,
   buildSiloedNullifierReadRequestHints,
@@ -27,11 +28,19 @@ import { type IndexedTreeId, type MerkleTreeOperations } from '@aztec/world-stat
 export class HintsBuilder {
   constructor(private db: MerkleTreeOperations) {}
 
-  getNullifierReadRequestHints(
+  async getNullifierReadRequestHints(
     nullifierReadRequests: Tuple<ScopedReadRequest, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
     pendingNullifiers: Tuple<Nullifier, typeof MAX_NEW_NULLIFIERS_PER_TX>,
   ) {
-    return buildSiloedNullifierReadRequestHints(this, nullifierReadRequests, pendingNullifiers);
+    return (
+      await buildSiloedNullifierReadRequestHints(
+        this,
+        nullifierReadRequests,
+        pendingNullifiers,
+        MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+        MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+      )
+    ).hints;
   }
 
   getNullifierNonExistentReadRequestHints(
@@ -48,6 +57,11 @@ export class HintsBuilder {
     return buildPublicDataHints(this, publicDataReads, publicDataUpdateRequests);
   }
 
+  getPublicDataHint(dataAction: PublicDataRead | PublicDataUpdateRequest | bigint) {
+    const slot = typeof dataAction === 'bigint' ? dataAction : dataAction.leafSlot.toBigInt();
+    return buildPublicDataHint(this, slot);
+  }
+
   getPublicDataReadRequestHints(
     publicDataReads: Tuple<PublicDataRead, typeof MAX_PUBLIC_DATA_READS_PER_TX>,
     publicDataUpdateRequests: Tuple<PublicDataUpdateRequest, typeof MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX>,

package/src/public/index.ts

@@ -1,4 +1,4 @@
-export * from './db.js';
+export * from './db_interfaces.js';
 export {
   type PublicExecution,
   type PublicExecutionResult,
@@ -8,7 +8,9 @@ export {
 } from './execution.js';
 export { PublicExecutor } from './executor.js';
 export { PublicProcessor, PublicProcessorFactory } from './public_processor.js';
-export * from './public_executor.js';
+export * from './public_db_sources.js';
 export * from './abstract_phase_manager.js';
 export * from './public_kernel_circuit_simulator.js';
 export * from './public_kernel.js';
+export { HintsBuilder } from './hints_builder.js';
+export * from './fee_payment.js';

package/src/public/phase_manager_factory.ts

@@ -5,7 +5,7 @@ import { type MerkleTreeOperations } from '@aztec/world-state';
 
 import { type AbstractPhaseManager, PublicKernelPhase } from './abstract_phase_manager.js';
 import { AppLogicPhaseManager } from './app_logic_phase_manager.js';
-import { type ContractsDataSourcePublicDB } from './public_executor.js';
+import { type ContractsDataSourcePublicDB } from './public_db_sources.js';
 import { type PublicKernelCircuitSimulator } from './public_kernel_circuit_simulator.js';
 import { SetupPhaseManager } from './setup_phase_manager.js';
 import { TailPhaseManager } from './tail_phase_manager.js';

package/src/public/{public_executor.ts → public_db_sources.ts}

@@ -145,11 +145,12 @@ export class WorldStatePublicDB implements PublicStateDB {
    * @param contract - Owner of the storage.
    * @param slot - Slot to read in the contract storage.
    * @param newValue - The new value to store.
+   * @returns The slot of the written leaf in the public data tree.
    */
-  public storageWrite(contract: AztecAddress, slot: Fr, newValue: Fr): Promise<void> {
+  public storageWrite(contract: AztecAddress, slot: Fr, newValue: Fr): Promise<bigint> {
     const index = computePublicDataTreeLeafSlot(contract, slot).value;
     this.uncommittedWriteCache.set(index, newValue);
-    return Promise.resolve();
+    return Promise.resolve(index);
   }
 
   /**