@aztec/pxe 0.0.1-commit.2448fdb → 0.0.1-commit.2606882

package/src/contract_function_simulator/contract_function_simulator.ts

@@ -76,6 +76,7 @@ import {
 import { PrivateLog } from '@aztec/stdlib/logs';
 import { ScopedL2ToL1Message } from '@aztec/stdlib/messaging';
 import { ChonkProof } from '@aztec/stdlib/proofs';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
 import {
   BlockHeader,
   CallContext,
@@ -90,6 +91,7 @@ import {
 } from '@aztec/stdlib/tx';
 
 import type { ContractSyncService } from '../contract_sync/contract_sync_service.js';
+import type { ExecutionHooks } from '../hooks/index.js';
 import type { MessageContextService } from '../messages/message_context_service.js';
 import type { AddressStore } from '../storage/address_store/address_store.js';
 import { CapsuleService } from '../storage/capsule_store/capsule_service.js';
@@ -143,6 +145,7 @@ export type ContractFunctionSimulatorArgs = {
   simulator: CircuitSimulator;
   contractSyncService: ContractSyncService;
   messageContextService: MessageContextService;
+  hooks?: ExecutionHooks;
 };
 
 /**
@@ -164,6 +167,7 @@ export class ContractFunctionSimulator {
   private readonly simulator: CircuitSimulator;
   private readonly contractSyncService: ContractSyncService;
   private readonly messageContextService: MessageContextService;
+  private readonly hooks: ExecutionHooks | undefined;
 
   constructor(args: ContractFunctionSimulatorArgs) {
     this.contractStore = args.contractStore;
@@ -180,6 +184,7 @@ export class ContractFunctionSimulator {
     this.simulator = args.simulator;
     this.contractSyncService = args.contractSyncService;
     this.messageContextService = args.messageContextService;
+    this.hooks = args.hooks;
     this.log = createLogger('simulator');
   }
 
@@ -208,7 +213,7 @@ export class ContractFunctionSimulator {
     }
 
     if (request.origin !== contractAddress) {
-      this.log.warn(
+      throw new Error(
         `Request origin does not match contract address in simulation. Request origin: ${request.origin}, contract address: ${contractAddress}`,
       );
     }
@@ -259,6 +264,7 @@ export class ContractFunctionSimulator {
       senderForTags,
       simulator: this.simulator,
       l2TipsStore: this.l2TipsStore,
+      hooks: this.hooks,
     });
 
     const setupTime = simulatorSetupTimer.ms();
@@ -309,7 +315,6 @@ export class ContractFunctionSimulator {
     }
   }
 
-  // docs:start:execute_utility_function
   /**
    * Runs a utility function.
    * @param call - The function call to execute.
@@ -332,6 +337,10 @@ export class ContractFunctionSimulator {
       throw new Error(`Cannot run ${entryPointArtifact.functionType} function as utility`);
     }
 
+    const utilityExecutor = async (syncCall: FunctionCall, execScopes: AztecAddress[]) => {
+      await this.runUtility(syncCall, [], anchorBlockHeader, execScopes, jobId);
+    };
+
     const oracle = new UtilityExecutionOracle({
       contractAddress: call.to,
       authWitnesses: authwits,
@@ -351,6 +360,9 @@ export class ContractFunctionSimulator {
       l2TipsStore: this.l2TipsStore,
       jobId,
       scopes,
+      simulator: this.simulator,
+      hooks: this.hooks,
+      utilityExecutor,
     });
 
     try {
@@ -384,7 +396,6 @@ export class ContractFunctionSimulator {
       throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during private execution'));
     }
   }
-  // docs:end:execute_utility_function
 
   /**
    * Returns the execution statistics collected during the simulator run.
@@ -753,7 +764,7 @@ function squashTransientSideEffects(
  * at the tx's anchor block, mimicking the behavior of the kernels
  */
 async function verifyReadRequests(
-  node: Pick<AztecNode, 'getNoteHashMembershipWitness' | 'getNullifierMembershipWitness'>,
+  node: Pick<AztecNode, 'findLeavesIndexes'>,
   anchorBlockHash: BlockParameter,
   noteHashReadRequests: ScopedReadRequest[],
   nullifierReadRequests: ScopedReadRequest[],
@@ -786,13 +797,25 @@ async function verifyReadRequests(
     }
   }
 
-  const [noteHashWitnesses, nullifierWitnesses] = await Promise.all([
-    Promise.all(settledNoteHashReads.map(({ value }) => node.getNoteHashMembershipWitness(anchorBlockHash, value))),
-    Promise.all(settledNullifierReads.map(({ value }) => node.getNullifierMembershipWitness(anchorBlockHash, value))),
+  const [noteHashResults, nullifierResults] = await Promise.all([
+    settledNoteHashReads.length > 0
+      ? node.findLeavesIndexes(
+          anchorBlockHash,
+          MerkleTreeId.NOTE_HASH_TREE,
+          settledNoteHashReads.map(({ value }) => value),
+        )
+      : [],
+    settledNullifierReads.length > 0
+      ? node.findLeavesIndexes(
+          anchorBlockHash,
+          MerkleTreeId.NULLIFIER_TREE,
+          settledNullifierReads.map(({ value }) => value),
+        )
+      : [],
   ]);
 
   for (let i = 0; i < settledNoteHashReads.length; i++) {
-    if (!noteHashWitnesses[i]) {
+    if (!noteHashResults[i]) {
       throw new Error(
         `Note hash read request at index ${settledNoteHashReads[i].index} is reading an unknown note hash: ${settledNoteHashReads[i].value}`,
       );
@@ -800,7 +823,7 @@ async function verifyReadRequests(
   }
 
   for (let i = 0; i < settledNullifierReads.length; i++) {
-    if (!nullifierWitnesses[i]) {
+    if (!nullifierResults[i]) {
       throw new Error(
         `Nullifier read request at index ${settledNullifierReads[i].index} is reading an unknown nullifier: ${settledNullifierReads[i].value}`,
       );
@@ -846,9 +869,9 @@ function meterGasUsed(data: PrivateToRollupAccumulatedData | PrivateToPublicAccu
   meteredL2Gas += numPrivatelogs * L2_GAS_PER_PRIVATE_LOG;
 
   const numContractClassLogs = arrayNonEmptyLength(data.contractClassLogsHashes, log => log.isEmpty());
-  // Every contract class log emits its length and contract address as additional fields
+  // Every contract class log emits its contract address as an additional field
   meteredDAFields += data.contractClassLogsHashes.reduce(
-    (acc, log) => (!log.isEmpty() ? acc + log.logHash.length + 2 : acc),
+    (acc, log) => (!log.isEmpty() ? acc + log.logHash.length + 1 : acc),
     0,
   );
   meteredL2Gas += numContractClassLogs * L2_GAS_PER_CONTRACT_CLASS_LOG;

package/src/contract_function_simulator/execution_note_cache.ts

@@ -2,7 +2,7 @@ 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 './oracle/interfaces.js';
+import type { NoteData } from './noir-structs/note_data.js';
 
 interface PendingNote {
   note: NoteData;

package/src/contract_function_simulator/execution_tagging_index_cache.ts

@@ -1,18 +1,14 @@
-import { ExtendedDirectionalAppTaggingSecret, type TaggingIndexRange } from '@aztec/stdlib/logs';
+import { AppTaggingSecret, type TaggingIndexRange } from '@aztec/stdlib/logs';
 
-/**
- * A map that stores the tagging index range for a given extended directional app tagging secret.
- * Note: The directional app tagging secret is unique for a (sender, recipient, contract) tuple while the direction
- * of sender -> recipient matters.
- */
+/** 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: ExtendedDirectionalAppTaggingSecret): number | undefined {
+  public getLastUsedIndex(secret: AppTaggingSecret): number | undefined {
     return this.taggingIndexMap.get(secret.toString())?.highestIndex;
   }
 
-  public setLastUsedIndex(secret: ExtendedDirectionalAppTaggingSecret, index: number) {
+  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}`);
@@ -29,7 +25,7 @@ export class ExecutionTaggingIndexCache {
    */
   public getUsedTaggingIndexRanges(): TaggingIndexRange[] {
     return Array.from(this.taggingIndexMap.entries()).map(([secret, { lowestIndex, highestIndex }]) => ({
-      extendedSecret: ExtendedDirectionalAppTaggingSecret.fromString(secret),
+      extendedSecret: AppTaggingSecret.fromString(secret),
       lowestIndex,
       highestIndex,
     }));

package/src/contract_function_simulator/index.ts

@@ -1,8 +1,49 @@
+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 { NoteData, IMiscOracle, IUtilityExecutionOracle, IPrivateExecutionOracle } from './oracle/interfaces.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';
@@ -11,4 +52,12 @@ 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

@@ -18,7 +18,7 @@ export class EventValidationRequest {
     public txHash: TxHash,
   ) {}
 
-  static fromFields(fields: Fr[], maxEventSerializedLen: number): EventValidationRequest {
+  static fromFields(fields: Fr[] | FieldReader): EventValidationRequest {
     const reader = FieldReader.asReader(fields);
 
     const contractAddress = AztecAddress.fromField(reader.readField());
@@ -26,6 +26,7 @@ export class EventValidationRequest {
 
     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);
@@ -35,7 +36,7 @@ export class EventValidationRequest {
 
     if (reader.remainingFields() !== 0) {
       throw new Error(
-        `Error converting array of fields to EventValidationRequest: expected ${reader.cursor} fields but received ${fields.length} (maxEventSerializedLen=${maxEventSerializedLen}).`,
+        `Error converting array of fields to EventValidationRequest: expected ${reader.cursor} fields but received ${reader.cursor + reader.remainingFields()} (maxEventSerializedLen=${maxEventSerializedLen}).`,
       );
     }
 

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

@@ -1,8 +1,16 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { FieldReader } from '@aztec/foundation/serialize';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { Tag } from '@aztec/stdlib/logs';
 
+/** Discriminant for which log source to query. */
+export enum LogSource {
+  PRIVATE = 0,
+  PUBLIC = 1,
+  PUBLIC_AND_PRIVATE = 2,
+}
+
 /**
  * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle expects values of this
  * type to be stored in a `EphemeralArray`.
@@ -11,10 +19,21 @@ export class LogRetrievalRequest {
   constructor(
     public contractAddress: AztecAddress,
     public tag: Tag,
+    public source: LogSource = LogSource.PUBLIC_AND_PRIVATE,
+    public fromBlock?: BlockNumber,
+    public toBlock?: BlockNumber,
   ) {}
 
   toFields(): Fr[] {
-    return [this.contractAddress.toField(), this.tag.value];
+    return [
+      this.contractAddress.toField(),
+      this.tag.value,
+      new Fr(this.source),
+      new Fr(this.fromBlock !== undefined ? 1 : 0),
+      new Fr(this.fromBlock ?? 0),
+      new Fr(this.toBlock !== undefined ? 1 : 0),
+      new Fr(this.toBlock ?? 0),
+    ];
   }
 
   static fromFields(fields: Fr[] | FieldReader): LogRetrievalRequest {
@@ -22,7 +41,21 @@ export class LogRetrievalRequest {
 
     const contractAddress = AztecAddress.fromField(reader.readField());
     const tag = new Tag(reader.readField());
+    const sourceNum = reader.readField().toNumber();
+    if (!(sourceNum in LogSource)) {
+      const validNames = Object.keys(LogSource).filter(k => isNaN(Number(k)));
+      throw new Error(`Invalid LogSource value ${sourceNum}, expected one of ${validNames.join(', ')}`);
+    }
+    const source = sourceNum as LogSource;
+
+    const fromBlockIsSome = reader.readBoolean();
+    const fromBlockValue = reader.readField();
+    const fromBlock = fromBlockIsSome ? BlockNumber(fromBlockValue.toNumber()) : undefined;
+
+    const toBlockIsSome = reader.readBoolean();
+    const toBlockValue = reader.readField();
+    const toBlock = toBlockIsSome ? BlockNumber(toBlockValue.toNumber()) : undefined;
 
-    return new LogRetrievalRequest(contractAddress, tag);
+    return new LogRetrievalRequest(contractAddress, tag, source, fromBlock, toBlock);
   }
 }

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

@@ -0,0 +1,27 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { Note } from '@aztec/stdlib/note';
+
+/**
+ * Information about a note needed during execution.
+ */
+export interface NoteData {
+  /** The actual note content (the fields of the Noir #[note] struct). */
+  note: Note;
+  /** The address of the contract that owns the note. */
+  contractAddress: AztecAddress;
+  /** The owner of the note. */
+  owner: AztecAddress;
+  /** The storage slot of the note. */
+  storageSlot: Fr;
+  /** The randomness injected to the note */
+  randomness: Fr;
+  /** The nonce injected into the note hash preimage by kernels. */
+  noteNonce: Fr;
+  /** A hash of the note as it gets stored in the note hash tree. */
+  noteHash: Fr;
+  /** True if the note is pending, false if settled. */
+  isPending: boolean;
+  /** The corresponding nullifier of the note. Undefined for pending notes. */
+  siloedNullifier?: Fr;
+}

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

@@ -20,7 +20,7 @@ export class NoteValidationRequest {
     public txHash: TxHash,
   ) {}
 
-  static fromFields(fields: Fr[], maxNotePackedLen: number): NoteValidationRequest {
+  static fromFields(fields: Fr[] | FieldReader): NoteValidationRequest {
     const reader = FieldReader.asReader(fields);
 
     const contractAddress = AztecAddress.fromField(reader.readField());
@@ -29,6 +29,7 @@ export class NoteValidationRequest {
     const randomness = reader.readField();
     const noteNonce = reader.readField();
 
+    const maxNotePackedLen = reader.readField().toNumber();
     const contentStorage = reader.readFieldArray(maxNotePackedLen);
     const contentLen = reader.readField().toNumber();
     const content = contentStorage.slice(0, contentLen);
@@ -39,7 +40,7 @@ export class NoteValidationRequest {
 
     if (reader.remainingFields() !== 0) {
       throw new Error(
-        `Error converting array of fields to NoteValidationRequest: expected ${reader.cursor} fields but received ${fields.length} (maxNotePackedLen=${maxNotePackedLen}).`,
+        `Error converting array of fields to NoteValidationRequest: expected ${reader.cursor} fields but received ${reader.cursor + reader.remainingFields()} (maxNotePackedLen=${maxNotePackedLen}).`,
       );
     }
 

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

@@ -0,0 +1,69 @@
+/**
+ * TypeScript counterpart of Noir's `Option<T>`.
+ *
+ * Wraps a value that may or may not be present. Use {@link Option.some} to wrap a present value and
+ * {@link Option.none} for an absent one. The type guards {@link isSome} and {@link isNone} narrow
+ * `value` in conditional branches.
+ */
+export class Option<T> {
+  private constructor(
+    public readonly value: T | undefined,
+    public readonly template: T | undefined,
+  ) {}
+
+  /**
+   * Wrap a present value.
+   *
+   * @example
+   * ```ts
+   * return Option.some(values);
+   * ```
+   */
+  static some<T>(value: T): Option<T> {
+    return new Option<T>(value, undefined);
+  }
+
+  /**
+   * Construct an absent Option.
+   *
+   * When serialized back to ACVM, the `None` case must produce the same number of fields as `Some`.
+   * For types whose wire size varies per call site (`BoundedVec`, `FixedArray`), pass a `template` so the
+   * serializer knows how many zero fields to emit. Omit the template when the Option will not be
+   * re-serialized (e.g. deserialized input params).
+   *
+   * @param template - A representative empty `T` whose serialization determines the zero-filled wire format.
+   *
+   * @example None for a fixed-size type:
+   * ```ts
+   * return Option.none(AztecAddress.ZERO);
+   * ```
+   *
+   * @example None for a dynamic-size type:
+   * ```ts
+   * return Option.none(BoundedVec.empty<number>({ maxLength: ciphertext.maxLength }));
+   * ```
+   */
+  static none<T>(template?: T): Option<T> {
+    return new Option<T>(undefined, template);
+  }
+
+  /**
+   * Type guard: narrows `value` to `T` in the truthy branch.
+   *
+   * @example
+   * ```ts
+   * const opt = await handler.getSenderForTags();
+   * if (opt.isSome()) {
+   *   console.log(opt.value); // narrowed to T
+   * }
+   * ```
+   */
+  isSome(): this is Option<T> & { value: T } {
+    return this.value !== undefined;
+  }
+
+  /** Type guard: narrows `value` to `undefined` in the truthy branch. */
+  isNone(): this is Option<T> & { value: undefined } {
+    return this.value === undefined;
+  }
+}

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

@@ -0,0 +1,27 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { AppTaggingSecretKind } from '@aztec/stdlib/logs';
+
+/** A tagging secret an app supplies explicitly to `getPendingTaggedLogs` when PXE cannot derive it internally. */
+export class ProvidedSecret {
+  constructor(
+    public secret: Fr,
+    public mode: AppTaggingSecretKind,
+  ) {}
+
+  static fromFields(fields: Fr[] | FieldReader): ProvidedSecret {
+    const reader = FieldReader.asReader(fields);
+    return new ProvidedSecret(reader.readField(), kindFromField(reader.readField()));
+  }
+}
+
+function kindFromField(mode: Fr): AppTaggingSecretKind {
+  switch (mode.toBigInt()) {
+    case 0n:
+      return AppTaggingSecretKind.UNCONSTRAINED;
+    case 1n:
+      return AppTaggingSecretKind.CONSTRAINED;
+    default:
+      throw new Error(`Invalid app tagging secret kind: ${mode.toString()}`);
+  }
+}