@aztec-labs/simulator 6.0.0-nightly.20260829

package/src/public/test_executor_metrics.ts

@@ -0,0 +1,399 @@
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import { Timer } from '@aztec-labs/foundation/timer';
+import type { RevertCode } from '@aztec-labs/stdlib/avm';
+import type { GasUsed } from '@aztec-labs/stdlib/gas';
+import { strict as assert } from 'assert';
+
+import type { ExecutorMetricsInterface } from './executor_metrics_interface.js';
+
+export interface PublicEnqueuedCallMetrics {
+  fnName: string;
+  durationMs: number;
+  manaUsed: number;
+  totalInstructionsExecuted: number;
+  reverted: boolean;
+}
+
+export interface PublicTxMetrics {
+  // TS simulation
+  totalDurationMs: number;
+  manaUsed: number | undefined;
+  totalInstructionsExecuted: number;
+  nonRevertiblePrivateInsertionsUs: number | undefined;
+  revertiblePrivateInsertionsUs: number | undefined;
+  enqueuedCalls: PublicEnqueuedCallMetrics[];
+  revertedCode: RevertCode | undefined;
+  // Proving
+  proverSimulationStepMs: number | undefined;
+  proverProvingStepMs: number | undefined;
+  proverTraceGenerationStepMs: number | undefined;
+  // Proving (detail)
+  traceGenerationInteractionsMs: number | undefined;
+  traceGenerationTracesMs: number | undefined;
+  provingSumcheckMs: number | undefined;
+  provingPcsMs: number | undefined;
+  provingLogDerivativeInverseMs: number | undefined;
+  provingLogDerivativeInverseCommitmentsMs: number | undefined;
+  provingWireCommitmentsMs: number | undefined;
+}
+
+const NUM_SPACES = 4;
+const H1 = '# ';
+const H2 = '\n## ';
+const INDENT = ' '.repeat(NUM_SPACES);
+const INDENT0 = '- ';
+const INDENT1 = INDENT + '- ';
+const INDENT2 = INDENT + INDENT + '- ';
+const H_LINE = '\n---------------------------------------------------------------------';
+
+export enum PublicTxMetricsFilter {
+  ALL,
+  TOTALS,
+  DURATIONS,
+  INSTRUCTIONS,
+  PROVING,
+}
+
+function createEmptyTxMetrics(): PublicTxMetrics {
+  return {
+    // TS simulation
+    totalDurationMs: 0,
+    manaUsed: 0,
+    totalInstructionsExecuted: 0,
+    nonRevertiblePrivateInsertionsUs: undefined,
+    revertiblePrivateInsertionsUs: undefined,
+    enqueuedCalls: [],
+    revertedCode: undefined,
+    // Proving
+    proverSimulationStepMs: undefined,
+    proverProvingStepMs: undefined,
+    proverTraceGenerationStepMs: undefined,
+    // Proving (detail)
+    traceGenerationInteractionsMs: undefined,
+    traceGenerationTracesMs: undefined,
+    provingSumcheckMs: undefined,
+    provingPcsMs: undefined,
+    provingLogDerivativeInverseMs: undefined,
+    provingLogDerivativeInverseCommitmentsMs: undefined,
+    provingWireCommitmentsMs: undefined,
+  };
+}
+
+export class TestExecutorMetrics implements ExecutorMetricsInterface {
+  private logger: Logger;
+  // tx label -> tx metrics
+  private txMetrics: Map<string, PublicTxMetrics> = new Map();
+  private currentTxLabel: string | undefined;
+  private txTimer: Timer | undefined;
+
+  constructor(bindings?: LoggerBindings) {
+    this.logger = createLogger(`simulator:test_executor_metrics`, bindings);
+  }
+
+  startRecordingTxSimulation(txLabel: string) {
+    assert(!this.currentTxLabel, 'Cannot start recording tx simulation when another is live');
+    assert(!this.txMetrics.has(txLabel), 'Cannot start recording metrics for tx with duplicate label');
+    this.txMetrics.set(txLabel, createEmptyTxMetrics());
+    this.currentTxLabel = txLabel;
+    this.txTimer = new Timer();
+  }
+
+  stopRecordingTxSimulation(
+    txLabel: string,
+    gasUsed?: GasUsed,
+    revertedCode?: RevertCode,
+    stats?: Record<string, string>,
+  ) {
+    assert(this.currentTxLabel === txLabel, 'Cannot stop recording metrics for tx when another is live');
+
+    const txMetrics = this.txMetrics.get(txLabel)!;
+
+    // total duration of tx
+    txMetrics.totalDurationMs = this.txTimer!.ms();
+    this.logger.debug(`Public TX simulation of ${txLabel} took ${txMetrics.totalDurationMs}ms`);
+
+    // manaUsed and totalInstructionsExecuted are tx-level totals reported by the simulator.
+    txMetrics.manaUsed = gasUsed?.publicGas.l2Gas;
+    txMetrics.totalInstructionsExecuted = Number(stats?.['total_instructions_executed'] ?? 0);
+    txMetrics.revertedCode = revertedCode;
+
+    this.currentTxLabel = undefined;
+  }
+
+  recordEnqueuedCallSimulation(
+    fnName: string,
+    durationMs: number,
+    manaUsed: number,
+    totalInstructionsExecuted: number,
+  ) {
+    this.#recordEnqueuedCallSimulation(fnName, durationMs, manaUsed, totalInstructionsExecuted, false);
+  }
+
+  recordEnqueuedCallSimulationFailure(
+    fnName: string,
+    durationMs: number,
+    manaUsed: number,
+    totalInstructionsExecuted: number,
+  ) {
+    this.#recordEnqueuedCallSimulation(fnName, durationMs, manaUsed, totalInstructionsExecuted, true);
+  }
+
+  #recordEnqueuedCallSimulation(
+    fnName: string,
+    durationMs: number,
+    manaUsed: number,
+    totalInstructionsExecuted: number,
+    reverted: boolean,
+  ) {
+    assert(this.currentTxLabel, 'Cannot record enqueued call simulation when no tx is live');
+    const txMetrics = this.txMetrics.get(this.currentTxLabel)!;
+    txMetrics.enqueuedCalls.push({
+      fnName,
+      durationMs,
+      manaUsed,
+      totalInstructionsExecuted: totalInstructionsExecuted,
+      reverted,
+    });
+  }
+
+  recordPrivateEffectsInsertion(durationUs: number, type: 'revertible' | 'non-revertible') {
+    assert(this.currentTxLabel, 'Cannot record private effects insertion when no tx is live');
+    const txMetrics = this.txMetrics.get(this.currentTxLabel)!;
+    if (type === 'revertible') {
+      assert(
+        txMetrics.revertiblePrivateInsertionsUs === undefined,
+        'Cannot RE-record revertible insertions of private effects',
+      );
+      txMetrics.revertiblePrivateInsertionsUs = durationUs;
+    } else {
+      assert(
+        txMetrics.nonRevertiblePrivateInsertionsUs === undefined,
+        'Cannot RE-record non-revertible insertions of private effects',
+      );
+      txMetrics.nonRevertiblePrivateInsertionsUs = durationUs;
+    }
+  }
+
+  recordProverMetrics(txLabel: string, metrics: Partial<PublicTxMetrics>) {
+    if (!this.txMetrics.has(txLabel)) {
+      this.txMetrics.set(txLabel, createEmptyTxMetrics());
+    }
+    const txMetrics = this.txMetrics.get(txLabel)!;
+    for (const [key, value] of Object.entries(metrics)) {
+      if (key in txMetrics) {
+        txMetrics[key as keyof PublicTxMetrics] = value as any;
+      }
+    }
+  }
+
+  prettyPrint(filter: PublicTxMetricsFilter = PublicTxMetricsFilter.ALL) {
+    this.logger.info(this.toPrettyString(filter));
+  }
+
+  toPrettyString(filter: PublicTxMetricsFilter = PublicTxMetricsFilter.ALL) {
+    let pretty = '';
+    //pretty += H_LINE + '\n';
+    pretty += `${H1}Public TX Simulation Metrics (${PublicTxMetricsFilter[filter]})\n`;
+    for (const [txLabel, txMetrics] of this.txMetrics.entries()) {
+      //pretty += H_LINE + '\n';
+      pretty += `${H2}TX Label: ${txLabel}\n`;
+      if (
+        filter == PublicTxMetricsFilter.DURATIONS ||
+        filter === PublicTxMetricsFilter.TOTALS ||
+        filter === PublicTxMetricsFilter.ALL
+      ) {
+        pretty += `${INDENT0}Total duration: ${fmtNum(txMetrics.totalDurationMs, 'ms')}\n`;
+      }
+      if (filter === PublicTxMetricsFilter.TOTALS || filter === PublicTxMetricsFilter.ALL) {
+        const manaUsed = txMetrics.manaUsed || 0;
+        pretty += `${INDENT0}Total mana used: ${fmtNum(manaUsed)}\n`;
+        const manaPerSecond = Math.round((manaUsed * 1000) / txMetrics.totalDurationMs);
+        pretty += `${INDENT0}Mana per second: ${fmtNum(manaPerSecond)}\n`;
+      }
+
+      if (
+        filter === PublicTxMetricsFilter.INSTRUCTIONS ||
+        filter === PublicTxMetricsFilter.TOTALS ||
+        filter === PublicTxMetricsFilter.ALL
+      ) {
+        pretty += `${INDENT0}Total instructions executed: ${fmtNum(txMetrics.totalInstructionsExecuted)}\n`;
+      }
+      if (filter === PublicTxMetricsFilter.DURATIONS || filter === PublicTxMetricsFilter.ALL) {
+        pretty += `${INDENT0}Private insertions:\n`;
+        pretty += `${INDENT1}Non-revertible: ${fmtNum(txMetrics.nonRevertiblePrivateInsertionsUs! / 1_000, 'ms')}\n`;
+        pretty += `${INDENT1}Revertible: ${fmtNum(txMetrics.revertiblePrivateInsertionsUs! / 1_000, 'ms')}\n`;
+      }
+      if (filter === PublicTxMetricsFilter.PROVING || filter === PublicTxMetricsFilter.ALL) {
+        let provingPretty = '';
+        if (txMetrics.proverSimulationStepMs !== undefined) {
+          provingPretty += `${INDENT1}Simulation (all): ${fmtNum(txMetrics.proverSimulationStepMs, 'ms')}\n`;
+        }
+        if (txMetrics.proverProvingStepMs !== undefined) {
+          provingPretty += `${INDENT1}Proving (all): ${fmtNum(txMetrics.proverProvingStepMs, 'ms')}\n`;
+        }
+        if (txMetrics.proverTraceGenerationStepMs !== undefined) {
+          provingPretty += `${INDENT1}Trace generation (all): ${fmtNum(txMetrics.proverTraceGenerationStepMs, 'ms')}\n`;
+        }
+        if (txMetrics.traceGenerationInteractionsMs !== undefined) {
+          provingPretty += `${INDENT1}Trace generation interactions: ${fmtNum(txMetrics.traceGenerationInteractionsMs, 'ms')}\n`;
+        }
+        if (txMetrics.traceGenerationTracesMs !== undefined) {
+          provingPretty += `${INDENT1}Trace generation traces: ${fmtNum(txMetrics.traceGenerationTracesMs, 'ms')}\n`;
+        }
+        if (txMetrics.provingSumcheckMs !== undefined) {
+          provingPretty += `${INDENT1}Sumcheck: ${fmtNum(txMetrics.provingSumcheckMs, 'ms')}\n`;
+        }
+        if (txMetrics.provingPcsMs !== undefined) {
+          provingPretty += `${INDENT1}PCS: ${fmtNum(txMetrics.provingPcsMs, 'ms')}\n`;
+        }
+        if (txMetrics.provingLogDerivativeInverseMs !== undefined) {
+          provingPretty += `${INDENT1}Log derivative inverse: ${fmtNum(txMetrics.provingLogDerivativeInverseMs, 'ms')}\n`;
+        }
+        if (txMetrics.provingLogDerivativeInverseCommitmentsMs !== undefined) {
+          provingPretty += `${INDENT1}Log derivative inverse commitments: ${fmtNum(txMetrics.provingLogDerivativeInverseCommitmentsMs, 'ms')}\n`;
+        }
+        if (txMetrics.provingWireCommitmentsMs !== undefined) {
+          provingPretty += `${INDENT1}Wire commitments: ${fmtNum(txMetrics.provingWireCommitmentsMs, 'ms')}\n`;
+        }
+        if (provingPretty.length > 0) {
+          pretty += `${INDENT0}Proving:\n${provingPretty}`;
+        }
+      }
+      if (filter !== PublicTxMetricsFilter.TOTALS) {
+        // totals exclude enqueued calls
+        pretty += this.#enqueuedCallsToPrettyString(txMetrics, filter);
+      }
+      if (txMetrics.revertedCode !== undefined && !txMetrics.revertedCode.isOK()) {
+        pretty += `${INDENT0}Reverted code: ${txMetrics.revertedCode?.getDescription()}\n`;
+      }
+      pretty += H_LINE + '\n';
+    }
+    return pretty;
+  }
+
+  #enqueuedCallsToPrettyString(txMetrics: PublicTxMetrics, filter: PublicTxMetricsFilter) {
+    let pretty = '';
+    pretty += `${INDENT0}Enqueued public calls:\n`;
+    for (const enqueuedCall of txMetrics.enqueuedCalls) {
+      pretty += `${INDENT1}**Fn: ${enqueuedCall.fnName}**\n`;
+      if (filter === PublicTxMetricsFilter.DURATIONS || filter === PublicTxMetricsFilter.ALL) {
+        pretty += `${INDENT2}Duration: ${fmtNum(enqueuedCall.durationMs, 'ms')}\n`;
+      }
+      if (filter === PublicTxMetricsFilter.ALL) {
+        pretty += `${INDENT2}Mana used: ${fmtNum(enqueuedCall.manaUsed)}\n`;
+        const manaPerSecond = Math.round((enqueuedCall.manaUsed * 1000) / enqueuedCall.durationMs);
+        pretty += `${INDENT2}Mana per second: ${fmtNum(manaPerSecond)}\n`;
+      }
+
+      if (filter === PublicTxMetricsFilter.INSTRUCTIONS || filter === PublicTxMetricsFilter.ALL) {
+        pretty += `${INDENT2}Instructions executed: ${fmtNum(enqueuedCall.totalInstructionsExecuted)}\n`;
+      }
+      if (enqueuedCall.reverted) {
+        pretty += `${INDENT2}Reverted!\n`;
+      }
+    }
+    return pretty;
+  }
+
+  toJSON(indent = 2) {
+    return JSON.stringify(Object.fromEntries(this.txMetrics.entries()), null, indent);
+  }
+
+  toGithubActionBenchmarkJSON(indent = 2) {
+    const metricsInfo = {
+      totalInstructionsExecuted: {
+        name: 'totalInstructionsExecuted',
+        unit: '#instructions',
+        category: PublicTxMetricsFilter.INSTRUCTIONS,
+      },
+      totalDurationMs: {
+        name: 'totalDurationMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.DURATIONS,
+      },
+      manaUsed: {
+        name: 'manaUsed',
+        unit: 'mana',
+        category: PublicTxMetricsFilter.TOTALS,
+      },
+      nonRevertiblePrivateInsertionsUs: {
+        name: 'nonRevertiblePrivateInsertionsUs',
+        unit: 'us',
+        category: PublicTxMetricsFilter.DURATIONS,
+      },
+      revertiblePrivateInsertionsUs: {
+        name: 'revertiblePrivateInsertionsUs',
+        unit: 'us',
+        category: PublicTxMetricsFilter.DURATIONS,
+      },
+      proverSimulationStepMs: {
+        name: 'proverSimulationStepMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      proverProvingStepMs: {
+        name: 'proverProvingStepMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      proverTraceGenerationStepMs: {
+        name: 'proverTraceGenerationStepMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      traceGenerationInteractionsMs: {
+        name: 'traceGenerationInteractionsMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      traceGenerationTracesMs: {
+        name: 'traceGenerationTracesMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      provingSumcheckMs: {
+        name: 'provingSumcheckMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      provingPcsMs: {
+        name: 'provingPcsMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      provingLogDerivativeInverseMs: {
+        name: 'provingLogDerivativeInverseMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      provingLogDerivativeInverseCommitmentsMs: {
+        name: 'provingLogDerivativeInverseCommitmentsMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+      provingWireCommitmentsMs: {
+        name: 'provingWireCommitmentsMs',
+        unit: 'ms',
+        category: PublicTxMetricsFilter.PROVING,
+      },
+    };
+
+    const data = [];
+    for (const [txLabel, txMetrics] of this.txMetrics.entries()) {
+      for (const [key, value] of Object.entries(txMetrics)) {
+        if (value !== undefined && key in metricsInfo) {
+          data.push({
+            name: `${txLabel}/${metricsInfo[key as keyof typeof metricsInfo].name}`,
+            value: value,
+            unit: metricsInfo[key as keyof typeof metricsInfo].unit,
+          });
+        }
+      }
+    }
+    return JSON.stringify(data, null, indent);
+  }
+}
+
+function fmtNum(num: number, unit?: string) {
+  return `\`${num.toLocaleString()}${unit ? ` ${unit}` : ''}\``;
+}

