@aztec-labs/simulator 6.0.0-nightly.20260829

package/src/public/public_processor/public_processor_metrics.ts

@@ -0,0 +1,138 @@
+import type { ContractClassPublishedEvent } from '@aztec-labs/protocol-contracts/class-registry';
+import type { Gas } from '@aztec-labs/stdlib/gas';
+import { TxExecutionPhase } from '@aztec-labs/stdlib/tx';
+import {
+  Attributes,
+  type Gauge,
+  type Histogram,
+  Metrics,
+  type TelemetryClient,
+  type Tracer,
+  type UpDownCounter,
+  createUpDownCounterWithDefault,
+} from '@aztec-labs/telemetry-client';
+
+export class PublicProcessorMetrics {
+  public readonly tracer: Tracer;
+
+  private txDuration: Histogram;
+  private txCount: UpDownCounter;
+  private txPhaseCount: UpDownCounter;
+
+  private phaseDuration: Histogram;
+  private phaseCount: UpDownCounter;
+
+  private bytecodeDeployed: Histogram;
+  private totalGas: Gauge;
+  private totalGasHistogram: Histogram;
+  private gasRate: Histogram;
+  private txGas: Histogram;
+
+  private treeInsertionDuration: Histogram;
+
+  private silentlySkippedCount: UpDownCounter;
+  private silentlySkippedDuration: Histogram;
+
+  constructor(client: TelemetryClient, name = 'PublicProcessor') {
+    this.tracer = client.getTracer(name);
+    const meter = client.getMeter(name);
+
+    this.txDuration = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_TX_DURATION);
+
+    this.txCount = createUpDownCounterWithDefault(meter, Metrics.PUBLIC_PROCESSOR_TX_COUNT, {
+      [Attributes.OK]: [true, false],
+    });
+
+    this.txPhaseCount = createUpDownCounterWithDefault(meter, Metrics.PUBLIC_PROCESSOR_TX_PHASE_COUNT);
+
+    this.phaseDuration = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_PHASE_DURATION);
+
+    this.phaseCount = createUpDownCounterWithDefault(meter, Metrics.PUBLIC_PROCESSOR_PHASE_COUNT, {
+      [Attributes.TX_PHASE_NAME]: [TxExecutionPhase.SETUP, TxExecutionPhase.APP_LOGIC, TxExecutionPhase.TEARDOWN],
+      [Attributes.OK]: [true, false],
+    });
+
+    this.bytecodeDeployed = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_DEPLOY_BYTECODE_SIZE);
+
+    this.totalGas = meter.createGauge(Metrics.PUBLIC_PROCESSOR_TOTAL_GAS);
+
+    this.totalGasHistogram = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_TOTAL_GAS_HISTOGRAM);
+
+    this.txGas = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_TX_GAS);
+
+    this.gasRate = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_GAS_RATE);
+
+    this.treeInsertionDuration = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_TREE_INSERTION);
+
+    this.silentlySkippedCount = createUpDownCounterWithDefault(meter, Metrics.PUBLIC_PROCESSOR_SILENTLY_SKIPPED_COUNT);
+
+    this.silentlySkippedDuration = meter.createHistogram(Metrics.PUBLIC_PROCESSOR_SILENTLY_SKIPPED_DURATION);
+  }
+
+  recordPhaseDuration(phaseName: TxExecutionPhase, durationMs: number) {
+    this.phaseCount.add(1, { [Attributes.TX_PHASE_NAME]: phaseName, [Attributes.OK]: true });
+    this.phaseDuration.record(Math.ceil(durationMs), { [Attributes.TX_PHASE_NAME]: phaseName });
+  }
+
+  recordTx(phaseCount: number, durationMs: number, gasUsed: Gas) {
+    this.txPhaseCount.add(phaseCount);
+    this.txDuration.record(Math.ceil(durationMs));
+    this.txCount.add(1, {
+      [Attributes.OK]: true,
+    });
+    this.txGas.record(gasUsed.daGas, {
+      [Attributes.GAS_DIMENSION]: 'DA',
+    });
+    this.txGas.record(gasUsed.l2Gas, {
+      [Attributes.GAS_DIMENSION]: 'L2',
+    });
+  }
+
+  recordAllTxs(totalGas: Gas, gasRate: number) {
+    this.totalGas.record(totalGas.daGas, {
+      [Attributes.GAS_DIMENSION]: 'DA',
+    });
+    this.totalGas.record(totalGas.l2Gas, {
+      [Attributes.GAS_DIMENSION]: 'L2',
+    });
+    this.gasRate.record(gasRate, {
+      [Attributes.GAS_DIMENSION]: 'L2',
+    });
+    this.totalGasHistogram.record(totalGas.daGas, {
+      [Attributes.GAS_DIMENSION]: 'DA',
+    });
+    this.totalGasHistogram.record(totalGas.l2Gas, {
+      [Attributes.GAS_DIMENSION]: 'L2',
+    });
+  }
+
+  recordFailedTx() {
+    this.txCount.add(1, {
+      [Attributes.OK]: false,
+    });
+  }
+
+  recordRevertedPhase(phaseName: TxExecutionPhase) {
+    this.phaseCount.add(1, { [Attributes.TX_PHASE_NAME]: phaseName, [Attributes.OK]: false });
+  }
+
+  recordClassPublication(...events: ContractClassPublishedEvent[]) {
+    let totalBytecode = 0;
+    for (const event of events) {
+      totalBytecode += event.packedPublicBytecode.length;
+    }
+
+    if (totalBytecode > 0) {
+      this.bytecodeDeployed.record(totalBytecode);
+    }
+  }
+
+  recordTreeInsertions(durationUs: number) {
+    this.treeInsertionDuration.record(Math.ceil(durationUs));
+  }
+
+  recordSilentlySkipped(durationMs: number) {
+    this.silentlySkippedCount.add(1);
+    this.silentlySkippedDuration.record(Math.ceil(durationMs));
+  }
+}

