refactor(pxe): introduce typed oracle registry for serialization (#23516)

Author: nchamo

yarn-project/pxe/src/contract_function_simulator/index.ts

@@ -11,4 +11,6 @@ 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 { Option } from './noir-structs/option.js';
 export { UtilityContext } from './noir-structs/utility_context.js';

yarn-project/pxe/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);
+  }
+}

yarn-project/pxe/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;
+  }
+}

yarn-project/pxe/src/contract_function_simulator/oracle/interfaces.ts

@@ -1,18 +1,20 @@
 import type { ARCHIVE_HEIGHT, L1_TO_L2_MSG_TREE_HEIGHT, NOTE_HASH_TREE_HEIGHT } from '@aztec/constants';
 import type { BlockNumber } from '@aztec/foundation/branded-types';
-import { Fr } from '@aztec/foundation/curves/bn254';
-import { MembershipWitness } from '@aztec/foundation/trees';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { BlockHash } from '@aztec/stdlib/block';
+import type { BlockHash } from '@aztec/stdlib/block';
 import type { ContractInstance, PartialAddress } from '@aztec/stdlib/contract';
 import type { KeyValidationRequest } from '@aztec/stdlib/kernel';
 import type { PublicKeys } from '@aztec/stdlib/keys';
 import type { ContractClassLog, Tag } from '@aztec/stdlib/logs';
 import type { Note, NoteStatus } from '@aztec/stdlib/note';
-import { type NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
+import type { NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
 import type { BlockHeader, TxEffect, TxHash } from '@aztec/stdlib/tx';
 
+import type { BoundedVec } from '../noir-structs/bounded_vec.js';
+import type { Option } from '../noir-structs/option.js';
 import type { UtilityContext } from '../noir-structs/utility_context.js';
 import type { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
 
@@ -74,17 +76,17 @@ export interface IUtilityExecutionOracle {
   getBlockHashMembershipWitness(
     anchorBlockHash: BlockHash,
     blockHash: BlockHash,
-  ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined>;
+  ): Promise<Option<MembershipWitness<typeof ARCHIVE_HEIGHT>>>;
   getNullifierMembershipWitness(anchorBlockHash: BlockHash, nullifier: Fr): Promise<NullifierMembershipWitness>;
   getPublicDataWitness(anchorBlockHash: BlockHash, leafSlot: Fr): Promise<PublicDataWitness>;
   getLowNullifierMembershipWitness(anchorBlockHash: BlockHash, nullifier: Fr): Promise<NullifierMembershipWitness>;
   getBlockHeader(blockNumber: BlockNumber): Promise<BlockHeader>;
   getPublicKeysAndPartialAddress(
     account: AztecAddress,
-  ): Promise<{ publicKeys: PublicKeys; partialAddress: PartialAddress } | undefined>;
+  ): Promise<Option<{ publicKeys: PublicKeys; partialAddress: PartialAddress }>>;
   getAuthWitness(messageHash: Fr): Promise<Fr[]>;
   getNotes(
-    owner: AztecAddress | undefined,
+    owner: Option<AztecAddress>,
     storageSlot: Fr,
     numSelects: number,
     selectByIndexes: number[],
@@ -99,7 +101,9 @@ export interface IUtilityExecutionOracle {
     limit: number,
     offset: number,
     status: NoteStatus,
-  ): Promise<NoteData[]>;
+    maxNotes: number,
+    packedHintedNoteLength: number,
+  ): Promise<BoundedVec<NoteData>>;
   doesNullifierExist(innerNullifier: Fr): Promise<boolean>;
   getL1ToL2MembershipWitness(
     contractAddress: AztecAddress,
@@ -122,9 +126,9 @@ export interface IUtilityExecutionOracle {
   ): Promise<void>;
   getLogsByTag(requestArrayBaseSlot: Fr): Promise<Fr>;
   getMessageContextsByTxHash(requestArrayBaseSlot: Fr): Promise<Fr>;
-  getTxEffect(txHash: TxHash): Promise<TxEffect | null>;
+  getTxEffect(txHash: TxHash): Promise<Option<TxEffect>>;
   setCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[], scope: AztecAddress): void;
-  getCapsule(contractAddress: AztecAddress, key: Fr, scope: AztecAddress): Promise<Fr[] | null>;
+  getCapsule(contractAddress: AztecAddress, key: Fr, tSize: number, scope: AztecAddress): Promise<Option<Fr[]>>;
   deleteCapsule(contractAddress: AztecAddress, key: Fr, scope: AztecAddress): void;
   copyCapsule(
     contractAddress: AztecAddress,
@@ -133,9 +137,9 @@ export interface IUtilityExecutionOracle {
     numEntries: number,
     scope: AztecAddress,
   ): Promise<void>;
-  decryptAes128(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer | undefined>;
+  decryptAes128(ciphertext: BoundedVec<number>, iv: Buffer, symKey: Buffer): Promise<Option<BoundedVec<number>>>;
   getSharedSecrets(address: AztecAddress, ephPksSlot: Fr, contractAddress: AztecAddress): Promise<Fr>;
-  setContractSyncCacheInvalid(contractAddress: AztecAddress, scopes: AztecAddress[]): void;
+  setContractSyncCacheInvalid(contractAddress: AztecAddress, scopes: BoundedVec<AztecAddress>): void;
   emitOffchainEffect(data: Fr[]): Promise<void>;
   callUtilityFunction(
     targetContractAddress: AztecAddress,
@@ -190,7 +194,7 @@ export interface IPrivateExecutionOracle {
   assertValidPublicCalldata(calldataHash: Fr): Promise<void>;
   notifyRevertiblePhaseStart(minRevertibleSideEffectCounter: number): Promise<void>;
   isExecutionInRevertiblePhase(sideEffectCounter: number): Promise<boolean>;
-  getSenderForTags(): Promise<AztecAddress | undefined>;
+  getSenderForTags(): Promise<Option<AztecAddress>>;
   setSenderForTags(senderForTags: AztecAddress): Promise<void>;
   getNextAppTagAsSender(sender: AztecAddress, recipient: AztecAddress): Promise<Tag>;
 }

yarn-project/pxe/src/contract_function_simulator/oracle/note_packing_utils.ts

@@ -48,7 +48,7 @@ export function packAsHintedNote({
   noteNonce: Fr;
   isPending: boolean;
   note: Note;
-}) {
+}): Fr[] {
   // If the note is pending it means it has a non-zero note hash counter associated with it.
   const nonZeroNoteHashCounter = isPending;
 
@@ -58,8 +58,8 @@ export function packAsHintedNote({
   // Pack in order: note, contract_address, owner, randomness, storage_slot, metadata (stage, maybe_note_nonce)
   return [
     ...note.items,
-    contractAddress,
-    owner,
+    contractAddress.toField(),
+    owner.toField(),
     randomness,
     storageSlot,
     new Fr(noteMetadata.stage),