@aztec/simulator 0.42.0 → 0.44.0

package/src/public/index.ts

@@ -1,16 +1,10 @@
+export * from './abstract_phase_manager.js';
 export * from './db_interfaces.js';
-export {
-  type PublicExecution,
-  type PublicExecutionResult,
-  isPublicExecutionResult,
-  collectPublicDataReads,
-  collectPublicDataUpdateRequests,
-} from './execution.js';
+export { isPublicExecutionResult, type PublicExecution, type PublicExecutionResult } from './execution.js';
 export { PublicExecutor } from './executor.js';
-export { PublicProcessor, PublicProcessorFactory } from './public_processor.js';
+export * from './fee_payment.js';
+export { HintsBuilder } from './hints_builder.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';
+export * from './public_kernel_circuit_simulator.js';
+export { PublicProcessor, PublicProcessorFactory } from './public_processor.js';

package/src/public/phase_manager_factory.ts

@@ -1,9 +1,9 @@
-import { type Tx } from '@aztec/circuit-types';
+import { PublicKernelType, type Tx } from '@aztec/circuit-types';
 import { type GlobalVariables, type Header, type PublicKernelCircuitPublicInputs } from '@aztec/circuits.js';
 import { type PublicExecutor, type PublicStateDB } from '@aztec/simulator';
 import { type MerkleTreeOperations } from '@aztec/world-state';
 
-import { type AbstractPhaseManager, PublicKernelPhase } from './abstract_phase_manager.js';
+import { type AbstractPhaseManager } from './abstract_phase_manager.js';
 import { AppLogicPhaseManager } from './app_logic_phase_manager.js';
 import { type ContractsDataSourcePublicDB } from './public_db_sources.js';
 import { type PublicKernelCircuitSimulator } from './public_kernel_circuit_simulator.js';
