feat: merge-train/fairies (#23775)

BEGIN_COMMIT_OVERRIDE
refactor(pxe): type EphemeralArray<T> end-to-end via registry (#23649)
END_COMMIT_OVERRIDE

Author: AztecBot

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

@@ -12,5 +12,18 @@ export { executePrivateFunction, extractPrivateCircuitPublicInputs } from './ora
 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 {
+  EPHEMERAL_ARRAY,
+  EVENT_VALIDATION_REQUEST,
+  FIELD,
+  LOG_RETRIEVAL_REQUEST,
+  LOG_RETRIEVAL_RESPONSE,
+  MESSAGE_CONTEXT,
+  NOTE_VALIDATION_REQUEST,
+  OPTION,
+  PENDING_TAGGED_LOG,
+  POINT,
+} from './oracle/oracle_registry.js';

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

yarn-project/pxe/src/contract_function_simulator/noir-structs/event_validation_request.ts

@@ -18,7 +18,7 @@ export class EventValidationRequest {
     public txHash: TxHash,
   ) {}
 
-  static fromFields(fields: Fr[]): EventValidationRequest {
+  static fromFields(fields: Fr[] | FieldReader): EventValidationRequest {
     const reader = FieldReader.asReader(fields);
 
     const contractAddress = AztecAddress.fromField(reader.readField());
@@ -36,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}).`,
       );
     }
 

yarn-project/pxe/src/contract_function_simulator/noir-structs/note_validation_request.ts

@@ -20,7 +20,7 @@ export class NoteValidationRequest {
     public txHash: TxHash,
   ) {}
 
-  static fromFields(fields: Fr[]): NoteValidationRequest {
+  static fromFields(fields: Fr[] | FieldReader): NoteValidationRequest {
     const reader = FieldReader.asReader(fields);
 
     const contractAddress = AztecAddress.fromField(reader.readField());
@@ -40,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}).`,
       );
     }
 

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

@@ -1,19 +1,25 @@
 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 type { Fr } from '@aztec/foundation/curves/bn254';
+import type { Point } from '@aztec/foundation/curves/grumpkin';
 import type { MembershipWitness } from '@aztec/foundation/trees';
 import type { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 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 { ContractClassLog, MessageContext, PendingTaggedLog, Tag } from '@aztec/stdlib/logs';
 import type { Note, NoteStatus } from '@aztec/stdlib/note';
 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 { EphemeralArray } from '../noir-structs/ephemeral_array.js';
+import type { EventValidationRequest } from '../noir-structs/event_validation_request.js';
+import type { LogRetrievalRequest } from '../noir-structs/log_retrieval_request.js';
+import type { LogRetrievalResponse } from '../noir-structs/log_retrieval_response.js';
+import type { NoteValidationRequest } from '../noir-structs/note_validation_request.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';
@@ -116,14 +122,16 @@ export interface IUtilityExecutionOracle {
     startStorageSlot: Fr,
     numberOfElements: number,
   ): Promise<Fr[]>;
-  getPendingTaggedLogs(scope: AztecAddress): Promise<Fr>;
+  getPendingTaggedLogs(scope: AztecAddress): Promise<EphemeralArray<PendingTaggedLog>>;
   validateAndStoreEnqueuedNotesAndEvents(
-    noteValidationRequestsArrayBaseSlot: Fr,
-    eventValidationRequestsArrayBaseSlot: Fr,
+    noteValidationRequests: EphemeralArray<NoteValidationRequest>,
+    eventValidationRequests: EphemeralArray<EventValidationRequest>,
     scope: AztecAddress,
   ): Promise<void>;
-  getLogsByTag(requestArrayBaseSlot: Fr): Promise<Fr>;
-  getMessageContextsByTxHash(requestArrayBaseSlot: Fr): Promise<Fr>;
+  getLogsByTag(
+    requests: EphemeralArray<LogRetrievalRequest>,
+  ): Promise<EphemeralArray<EphemeralArray<LogRetrievalResponse>>>;
+  getMessageContextsByTxHash(requests: EphemeralArray<Fr>): Promise<EphemeralArray<Option<MessageContext>>>;
   getTxEffect(txHash: TxHash): Promise<Option<TxEffect>>;
   setCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[], scope: AztecAddress): void;
   getCapsule(contractAddress: AztecAddress, key: Fr, tSize: number, scope: AztecAddress): Promise<Option<Fr[]>>;
@@ -136,7 +144,11 @@ export interface IUtilityExecutionOracle {
     scope: AztecAddress,
   ): Promise<void>;
   decryptAes128(ciphertext: BoundedVec<number>, iv: Buffer, symKey: Buffer): Promise<Option<BoundedVec<number>>>;