package/src/public/public_tx_simulator/dumping_public_tx_simulator.ts

@@ -0,0 +1,66 @@
+import type { LoggerBindings } from '@aztec-labs/foundation/log';
+import {
+  AvmCircuitInputs,
+  AvmCircuitPublicInputs,
+  AvmExecutionHints,
+  type PublicSimulatorConfig,
+  type PublicTxResult,
+  serializeWithMessagePack,
+} from '@aztec-labs/stdlib/avm';
+import type { GlobalVariables, Tx } from '@aztec-labs/stdlib/tx';
+import { strict as assert } from 'assert';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+import type { AvmSimulator } from '../avm_simulator.js';
+import type { PublicContractsDB } from '../public_db_sources.js';
+import { PublicTxSimulator } from './public_tx_simulator.js';
+
+/**
+ * A {@link PublicTxSimulator} that dumps AVM circuit inputs to disk after simulation.
+ * Used during nightly CI runs to collect circuit inputs for AVM proving benchmarks.
+ */
+export class DumpingPublicTxSimulator extends PublicTxSimulator {
+  private readonly outputDir: string;
+
+  constructor(
+    avmSimulator: AvmSimulator,
+    globalVariables: GlobalVariables,
+    contractsDB: PublicContractsDB,
+    forkId: number,
+    config: Partial<PublicSimulatorConfig>,
+    outputDir: string,
+    bindings?: LoggerBindings,
+  ) {
+    super(avmSimulator, globalVariables, contractsDB, forkId, config, bindings);
+    assert(config.collectHints === true, 'collectHints must be enabled to dump AVM circuit inputs');
+    assert(config.collectPublicInputs === true, 'collectPublicInputs must be enabled to dump AVM circuit inputs');
+    this.outputDir = outputDir;
+  }
+
+  public override async simulate(tx: Tx): Promise<PublicTxResult> {
+    const result = await super.simulate(tx);
+    this.dumpAvmCircuitInputs(result, tx.getTxHash().toString());
+    return result;
+  }
+
+  private dumpAvmCircuitInputs(result: PublicTxResult, txHash: string): void {
+    try {
+      mkdirSync(this.outputDir, { recursive: true });
+
+      const filename = `avm-circuit-inputs-tx-${txHash}.bin`;
+      const filepath = join(this.outputDir, filename);
+
+      const hints = result.hints ?? AvmExecutionHints.empty();
+      const publicInputs = result.publicInputs ?? AvmCircuitPublicInputs.empty();
+      const avmCircuitInputs = new AvmCircuitInputs(hints, publicInputs);
+
+      const serialized = serializeWithMessagePack(avmCircuitInputs);
+      writeFileSync(filepath, serialized);
+
+      this.log.debug(`Dumped AVM circuit inputs to ${filepath}`);
+    } catch (error) {
+      this.log.warn(`Failed to dump AVM circuit inputs for tx ${txHash}: ${error}`);
+    }
+  }
+}