@@ -12,7 +12,7 @@ import { TailPhaseManager } from './tail_phase_manager.js';
 import { TeardownPhaseManager } from './teardown_phase_manager.js';
 
 export class PhaseDidNotChangeError extends Error {
-  constructor(phase: PublicKernelPhase) {
+  constructor(phase: PublicKernelType) {
     super(`Tried to advance the phase from [${phase}] when the circuit still needs [${phase}]`);
   }
 }
@@ -84,7 +84,7 @@ export class PhaseManagerFactory {
     if (output.needsSetup) {
       throw new CannotTransitionToSetupError();
     } else if (output.needsAppLogic) {
-      if (currentPhaseManager.phase === PublicKernelPhase.APP_LOGIC) {
+      if (currentPhaseManager.phase === PublicKernelType.APP_LOGIC) {
         throw new PhaseDidNotChangeError(currentPhaseManager.phase);
       }
       return new AppLogicPhaseManager(
@@ -97,7 +97,7 @@ export class PhaseManagerFactory {
         publicStateDB,
       );
     } else if (output.needsTeardown) {
-      if (currentPhaseManager.phase === PublicKernelPhase.TEARDOWN) {
+      if (currentPhaseManager.phase === PublicKernelType.TEARDOWN) {
         throw new PhaseDidNotChangeError(currentPhaseManager.phase);
       }
       return new TeardownPhaseManager(
@@ -109,7 +109,7 @@ export class PhaseManagerFactory {
         publicContractsDB,
         publicStateDB,
       );
-    } else if (currentPhaseManager.phase !== PublicKernelPhase.TAIL) {
+    } else if (currentPhaseManager.phase !== PublicKernelType.TAIL) {
       return new TailPhaseManager(
         db,
         publicExecutor,

package/src/public/public_db_sources.ts

@@ -1,10 +1,11 @@
 import { MerkleTreeId, NullifierMembershipWitness, type Tx } from '@aztec/circuit-types';
+import { type PublicDBAccessStats } from '@aztec/circuit-types/stats';
 import {
   type AztecAddress,
   ContractClassRegisteredEvent,
   ContractInstanceDeployedEvent,
   Fr,
-  type FunctionSelector,
+  FunctionSelector,
   type L1_TO_L2_MSG_TREE_HEIGHT,
   type NULLIFIER_TREE_HEIGHT,
   type NullifierLeafPreimage,
@@ -12,7 +13,8 @@ import {
 } from '@aztec/circuits.js';
 import { computeL1ToL2MessageNullifier, computePublicDataTreeLeafSlot } from '@aztec/circuits.js/hash';
 import { createDebugLogger } from '@aztec/foundation/log';
-import { getCanonicalClassRegistererAddress } from '@aztec/protocol-contracts/class-registerer';
+import { Timer } from '@aztec/foundation/timer';
+import { ClassRegistererAddress } from '@aztec/protocol-contracts/class-registerer';
 import {
   type CommitmentsDB,
   MessageLoadOracleInputs,
@@ -45,7 +47,7 @@ export class ContractsDataSourcePublicDB implements PublicContractsDB {
   public addNewContracts(tx: Tx): Promise<void> {
     // Extract contract class and instance data from logs and add to cache for this block
     const logs = tx.unencryptedLogs.unrollLogs();
-    ContractClassRegisteredEvent.fromLogs(logs, getCanonicalClassRegistererAddress()).forEach(e => {
+    ContractClassRegisteredEvent.fromLogs(logs, ClassRegistererAddress).forEach(e => {
       this.log.debug(`Adding class ${e.contractClassId.toString()} to public execution contract cache`);
       this.classCache.set(e.contractClassId.toString(), e.toContractClassPublic());
     });
@@ -68,7 +70,7 @@ export class ContractsDataSourcePublicDB implements PublicContractsDB {
     // Let's say we have two txs adding the same contract on the same block. If the 2nd one reverts,
     // wouldn't that accidentally remove the contract added on the first one?
     const logs = tx.unencryptedLogs.unrollLogs();
-    ContractClassRegisteredEvent.fromLogs(logs, getCanonicalClassRegistererAddress()).forEach(e =>
+    ContractClassRegisteredEvent.fromLogs(logs, ClassRegistererAddress).forEach(e =>
       this.classCache.delete(e.contractClassId.toString()),
     );
     ContractInstanceDeployedEvent.fromLogs(logs).forEach(e => this.instanceCache.delete(e.address.toString()));
@@ -94,6 +96,22 @@ export class ContractsDataSourcePublicDB implements PublicContractsDB {
     }
     return contractClass.publicFunctions.find(f => f.selector.equals(selector))?.bytecode;
   }
+
+  public async getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined> {
+    const artifact = await this.db.getContractArtifact(address);
+    if (!artifact) {
+      return Promise.resolve(undefined);
+    }
+
+    const f = artifact.functions.find(f =>
+      FunctionSelector.fromNameAndParameters(f.name, f.parameters).equals(selector),
+    );
+    if (!f) {
+      return Promise.resolve(undefined);
+    }
+
+    return Promise.resolve(`${artifact.name}:${f.name}`);
+  }
 }
 
 /**
@@ -196,11 +214,14 @@ export class WorldStatePublicDB implements PublicStateDB {
  * Implements WorldState db using a world state database.
  */
 export class WorldStateDB implements CommitmentsDB {
+  private log = createDebugLogger('aztec:sequencer:world-state-db');
+
   constructor(private db: MerkleTreeOperations) {}
 
   public async getNullifierMembershipWitnessAtLatestBlock(
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined> {
+    const timer = new Timer();
     const index = await this.db.findLeafIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBuffer());
     if (!index) {
       return undefined;
@@ -218,6 +239,12 @@ export class WorldStateDB implements CommitmentsDB {
       return undefined;
     }
 
+    this.log.debug(`[DB] Fetched nullifier membership`, {
+      eventName: 'public-db-access',
+      duration: timer.ms(),
+      operation: 'get-nullifier-membership-witness-at-latest-block',
+    } satisfies PublicDBAccessStats);
+
     return new NullifierMembershipWitness(BigInt(index), leafPreimage as NullifierLeafPreimage, siblingPath);
   }
 
@@ -232,6 +259,7 @@ export class WorldStateDB implements CommitmentsDB {
 
     // We iterate over messages until we find one whose nullifier is not in the nullifier tree --> we need to check
     // for nullifiers because messages can have duplicates.
+    const timer = new Timer();
     do {
       messageIndex = (await this.db.findLeafIndexAfter(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, messageHash, startIndex))!;
       if (messageIndex === undefined) {
@@ -249,18 +277,45 @@ export class WorldStateDB implements CommitmentsDB {
       messageIndex,
     );
 
+    this.log.debug(`[DB] Fetched L1 to L2 message membership`, {
+      eventName: 'public-db-access',
+      duration: timer.ms(),
+      operation: 'get-l1-to-l2-message-membership-witness',
+    } satisfies PublicDBAccessStats);
+
     return new MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>(messageIndex, siblingPath);
   }
 
   public async getL1ToL2LeafValue(leafIndex: bigint): Promise<Fr | undefined> {
-    return await this.db.getLeafValue(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, leafIndex);
+    const timer = new Timer();
+    const leafValue = await this.db.getLeafValue(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, leafIndex);
+    this.log.debug(`[DB] Fetched L1 to L2 message leaf value`, {
+      eventName: 'public-db-access',
+      duration: timer.ms(),
+      operation: 'get-l1-to-l2-message-leaf-value',
+    } satisfies PublicDBAccessStats);
+    return leafValue;
   }
 
   public async getCommitmentIndex(commitment: Fr): Promise<bigint | undefined> {
-    return await this.db.findLeafIndex(MerkleTreeId.NOTE_HASH_TREE, commitment);
+    const timer = new Timer();
+    const index = await this.db.findLeafIndex(MerkleTreeId.NOTE_HASH_TREE, commitment);
+    this.log.debug(`[DB] Fetched commitment index`, {
+      eventName: 'public-db-access',
+      duration: timer.ms(),
+      operation: 'get-commitment-index',
+    } satisfies PublicDBAccessStats);
+    return index;
   }
 
   public async getNullifierIndex(nullifier: Fr): Promise<bigint | undefined> {
-    return await this.db.findLeafIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBuffer());
+    const timer = new Timer();
+    const index = await this.db.findLeafIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBuffer());
+    this.log.debug(`[DB] Fetched nullifier index`, {
+      eventName: 'public-db-access',
+      duration: timer.ms(),
+      operation: 'get-nullifier-index',
+    } satisfies PublicDBAccessStats);
+    return index;
   }
 }

package/src/public/public_processor.ts

@@ -3,6 +3,7 @@ import {
   type FailedTx,
   NestedProcessReturnValues,
   type ProcessedTx,
+  PublicKernelType,
   type PublicProvingRequest,
   type SimulationError,
   Tx,
@@ -29,14 +30,11 @@ import {
   computeFeePayerBalanceLeafSlot,
   computeFeePayerBalanceStorageSlot,
 } from '@aztec/simulator';
+import { Attributes, type TelemetryClient, type Tracer, trackSpan } from '@aztec/telemetry-client';
 import { type ContractDataSource } from '@aztec/types/contracts';
 import { type MerkleTreeOperations } from '@aztec/world-state';
 
-import {
-  type AbstractPhaseManager,
-  PublicKernelPhase,
-  publicKernelPhaseToKernelType,
-} from './abstract_phase_manager.js';
+import { type AbstractPhaseManager } from './abstract_phase_manager.js';
 import { PhaseManagerFactory } from './phase_manager_factory.js';
 import { ContractsDataSourcePublicDB, WorldStateDB, WorldStatePublicDB } from './public_db_sources.js';
 import { RealPublicKernelCircuitSimulator } from './public_kernel.js';
@@ -50,6 +48,7 @@ export class PublicProcessorFactory {
     private merkleTree: MerkleTreeOperations,
     private contractDataSource: ContractDataSource,
     private simulator: SimulationProvider,
+    private telemetryClient: TelemetryClient,
   ) {}
 
   /**
@@ -77,6 +76,7 @@ export class PublicProcessorFactory {
       historicalHeader,
       publicContractsDB,
       worldStatePublicDB,
+      this.telemetryClient,
     );
   }
 }
@@ -86,6 +86,7 @@ export class PublicProcessorFactory {
  * any public function calls in them. Txs with private calls only are unaffected.
  */
 export class PublicProcessor {
+  public readonly tracer: Tracer;
   constructor(
     protected db: MerkleTreeOperations,
     protected publicExecutor: PublicExecutor,
@@ -94,9 +95,11 @@ export class PublicProcessor {
     protected historicalHeader: Header,
     protected publicContractsDB: ContractsDataSourcePublicDB,
     protected publicStateDB: PublicStateDB,
-
+    telemetryClient: TelemetryClient,
     private log = createDebugLogger('aztec:sequencer:public-processor'),
-  ) {}
+  ) {
+    this.tracer = telemetryClient.getTracer('PublicProcessor');
+  }
 
   /**
    * Run each tx through the public circuit and the public kernel circuit if needed.
@@ -211,6 +214,9 @@ export class PublicProcessor {
     return finalPublicDataUpdateRequests;
   }
 
+  @trackSpan('PublicProcessor.processTxWithPublicCalls', tx => ({
+    [Attributes.TX_HASH]: tx.getTxHash().toString(),
+  }))
   private async processTxWithPublicCalls(tx: Tx): Promise<[ProcessedTx, NestedProcessReturnValues[]]> {
     let returnValues: NestedProcessReturnValues[] = [];
     const publicProvingRequests: PublicProvingRequest[] = [];
@@ -231,8 +237,8 @@ export class PublicProcessor {
     const gasUsed: ProcessedTx['gasUsed'] = {};
     while (phase) {
       const output = await phase.handle(tx, publicKernelPublicInput);
-      gasUsed[publicKernelPhaseToKernelType(phase.phase)] = output.gasUsed;
-      if (phase.phase === PublicKernelPhase.APP_LOGIC) {
+      gasUsed[phase.phase] = output.gasUsed;
+      if (phase.phase === PublicKernelType.APP_LOGIC) {
         returnValues = output.returnValues;
       }
       publicProvingRequests.push(...output.publicProvingRequests);

package/src/public/setup_phase_manager.ts

@@ -3,7 +3,7 @@ import { type GlobalVariables, type Header, type PublicKernelCircuitPublicInputs
 import { type PublicExecutor, type PublicStateDB } from '@aztec/simulator';
 import { type MerkleTreeOperations } from '@aztec/world-state';
 
-import { AbstractPhaseManager, PublicKernelPhase, makeAvmProvingRequest } from './abstract_phase_manager.js';
+import { AbstractPhaseManager, makeAvmProvingRequest } from './abstract_phase_manager.js';
 import { type ContractsDataSourcePublicDB } from './public_db_sources.js';
 import { type PublicKernelCircuitSimulator } from './public_kernel_circuit_simulator.js';
 
@@ -19,7 +19,7 @@ export class SetupPhaseManager extends AbstractPhaseManager {
     historicalHeader: Header,
     protected publicContractsDB: ContractsDataSourcePublicDB,
     protected publicStateDB: PublicStateDB,
-    phase: PublicKernelPhase = PublicKernelPhase.SETUP,
+    phase: PublicKernelType = PublicKernelType.SETUP,
   ) {
     super(db, publicExecutor, publicKernel, globalVariables, historicalHeader, phase);
   }

package/src/public/side_effect_trace.ts

@@ -0,0 +1,323 @@
+import { UnencryptedFunctionL2Logs, UnencryptedL2Log } from '@aztec/circuit-types';
+import {
+  AvmContractInstanceHint,
+  AvmExecutionHints,
+  AvmExternalCallHint,
+  AvmKeyValueHint,
+  AztecAddress,
+  CallContext,
+  ContractStorageRead,
+  ContractStorageUpdateRequest,
+  EthAddress,
+  Gas,
+  L2ToL1Message,
+  LogHash,
+  NoteHash,
+  Nullifier,
+  ReadRequest,
+} from '@aztec/circuits.js';
+import { EventSelector } from '@aztec/foundation/abi';
+import { Fr } from '@aztec/foundation/fields';
+import { type ContractInstanceWithAddress } from '@aztec/types/contracts';
+
+import { type AvmExecutionEnvironment } from '../avm/avm_execution_environment.js';
+import { type AvmContractCallResults } from '../avm/avm_message_call_result.js';
+import { createSimulationError } from '../common/errors.js';
+import { type PublicExecution, type PublicExecutionResult } from './execution.js';
+import { type PublicSideEffectTraceInterface } from './side_effect_trace_interface.js';
+
+export type TracedContractInstance = { exists: boolean } & ContractInstanceWithAddress;
+
+export class PublicSideEffectTrace implements PublicSideEffectTraceInterface {
+  /** The side effect counter increments with every call to the trace. */
+  private sideEffectCounter: number; // kept as number until finalized for efficiency
+
+  private contractStorageReads: ContractStorageRead[] = [];
+  private contractStorageUpdateRequests: ContractStorageUpdateRequest[] = [];
+
+  private noteHashReadRequests: ReadRequest[] = [];
+  private newNoteHashes: NoteHash[] = [];
+
+  private nullifierReadRequests: ReadRequest[] = [];
+  private nullifierNonExistentReadRequests: ReadRequest[] = [];
+  private newNullifiers: Nullifier[] = [];
+
+  private l1ToL2MsgReadRequests: ReadRequest[] = [];
+  private newL2ToL1Messages: L2ToL1Message[] = [];
+
+  private unencryptedLogs: UnencryptedL2Log[] = [];
+  private allUnencryptedLogs: UnencryptedL2Log[] = [];
+  private unencryptedLogsHashes: LogHash[] = [];
+
+  private gotContractInstances: ContractInstanceWithAddress[] = [];
+
+  private nestedExecutions: PublicExecutionResult[] = [];
+
+  private avmCircuitHints: AvmExecutionHints;
+
+  constructor(
+    /** The counter of this trace's first side effect. */
+    public readonly startSideEffectCounter: number = 0,
+  ) {
+    this.sideEffectCounter = startSideEffectCounter;
+    this.avmCircuitHints = AvmExecutionHints.empty();
+  }
+
+  public fork() {
+    return new PublicSideEffectTrace(this.sideEffectCounter);
+  }
+
+  public getCounter() {
+    return this.sideEffectCounter;
+  }
+
+  private incrementSideEffectCounter() {
+    this.sideEffectCounter++;
+  }
+
+  public tracePublicStorageRead(storageAddress: Fr, slot: Fr, value: Fr, _exists: boolean, _cached: boolean) {
+    // TODO(4805): check if some threshold is reached for max storage reads
+    // (need access to parent length, or trace needs to be initialized with parent's contents)
+    // NOTE: exists and cached are unused for now but may be used for optimizations or kernel hints later
+    this.contractStorageReads.push(
+      new ContractStorageRead(slot, value, this.sideEffectCounter, AztecAddress.fromField(storageAddress)),
+    );
+    this.avmCircuitHints.storageValues.items.push(
+      new AvmKeyValueHint(/*key=*/ new Fr(this.sideEffectCounter), /*value=*/ value),
+    );
+    this.incrementSideEffectCounter();
+  }
+
+  public tracePublicStorageWrite(storageAddress: Fr, slot: Fr, value: Fr) {
+    // TODO(4805): check if some threshold is reached for max storage writes
+    // (need access to parent length, or trace needs to be initialized with parent's contents)
+    this.contractStorageUpdateRequests.push(
+      new ContractStorageUpdateRequest(slot, value, this.sideEffectCounter, storageAddress),
+    );
+    this.incrementSideEffectCounter();
+  }
+
+  public traceNoteHashCheck(_storageAddress: Fr, noteHash: Fr, _leafIndex: Fr, exists: boolean) {
+    // TODO(4805): check if some threshold is reached for max note hash checks
+    // NOTE: storageAddress is unused but will be important when an AVM circuit processes an entire enqueued call
+    // TODO(dbanks12): leafIndex is unused for now but later must be used by kernel to constrain that the kernel
+    // is in fact checking the leaf indicated by the user
+    this.noteHashReadRequests.push(new ReadRequest(noteHash, this.sideEffectCounter));
+    this.avmCircuitHints.noteHashExists.items.push(
+      new AvmKeyValueHint(/*key=*/ new Fr(this.sideEffectCounter), /*value=*/ new Fr(exists ? 1 : 0)),
+    );
+    this.incrementSideEffectCounter();
+  }
+
+  public traceNewNoteHash(_storageAddress: Fr, noteHash: Fr) {
+    // TODO(4805): check if some threshold is reached for max new note hash
+    // NOTE: storageAddress is unused but will be important when an AVM circuit processes an entire enqueued call
+    // TODO(dbanks12): non-existent note hashes should emit a read request of the note hash that actually
+    // IS there, and the AVM circuit should accept THAT noteHash as a hint. The circuit will then compare
+    // the noteHash against the one provided by the user code to determine what to return to the user (exists or not),
+    // and will then propagate the actually-present noteHash to its public inputs.
+    this.newNoteHashes.push(new NoteHash(noteHash, this.sideEffectCounter));
+    this.incrementSideEffectCounter();
+  }
+
+  public traceNullifierCheck(_storageAddress: Fr, nullifier: Fr, _leafIndex: Fr, exists: boolean, _isPending: boolean) {
+    // TODO(4805): check if some threshold is reached for max new nullifier
+    // NOTE: storageAddress is unused but will be important when an AVM circuit processes an entire enqueued call
+    // NOTE: isPending and leafIndex are unused for now but may be used for optimizations or kernel hints later
+    const readRequest = new ReadRequest(nullifier, this.sideEffectCounter);
+    if (exists) {
+      this.nullifierReadRequests.push(readRequest);
+    } else {
+      this.nullifierNonExistentReadRequests.push(readRequest);
+    }
+    this.avmCircuitHints.nullifierExists.items.push(
+      new AvmKeyValueHint(/*key=*/ new Fr(this.sideEffectCounter), /*value=*/ new Fr(exists ? 1 : 0)),
+    );
+    this.incrementSideEffectCounter();
+  }
+
+  public traceNewNullifier(_storageAddress: Fr, nullifier: Fr) {
+    // TODO(4805): check if some threshold is reached for max new nullifier
+    // NOTE: storageAddress is unused but will be important when an AVM circuit processes an entire enqueued call
+    this.newNullifiers.push(new Nullifier(nullifier, this.sideEffectCounter, /*noteHash=*/ Fr.ZERO));
+    this.incrementSideEffectCounter();
+  }
+
+  public traceL1ToL2MessageCheck(_contractAddress: Fr, msgHash: Fr, _msgLeafIndex: Fr, exists: boolean) {
+    // TODO(4805): check if some threshold is reached for max message reads
+    // NOTE: contractAddress is unused but will be important when an AVM circuit processes an entire enqueued call
+    // TODO(dbanks12): leafIndex is unused for now but later must be used by kernel to constrain that the kernel
+    // is in fact checking the leaf indicated by the user
+    this.l1ToL2MsgReadRequests.push(new ReadRequest(msgHash, this.sideEffectCounter));
+    this.avmCircuitHints.l1ToL2MessageExists.items.push(
+      new AvmKeyValueHint(/*key=*/ new Fr(this.sideEffectCounter), /*value=*/ new Fr(exists ? 1 : 0)),
+    );
+    this.incrementSideEffectCounter();
+  }
+
+  public traceNewL2ToL1Message(recipient: Fr, content: Fr) {
+    // TODO(4805): check if some threshold is reached for max messages
+    const recipientAddress = EthAddress.fromField(recipient);
+    this.newL2ToL1Messages.push(new L2ToL1Message(recipientAddress, content, this.sideEffectCounter));
+    this.incrementSideEffectCounter();
+  }
+
+  public traceUnencryptedLog(contractAddress: Fr, event: Fr, log: Fr[]) {
+    // TODO(4805): check if some threshold is reached for max logs
+    const ulog = new UnencryptedL2Log(
+      AztecAddress.fromField(contractAddress),
+      EventSelector.fromField(event),
+      Buffer.concat(log.map(f => f.toBuffer())),
+    );
+    const basicLogHash = Fr.fromBuffer(ulog.hash());
+    this.unencryptedLogs.push(ulog);
+    this.allUnencryptedLogs.push(ulog);
+    // TODO(6578): explain magic number 4 here
+    this.unencryptedLogsHashes.push(new LogHash(basicLogHash, this.sideEffectCounter, new Fr(ulog.length + 4)));
+    this.incrementSideEffectCounter();
+  }
+
+  public traceGetContractInstance(instance: TracedContractInstance) {
+    // TODO(4805): check if some threshold is reached for max contract instance retrievals
+    this.gotContractInstances.push(instance);
+    this.avmCircuitHints.contractInstances.items.push(
+      new AvmContractInstanceHint(
+        instance.address,
+        new Fr(instance.exists ? 1 : 0),
+        instance.salt,
+        instance.deployer,
+        instance.contractClassId,
+        instance.initializationHash,
+        instance.publicKeysHash,
+      ),
+    );
+    this.incrementSideEffectCounter();
+  }
+
+  /**
+   * Trace a nested call.
+   * Accept some results from a finished nested call's trace into this one.
+   */
+  public traceNestedCall(
+    /** The trace of the nested call. */
+    nestedCallTrace: PublicSideEffectTrace,
+    /** The execution environment of the nested call. */
+    nestedEnvironment: AvmExecutionEnvironment,
+    /** How much gas was available for this public execution. */
+    startGasLeft: Gas,
+    /** How much gas was left after this public execution. */
+    endGasLeft: Gas,
+    /** Bytecode used for this execution. */
+    bytecode: Buffer,
+    /** The call's results */
+    avmCallResults: AvmContractCallResults,
+    /** Function name for logging */
+    functionName: string = 'unknown',
+  ) {
+    const result = nestedCallTrace.toPublicExecutionResult(
+      nestedEnvironment,
+      startGasLeft,
+      endGasLeft,
+      bytecode,
+      avmCallResults,
+      functionName,
+    );
+    this.sideEffectCounter = result.endSideEffectCounter.toNumber();
+    // when a nested call returns, caller accepts its updated counter
+    this.allUnencryptedLogs.push(...result.allUnencryptedLogs.logs);
+    // NOTE: eventually if the AVM circuit processes an entire enqueued call,
+    // this function will accept all of the nested's side effects into this instance
+    this.nestedExecutions.push(result);
+
+    const gasUsed = new Gas(
+      result.startGasLeft.daGas - result.endGasLeft.daGas,
+      result.startGasLeft.l2Gas - result.endGasLeft.l2Gas,
+    );
+    this.avmCircuitHints.externalCalls.items.push(
+      new AvmExternalCallHint(/*success=*/ new Fr(result.reverted ? 0 : 1), result.returnValues, gasUsed),
+    );
+  }
+
+  /**
+   * Convert this trace to a PublicExecutionResult for use externally to the simulator.
+   */
+  public toPublicExecutionResult(
+    /** The execution environment of the nested call. */
+    avmEnvironment: AvmExecutionEnvironment,
+    /** How much gas was available for this public execution. */
+    startGasLeft: Gas,
+    /** How much gas was left after this public execution. */
+    endGasLeft: Gas,
+    /** Bytecode used for this execution. */
+    bytecode: Buffer,
+    /** The call's results */
+    avmCallResults: AvmContractCallResults,
+    /** Function name for logging */
+    functionName: string = 'unknown',
+    /** The side effect counter of the execution request itself */
+    requestSideEffectCounter: number = this.startSideEffectCounter,
+  ): PublicExecutionResult {
+    return {
+      execution: createPublicExecutionRequest(requestSideEffectCounter, avmEnvironment),
+
+      startSideEffectCounter: new Fr(this.startSideEffectCounter),
+      endSideEffectCounter: new Fr(this.sideEffectCounter),
+      startGasLeft,
+      endGasLeft,
+      transactionFee: avmEnvironment.transactionFee,
+
+      bytecode,
+      calldata: avmEnvironment.calldata,
+      returnValues: avmCallResults.output,
+      reverted: avmCallResults.reverted,
+      revertReason: avmCallResults.revertReason ? createSimulationError(avmCallResults.revertReason) : undefined,
+
+      contractStorageReads: this.contractStorageReads,
+      contractStorageUpdateRequests: this.contractStorageUpdateRequests,
+      noteHashReadRequests: this.noteHashReadRequests,
+      newNoteHashes: this.newNoteHashes,
+      nullifierReadRequests: this.nullifierReadRequests,
+      nullifierNonExistentReadRequests: this.nullifierNonExistentReadRequests,
+      newNullifiers: this.newNullifiers,
+      l1ToL2MsgReadRequests: this.l1ToL2MsgReadRequests,
+      newL2ToL1Messages: this.newL2ToL1Messages,
+      // correct the type on these now that they are finalized (lists won't grow)
+      unencryptedLogs: new UnencryptedFunctionL2Logs(this.unencryptedLogs),
+      allUnencryptedLogs: new UnencryptedFunctionL2Logs(this.allUnencryptedLogs),
+      unencryptedLogsHashes: this.unencryptedLogsHashes,
+      // TODO(dbanks12): process contract instance read requests in public kernel
+      //gotContractInstances: this.gotContractInstances,
+
+      nestedExecutions: this.nestedExecutions,
+
+      avmCircuitHints: this.avmCircuitHints,
+
+      functionName,
+    };
+  }
+}
+
+/**
+ * Helper function to create a public execution request from an AVM execution environment
+ */
+function createPublicExecutionRequest(
+  requestSideEffectCounter: number,
+  avmEnvironment: AvmExecutionEnvironment,
+): PublicExecution {
+  const callContext = CallContext.from({
+    msgSender: avmEnvironment.sender,
+    storageContractAddress: avmEnvironment.storageAddress,
+    functionSelector: avmEnvironment.temporaryFunctionSelector,
+    isDelegateCall: avmEnvironment.isDelegateCall,
+    isStaticCall: avmEnvironment.isStaticCall,
+    sideEffectCounter: requestSideEffectCounter,
+  });
+  const execution: PublicExecution = {
+    contractAddress: avmEnvironment.address,
+    functionSelector: avmEnvironment.temporaryFunctionSelector,
+    callContext,
+    // execution request does not contain AvmContextInputs prefix
+    args: avmEnvironment.getCalldataWithoutPrefix(),
+  };
+  return execution;
+}