package/src/public/unique_class_ids.ts

@@ -0,0 +1,79 @@
+import { MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS } from '@aztec-labs/constants';
+import { strict as assert } from 'assert';
+
+/**
+ * A class manage a de-duplicated set of class IDs that errors if you try to add a duplicate.
+ * Useful for bytecode retrieval hints to avoid duplicates in parent trace & grandparent trace....
+ */
+export class UniqueClassIds {
+  private readonly classIds: Set<string> = new Set();
+
+  constructor(private readonly parent?: UniqueClassIds) {}
+
+  /**
+   * Create a fork that references this one as its parent
+   */
+  public fork() {
+    return new UniqueClassIds(/*parent=*/ this);
+  }
+
+  /**
+   * Check for a class ID here or in parent's (recursively).
+   *
+   * @param classId - the contract class ID (as a string) to check
+   * @returns boolean: whether the class ID is here
+   */
+  public has(classId: string): boolean {
+    // First try check this' classIds
+    let here = this.classIds.has(classId);
+    // Then try parent's
+    if (!here && this.parent) {
+      // Note: this will recurse to grandparent/etc until we reach top or find it
+      here = this.parent.has(classId);
+    }
+    return here;
+  }
+
+  /**
+   * Get the total number of classIds
+   */
+  public size(): number {
+    return this.classIds.size + (this.parent ? this.parent.size() : 0);
+  }
+
+  /**
+   * Add a class ID (if not already present) to the set.
+   *
+   * @param classId - the contract class ID (as a string)
+   */
+  public add(classId: string) {
+    assert(!this.has(classId), `Bug! Tried to add duplicate classId ${classId} to set of unique classIds.`);
+    if (!this.has(classId)) {
+      this.classIds.add(classId);
+      assert(
+        this.size() <= MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS,
+        `Bug! Surpassed limit (${MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS}) of unique contract class IDs used for bytecode retrievals.`,
+      );
+    }
+  }
+
+  /**
+   * Merge in another set of unique class IDs into this one, but fail on duplicates.
+   *
+   * @param incoming: other unique class IDs
+   */
+  public acceptAndMerge(incoming: UniqueClassIds) {
+    for (const classId of incoming.classIds.keys()) {
+      assert(
+        !this.has(classId),
+        `Bug! Cannot merge classId ${classId} into set of unique classIds as it already exists.`,
+      );
+      this.classIds.add(classId);
+    }
+    // since set() has an assertion, and size() always checks parent, this should be impossible
+    assert(
+      this.size() <= MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS,
+      `Bug! Merging unique class Ids should never exceed the limit of ${MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS}.`,
+    );
+  }
+}