package/src/public/public_tx_simulator/factories.ts

@@ -0,0 +1,61 @@
+import type { LoggerBindings } from '@aztec-labs/foundation/log';
+import { PublicSimulatorConfig } from '@aztec-labs/stdlib/avm';
+import type { GlobalVariables } from '@aztec-labs/stdlib/tx';
+import type { TelemetryClient } from '@aztec-labs/telemetry-client';
+
+import type { AvmSimulator } from '../avm_simulator.js';
+import type { PublicContractsDB } from '../public_db_sources.js';
+import { DumpingPublicTxSimulator } from './dumping_public_tx_simulator.js';
+import { TelemetryPublicTxSimulator } from './public_tx_simulator.js';
+
+/**
+ * Creates an IPC-based public tx simulator for block building.
+ * Uses DumpingPublicTxSimulator if DUMP_AVM_INPUTS_TO_DIR env var is set (for CI/testing the AVM circuit),
+ * otherwise uses TelemetryPublicTxSimulator (for production).
+ */
+export function createPublicTxSimulatorForBlockBuilding(
+  avmSimulator: AvmSimulator,
+  globalVariables: GlobalVariables,
+  contractsDB: PublicContractsDB,
+  forkId: number,
+  telemetryClient: TelemetryClient,
+  bindings?: LoggerBindings,
+  collectDebugLogs = false,
+) {
+  const config = PublicSimulatorConfig.from({
+    skipFeeEnforcement: false,
+    collectDebugLogs,
+    collectHints: false,
+    collectPublicInputs: false,
+    collectStatistics: false,
+    collectCallMetadata: false,
+  });
+
+  const dumpDir = process.env.DUMP_AVM_INPUTS_TO_DIR;
+  if (dumpDir) {
+    // must collect hints and PIs for dumping
+    const dumpingConfig = {
+      ...config,
+      collectHints: true,
+      collectPublicInputs: true,
+    };
+    return new DumpingPublicTxSimulator(
+      avmSimulator,
+      globalVariables,
+      contractsDB,
+      forkId,
+      dumpingConfig,
+      dumpDir,
+      bindings,
+    );
+  }
+  return new TelemetryPublicTxSimulator(
+    avmSimulator,
+    globalVariables,
+    contractsDB,
+    forkId,
+    telemetryClient,
+    config,
+    bindings,
+  );
+}

package/src/public/public_tx_simulator/index.ts

@@ -0,0 +1,8 @@
+export { PublicTxSimulator, MeasuredPublicTxSimulator, TelemetryPublicTxSimulator } from './public_tx_simulator.js';
+export { DumpingPublicTxSimulator } from './dumping_public_tx_simulator.js';
+export { createPublicTxSimulatorForBlockBuilding } from './factories.js';
+export type {
+  PublicTxSimulatorInterface,
+  MeasuredPublicTxSimulatorInterface,
+} from './public_tx_simulator_interface.js';
+export type { PublicTxResult, PublicSimulatorConfig as PublicTxSimulatorConfig } from '@aztec-labs/stdlib/avm';

package/src/public/public_tx_simulator/public_tx_simulator.ts

