@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/tx/simulated_tx.ts

@@ -0,0 +1,187 @@
+import { type ZodFor, optional } from '@aztec-labs/foundation/schemas';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import { z } from 'zod';
+
+import {
+  type ContractInstanceWithAddress,
+  ContractInstanceWithAddressSchema,
+} from '../contract/interfaces/contract_instance.js';
+import { Gas } from '../gas/gas.js';
+import type { GasUsed } from '../gas/gas_used.js';
+import { MAX_RPC_CONTRACT_OVERRIDES_LEN, MAX_RPC_PUBLIC_STORAGE_OVERRIDES_LEN } from '../interfaces/api_limit.js';
+import { type PublicStorageOverride, PublicStorageOverrideSchema } from '../interfaces/public_storage_override.js';
+import { PrivateKernelTailCircuitPublicInputs } from '../kernel/private_kernel_tail_circuit_public_inputs.js';
+import { ChonkProof } from '../proofs/chonk_proof.js';
+import type { OffchainEffect } from './offchain_effect.js';
+import {
+  PrivateCallExecutionResult,
+  PrivateExecutionResult,
+  collectOffchainEffects,
+  collectSortedContractClassLogs,
+} from './private_execution_result.js';
+import { type SimulationStats, SimulationStatsSchema } from './profiling.js';
+import { NestedProcessReturnValues, PublicSimulationOutput } from './public_simulation_output.js';
+import { Tx } from './tx.js';
+
+/*
+ * If passed during the execution of a user circuit, the contract function simulator will replace
+ * the contract instance at that address with the one provided. An example use case would be
+ * overriding your own account contract so that valid signatures don't have to be provided while
+ * simulating. The override's `currentContractClassId` resolves through PXE's locally registered
+ * classes, so pre-register the target artifact via `pxe.registerContractClass(...)`.
+ */
+export type ContractOverrides = Record<string /* AztecAddress as string */, { instance: ContractInstanceWithAddress }>;
+
+/*
+ * Optional values that can be overridden during simulation. `publicStorage` writes to the public-data
+ * tree fork. `contracts` overrides contract instances in the contract DB.
+ * In order to simulate a transaction with these set, it *must* be run without the kernel circuits,
+ * or validations will fail.
+ */
+export class SimulationOverrides {
+  public publicStorage?: PublicStorageOverride[];
+  public contracts?: ContractOverrides;
+
+  constructor(args: { publicStorage?: PublicStorageOverride[]; contracts?: ContractOverrides } = {}) {
+    this.publicStorage = args.publicStorage?.length ? args.publicStorage : undefined;
+    this.contracts = args.contracts && Object.keys(args.contracts).length > 0 ? args.contracts : undefined;
+  }
+
+  static get schema() {
+    return z
+      .object({
+        publicStorage: optional(
+          z.array(PublicStorageOverrideSchema).max(MAX_RPC_PUBLIC_STORAGE_OVERRIDES_LEN, {
+            message: `publicStorage must have at most ${MAX_RPC_PUBLIC_STORAGE_OVERRIDES_LEN} entries`,
+          }),
+        ),
+        contracts: optional(
+          z
+            .record(z.string(), z.object({ instance: ContractInstanceWithAddressSchema }))
+            .refine(contracts => Object.keys(contracts).length <= MAX_RPC_CONTRACT_OVERRIDES_LEN, {
+              message: `contracts must have at most ${MAX_RPC_CONTRACT_OVERRIDES_LEN} entries`,
+            }),
+        ),
+      })
+      .transform(args => new SimulationOverrides(args));
+  }
+}
+
+export class PrivateSimulationResult {
+  constructor(
+    public privateExecutionResult: PrivateExecutionResult,
+    public publicInputs: PrivateKernelTailCircuitPublicInputs,
+  ) {}
+
+  getPrivateReturnValues() {
+    return accumulatePrivateReturnValues(this.privateExecutionResult);
+  }
+
+  async toSimulatedTx(): Promise<Tx> {
+    const contractClassLogs = collectSortedContractClassLogs(this.privateExecutionResult);
+
+    return await Tx.create({
+      data: this.publicInputs,
+      chonkProof: ChonkProof.empty(),
+      contractClassLogFields: contractClassLogs,
+      publicFunctionCalldata: this.privateExecutionResult.publicFunctionCalldata,
+    });
+  }
+}
+
+export class TxSimulationResult {
+  constructor(
+    public privateExecutionResult: PrivateExecutionResult,
+    public publicInputs: PrivateKernelTailCircuitPublicInputs,
+    public publicOutput?: PublicSimulationOutput,
+    public stats?: SimulationStats,
+  ) {}
+
+  /** Returns offchain effects collected from private execution. */
+  get offchainEffects(): OffchainEffect[] {
+    return collectOffchainEffects(this.privateExecutionResult);
+  }
+
+  get gasUsed(): GasUsed {
+    return (
+      this.publicOutput?.gasUsed ?? {
+        totalGas: this.publicInputs.gasUsed,
+        billedGas: this.publicInputs.gasUsed,
+        teardownGas: Gas.empty(),
+        publicGas: Gas.empty(),
+      }
+    );
+  }
+
+  static get schema(): ZodFor<TxSimulationResult> {
+    return z
+      .object({
+        privateExecutionResult: PrivateExecutionResult.schema,
+        publicInputs: PrivateKernelTailCircuitPublicInputs.schema,
+        publicOutput: PublicSimulationOutput.schema.optional(),
+        stats: optional(SimulationStatsSchema),
+      })
+      .transform(TxSimulationResult.from);
+  }
+
+  static from(fields: Omit<FieldsOf<TxSimulationResult>, 'gasUsed' | 'offchainEffects'>) {
+    return new TxSimulationResult(
+      fields.privateExecutionResult,
+      fields.publicInputs,
+      fields.publicOutput,
+      fields.stats,
+    );
+  }
+
+  static fromPrivateSimulationResultAndPublicOutput(
+    privateSimulationResult: PrivateSimulationResult,
+    publicOutput?: PublicSimulationOutput,
+    stats?: SimulationStats,
+  ) {
+    return new TxSimulationResult(
+      privateSimulationResult.privateExecutionResult,
+      privateSimulationResult.publicInputs,
+      publicOutput,
+      stats,
+    );
+  }
+
+  static async random() {
+    return new TxSimulationResult(
+      await PrivateExecutionResult.random(),
+      PrivateKernelTailCircuitPublicInputs.empty(),
+      await PublicSimulationOutput.random(),
+    );
+  }
+
+  getPrivateReturnValues() {
+    return new PrivateSimulationResult(this.privateExecutionResult, this.publicInputs).getPrivateReturnValues();
+  }
+
+  toSimulatedTx(): Promise<Tx> {
+    return new PrivateSimulationResult(this.privateExecutionResult, this.publicInputs).toSimulatedTx();
+  }
+
+  getPublicReturnValues() {
+    return this.publicOutput ? this.publicOutput.publicReturnValues : [];
+  }
+}
+
+/**
+ * Recursively accumulate the return values of a call result and its nested executions,
+ * so they can be retrieved in order.
+ * @param executionResult
+ * @returns
+ */
+export function accumulatePrivateReturnValues(executionResult: PrivateExecutionResult): NestedProcessReturnValues {
+  const collectPrivateReturnValuesRecursive = (
+    executionResult: PrivateCallExecutionResult,
+  ): NestedProcessReturnValues => {
+    const acc = new NestedProcessReturnValues(executionResult.returnValues);
+    acc.nested = executionResult.nestedExecutionResults.map(nestedExecutionResult =>
+      collectPrivateReturnValuesRecursive(nestedExecutionResult),
+    );
+    return acc;
+  };
+  return collectPrivateReturnValuesRecursive(executionResult.entrypoint);
+}