-  getSharedSecrets(address: AztecAddress, ephPksSlot: Fr, contractAddress: AztecAddress): Promise<Fr>;
+  getSharedSecrets(
+    address: AztecAddress,
+    ephPks: EphemeralArray<Point>,
+    contractAddress: AztecAddress,
+  ): Promise<EphemeralArray<Fr>>;
   setContractSyncCacheInvalid(contractAddress: AztecAddress, scopes: BoundedVec<AztecAddress>): void;
   emitOffchainEffect(data: Fr[]): Promise<void>;
   callUtilityFunction(

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

@@ -514,10 +514,10 @@ export class Oracle {
     return callHandler({
       oracle: 'aztec_utl_validateAndStoreEnqueuedNotesAndEvents',
       inputs,
-      handler: ([noteValidationRequestsArrayBaseSlot, eventValidationRequestsArrayBaseSlot, scope]) =>
+      handler: ([noteValidationRequests, eventValidationRequests, scope]) =>
         this.handlerAsUtility().validateAndStoreEnqueuedNotesAndEvents(
-          noteValidationRequestsArrayBaseSlot,
-          eventValidationRequestsArrayBaseSlot,
+          noteValidationRequests,
+          eventValidationRequests,
           scope,
         ),
     });
@@ -528,7 +528,7 @@ export class Oracle {
     return callHandler({
       oracle: 'aztec_utl_getLogsByTag',
       inputs,
-      handler: ([requestArrayBaseSlot]) => this.handlerAsUtility().getLogsByTag(requestArrayBaseSlot),
+      handler: ([requests]) => this.handlerAsUtility().getLogsByTag(requests),
     });
   }
 
@@ -537,7 +537,7 @@ export class Oracle {
     return callHandler({
       oracle: 'aztec_utl_getMessageContextsByTxHash',
       inputs,
-      handler: ([requestArrayBaseSlot]) => this.handlerAsUtility().getMessageContextsByTxHash(requestArrayBaseSlot),
+      handler: ([requests]) => this.handlerAsUtility().getMessageContextsByTxHash(requests),
     });
   }
 
@@ -675,8 +675,8 @@ export class Oracle {
     return callHandler({
       oracle: 'aztec_utl_getSharedSecrets',
       inputs,
-      handler: ([address, ephPksSlot, contractAddress]) =>
-        this.handlerAsUtility().getSharedSecrets(address, ephPksSlot, contractAddress),
+      handler: ([address, ephPks, contractAddress]) =>
+        this.handlerAsUtility().getSharedSecrets(address, ephPks, contractAddress),
     });
   }
 

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

@@ -15,6 +15,7 @@ import {
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { padArrayEnd } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
+import { Point } from '@aztec/foundation/curves/grumpkin';
 import { FieldReader } from '@aztec/foundation/serialize';
 import { MembershipWitness } from '@aztec/foundation/trees';
 import { type ACVMField, fromUintArray, toACVMField } from '@aztec/simulator/client';
@@ -25,18 +26,31 @@ import { BlockHash } from '@aztec/stdlib/block';
 import type { ContractInstance, PartialAddress } from '@aztec/stdlib/contract';
 import { KeyValidationRequest } from '@aztec/stdlib/kernel';
 import type { PublicKeys } from '@aztec/stdlib/keys';
-import { ContractClassLog, ContractClassLogFields, FlatPublicLogs, PrivateLog, Tag } from '@aztec/stdlib/logs';
+import {
+  ContractClassLog,
+  ContractClassLogFields,
+  FlatPublicLogs,
+  MessageContext,
+  PendingTaggedLog,
+  PrivateLog,
+  Tag,
+} from '@aztec/stdlib/logs';
 import { NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
 import { BlockHeader, TxEffect, TxHash } from '@aztec/stdlib/tx';
 
 import { BoundedVec } from '../noir-structs/bounded_vec.js';
+import { EphemeralArray } from '../noir-structs/ephemeral_array.js';
+import { EventValidationRequest } from '../noir-structs/event_validation_request.js';
+import { LogRetrievalRequest } from '../noir-structs/log_retrieval_request.js';
+import { LogRetrievalResponse } from '../noir-structs/log_retrieval_response.js';
+import { NoteValidationRequest } from '../noir-structs/note_validation_request.js';
 import { Option } from '../noir-structs/option.js';
 import { UtilityContext } from '../noir-structs/utility_context.js';
 import type { NoteData } from './interfaces.js';
 import { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
 import { packAsHintedNote } from './note_packing_utils.js';
 
-const FIELD: TypeMapping<Fr> = {
+export const FIELD: TypeMapping<Fr> = {
   serialization: { fn: v => [v] },
   deserialization: { fn: ([reader]) => reader.readField(), slots: 1 },
 };
@@ -254,6 +268,48 @@ const NOTE: TypeMapping<NoteData> = {
   },
 };
 
+export const POINT: TypeMapping<Point> = {
+  serialization: { fn: p => [p.toFields()] },
+  deserialization: {
+    fn: ([reader]) => Point.fromFields([reader.readField(), reader.readField()]),
+    slots: 1,
+  },
+};
+
+export const PENDING_TAGGED_LOG: TypeMapping<PendingTaggedLog> = {
+  serialization: { fn: log => [log.toFields()] },
+};
+
+export const NOTE_VALIDATION_REQUEST: TypeMapping<NoteValidationRequest> = {
+  deserialization: {
+    fn: ([reader]) => NoteValidationRequest.fromFields(reader),
+    slots: 1,
+  },
+};
+
+export const EVENT_VALIDATION_REQUEST: TypeMapping<EventValidationRequest> = {
+  deserialization: {
+    fn: ([reader]) => EventValidationRequest.fromFields(reader),
+    slots: 1,
+  },
+};
+
+export const LOG_RETRIEVAL_REQUEST: TypeMapping<LogRetrievalRequest> = {
+  serialization: { fn: req => [req.toFields()] },
+  deserialization: {
+    fn: ([reader]) => LogRetrievalRequest.fromFields(reader),
+    slots: 1,
+  },
+};
+
+export const LOG_RETRIEVAL_RESPONSE: TypeMapping<LogRetrievalResponse> = {
+  serialization: { fn: resp => [resp.toFields()] },
+};
+
+export const MESSAGE_CONTEXT: TypeMapping<MessageContext> = {
+  serialization: { fn: mc => [mc.toFields()] },
+};
+
 const ORACLE_REGISTRY = {
   aztec_utl_assertCompatibleOracleVersion: makeEntry({
     params: [
@@ -389,25 +445,25 @@ const ORACLE_REGISTRY = {
 
   aztec_utl_getPendingTaggedLogs: makeEntry({
     params: [{ name: 'scope', type: AZTEC_ADDRESS }],
-    returnType: FIELD,
+    returnType: EPHEMERAL_ARRAY(PENDING_TAGGED_LOG),
   }),
 
   aztec_utl_validateAndStoreEnqueuedNotesAndEvents: makeEntry({
     params: [
-      { name: 'noteValidationRequestsArrayBaseSlot', type: FIELD },
-      { name: 'eventValidationRequestsArrayBaseSlot', type: FIELD },
+      { name: 'noteValidationRequests', type: EPHEMERAL_ARRAY(NOTE_VALIDATION_REQUEST) },
+      { name: 'eventValidationRequests', type: EPHEMERAL_ARRAY(EVENT_VALIDATION_REQUEST) },
       { name: 'scope', type: AZTEC_ADDRESS },
     ],
   }),
 
   aztec_utl_getLogsByTag: makeEntry({
-    params: [{ name: 'requestArrayBaseSlot', type: FIELD }],
-    returnType: FIELD,
+    params: [{ name: 'requests', type: EPHEMERAL_ARRAY(LOG_RETRIEVAL_REQUEST) }],
+    returnType: EPHEMERAL_ARRAY(EPHEMERAL_ARRAY(LOG_RETRIEVAL_RESPONSE)),
   }),
 
   aztec_utl_getMessageContextsByTxHash: makeEntry({
-    params: [{ name: 'requestArrayBaseSlot', type: FIELD }],
-    returnType: FIELD,
+    params: [{ name: 'requests', type: EPHEMERAL_ARRAY(FIELD) }],
+    returnType: EPHEMERAL_ARRAY(OPTION(MESSAGE_CONTEXT)),
   }),
 
   aztec_utl_getTxEffect: makeEntry({
@@ -464,10 +520,10 @@ const ORACLE_REGISTRY = {
   aztec_utl_getSharedSecrets: makeEntry({
     params: [
       { name: 'address', type: AZTEC_ADDRESS },
-      { name: 'ephPksSlot', type: FIELD },
+      { name: 'ephPks', type: EPHEMERAL_ARRAY(POINT) },
       { name: 'contractAddress', type: AZTEC_ADDRESS },
     ],
-    returnType: FIELD,
+    returnType: EPHEMERAL_ARRAY(FIELD),
   }),
 
   aztec_utl_setContractSyncCacheInvalid: makeEntry({
@@ -820,7 +876,7 @@ function BOUNDED_VEC<T>(element: TypeMapping<T>): TypeMapping<BoundedVec<T>> {
  * slot 1: Fr(0)    // zero-filled using shape
  * ```
  */
-function OPTION<T>(inner: TypeMapping<T>): TypeMapping<Option<T>> {
+export function OPTION<T>(inner: TypeMapping<T>): TypeMapping<Option<T>> {
   return {
     serialization: inner.serialization
       ? {
@@ -870,6 +926,17 @@ function BUFFER(bitSize: number): TypeMapping<Buffer> {
   };
 }
 
+export function EPHEMERAL_ARRAY<T>(element: TypeMapping<T>): TypeMapping<EphemeralArray<T>> {
+  return {
+    serialization: element.serialization
+      ? { fn: ea => [ea.materializeSlot(v => element.serialization!.fn(v).flat() as Fr[])] }
+      : undefined,
+    deserialization: element.deserialization
+      ? { fn: ([reader]) => EphemeralArray.fromSlot(reader.readField(), element), slots: 1 }
+      : undefined,
+  };
+}
+
 /** A named oracle parameter with its TypeMapping. */
 interface RegistryParam<TName extends string = string, T = any> {
   name: TName;