@@ -0,0 +1,190 @@
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import { sleep } from '@aztec-labs/foundation/sleep';
+import {
+  AvmFastSimulationInputs,
+  AvmTxHint,
+  type PublicSimulatorConfig,
+  PublicTxResult,
+  deserializeFromMessagePack,
+} from '@aztec-labs/stdlib/avm';
+import { SimulationError } from '@aztec-labs/stdlib/errors';
+import type { GlobalVariables, Tx } from '@aztec-labs/stdlib/tx';
+import { WorldStateRevision } from '@aztec-labs/stdlib/world-state';
+import { type TelemetryClient, type Tracer, getTelemetryClient } from '@aztec-labs/telemetry-client';
+
+import type { AvmContractsDBContext, AvmSimulator } from '../avm_simulator.js';
+import { ExecutorMetrics } from '../executor_metrics.js';
+import type { ExecutorMetricsInterface } from '../executor_metrics_interface.js';
+import type { PublicContractsDB } from '../public_db_sources.js';
+import { PublicTxSimulatorBase } from './public_tx_simulator_base.js';
+import type {
+  MeasuredPublicTxSimulatorInterface,
+  PublicTxSimulatorInterface,
+} from './public_tx_simulator_interface.js';
+
+/**
+ * Simulates a transaction's public portion by running its public calls through an {@link AvmSimulator}.
+ * `forkId` selects the fork whose contract data the simulation reads.
+ */
+export class PublicTxSimulator extends PublicTxSimulatorBase implements PublicTxSimulatorInterface {
+  protected override log: Logger;
+  /** Aborts the in-flight simulation. */
+  private abortController?: AbortController;
+  /** Current simulation promise, used to wait for completion after cancellation. */
+  private simulationPromise?: Promise<PublicTxResult>;
+
+  constructor(
+    avmSimulator: AvmSimulator,
+    globalVariables: GlobalVariables,
+    contractsDB: PublicContractsDB,
+    forkId: number,
+    config?: Partial<PublicSimulatorConfig>,
+    bindings?: LoggerBindings,
+  ) {
+    super(avmSimulator, globalVariables, contractsDB, forkId, config, undefined, bindings);
+    this.log = createLogger(`simulator:public_tx_simulator`, bindings);
+  }
+
+  /**
+   * Simulate a transaction's public portion.
+   *
+   * @param tx - The transaction to simulate.
+   * @returns The result of the transaction's public execution.
+   */
+  public async simulate(tx: Tx): Promise<PublicTxResult> {
+    this.abortController = new AbortController();
+    this.simulationPromise = this.doSimulate(tx, this.abortController.signal);
+    try {
+      return await this.simulationPromise;
+    } finally {
+      this.abortController = undefined;
+      this.simulationPromise = undefined;
+    }
+  }
+
+  protected async doSimulate(tx: Tx, signal: AbortSignal): Promise<PublicTxResult> {
+    const txHash = this.computeTxHash(tx);
+    this.log.debug(
+      `Simulating ${tx.publicFunctionCalldata.length} public calls for tx ${txHash}, forkId=${this.forkId}`,
+      { txHash },
+    );
+
+    // Create the fast simulation inputs.
+    const txHint = AvmTxHint.fromTx(tx, this.globalVariables.gasFees);
+    const fastSimInputs = new AvmFastSimulationInputs(
+      // blockNumber: WorldStateRevision.LATEST sentinel so the WSDB walks the fork's current
+      // uncommitted state. Using 0 here makes WSDB treat this as a historical query against
+      // the empty genesis tree and miss any in-fork uncommitted leaves (deployed contracts,
+      // etc.) from earlier txs in the same block.
+      { forkId: this.forkId, blockNumber: WorldStateRevision.LATEST, includeUncommitted: true },
+      this.config,
+      txHint,
+      this.globalVariables,
+      this.protocolContracts,
+    );
+
+    this.log.trace(`Serializing fast simulation inputs to msgpack...`);
+    const inputBuffer = fastSimInputs.serializeWithMessagePack();
+
+    this.log.debug(`Running AVM simulation for tx ${txHash}`);
+    const context: AvmContractsDBContext = {
+      contractsDB: this.contractsDB,
+      forkId: this.forkId,
+      timestamp: this.globalVariables.timestamp,
+    };
+    let resultBuffer: Uint8Array;
+    try {
+      resultBuffer = await this.avmSimulator.simulate(inputBuffer, context, signal);
+    } catch (error: any) {
+      if (error.message?.includes('cancelled')) {
+        throw new SimulationError(`AVM simulation cancelled`, []);
+      }
+      throw new SimulationError(`AVM simulation failed: ${error.message}`, []);
+    }
+
+    this.log.trace(`Deserializing simulation result from buffer (size: ${resultBuffer.length})...`);
+    const resultJSON: object = deserializeFromMessagePack(Buffer.from(resultBuffer));
+    const result = PublicTxResult.fromPlainObject(resultJSON);
+
+    this.log.trace(`AVM simulation completed for tx ${txHash}`, {
+      txHash,
+      reverted: !result.revertCode.isOK(),
+      l2GasUsed: result.gasUsed.totalGas.l2Gas,
+    });
+
+    return result;
+  }
+
+  /**
+   * Cancel the current simulation if one is in progress.
+   * This signals the underlying simulator to stop at the next safe point (between opcodes, before a
+   * world-state 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.
+   *                        Cancellation is cooperative: the simulator may be mid slow-operation and
+   *                        won't observe the cancellation until it completes.
+   *                        Default timeout of 100ms after cancellation.
+   */
+  public async cancel(waitTimeoutMs: number = 100): Promise<void> {
+    if (this.abortController) {
+      this.log.debug('Cancelling AVM simulation');
+      this.abortController.abort();
+    }
+
+    if (this.simulationPromise) {
+      this.log.debug(`Waiting up to ${waitTimeoutMs}ms for AVM simulation to stop`);
+      await Promise.race([
+        this.simulationPromise.catch(() => {}), // Ignore rejection, just wait for completion
+        sleep(waitTimeoutMs),
+      ]);
+      this.log.debug('AVM simulation stopped or wait timed out');
+    }
+  }
+}
+
+export class MeasuredPublicTxSimulator extends PublicTxSimulator implements MeasuredPublicTxSimulatorInterface {
+  constructor(
+    avmSimulator: AvmSimulator,
+    globalVariables: GlobalVariables,
+    contractsDB: PublicContractsDB,
+    forkId: number,
+    protected readonly metrics: ExecutorMetricsInterface,
+    config?: Partial<PublicSimulatorConfig>,
+    bindings?: LoggerBindings,
+  ) {
+    super(avmSimulator, globalVariables, contractsDB, forkId, config, bindings);
+  }
+
+  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?.gasUsed, result?.revertCode, result?.stats);
+    }
+    return result;
+  }
+}
+
+/**
+ * A public tx simulator that tracks runtime/production metrics with telemetry.
+ */
+export class TelemetryPublicTxSimulator extends MeasuredPublicTxSimulator {
+  /* tracer needed by trackSpans */
+  public readonly tracer: Tracer;
+
+  constructor(
+    avmSimulator: AvmSimulator,
+    globalVariables: GlobalVariables,
+    contractsDB: PublicContractsDB,
+    forkId: number,
+    telemetryClient: TelemetryClient = getTelemetryClient(),
+    config?: Partial<PublicSimulatorConfig>,
+    bindings?: LoggerBindings,
+  ) {
+    const metrics = new ExecutorMetrics(telemetryClient, 'PublicTxSimulator');
+    super(avmSimulator, globalVariables, contractsDB, forkId, metrics, config, bindings);
+    this.tracer = metrics.tracer;
+  }
+}