package/src/tx/state_reference.ts

@@ -0,0 +1,133 @@
+import { MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX, STATE_REFERENCE_LENGTH } from '@aztec-labs/constants';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec-labs/foundation/serialize';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import { inspect } from 'util';
+import { z } from 'zod';
+
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { PartialStateReference } from './partial_state_reference.js';
+
+/**
+ * Stores snapshots of all the trees but archive.
+ */
+export class StateReference {
+  constructor(
+    /** Snapshot of the l1 to l2 message tree. */
+    public l1ToL2MessageTree: AppendOnlyTreeSnapshot,
+    /** Reference to the rest of the state. */
+    public partial: PartialStateReference,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        l1ToL2MessageTree: AppendOnlyTreeSnapshot.schema,
+        partial: PartialStateReference.schema,
+      })
+      .transform(({ l1ToL2MessageTree, partial }) => new StateReference(l1ToL2MessageTree, partial));
+  }
+
+  getSize() {
+    return this.l1ToL2MessageTree.getSize() + this.partial.getSize();
+  }
+
+  static getFields(fields: FieldsOf<StateReference>) {
+    return [fields.l1ToL2MessageTree, fields.partial] as const;
+  }
+
+  static from(fields: FieldsOf<StateReference>) {
+    return new StateReference(...StateReference.getFields(fields));
+  }
+
+  // Note: The order here must match the order in the ProposedHeaderLib solidity library.
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.l1ToL2MessageTree, this.partial);
+  }
+
+  toFields(): Fr[] {
+    const fields = [...this.l1ToL2MessageTree.toFields(), ...this.partial.toFields()];
+    if (fields.length !== STATE_REFERENCE_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for StateReference. Expected ${STATE_REFERENCE_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): StateReference {
+    const reader = BufferReader.asReader(buffer);
+    return new StateReference(reader.readObject(AppendOnlyTreeSnapshot), reader.readObject(PartialStateReference));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): StateReference {
+    const reader = FieldReader.asReader(fields);
+
+    const l1ToL2MessageTree = AppendOnlyTreeSnapshot.fromFields(reader);
+    const partial = PartialStateReference.fromFields(reader);
+
+    return new StateReference(l1ToL2MessageTree, partial);
+  }
+
+  static empty(): StateReference {
+    return new StateReference(AppendOnlyTreeSnapshot.empty(), PartialStateReference.empty());
+  }
+
+  static random(): StateReference {
+    return new StateReference(AppendOnlyTreeSnapshot.random(), PartialStateReference.random());
+  }
+
+  toAbi(): [ReturnType<AppendOnlyTreeSnapshot['toAbi']>, ReturnType<PartialStateReference['toAbi']>] {
+    return [this.l1ToL2MessageTree.toAbi(), [...this.partial.toAbi()]];
+  }
+
+  isEmpty(): boolean {
+    return this.l1ToL2MessageTree.isEmpty() && this.partial.isEmpty();
+  }
+
+  toInspect() {
+    return {
+      l1ToL2MessageTree: this.l1ToL2MessageTree.root.toString(),
+      noteHashTree: this.partial.noteHashTree.root.toString(),
+      nullifierTree: this.partial.nullifierTree.root.toString(),
+      publicDataTree: this.partial.publicDataTree.root.toString(),
+    };
+  }
+
+  /**
+   * Validates the partial-state trees have the expected number of leaves (multiple of number of insertions per tx).
+   *
+   * The L1-to-L2 message tree is not checked: it grows by real message counts at compact (unaligned)
+   * indices, so its next-available leaf index is no longer a multiple of any per-block subtree size.
+   */
+  public validate() {
+    if (this.partial.noteHashTree.nextAvailableLeafIndex % MAX_NOTE_HASHES_PER_TX !== 0) {
+      throw new Error(
+        `Invalid note hash tree next available leaf index ${this.partial.noteHashTree.nextAvailableLeafIndex} (must be a multiple of ${MAX_NOTE_HASHES_PER_TX})`,
+      );
+    }
+    if (this.partial.nullifierTree.nextAvailableLeafIndex % MAX_NULLIFIERS_PER_TX !== 0) {
+      throw new Error(
+        `Invalid nullifier tree next available leaf index ${this.partial.nullifierTree.nextAvailableLeafIndex} (must be a multiple of ${MAX_NULLIFIERS_PER_TX})`,
+      );
+    }
+  }
+
+  [inspect.custom]() {
+    return `StateReference {
+  l1ToL2MessageTree: ${inspect(this.l1ToL2MessageTree)},
+  noteHashTree: ${inspect(this.partial.noteHashTree)},
+  nullifierTree: ${inspect(this.partial.nullifierTree)},
+  publicDataTree: ${inspect(this.partial.publicDataTree)},
+}`;
+  }
+
+  public equals(other: this): boolean {
+    return this.l1ToL2MessageTree.equals(other.l1ToL2MessageTree) && this.partial.equals(other.partial);
+  }
+}

package/src/tx/tree_snapshots.ts

@@ -0,0 +1,131 @@
+import { TREE_SNAPSHOTS_LENGTH } from '@aztec-labs/constants';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec-labs/foundation/serialize';
+import { inspect } from 'util';
+import { z } from 'zod';
+
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+
+/**
+ * Stores snapshots of all the trees but archive.
+ */
+export class TreeSnapshots {
+  constructor(
+    public l1ToL2MessageTree: AppendOnlyTreeSnapshot,
+    public noteHashTree: AppendOnlyTreeSnapshot,
+    public nullifierTree: AppendOnlyTreeSnapshot,
+    public publicDataTree: AppendOnlyTreeSnapshot,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        l1ToL2MessageTree: AppendOnlyTreeSnapshot.schema,
+        noteHashTree: AppendOnlyTreeSnapshot.schema,
+        nullifierTree: AppendOnlyTreeSnapshot.schema,
+        publicDataTree: AppendOnlyTreeSnapshot.schema,
+      })
+      .transform(
+        ({ l1ToL2MessageTree, noteHashTree, nullifierTree, publicDataTree }) =>
+          new TreeSnapshots(l1ToL2MessageTree, noteHashTree, nullifierTree, publicDataTree),
+      );
+  }
+
+  getSize() {
+    return (
+      this.l1ToL2MessageTree.getSize() +
+      this.noteHashTree.getSize() +
+      this.nullifierTree.getSize() +
+      this.publicDataTree.getSize()
+    );
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): TreeSnapshots {
+    const reader = BufferReader.asReader(buffer);
+    return new TreeSnapshots(
+      reader.readObject(AppendOnlyTreeSnapshot),
+      reader.readObject(AppendOnlyTreeSnapshot),
+      reader.readObject(AppendOnlyTreeSnapshot),
+      reader.readObject(AppendOnlyTreeSnapshot),
+    );
+  }
+
+  // Note: The order here must match the order in the ProposedHeaderLib solidity library.
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.l1ToL2MessageTree, this.noteHashTree, this.nullifierTree, this.publicDataTree);
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+
+    const l1ToL2MessageTree = AppendOnlyTreeSnapshot.fromFields(reader);
+    const noteHashTree = AppendOnlyTreeSnapshot.fromFields(reader);
+    const nullifierTree = AppendOnlyTreeSnapshot.fromFields(reader);
+    const publicDataTree = AppendOnlyTreeSnapshot.fromFields(reader);
+
+    return new TreeSnapshots(l1ToL2MessageTree, noteHashTree, nullifierTree, publicDataTree);
+  }
+
+  toFields(): Fr[] {
+    const fields = [
+      ...this.l1ToL2MessageTree.toFields(),
+      ...this.noteHashTree.toFields(),
+      ...this.nullifierTree.toFields(),
+      ...this.publicDataTree.toFields(),
+    ];
+    if (fields.length !== TREE_SNAPSHOTS_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for TreeSnapshots. Expected ${TREE_SNAPSHOTS_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  static empty(): TreeSnapshots {
+    return new TreeSnapshots(
+      AppendOnlyTreeSnapshot.empty(),
+      AppendOnlyTreeSnapshot.empty(),
+      AppendOnlyTreeSnapshot.empty(),
+      AppendOnlyTreeSnapshot.empty(),
+    );
+  }
+
+  /**
+   * Creates a TreeSnapshots instance from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing TreeSnapshots fields
+   * @returns A TreeSnapshots instance
+   */
+  static fromPlainObject(obj: any): TreeSnapshots {
+    return new TreeSnapshots(
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.l1ToL2MessageTree),
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.noteHashTree),
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.nullifierTree),
+      AppendOnlyTreeSnapshot.fromPlainObject(obj.publicDataTree),
+    );
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.l1ToL2MessageTree.isEmpty() &&
+      this.noteHashTree.isEmpty() &&
+      this.nullifierTree.isEmpty() &&
+      this.publicDataTree.isEmpty()
+    );
+  }
+
+  [inspect.custom]() {
+    return `TreeSnapshots {
+  l1ToL2MessageTree: ${inspect(this.l1ToL2MessageTree)},
+  noteHashTree: ${inspect(this.noteHashTree)},
+  nullifierTree: ${inspect(this.nullifierTree)},
+  publicDataTree: ${inspect(this.publicDataTree)},
+}`;
+  }
+}