@aztec/pxe 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/contract_function_simulator/ephemeral_array_service.ts

@@ -0,0 +1,110 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+
+/** In-memory store for ephemeral arrays scoped to a single contract call frame. */
+export class EphemeralArrayService {
+  /**
+   * Maps a slot to the elements of the array stored at that slot. Each element is a serialized representation of
+   * the original type.
+   */
+  #arrays: Map<string, Fr[][]> = new Map();
+
+  /** Returns all elements in the array, or an empty array if uninitialized. */
+  readArrayAt(slot: Fr): Fr[][] {
+    return this.#arrays.get(slot.toString()) ?? [];
+  }
+
+  #setArray(slot: Fr, array: Fr[][]): void {
+    this.#arrays.set(slot.toString(), array);
+  }
+
+  /** Returns the number of elements in the array at the given slot. */
+  len(slot: Fr): number {
+    return this.readArrayAt(slot).length;
+  }
+
+  /** Appends an element to the array and returns the new length. */
+  push(slot: Fr, elements: Fr[]): number {
+    const array = this.readArrayAt(slot);
+    array.push(elements);
+    this.#setArray(slot, array);
+    return array.length;
+  }
+
+  /** Removes and returns the last element. Throws if empty. */
+  pop(slot: Fr): Fr[] {
+    const array = this.readArrayAt(slot);
+    if (array.length === 0) {
+      throw new Error(`Ephemeral array at slot ${slot} is empty`);
+    }
+    const element = array.pop()!;
+    this.#setArray(slot, array);
+    return element;
+  }
+
+  /** Returns the element at the given index. Throws if out of bounds. */
+  get(slot: Fr, index: number): Fr[] {
+    const array = this.readArrayAt(slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Ephemeral array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    return array[index];
+  }
+
+  /** Overwrites the element at the given index. Throws if out of bounds. */
+  set(slot: Fr, index: number, value: Fr[]): void {
+    const array = this.readArrayAt(slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Ephemeral array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array[index] = value;
+  }
+
+  /** Removes the element at the given index, shifting subsequent elements backward. Throws if out of bounds. */
+  remove(slot: Fr, index: number): void {
+    const array = this.readArrayAt(slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Ephemeral array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array.splice(index, 1);
+  }
+
+  /** Removes all elements from the array. */
+  clear(slot: Fr): void {
+    this.#arrays.delete(slot.toString());
+  }
+
+  /** Allocates a fresh, unused slot for a new ephemeral array. */
+  allocateSlot(): Fr {
+    let slot: Fr;
+    do {
+      slot = Fr.random();
+    } while (this.#arrays.has(slot.toString()));
+    return slot;
+  }
+
+  /** Creates a new ephemeral array pre-populated with the given elements and returns its slot. */
+  newArray(elements: Fr[][]): Fr {
+    const slot = this.allocateSlot();
+    this.#setArray(slot, elements);
+    return slot;
+  }
+
+  /** Copies `count` elements from the source array to the destination array (overwrites destination). */
+  copy(srcSlot: Fr, dstSlot: Fr, count: number): void {
+    const srcArray = this.readArrayAt(srcSlot);
+    if (count > srcArray.length) {
+      throw new Error(
+        `Cannot copy ${count} elements from ephemeral array of length ${srcArray.length} at slot ${srcSlot}`,
+      );
+    }
+    // Deep copy the elements to avoid aliasing
+    const copied = srcArray.slice(0, count).map(el => [...el]);
+    this.#setArray(dstSlot, copied);
+  }
+}

package/src/contract_function_simulator/execution_note_cache.ts

@@ -0,0 +1,252 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { computeNoteHashNonce, computeUniqueNoteHash, siloNoteHash, siloNullifier } from '@aztec/stdlib/hash';
+
+import type { NoteData } from './noir-structs/note_data.js';
+
+interface PendingNote {
+  note: NoteData;
+  counter: number;
+  noteHashForConsumption: Fr;
+}
+
+/**
+ * Data that's accessible by all the function calls in an execution.
+ */
+export class ExecutionNoteCache {
+  /**
+   * New notes created in this transaction.
+   * They are pushed to this array in the same order as they are emitted.
+   */
+  private notes: PendingNote[] = [];
+  /**
+   * This mapping maps from a contract address to the notes in the contract.
+   */
+  private noteMap: Map<bigint, PendingNote[]> = new Map();
+
+  /**
+   * This maps from a contract address to the nullifiers emitted from the contract.
+   * The note which is nullified might be new or not (i.e., was generated in a previous transaction).
+   * Note that their value (bigint representation) is used because Frs cannot be looked up in Sets.
+   */
+  private nullifierMap: Map<bigint, Set<bigint>> = new Map();
+
+  /**
+   * Nullifiers emitted by private calls in this transaction.
+   */
+  private emittedNullifiers: Set<bigint> = new Set();
+
+  /**
+   * The counter that separates non-revertible side effects (which persist even if the tx reverts) from revertible ones.
+   */
+  private minRevertibleSideEffectCounter = 0;
+
+  private inRevertiblePhase = false;
+
+  /**
+   * Whether the protocol nullifier was used for nonce generation.
+   * We don't need to use the protocol nullifier if a non-revertible nullifier is emitted.
+   */
+  private usedProtocolNullifierForNonces: boolean | undefined;
+
+  constructor(private readonly protocolNullifier: Fr) {}
+
+  /**
+   * Enters the revertible phase of the transaction.
+   * @param minRevertibleSideEffectCounter - The counter at which the transaction enters the revertible phase.
+   */
+  public async setMinRevertibleSideEffectCounter(minRevertibleSideEffectCounter: number) {
+    if (this.inRevertiblePhase) {
+      throw new Error(
+        `Cannot enter the revertible phase twice. Current counter: ${minRevertibleSideEffectCounter}. Previous enter counter: ${this.minRevertibleSideEffectCounter}`,
+      );
+    }
+    this.inRevertiblePhase = true;
+    this.minRevertibleSideEffectCounter = minRevertibleSideEffectCounter;
+
+    const nullifiers = this.getEmittedNullifiers();
+    // If there are no nullifiers emitted by private calls so far, we use the protocol nullifier as the nonce generator.
+    // Note: There could still be nullifiers emitted after the counter is set, but those nullifiers are revertible, so
+    // we don't want to use them as the nonce generator.
+    this.usedProtocolNullifierForNonces = nullifiers.length === 0;
+    const nonceGenerator = this.usedProtocolNullifierForNonces ? this.protocolNullifier : new Fr(nullifiers[0]);
+
+    // The existing pending notes are all non-revertible.
+    // They cannot be squashed by nullifiers emitted after minRevertibleSideEffectCounter is set.
+    // Their indexes in the tx are known at this point and won't change. So we can assign a nonce to each one of them.
+    // The nonces will be used to create the "unique" note hashes.
+    const updatedNotes = await Promise.all(
+      this.notes.map(async ({ note, counter }, i) => {
+        const noteNonce = await computeNoteHashNonce(nonceGenerator, i);
+        const uniqueNoteHash = await computeUniqueNoteHash(
+          noteNonce,
+          await siloNoteHash(note.contractAddress, note.noteHash),
+        );
+        return {
+          counter,
+          note: { ...note, noteNonce },
+          noteHashForConsumption: uniqueNoteHash,
+        };
+      }),
+    );
+    // Rebuild the data.
+    this.notes = [];
+    this.noteMap = new Map();
+    updatedNotes.forEach(n => this.#addNote(n));
+  }
+
+  public isSideEffectCounterRevertible(sideEffectCounter: number): boolean {
+    if (!this.inRevertiblePhase) {
+      return false;
+    }
+    return sideEffectCounter >= this.minRevertibleSideEffectCounter;
+  }
+
+  public finish() {
+    // If we never entered the revertible phase, and there are no nullifiers emitted, we need to use the protocol
+    // nullifier as the nonce generator.
+    if (!this.inRevertiblePhase) {
+      this.usedProtocolNullifierForNonces = this.getEmittedNullifiers().length === 0;
+    }
+  }
+
+  /**
+   * Add a new note to cache.
+   * @param note - New note created during execution.
+   */
+  public addNewNote(note: NoteData, counter: number) {
+    const previousNote = this.notes[this.notes.length - 1];
+    if (previousNote && previousNote.counter >= counter) {
+      throw new Error(
+        `Note hash counters must be strictly increasing. Current counter: ${counter}. Previous counter: ${previousNote.counter}.`,
+      );
+    }
+
+    this.#addNote({ note, counter, noteHashForConsumption: note.noteHash });
+  }
+
+  /**
+   * Add a nullifier to cache. It could be for a db note or a new note created during execution.
+   * @param contractAddress - Contract address of the note.
+   * @param innerNullifier - Inner nullifier of the note.
+   * @param noteHash - A hash of the note. If this value equals 0, it means the note being nullified is from a previous
+   * transaction (and thus not a new note).
+   */
+  public async nullifyNote(contractAddress: AztecAddress, innerNullifier: Fr, noteHash: Fr) {
+    const siloedNullifier = (await siloNullifier(contractAddress, innerNullifier)).toBigInt();
+    let nullifiedNoteHashCounter: number | undefined = undefined;
+    // Find and remove the matching new note and log(s) if the emitted noteHash is not empty.
+    if (!noteHash.isEmpty()) {
+      const notesInContract = this.noteMap.get(contractAddress.toBigInt()) ?? [];
+      const noteIndexToRemove = notesInContract.findIndex(n => n.noteHashForConsumption.equals(noteHash));
+      if (noteIndexToRemove === -1) {
+        throw new Error('Attempt to remove a pending note that does not exist.');
+      }
+
+      const note = notesInContract.splice(noteIndexToRemove, 1)[0];
+      nullifiedNoteHashCounter = note.counter;
+      this.noteMap.set(contractAddress.toBigInt(), notesInContract);
+      this.notes = this.notes.filter(n => n.counter !== note.counter);
+
+      // If the note is non revertible and the nullifier was emitted in the revertible phase, both the note hash and the nullifier will be emitted
+      if (this.inRevertiblePhase && note.counter < this.minRevertibleSideEffectCounter) {
+        this.#recordNullifier(contractAddress, siloedNullifier);
+      }
+    } else {
+      // If the note being nullified comes from a previous tx the nullifier will be emitted.
+      this.#recordNullifier(contractAddress, siloedNullifier);
+    }
+    return nullifiedNoteHashCounter;
+  }
+
+  /**
+   * Adds a nullifier to the cache. Note cache needs to track all nullifiers to decide which nullifier to use for note siloing.
+   * @param contractAddress - Contract address that emitted the nullifier.
+   * @param innerNullifier
+   */
+  public async nullifierCreated(contractAddress: AztecAddress, innerNullifier: Fr) {
+    const siloedNullifier = (await siloNullifier(contractAddress, innerNullifier)).toBigInt();
+    this.#recordNullifier(contractAddress, siloedNullifier);
+  }
+
+  /**
+   * Return notes created up to current point in execution.
+   * If a nullifier for a note in this list is emitted, the note will be deleted.
+   * @param contractAddress - Contract address of the notes.
+   * @param owner - Owner of the notes. If undefined, returns all notes regardless of owner.
+   * @param storageSlot - Storage slot of the notes.
+   **/
+  public getNotes(contractAddress: AztecAddress, owner: AztecAddress | undefined, storageSlot: Fr) {
+    const notes = this.noteMap.get(contractAddress.toBigInt()) ?? [];
+    return notes
+      .filter(n => owner === undefined || n.note.owner.equals(owner))
+      .filter(n => n.note.storageSlot.equals(storageSlot))
+      .map(n => n.note);
+  }
+
+  /**
+   * Check if a note exists in the newNotes array.
+   * @param contractAddress - Contract address of the note.
+   * @param storageSlot - Storage slot of the note.
+   * @param noteHash - A hash of the note.
+   **/
+  public checkNoteExists(contractAddress: AztecAddress, noteHash: Fr) {
+    const notes = this.noteMap.get(contractAddress.toBigInt()) ?? [];
+    return notes.some(n => n.note.noteHash.equals(noteHash));
+  }
+
+  /**
+   * Return all nullifiers emitted from a contract.
+   * @param contractAddress - Address of the contract.
+   */
+  public getNullifiers(contractAddress: AztecAddress): Set<bigint> {
+    return this.nullifierMap.get(contractAddress.toBigInt()) ?? new Set();
+  }
+
+  #addNote(note: PendingNote) {
+    this.notes.push(note);
+
+    const notes = this.noteMap.get(note.note.contractAddress.toBigInt()) ?? [];
+    notes.push(note);
+    this.noteMap.set(note.note.contractAddress.toBigInt(), notes);
+  }
+
+  getAllNotes(): PendingNote[] {
+    return this.notes;
+  }
+
+  /**
+   * @returns All nullifiers emitted by private calls in this transaction.
+   */
+  getEmittedNullifiers(): Fr[] {
+    return [...this.emittedNullifiers].map(n => new Fr(n));
+  }
+
+  /**
+   * @returns All nullifiers emitted by private calls in this transaction. If the protocol nullifier was used as the
+   * nonce generator, it is injected as the first nullifier.
+   */
+  getAllNullifiers(): Fr[] {
+    if (this.usedProtocolNullifierForNonces === undefined) {
+      throw new Error('usedProtocolNullifierForNonces is not set yet. Call finish() to complete the transaction.');
+    }
+    const allNullifiers = this.getEmittedNullifiers();
+    return [...(this.usedProtocolNullifierForNonces ? [this.protocolNullifier] : []), ...allNullifiers];
+  }
+
+  getNonceGenerator(): Fr {
+    return this.getAllNullifiers()[0];
+  }
+
+  #recordNullifier(contractAddress: AztecAddress, siloedNullifier: bigint) {
+    const nullifiers = this.getNullifiers(contractAddress);
+
+    if (nullifiers.has(siloedNullifier)) {
+      throw new Error(`Duplicate siloed nullifier ${siloedNullifier} emitted by contract ${contractAddress}`);
+    }
+
+    nullifiers.add(siloedNullifier);
+    this.nullifierMap.set(contractAddress.toBigInt(), nullifiers);
+    this.emittedNullifiers.add(siloedNullifier);
+  }
+}

package/src/contract_function_simulator/execution_tagging_index_cache.ts

@@ -0,0 +1,33 @@
+import { AppTaggingSecret, type TaggingIndexRange } from '@aztec/stdlib/logs';
+
+/** A map that stores the tagging index range for a given app tagging secret. */
+export class ExecutionTaggingIndexCache {
+  private taggingIndexMap: Map<string, { lowestIndex: number; highestIndex: number }> = new Map();
+
+  public getLastUsedIndex(secret: AppTaggingSecret): number | undefined {
+    return this.taggingIndexMap.get(secret.toString())?.highestIndex;
+  }
+
+  public setLastUsedIndex(secret: AppTaggingSecret, index: number) {
+    const currentValue = this.taggingIndexMap.get(secret.toString());
+    if (currentValue !== undefined && currentValue.highestIndex !== index - 1) {
+      throw new Error(`Invalid tagging index update. Current value: ${currentValue.highestIndex}, new value: ${index}`);
+    }
+    if (currentValue !== undefined) {
+      currentValue.highestIndex = index;
+    } else {
+      this.taggingIndexMap.set(secret.toString(), { lowestIndex: index, highestIndex: index });
+    }
+  }
+
+  /**
+   * Returns the tagging index ranges that were used in this execution (and that need to be stored in the db).
+   */
+  public getUsedTaggingIndexRanges(): TaggingIndexRange[] {
+    return Array.from(this.taggingIndexMap.entries()).map(([secret, { lowestIndex, highestIndex }]) => ({
+      extendedSecret: AppTaggingSecret.fromString(secret),
+      lowestIndex,
+      highestIndex,
+    }));
+  }
+}

package/src/contract_function_simulator/hashed_values_cache.ts

@@ -0,0 +1,47 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { HashedValues } from '@aztec/stdlib/tx';
+
+/**
+ * A cache for hashed values (arguments, returns) during transaction execution.
+ */
+export class HashedValuesCache {
+  private cache: Map<bigint, Fr[]>;
+
+  constructor(initialArguments: HashedValues[] = []) {
+    this.cache = new Map();
+    for (const initialArg of initialArguments) {
+      this.cache.set(initialArg.hash.toBigInt(), initialArg.values);
+    }
+  }
+
+  /**
+   * Creates a new hashed values cache.
+   * @param initialArguments - The initial arguments to add to the cache.
+   * @returns The new hashed values cache.
+   */
+  public static create(initialArguments: HashedValues[] = []) {
+    return new HashedValuesCache(initialArguments);
+  }
+
+  /**
+   * Gets preimage of a hash.
+   * @param hash - The hash to get the preimage of.
+   * @returns The preimage.
+   */
+  public getPreimage(hash: Fr): Fr[] | undefined {
+    if (hash.isEmpty()) {
+      return [];
+    } else {
+      return this.cache.get(hash.toBigInt());
+    }
+  }
+
+  /**
+   * Stores values in cache and returns its hash.
+   * @param values - The values to store.
+   * @returns The hash of the values.
+   */
+  public store(values: Fr[], hash: Fr) {
+    this.cache.set(hash.toBigInt(), values);
+  }
+}

package/src/contract_function_simulator/index.ts

@@ -0,0 +1,63 @@
+export {
+  ORACLE_REGISTRY,
+  callHandler,
+  makeEntry,
+  type HandlersForPrefix,
+  type NamedValue,
+  type OracleRegistryEntry,
+  type ParamTypes,
+  type StripOraclePrefix,
+} from './oracle/oracle_registry.js';
+export {
+  ARRAY,
+  AZTEC_ADDRESS,
+  BIGINT,
+  BLOCK_NUMBER,
+  BOOL,
+  BOUNDED_VEC,
+  BUFFER,
+  BYTE,
+  DELIVERY_MODE,
+  EPHEMERAL_ARRAY,
+  EVENT_VALIDATION_REQUEST,
+  FIELD,
+  FUNCTION_SELECTOR,
+  LOG_RETRIEVAL_REQUEST,
+  LOG_RETRIEVAL_RESPONSE,
+  MEMBERSHIP_WITNESS,
+  MESSAGE_CONTEXT,
+  NOTE_VALIDATION_REQUEST,
+  OPTION,
+  PENDING_TAGGED_LOG,
+  POINT,
+  PROVIDED_SECRET,
+  STR,
+  U32,
+  type InputSlot,
+  type MaybePromise,
+  type OutputSlot,
+  type TypeMapping,
+} from './oracle/oracle_type_mappings.js';
+export { ExecutionNoteCache } from './execution_note_cache.js';
+export { ExecutionTaggingIndexCache } from './execution_tagging_index_cache.js';
+export { HashedValuesCache } from './hashed_values_cache.js';
+export { pickNotes } from './pick_notes.js';
+export type { IMiscOracle, IUtilityExecutionOracle, IPrivateExecutionOracle } from './oracle/interfaces.js';
+export type { NoteData } from './noir-structs/note_data.js';
+export { MessageLoadOracleInputs } from './oracle/message_load_oracle_inputs.js';
+export { MessageContextService } from '../messages/message_context_service.js';
+export { UtilityExecutionOracle } from './oracle/utility_execution_oracle.js';
+export { PrivateExecutionOracle } from './oracle/private_execution_oracle.js';
+export { Oracle } from './oracle/oracle.js';
+export { executePrivateFunction, extractPrivateCircuitPublicInputs } from './oracle/private_execution.js';
+export { generateSimulatedProvingResult } from './contract_function_simulator.js';
+export { packAsHintedNote } from './oracle/note_packing_utils.js';
+export { BoundedVec } from './noir-structs/bounded_vec.js';
+export { EphemeralArray } from './noir-structs/ephemeral_array.js';
+export { Option } from './noir-structs/option.js';
+export { UtilityContext } from './noir-structs/utility_context.js';
+export { EventValidationRequest } from './noir-structs/event_validation_request.js';
+export { LogRetrievalRequest } from './noir-structs/log_retrieval_request.js';
+export { LogRetrievalResponse } from './noir-structs/log_retrieval_response.js';
+export { NoteValidationRequest } from './noir-structs/note_validation_request.js';
+export { ProvidedSecret } from './noir-structs/provided_secret.js';

package/src/contract_function_simulator/noir-structs/bounded_vec.ts

@@ -0,0 +1,55 @@
+/**
+ * TypeScript counterpart of Noir's `BoundedVec<T, MaxLen>`.
+ *
+ * Carries the actual `data` plus wire-format metadata (`maxLength`, `elementSize`) so the ACVM
+ * serializer can pad the storage slot to exactly `maxLength * elementSize` fields.
+ */
+export class BoundedVec<T> {
+  private constructor(
+    public readonly data: T[],
+    public readonly maxLength: number,
+    public readonly elementSize: number,
+  ) {}
+
+  /**
+   * Construct a BoundedVec with data.
+   *
+   * @param data - Actual elements. Length must be `<= maxLength`.
+   * @param maxLength - Maximum capacity declared at the Noir call site.
+   *   The storage slot is padded to this many elements.
+   * @param elementSize - Number of Fr fields each element contributes when serialized.
+   *   `1` for scalar elements (u8, Field) — this is the default.
+   *   `> 1` for compound elements (e.g. a packed note that spans multiple fields).
+   *
+   * @example A bounded vec of bytes (elementSize defaults to 1):
+   * ```ts
+   * BoundedVec.from({ data: plaintext, maxLength: ciphertext.maxLength })
+   * ```
+   *
+   * @example A bounded vec of packed notes, each spanning `packedHintedNoteLength` fields:
+   * ```ts
+   * BoundedVec.from({ data: notes, maxLength: maxNotes, elementSize: packedHintedNoteLength })
+   * ```
+   */
+  static from<T>({
+    data,
+    maxLength,
+    elementSize = 1,
+  }: {
+    data: T[];
+    maxLength: number;
+    elementSize?: number;
+  }): BoundedVec<T> {
+    return new BoundedVec<T>(data, maxLength, elementSize);
+  }
+
+  /**
+   * Construct an empty BoundedVec, typically used as a shape template for `Option.empty(...)`.
+   *
+   * @param maxLength - Maximum capacity declared at the Noir call site.
+   * @param elementSize - Number of Fr fields each element contributes when serialized (default 1).
+   */
+  static empty<T>({ maxLength, elementSize = 1 }: { maxLength: number; elementSize?: number }): BoundedVec<T> {
+    return new BoundedVec<T>([], maxLength, elementSize);
+  }
+}

package/src/contract_function_simulator/noir-structs/ephemeral_array.ts

@@ -0,0 +1,66 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { FieldReader } from '@aztec/foundation/serialize';
+
+import type { EphemeralArrayService } from '../ephemeral_array_service.js';
+import type { TypeMapping } from '../oracle/oracle_registry.js';
+
+/**
+ * TypeScript counterpart of Noir's `EphemeralArray<T>`.
+ *
+ * An ephemeral array looks very different depending on whether it's being produced (as an oracle return value) or
+ * consumed (as an oracle parameter), so we use a discriminated state to model both without leaking those details to
+ * callers:
+ *
+ * - As a return value (`output` mode), what we have are the typed values the oracle just computed. The slot is just
+ *   an implementation detail of how those values get handed back to ACVM, so we hold onto the values and the service
+ *   they will eventually live in, and only materialize a slot when something actually asks for it.
+ *
+ * - As a parameter (`input` mode), what we have is a slot pointing at fields ACVM already wrote into the service,
+ *   plus the TypeMapping that knows how to interpret those fields. We hold onto both so callers can later ask for
+ *   the typed values without having to think about deserialization.
+ *
+ * In both modes the idea is the same: store everything we already know at construction time, so the rest of the
+ * code can work with typed values and never touch slots, services, or TypeMappings directly.
+ */
+export class EphemeralArray<T> {
+  private constructor(private readonly state: EphemeralArrayState<T>) {}
+
+  /** Create an output-mode array carrying typed values. The service is only used if/when the slot is materialized. */
+  static fromValues<T>(service: EphemeralArrayService, values: T[]): EphemeralArray<T> {
+    return new EphemeralArray({ kind: 'output', service, values });
+  }
+
+  /** Wrap an existing slot. Intended for the EPHEMERAL_ARRAY combinator during ACVM deserialization. */
+  static fromSlot<T>(slot: Fr, mapping: TypeMapping<T>): EphemeralArray<T> {
+    return new EphemeralArray({ kind: 'input', slot, mapping });
+  }
+
+  /**
+   * Returns the slot, materializing values into the service on first call for output-mode arrays.
+   * Intended for the EPHEMERAL_ARRAY combinator during ACVM serialization.
+   */
+  materializeSlot(serializeItem: (v: T) => Fr[]): Fr {
+    if (this.state.kind === 'input') {
+      return this.state.slot;
+    }
+    if (this.state.cachedSlot === undefined) {
+      this.state.cachedSlot = this.state.service.newArray(this.state.values.map(serializeItem));
+    }
+    return this.state.cachedSlot;
+  }
+
+  /** Read all elements: returns stored values for output-mode arrays, deserializes from the service for input-mode. */
+  readAll(service: EphemeralArrayService): T[] {
+    if (this.state.kind === 'output') {
+      return this.state.values;
+    }
+    const mapping = this.state.mapping;
+    return service
+      .readArrayAt(this.state.slot)
+      .map(fields => mapping.deserialization!.fn([FieldReader.asReader(fields)]));
+  }
+}
+
+type EphemeralArrayState<T> =
+  | { kind: 'output'; service: EphemeralArrayService; values: T[]; cachedSlot?: Fr }
+  | { kind: 'input'; slot: Fr; mapping: TypeMapping<T> };

package/src/contract_function_simulator/noir-structs/event_validation_request.ts

@@ -0,0 +1,52 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { EventSelector } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { TxHash } from '@aztec/stdlib/tx';
+
+/**
+ * Intermediate struct used to perform batch event validation by PXE. The `utilityValidateAndStoreEnqueuedNotesAndEvents` oracle
+ * expects for values of this type to be stored in a `EphemeralArray`.
+ */
+export class EventValidationRequest {
+  constructor(
+    public contractAddress: AztecAddress,
+    public eventTypeId: EventSelector,
+    public randomness: Fr,
+    public serializedEvent: Fr[],
+    public eventCommitment: Fr,
+    public txHash: TxHash,
+  ) {}
+
+  static fromFields(fields: Fr[] | FieldReader): EventValidationRequest {
+    const reader = FieldReader.asReader(fields);
+
+    const contractAddress = AztecAddress.fromField(reader.readField());
+    const eventTypeId = EventSelector.fromField(reader.readField());
+
+    const randomness = reader.readField();
+
+    const maxEventSerializedLen = reader.readField().toNumber();
+    const eventStorage = reader.readFieldArray(maxEventSerializedLen);
+    const eventLen = reader.readField().toNumber();
+    const serializedEvent = eventStorage.slice(0, eventLen);
+
+    const eventCommitment = reader.readField();
+    const txHash = TxHash.fromField(reader.readField());
+
+    if (reader.remainingFields() !== 0) {
+      throw new Error(
+        `Error converting array of fields to EventValidationRequest: expected ${reader.cursor} fields but received ${reader.cursor + reader.remainingFields()} (maxEventSerializedLen=${maxEventSerializedLen}).`,
+      );
+    }
+
+    return new EventValidationRequest(
+      contractAddress,
+      eventTypeId,
+      randomness,
+      serializedEvent,
+      eventCommitment,
+      txHash,
+    );
+  }
+}