package/src/public/public_tx_simulator/public_tx_simulator_base.ts

@@ -0,0 +1,37 @@
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import { ProtocolContractsList } from '@aztec-labs/protocol-contracts';
+import { PublicSimulatorConfig } from '@aztec-labs/stdlib/avm';
+import type { GlobalVariables, ProtocolContracts, Tx } from '@aztec-labs/stdlib/tx';
+
+import type { AvmSimulator } from '../avm_simulator.js';
+import type { PublicContractsDB } from '../public_db_sources.js';
+
+/**
+ * Shared base for public tx simulators: holds the common configuration, the {@link AvmSimulator} used
+ * to run the transaction's public calls, the contracts DB and fork id that scope the simulation's
+ * contract-data lookups, the logger, and the tx-hash helper. Concrete simulators extend this and
+ * implement `simulate`.
+ */
+export abstract class PublicTxSimulatorBase {
+  protected log: Logger;
+  protected readonly config: PublicSimulatorConfig;
+  protected readonly bindings?: LoggerBindings;
+
+  constructor(
+    protected avmSimulator: AvmSimulator,
+    protected globalVariables: GlobalVariables,
+    protected contractsDB: PublicContractsDB,
+    protected forkId: number,
+    config?: Partial<PublicSimulatorConfig>,
+    protected protocolContracts: ProtocolContracts = ProtocolContractsList,
+    bindings?: LoggerBindings,
+  ) {
+    this.config = PublicSimulatorConfig.from(config ?? {});
+    this.bindings = bindings;
+    this.log = createLogger(`simulator:public_tx_simulator`, bindings);
+  }
+
+  protected computeTxHash(tx: Tx) {
+    return tx.getTxHash();
+  }
+}