package/src/public/utils.ts

@@ -0,0 +1,16 @@
+import { PublicCallRequestWithCalldata, type Tx, TxExecutionPhase } from '@aztec-labs/stdlib/tx';
+
+export function getCallRequestsWithCalldataByPhase(tx: Tx, phase: TxExecutionPhase): PublicCallRequestWithCalldata[] {
+  switch (phase) {
+    case TxExecutionPhase.SETUP:
+      return tx.getNonRevertiblePublicCallRequestsWithCalldata();
+    case TxExecutionPhase.APP_LOGIC:
+      return tx.getRevertiblePublicCallRequestsWithCalldata();
+    case TxExecutionPhase.TEARDOWN: {
+      const request = tx.getTeardownPublicCallRequestWithCalldata();
+      return request ? [request] : [];
+    }
+    default:
+      throw new Error(`Unknown phase: ${phase}`);
+  }
+}

package/src/server.ts

@@ -0,0 +1,6 @@
+export * from './public/index.js';
+export * from './private/acvm/index.js';
+export { WASMSimulatorWithBlobs } from './private/acvm_wasm_with_blobs.js';
+export { NativeACVMSimulator } from './private/acvm_native.js';
+export { type CircuitSimulator, type DecodedError } from './private/circuit_simulator.js';
+export * from './common/index.js';