@aztec/pxe 5.0.0-rc.1 → 5.0.0-rc.2

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

@@ -1,66 +1,13 @@
-import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_CIPHERTEXT_LEN } from '@aztec/constants';
-import { range } from '@aztec/foundation/array';
-import { Fr } from '@aztec/foundation/curves/bn254';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { TxHash } from '@aztec/stdlib/tx';
 
-const MAX_LOG_CONTENT_LEN = PRIVATE_LOG_CIPHERTEXT_LEN;
-
 /**
  * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle stores values of this
  * type in a `EphemeralArray`.
  */
-export class LogRetrievalResponse {
-  constructor(
-    public logPayload: Fr[],
-    public txHash: TxHash,
-    public uniqueNoteHashesInTx: Fr[],
-    public firstNullifierInTx: Fr,
-  ) {}
-
-  toFields(): Fr[] {
-    return [
-      // We need to trim the payload since public logs can be larger than MAX_LOG_CONTENT_LEN.
-      // This is currently not a problem since this class is only used with public logs for note completion.
-      ...serializeBoundedVec(this.logPayload.slice(0, MAX_LOG_CONTENT_LEN), MAX_LOG_CONTENT_LEN),
-      this.txHash.hash,
-      ...serializeBoundedVec(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
-      this.firstNullifierInTx,
-    ];
-  }
-
-  static toEmptyFields(): Fr[] {
-    const serializationLen =
-      MAX_LOG_CONTENT_LEN +
-      1 /* logPayload BVec */ +
-      1 /* txHash */ +
-      MAX_NOTE_HASHES_PER_TX +
-      1 /* uniqueNoteHashesInTx BVec */ +
-      1; /* firstNullifierInTx */
-    return range(serializationLen).map(_ => Fr.zero());
-  }
-
-  static toSerializedOption(response: LogRetrievalResponse | null): Fr[] {
-    if (response) {
-      return [new Fr(1), ...response.toFields()];
-    } else {
-      return [new Fr(0), ...LogRetrievalResponse.toEmptyFields()];
-    }
-  }
-}
-
-/**
- * Helper function to serialize a bounded vector according to Noir's BoundedVec format
- * @param values - The values to serialize
- * @param maxLength - The maximum length of the bounded vector
- * @returns The serialized bounded vector as Fr[]
- */
-function serializeBoundedVec(values: Fr[], maxLength: number): Fr[] {
-  if (values.length > maxLength) {
-    throw new Error(`Attempted to serialize ${values} values into a BoundedVec with max length ${maxLength}`);
-  }
-
-  const lengthDiff = maxLength - values.length;
-  const zeroPaddingArray = Array(lengthDiff).fill(Fr.ZERO);
-  const storage = values.concat(zeroPaddingArray);
-  return [...storage, new Fr(values.length)];
-}
+export type LogRetrievalResponse = {
+  logPayload: Fr[];
+  txHash: TxHash;
+  uniqueNoteHashesInTx: Fr[];
+  firstNullifierInTx: Fr;
+};

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

@@ -23,8 +23,8 @@ export class NoteValidationRequest {
   static fromFields(fields: Fr[] | FieldReader): NoteValidationRequest {
     const reader = FieldReader.asReader(fields);
 
-    const contractAddress = AztecAddress.fromField(reader.readField());
-    const owner = AztecAddress.fromField(reader.readField());
+    const contractAddress = AztecAddress.fromFieldUnsafe(reader.readField());
+    const owner = AztecAddress.fromFieldUnsafe(reader.readField());
     const storageSlot = reader.readField();
     const randomness = reader.readField();
     const noteNonce = reader.readField();

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

@@ -8,7 +8,9 @@
 export class Option<T> {
   private constructor(
     public readonly value: T | undefined,
-    public readonly template: T | undefined,
+    // `unknown` (not the descriptor shape) keeps this generic Option decoupled from the serialization layer's
+    // `{ length }`/`{ maxLength }` size descriptors; only the None-serialization path inspects it.
+    public readonly size: unknown,
   ) {}
 
   /**
@@ -26,25 +28,22 @@ export class Option<T> {
   /**
    * 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.
+   * When serialized back to ACVM, the `None` case must produce the same number of fields as `Some`. For an inner type whose
+   * wire size varies per call site (`BoundedVec`, an array), pass a `size` descriptor so the inner type's shape can
+   * resolve how many zero fields to emit; fixed-size inners take no argument.
    *
    * @example None for a fixed-size type:
    * ```ts
-   * return Option.none(AztecAddress.ZERO);
+   * return Option.none();
    * ```
    *
    * @example None for a dynamic-size type:
    * ```ts
-   * return Option.none(BoundedVec.empty<number>({ maxLength: ciphertext.maxLength }));
+   * return Option.none({ maxLength: ciphertext.maxLength });
    * ```
    */
-  static none<T>(template?: T): Option<T> {
-    return new Option<T>(undefined, template);
+  static none<T>(size?: unknown): Option<T> {
+    return new Option<T>(undefined, size);
   }
 
   /**
@@ -66,4 +65,11 @@ export class Option<T> {
   isNone(): this is Option<T> & { value: undefined } {
     return this.value === undefined;
   }
+
+  equals(other: Option<T>, innerEquals: (a: T, b: T) => boolean): boolean {
+    if (this.isSome() && other.isSome()) {
+      return innerEquals(this.value, other.value);
+    }
+    return this.isNone() && other.isNone();
+  }
 }

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

@@ -0,0 +1,8 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+/**
+ * The block a retractable fact originates from.
+ *
+ * A TS version of the `OriginBlock` struct in `facts/mod.nr`.
+ */
+export type OriginBlock = { blockNumber: number; blockHash: Fr };

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

@@ -1,16 +1,5 @@
-import { Fr } from '@aztec/foundation/curves/bn254';
-import { FieldReader } from '@aztec/foundation/serialize';
-import { AppTaggingSecretKind, appTaggingSecretKindFromDeliveryMode } from '@aztec/stdlib/logs';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { 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(), appTaggingSecretKindFromDeliveryMode(reader.readField().toNumber()));
-  }
-}
+export type ProvidedSecret = { secret: Fr; mode: AppTaggingSecretKind };

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

@@ -0,0 +1,45 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+
+// Keep in sync with aztec::messages::delivery::ResolvedTaggingStrategy
+const NON_INTERACTIVE_HANDSHAKE = 1;
+const UNCONSTRAINED_SECRET = 2;
+
+/**
+ * The tagging secret PXE hands to the contract after applying the wallet's {@link TaggingSecretStrategy} choice
+ * (and app-siloing). The contract uses it directly to derive the message tag, so it never sees raw key material.
+ */
+export type ResolvedTaggingStrategy =
+  | {
+      /** A non-interactive handshake: the recipient re-derives the secret from the onchain handshake registry. */
+      type: 'non-interactive-handshake';
+    }
+  | {
+      /**
+       * An app-siloed, recipient-directional secret, ready to use. Only sound for unconstrained delivery.
+       */
+      type: 'unconstrained-secret';
+      /** The app-siloed directional tagging secret. */
+      secret: Fr;
+    };
+
+/** Serializes a {@link ResolvedTaggingStrategy} to its Noir `[kind, secret]` field layout, zero-filling absent fields. */
+export function resolvedTaggingStrategyToFields(resolved: ResolvedTaggingStrategy): Fr[] {
+  switch (resolved.type) {
+    case 'non-interactive-handshake':
+      return [new Fr(NON_INTERACTIVE_HANDSHAKE), Fr.ZERO];
+    case 'unconstrained-secret':
+      return [new Fr(UNCONSTRAINED_SECRET), resolved.secret];
+  }
+}
+
+/** Deserializes a {@link ResolvedTaggingStrategy} from its `kind` discriminant and `secret` field. */
+export function resolvedTaggingStrategyFromFields(kind: number, secret: Fr): ResolvedTaggingStrategy {
+  switch (kind) {
+    case NON_INTERACTIVE_HANDSHAKE:
+      return { type: 'non-interactive-handshake' };
+    case UNCONSTRAINED_SECRET:
+      return { type: 'unconstrained-secret', secret };
+    default:
+      throw new Error(`Unrecognized resolved tagging strategy kind: ${kind}`);
+  }
+}

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

@@ -0,0 +1,53 @@
+import { MAX_NOTE_HASHES_PER_TX } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { TxHash } from '@aztec/stdlib/tx';
+
+/**
+ * The resolved on-chain context of a transaction.
+ *
+ * Carries the note hashes and first nullifier needed to discover notes that originated from the transaction, plus the
+ * number and hash of the block in which it was mined.
+ *
+ * A TS version of the `ResolvedTx` struct in `oracle/tx_resolution.nr`.
+ */
+export class ResolvedTx {
+  constructor(
+    public txHash: TxHash,
+    public uniqueNoteHashesInTx: Fr[],
+    public firstNullifierInTx: Fr,
+    public blockNumber: number,
+    public blockHash: Fr,
+  ) {}
+
+  toFields(): Fr[] {
+    return [
+      this.txHash.hash,
+      ...serializeBoundedVec(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
+      this.firstNullifierInTx,
+      new Fr(this.blockNumber),
+      this.blockHash,
+    ];
+  }
+
+  static empty(): ResolvedTx {
+    return new ResolvedTx(TxHash.zero(), [], Fr.ZERO, 0, Fr.ZERO);
+  }
+}
+
+/**
+ * Helper function to serialize a bounded vector according to Noir's BoundedVec format: the storage array padded to
+ * `maxLength`, followed by the actual length.
+ * @param values - The values to serialize
+ * @param maxLength - The maximum length of the bounded vector
+ * @returns The serialized bounded vector as Fr[]
+ */
+function serializeBoundedVec(values: Fr[], maxLength: number): Fr[] {
+  const storage = padArrayEnd(
+    values,
+    Fr.ZERO,
+    maxLength,
+    `Attempted to serialize ${values} values into a BoundedVec with max length ${maxLength}`,
+  );
+  return [...storage, new Fr(values.length)];
+}

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

@@ -0,0 +1,15 @@
+import type { FieldsOf } from '@aztec/foundation/types';
+import type { FlatPublicLogs } from '@aztec/stdlib/logs';
+import type { TxEffect } from '@aztec/stdlib/tx';
+
+import type { ContractClassLogData } from './contract_class_log_data.js';
+
+/**
+ * Wire form of a {@link TxEffect} as the `getTxEffect` oracle returns it: identical to the domain type except its logs
+ * are flattened to their Noir layout. Keeping the conversion in the handler lets the `TX_EFFECT` mapping stay purely
+ * structural.
+ */
+export type TxEffectData = Omit<FieldsOf<TxEffect>, 'publicLogs' | 'contractClassLogs'> & {
+  publicLogs: FlatPublicLogs;
+  contractClassLogs: ContractClassLogData[];
+};

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

@@ -1,23 +1,11 @@
-import { toACVMField } from '@aztec/simulator/client';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { BlockHeader } from '@aztec/stdlib/tx';
 
 /**
  * TypeScript counterpart of utility_context.nr. Used only as a return value for the utilityGetUtilityContext oracle.
  */
-export class UtilityContext {
-  constructor(
-    public readonly blockHeader: BlockHeader,
-    public readonly contractAddress: AztecAddress,
-  ) {}
-
-  /**
-   * Returns a representation of the utility context as expected by intrinsic Noir deserialization.
-   * The order of the fields has to be the same as the order of the fields in the utility_context.nr.
-   */
-  public toNoirRepresentation(): (string | string[])[] {
-    // TODO(#12874): remove the stupid as string conversion by modifying ForeignCallOutput type in acvm.js
-    const blockHeaderFields = this.blockHeader.toFields().map(toACVMField);
-    return [...blockHeaderFields, this.contractAddress.toString() as string];
-  }
-}
+export type UtilityContext = {
+  blockHeader: BlockHeader;
+  contractAddress: AztecAddress;
+  msgSender: AztecAddress;
+};

package/src/contract_function_simulator/oracle/message_load_oracle_inputs.ts

@@ -1,23 +1,8 @@
-import { Fr } from '@aztec/foundation/curves/bn254';
 import type { SiblingPath } from '@aztec/foundation/trees';
 
-export class MessageLoadOracleInputs<N extends number> {
-  constructor(
-    /** The index of the message commitment in the merkle tree. */
-    public index: bigint,
-    /** The path in the merkle tree to the message. */
-    public siblingPath: SiblingPath<N>,
-  ) {}
-
-  toFields(): Fr[] {
-    return [new Fr(this.index), ...this.siblingPath.toFields()];
-  }
-
-  /**
-   * Returns a representation of the public data witness as expected by intrinsic Noir deserialization.
-   */
-  public toNoirRepresentation(): (string | string[])[] {
-    // TODO(#12874): remove the stupid as string conversion by modifying ForeignCallOutput type in acvm.js
-    return [new Fr(this.index).toString() as string, this.siblingPath.toFields().map(fr => fr.toString()) as string[]];
-  }
-}
+export type MessageLoadOracleInputs<N extends number> = {
+  /** The index of the message commitment in the merkle tree. */
+  index: bigint;
+  /** The path in the merkle tree to the message. */
+  siblingPath: SiblingPath<N>;
+};

package/src/contract_function_simulator/oracle/oracle_registry.ts

@@ -15,11 +15,12 @@ import {
   BUFFER,
   BYTE,
   CALL_PRIVATE_RESULT,
-  CONTRACT_CLASS_LOG_INPUT,
+  CONTRACT_CLASS_LOG,
   CONTRACT_INSTANCE,
   DELIVERY_MODE,
   EPHEMERAL_ARRAY,
   EVENT_VALIDATION_REQUEST,
+  FACT_COLLECTION,
   FIELD,
   FUNCTION_SELECTOR,
   type InputSlot,
@@ -27,7 +28,6 @@ import {
   LOG_RETRIEVAL_REQUEST,
   LOG_RETRIEVAL_RESPONSE,
   MEMBERSHIP_WITNESS,
-  MESSAGE_CONTEXT,
   MESSAGE_LOAD_ORACLE_INPUTS,
   type MaybePromise,
   NOTE,
@@ -35,12 +35,15 @@ import {
   NOTE_VALIDATION_REQUEST,
   NULLIFIER_MEMBERSHIP_WITNESS,
   OPTION,
+  ORIGIN_BLOCK,
   type OutputSlot,
   PENDING_TAGGED_LOG,
   POINT,
   PROVIDED_SECRET,
   PUBLIC_DATA_WITNESS,
   PUBLIC_KEYS_AND_PARTIAL_ADDRESS,
+  RESOLVED_TAGGING_STRATEGY,
+  RESOLVED_TX,
   STR,
   TX_EFFECT,
   TX_HASH,
@@ -48,6 +51,7 @@ import {
   U32,
   UTILITY_CONTEXT,
   assertReadersConsumed,
+  slotsOf,
 } from './oracle_type_mappings.js';
 
 export {
@@ -59,7 +63,9 @@ export {
   BOUNDED_VEC,
   BUFFER,
   BYTE,
+  CONTRACT_CLASS_LOG,
   DELIVERY_MODE,
+  RESOLVED_TAGGING_STRATEGY,
   EPHEMERAL_ARRAY,
   EVENT_VALIDATION_REQUEST,
   FIELD,
@@ -67,85 +73,23 @@ export {
   LOG_RETRIEVAL_REQUEST,
   LOG_RETRIEVAL_RESPONSE,
   MEMBERSHIP_WITNESS,
-  MESSAGE_CONTEXT,
   NOTE_VALIDATION_REQUEST,
   OPTION,
   PENDING_TAGGED_LOG,
   POINT,
   PROVIDED_SECRET,
+  RESOLVED_TX,
   STR,
   U32,
+  slotsOf,
   type InputSlot,
   type MaybePromise,
   type OutputSlot,
+  type SlotShape,
   type TypeMapping,
 } from './oracle_type_mappings.js';
 
-type OracleRegistryName =
-  | 'aztec_misc_assertCompatibleOracleVersion'
-  | 'aztec_misc_getRandomField'
-  | 'aztec_misc_log'
-  | 'aztec_utl_getUtilityContext'
-  | 'aztec_utl_getKeyValidationRequest'
-  | 'aztec_utl_getContractInstance'
-  | 'aztec_utl_getNoteHashMembershipWitness'
-  | 'aztec_utl_getBlockHashMembershipWitness'
-  | 'aztec_utl_getNullifierMembershipWitness'
-  | 'aztec_utl_getLowNullifierMembershipWitness'
-  | 'aztec_utl_getPublicDataWitness'
-  | 'aztec_utl_getBlockHeader'
-  | 'aztec_utl_getAuthWitness'
-  | 'aztec_utl_getPublicKeysAndPartialAddress'
-  | 'aztec_utl_doesNullifierExist'
-  | 'aztec_utl_getL1ToL2MembershipWitness'
-  | 'aztec_utl_getFromPublicStorage'
-  | 'aztec_utl_getNotes'
-  | 'aztec_utl_getPendingTaggedLogs'
-  | 'aztec_utl_validateAndStoreEnqueuedNotesAndEvents'
-  | 'aztec_utl_getLogsByTag'
-  | 'aztec_utl_getMessageContextsByTxHash'
-  | 'aztec_utl_getTxEffect'
-  | 'aztec_utl_setCapsule'
-  | 'aztec_utl_getCapsule'
-  | 'aztec_utl_deleteCapsule'
-  | 'aztec_utl_copyCapsule'
-  | 'aztec_utl_decryptAes128'
-  | 'aztec_utl_getSharedSecrets'
-  | 'aztec_utl_setContractSyncCacheInvalid'
-  | 'aztec_utl_emitOffchainEffect'
-  | 'aztec_utl_callUtilityFunction'
-  | 'aztec_utl_pushEphemeral'
-  | 'aztec_utl_popEphemeral'
-  | 'aztec_utl_getEphemeral'
-  | 'aztec_utl_setEphemeral'
-  | 'aztec_utl_getEphemeralLen'
-  | 'aztec_utl_removeEphemeral'
-  | 'aztec_utl_clearEphemeral'
-  | 'aztec_utl_pushTransient'
-  | 'aztec_utl_popTransient'
-  | 'aztec_utl_getTransient'
-  | 'aztec_utl_setTransient'
-  | 'aztec_utl_getTransientLen'
-  | 'aztec_utl_removeTransient'
-  | 'aztec_utl_clearTransient'
-  | 'aztec_prv_setHashPreimage'
-  | 'aztec_prv_getHashPreimage'
-  | 'aztec_prv_notifyCreatedNote'
-  | 'aztec_prv_notifyNullifiedNote'
-  | 'aztec_prv_notifyCreatedNullifier'
-  | 'aztec_prv_isNullifierPending'
-  | 'aztec_prv_notifyCreatedContractClassLog'
-  | 'aztec_prv_callPrivateFunction'
-  | 'aztec_prv_assertValidPublicCalldata'
-  | 'aztec_prv_notifyRevertiblePhaseStart'
-  | 'aztec_prv_isExecutionInRevertiblePhase'
-  | 'aztec_prv_getAppTaggingSecret'
-  | 'aztec_prv_getNextTaggingIndex'
-  | 'aztec_prv_getSenderForTags';
-
-type OracleRegistry = Record<OracleRegistryName, OracleRegistryEntry>;
-
-export const ORACLE_REGISTRY: OracleRegistry = {
+export const ORACLE_REGISTRY = {
   aztec_misc_assertCompatibleOracleVersion: makeEntry({
     params: [
       { name: 'major', type: U32 },
@@ -167,7 +111,10 @@ export const ORACLE_REGISTRY: OracleRegistry = {
   aztec_utl_getUtilityContext: makeEntry({ returnType: UTILITY_CONTEXT }),
 
   aztec_utl_getKeyValidationRequest: makeEntry({
-    params: [{ name: 'pkMHash', type: FIELD }],
+    params: [
+      { name: 'pkMHash', type: FIELD },
+      { name: 'keyIndex', type: FIELD },
+    ],
     returnType: KEY_VALIDATION_REQUEST,
   }),
 
@@ -299,9 +246,9 @@ export const ORACLE_REGISTRY: OracleRegistry = {
     returnType: EPHEMERAL_ARRAY(EPHEMERAL_ARRAY(LOG_RETRIEVAL_RESPONSE)),
   }),
 
-  aztec_utl_getMessageContextsByTxHash: makeEntry({
+  aztec_utl_getResolvedTxs: makeEntry({
     params: [{ name: 'requests', type: EPHEMERAL_ARRAY(FIELD) }],
-    returnType: EPHEMERAL_ARRAY(OPTION(MESSAGE_CONTEXT)),
+    returnType: EPHEMERAL_ARRAY(OPTION(RESOLVED_TX)),
   }),
 
   aztec_utl_getTxEffect: makeEntry({
@@ -349,8 +296,8 @@ export const ORACLE_REGISTRY: OracleRegistry = {
   aztec_utl_decryptAes128: makeEntry({
     params: [
       { name: 'ciphertext', type: BOUNDED_VEC(BYTE) },
-      { name: 'iv', type: BUFFER(8) },
-      { name: 'symKey', type: BUFFER(8) },
+      { name: 'iv', type: BUFFER(8, 16) },
+      { name: 'symKey', type: BUFFER(8, 16) },
     ],
     returnType: OPTION(BOUNDED_VEC(BYTE)),
   }),
@@ -375,6 +322,46 @@ export const ORACLE_REGISTRY: OracleRegistry = {
     params: [{ name: 'data', type: ARRAY(FIELD) }],
   }),
 
+  aztec_utl_recordFact: makeEntry({
+    params: [
+      { name: 'contractAddress', type: AZTEC_ADDRESS },
+      { name: 'scope', type: AZTEC_ADDRESS },
+      { name: 'factCollectionTypeId', type: FIELD },
+      { name: 'factCollectionId', type: FIELD },
+      { name: 'factTypeId', type: FIELD },
+      { name: 'payload', type: EPHEMERAL_ARRAY(FIELD) },
+      { name: 'originBlock', type: OPTION(ORIGIN_BLOCK) },
+    ],
+  }),
+
+  aztec_utl_deleteFactCollection: makeEntry({
+    params: [
+      { name: 'contractAddress', type: AZTEC_ADDRESS },
+      { name: 'scope', type: AZTEC_ADDRESS },
+      { name: 'factCollectionTypeId', type: FIELD },
+      { name: 'factCollectionId', type: FIELD },
+    ],
+  }),
+
+  aztec_utl_getFactCollection: makeEntry({
+    params: [
+      { name: 'contractAddress', type: AZTEC_ADDRESS },
+      { name: 'scope', type: AZTEC_ADDRESS },
+      { name: 'factCollectionTypeId', type: FIELD },
+      { name: 'factCollectionId', type: FIELD },
+    ],
+    returnType: OPTION(FACT_COLLECTION),
+  }),
+
+  aztec_utl_getFactCollectionsByType: makeEntry({
+    params: [
+      { name: 'contractAddress', type: AZTEC_ADDRESS },
+      { name: 'scope', type: AZTEC_ADDRESS },
+      { name: 'factCollectionTypeId', type: FIELD },
+    ],
+    returnType: EPHEMERAL_ARRAY(FACT_COLLECTION),
+  }),
+
   aztec_utl_callUtilityFunction: makeEntry({
     params: [
       { name: 'contractAddress', type: AZTEC_ADDRESS },
@@ -520,7 +507,7 @@ export const ORACLE_REGISTRY: OracleRegistry = {
 
   aztec_prv_notifyCreatedContractClassLog: makeEntry({
     params: [
-      { name: 'log', type: CONTRACT_CLASS_LOG_INPUT },
+      { name: 'log', type: CONTRACT_CLASS_LOG },
       { name: 'counter', type: U32 },
     ],
   }),
@@ -566,7 +553,16 @@ export const ORACLE_REGISTRY: OracleRegistry = {
   }),
 
   aztec_prv_getSenderForTags: makeEntry({ returnType: OPTION(AZTEC_ADDRESS) }),
-};
+
+  aztec_prv_resolveTaggingStrategy: makeEntry({
+    params: [
+      { name: 'sender', type: AZTEC_ADDRESS },
+      { name: 'recipient', type: AZTEC_ADDRESS },
+      { name: 'deliveryMode', type: DELIVERY_MODE },
+    ],
+    returnType: RESOLVED_TAGGING_STRATEGY,
+  }),
+} satisfies Record<string, OracleRegistryEntry>;
 
 // ─── Registry Infrastructure ─────────────────────────────────────────────────
 
@@ -584,6 +580,10 @@ export interface OracleRegistryEntry<
   deserializeParams(inputs: InputSlot[]): TDeserializedParams;
   /** Serialize a handler return value into ACVM output slots. */
   serializeReturn(result: TReturnValue): OutputSlot[];
+  /** The ordered named parameters with their {@link TypeMapping}s. Lets callers introspect the oracle's wire ABI. */
+  readonly params: readonly RegistryParam[];
+  /** The return {@link TypeMapping}, or `undefined` for oracles that return nothing. */
+  readonly returnType?: TypeMapping<TReturnValue>;
 }
 
 export function makeEntry<const TParams extends RegistryParam[] = [], TReturnValue = void>({
@@ -594,16 +594,18 @@ export function makeEntry<const TParams extends RegistryParam[] = [], TReturnVal
   returnType?: TypeMapping<TReturnValue>;
 } = {}): OracleRegistryEntry<InferDeserializedParams<TParams>, TReturnValue> {
   return {
+    params: params ?? [],
+    returnType,
     deserializeParams(inputs: InputSlot[]): InferDeserializedParams<TParams> {
       const resolvedParams: RegistryParam[] = params ?? [];
       // Walk the input slots left-to-right, advancing by each param's slot count.
       let offset = 0;
-      return resolvedParams.map(param => {
+      const named = resolvedParams.map(param => {
         if (!param.type.deserialization) {
           throw new Error(`Param '${param.name}' has no deserialization defined`);
         }
         // Collect the slots for this param and wrap each in a FieldReader.
-        const slotCount = param.type.deserialization.slots;
+        const slotCount = slotsOf(param.type);
         const readers = inputs
           .slice(offset, offset + slotCount)
           .map(slot => new FieldReader(slot.map(hex => Fr.fromString(hex))));
@@ -613,7 +615,13 @@ export function makeEntry<const TParams extends RegistryParam[] = [], TReturnVal
         const value = param.type.deserialization.fn(readers);
         assertReadersConsumed(readers);
         return { name: param.name, value };
-      }) as unknown as InferDeserializedParams<TParams>;
+      });
+      // Every input slot must be specified by a param: oracles whose Noir decl passes an extra field must declare it
+      // (the handler can ignore it). Otherwise an under-declared shape would silently drop a field into nothing.
+      if (offset !== inputs.length) {
+        throw new Error(`Oracle received ${inputs.length} input slot(s) but the registry specifies ${offset}`);
+      }
+      return named as unknown as InferDeserializedParams<TParams>;
     },
     serializeReturn(result: TReturnValue): OutputSlot[] {
       if (returnType?.serialization === undefined) {
@@ -660,7 +668,7 @@ type InferDeserializedParams<T extends RegistryParam[]> = {
 // ─── Derived Handler Interfaces ─────────────────────────────────────────────
 
 /** Strips the `aztec_{scope}_` prefix from an oracle key to get the handler method name. */
-export type StripOraclePrefix<K extends string> = K extends `aztec_${string}_${infer M}` ? M : never;
+type StripOraclePrefix<K extends string> = K extends `aztec_${string}_${infer M}` ? M : never;
 
 /** Derives the handler function signature from a registry entry's deserialization/serialization types. */
 type HandlerFn<E extends OracleRegistryEntry> = (