package/src/public/public_tx_simulator/public_tx_simulator_interface.ts

@@ -0,0 +1,33 @@
+import type { PublicTxResult } from '@aztec-labs/stdlib/avm';
+import type { Tx } from '@aztec-labs/stdlib/tx';
+
+export interface PublicTxSimulatorInterface {
+  simulate(tx: Tx): Promise<PublicTxResult>;
+  /**
+   * Cancel the current simulation if one is in progress.
+   * This signals the underlying simulator 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.
+   *                        Cancellation is cooperative: signaling it only sets a flag the simulator
+   *                        checks at certain points, so if it's mid slow-operation 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 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>;
+}

package/src/public/side_effect_errors.ts

@@ -0,0 +1,96 @@
+import {
+  L1_TO_L2_MSG_TREE_LEAF_COUNT,
+  MAX_L2_TO_L1_MSGS_PER_TX,
+  MAX_NOTE_HASHES_PER_TX,
+  MAX_NULLIFIERS_PER_TX,
+  MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS,
+  NOTE_HASH_TREE_LEAF_COUNT,
+} from '@aztec-labs/constants';
+
+import { CheckedPublicExecutionError } from './public_errors.js';
+
+/**
+ * Any error that can be thrown during side effect insertion in public.
+ * Includes SideEffectLimitReachedError and NullifierCollisionError.
+ */
+export abstract class SideEffectError extends CheckedPublicExecutionError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SideEffectInsertionError';
+  }
+}
+
+export class SideEffectLimitReachedError extends SideEffectError {
+  constructor(sideEffectType: string, limit: number) {
+    super(`Reached the limit (${limit}) on number of '${sideEffectType}' per tx`);
+    this.name = 'SideEffectLimitReachedError';
+  }
+}
+
+export class MaxCallsToUniqueContractClassIdsError extends SideEffectLimitReachedError {
+  constructor() {
+    super('contract calls to unique class IDs', MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS);
+    this.name = 'MaxCallsToUniqueContractClassIdsError';
+  }
+}
+
+export class NullifierLimitReachedError extends SideEffectLimitReachedError {
+  constructor() {
+    super('nullifier', MAX_NULLIFIERS_PER_TX);
+    this.name = 'NullifierLimitReachedError';
+  }
+}
+
+export class NoteHashLimitReachedError extends SideEffectLimitReachedError {
+  constructor() {
+    super('note hash', MAX_NOTE_HASHES_PER_TX);
+    this.name = 'NoteHashLimitReachedError';
+  }
+}
+
+export class L2ToL1MessageLimitReachedError extends SideEffectLimitReachedError {
+  constructor() {
+    super('l2 to l1 message', MAX_L2_TO_L1_MSGS_PER_TX);
+    this.name = 'L2ToL1MessageLimitReachedError';
+  }
+}
+
+export class NullifierCollisionError extends SideEffectError {
+  constructor(message: string) {
+    super(`Nullifier collision: ${message}`);
+    this.name = 'NullifierCollisionError';
+  }
+}
+
+/**
+ * Any error that can be thrown during side effect reads in public.
+ * Note: Thrown at state manager level and unknown by simulation, hence NOT considered
+ * CheckedPublicExecutionErrors. Currently only includes append-only tree reads.
+ */
+export abstract class SideEffectReadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SideEffectReadError';
+  }
+}
+
+export class IndexOutOfRangeError extends SideEffectReadError {
+  constructor(tree: string, index: number, limit: number) {
+    super(`Attempting to read index ${index} of ${tree} tree with maximum ${limit} leaves`);
+    this.name = 'IndexOutOfRangeError';
+  }
+}
+
+export class NoteHashIndexOutOfRangeError extends IndexOutOfRangeError {
+  constructor(index: number) {
+    super('note hash', index, NOTE_HASH_TREE_LEAF_COUNT);
+    this.name = 'NoteHashIndexOutOfRangeError';
+  }
+}
+
+export class L1ToL2MessageIndexOutOfRangeError extends IndexOutOfRangeError {
+  constructor(index: number) {
+    super('l1 to l2 message', index, L1_TO_L2_MSG_TREE_LEAF_COUNT);
+    this.name = 'L1ToL2MessageIndexOutOfRangeError';
+  }
+}