@aztec/pxe 5.0.0-rc.2 → 5.0.1

package/src/contract_function_simulator/index.ts

@@ -21,23 +21,27 @@ export {
   ETH_ADDRESS,
   EVENT_VALIDATION_REQUEST,
   FIELD,
+  FIXED_ARRAY,
   FUNCTION_SELECTOR,
   LOG_RETRIEVAL_REQUEST,
   LOG_RETRIEVAL_RESPONSE,
   MEMBERSHIP_WITNESS,
-  MESSAGE_CONTEXT,
   NOTE_SELECTOR,
   NOTE_VALIDATION_REQUEST,
   OPTION,
   PENDING_TAGGED_LOG,
   POINT,
   PROVIDED_SECRET,
+  SLOT_NUMBER,
   STR,
+  STRUCT,
   U32,
+  tryFieldWidth,
   type InputSlot,
   type MaybePromise,
   type OutputSlot,
   type SlotShape,
+  type StructField,
   type TypeMapping,
 } from './oracle/oracle_type_mappings.js';
 export { ExecutionNoteCache } from './execution_note_cache.js';
@@ -53,6 +57,7 @@ export { TxResolverService } from '../messages/tx_resolver_service.js';
 export { UtilityExecutionOracle } from './oracle/utility_execution_oracle.js';
 export { PrivateExecutionOracle } from './oracle/private_execution_oracle.js';
 export { buildACIRCallback, UnavailableOracleError } from './oracle/acir_callback.js';
+export { LEGACY_ORACLE_REGISTRY } from './oracle/legacy_oracle_registry.js';
 export { executePrivateFunction, extractPrivateCircuitPublicInputs } from './oracle/private_execution.js';
 export { generateSimulatedProvingResult } from './contract_function_simulator.js';
 export { packAsHintedNote } from './oracle/note_packing_utils.js';
@@ -66,6 +71,7 @@ export { EventValidationRequest } from './noir-structs/event_validation_request.
 export type { LogRetrievalRequest } from './noir-structs/log_retrieval_request.js';
 export type { LogRetrievalResponse } from './noir-structs/log_retrieval_response.js';
 export { NoteValidationRequest } from './noir-structs/note_validation_request.js';
+export type { PendingTaggedLog } from './noir-structs/pending_tagged_log.js';
 export type { TxEffectData } from './noir-structs/tx_effect_data.js';
 export type { ProvidedSecret } from './noir-structs/provided_secret.js';
 export { ResolvedTx } from './noir-structs/resolved_tx.js';

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

@@ -1,13 +1,13 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
+import type { RetractableFactOrigin } from '../../storage/fact_store/index.js';
 import type { EphemeralArray } from './ephemeral_array.js';
 import type { Option } from './option.js';
-import type { OriginBlock } from './origin_block.js';
 
 /**
  * A single fact returned within a fact collection by the fact store oracles.
  *
- * A TS version of the `Fact` struct in `facts/mod.nr`. `originBlock` is `Some` for a retractable fact (pruned on
- * reorg of that block) and `None` for a non-retractable one.
+ * A TS version of the `Fact` struct in `facts/mod.nr`. `originBlock` is `Some` for a retractable fact (carrying its
+ * origin block's current chain state) and `None` for a non-retractable one.
  */
-export type Fact = { factTypeId: Fr; payload: EphemeralArray<Fr>; originBlock: Option<OriginBlock> };
+export type Fact = { factTypeId: Fr; payload: EphemeralArray<Fr>; originBlock: Option<RetractableFactOrigin> };

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

@@ -1,7 +1,8 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 
-import type { Fact as FactFromStore, OriginBlock } from '../../storage/fact_store/index.js';
+import type { FactWithOriginState, RetractableFactOrigin } from '../../storage/fact_store/index.js';
+import { OriginBlockState } from '../../storage/fact_store/index.js';
 import type { EphemeralArrayService } from '../ephemeral_array_service.js';
 import { EphemeralArray } from './ephemeral_array.js';
 import type { Fact } from './fact.js';
@@ -27,7 +28,7 @@ export function toNoirFactCollection(
   scope: AztecAddress,
   factCollectionTypeId: Fr,
   factCollectionId: Fr,
-  facts: FactFromStore[],
+  facts: FactWithOriginState[],
 ): FactCollection {
   return {
     contractAddress,
@@ -37,12 +38,16 @@ export function toNoirFactCollection(
     facts: EphemeralArray.fromValues(
       service,
       facts.map(
-        (fact: FactFromStore): Fact => ({
+        (fact: FactWithOriginState): Fact => ({
           factTypeId: fact.factTypeId,
           payload: EphemeralArray.fromValues(service, fact.payload),
           originBlock: fact.originBlock
             ? Option.some(fact.originBlock)
-            : Option.none<OriginBlock>({ blockNumber: 0, blockHash: Fr.ZERO }),
+            : Option.none<RetractableFactOrigin>({
+                blockNumber: 0,
+                blockHash: Fr.ZERO,
+                blockState: OriginBlockState.Pending,
+              }),
         }),
       ),
     ),

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

@@ -1,5 +1,8 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { BlockHash } from '@aztec/stdlib/block';
 import type { TxHash } from '@aztec/stdlib/tx';
+import type { UInt64 } from '@aztec/stdlib/types';
 
 /**
  * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle stores values of this
@@ -10,4 +13,7 @@ export type LogRetrievalResponse = {
   txHash: TxHash;
   uniqueNoteHashesInTx: Fr[];
   firstNullifierInTx: Fr;
+  blockNumber: BlockNumber;
+  blockTimestamp: UInt64;
+  blockHash: BlockHash;
 };

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

@@ -0,0 +1,12 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { ResolvedTx } from './resolved_tx.js';
+
+/**
+ * Represents a pending tagged log as it is stored in the pending tagged log array to which the fetchTaggedLogs oracle
+ * inserts found private logs. A TS version of `pending_tagged_log.nr`.
+ */
+export type PendingTaggedLog = {
+  log: Fr[];
+  context: ResolvedTx;
+};

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

@@ -1,5 +1,5 @@
 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. */
+/** A tagging secret an app supplies explicitly to `getPendingTaggedLogsV2` when PXE cannot derive it internally. */
 export type ProvidedSecret = { secret: Fr; mode: AppTaggingSecretKind };

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

@@ -3,6 +3,7 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 // Keep in sync with aztec::messages::delivery::ResolvedTaggingStrategy
 const NON_INTERACTIVE_HANDSHAKE = 1;
 const UNCONSTRAINED_SECRET = 2;
+const INTERACTIVE_HANDSHAKE = 3;
 
 /**
  * The tagging secret PXE hands to the contract after applying the wallet's {@link TaggingSecretStrategy} choice
@@ -13,6 +14,14 @@ export type ResolvedTaggingStrategy =
       /** A non-interactive handshake: the recipient re-derives the secret from the onchain handshake registry. */
       type: 'non-interactive-handshake';
     }
+  | {
+      /**
+       * An interactive handshake: the registry obtains the recipient's signed authorization through the custom
+       * request oracle, and the recipient learns the secret while signing. Nothing announcing the handshake is
+       * published onchain.
+       */
+      type: 'interactive-handshake';
+    }
   | {
       /**
        * An app-siloed, recipient-directional secret, ready to use. Only sound for unconstrained delivery.
@@ -29,6 +38,8 @@ export function resolvedTaggingStrategyToFields(resolved: ResolvedTaggingStrateg
       return [new Fr(NON_INTERACTIVE_HANDSHAKE), Fr.ZERO];
     case 'unconstrained-secret':
       return [new Fr(UNCONSTRAINED_SECRET), resolved.secret];
+    case 'interactive-handshake':
+      return [new Fr(INTERACTIVE_HANDSHAKE), Fr.ZERO];
   }
 }
 
@@ -36,10 +47,20 @@ export function resolvedTaggingStrategyToFields(resolved: ResolvedTaggingStrateg
 export function resolvedTaggingStrategyFromFields(kind: number, secret: Fr): ResolvedTaggingStrategy {
   switch (kind) {
     case NON_INTERACTIVE_HANDSHAKE:
+      assertAbsentSecret(kind, secret);
       return { type: 'non-interactive-handshake' };
+    case INTERACTIVE_HANDSHAKE:
+      assertAbsentSecret(kind, secret);
+      return { type: 'interactive-handshake' };
     case UNCONSTRAINED_SECRET:
       return { type: 'unconstrained-secret', secret };
     default:
       throw new Error(`Unrecognized resolved tagging strategy kind: ${kind}`);
   }
 }
+
+function assertAbsentSecret(kind: number, secret: Fr): void {
+  if (!secret.isZero()) {
+    throw new Error(`Resolved tagging strategy ${kind} must not include a secret`);
+  }
+}

package/src/contract_function_simulator/oracle/acir_callback.ts

@@ -2,7 +2,8 @@ import type { ACIRCallback, ACVMField } from '@aztec/simulator/client';
 
 import { ORACLE_VERSION_MAJOR, ORACLE_VERSION_MINOR } from '../../oracle_version.js';
 import type { IMiscOracle, IPrivateExecutionOracle, IUtilityExecutionOracle } from './interfaces.js';
-import { ORACLE_REGISTRY } from './oracle_registry.js';
+import { LEGACY_ORACLE_REGISTRY, type LegacyOracleEntry } from './legacy_oracle_registry.js';
+import { type NamedValue, ORACLE_REGISTRY, type OracleRegistryEntry, makeEntry } from './oracle_registry.js';
 
 export class UnavailableOracleError extends Error {
   constructor(oracleName: string) {
@@ -17,26 +18,71 @@ export class UnavailableOracleError extends Error {
  * `aztec_{scope}_{methodName}` convention to resolve the handler, and calling the method directly. Unknown oracle
  * names produce enhanced error messages based on the contract's oracle version.
  */
-export function buildACIRCallback(handler: OracleHandler): ACIRCallback {
+export function buildACIRCallback(
+  handler: OracleHandler,
+  registries: {
+    real?: Record<string, OracleRegistryEntry>;
+    legacy?: Record<string, LegacyOracleEntry>;
+  } = {},
+): ACIRCallback {
+  const { real = ORACLE_REGISTRY, legacy: legacyRegistry = LEGACY_ORACLE_REGISTRY } = registries;
   const target = {} as ACIRCallback;
-  for (const [oracleKey, entry] of Object.entries(ORACLE_REGISTRY)) {
-    const match = oracleKey.match(/^aztec_(\w+?)_(.+)$/);
-    if (!match) {
-      throw new Error(`Oracle "${oracleKey}" does not follow the aztec_{scope}_{method} convention`);
-    }
-    const [, scope, methodName] = match;
+  for (const [oracleKey, entry] of Object.entries(real)) {
+    const { scope, methodName } = parseOracleName(oracleKey, 'Oracle');
     target[oracleKey] = async (...inputs: ACVMField[][]) => {
       assertHandlerSupportsScope(handler, scope);
       const named = entry.deserializeParams(inputs);
-      const positional = named.map(p => p.value);
+      const positional = named.map((p: NamedValue) => p.value);
       const result = await (handler as any)[methodName](...positional);
       return entry.serializeReturn(result);
     };
   }
 
-  return new Proxy(target, {
+  // Legacy oracle names: served for contracts compiled against a retired oracle version. Each reuses the current
+  // handler of its `modernOracle` and reshapes the wire (params and/or return) back to what the old bytecode expects.
+  for (const [legacyKey, legacy] of Object.entries(legacyRegistry)) {
+    const { scope } = parseOracleName(legacyKey, 'Legacy oracle');
+    if (legacyKey in target) {
+      throw new Error(`Legacy oracle "${legacyKey}" collides with a live oracle of the same name in the registry`);
+    }
+    const modernEntry = real[legacy.modernOracle];
+    const { methodName } = parseOracleName(legacy.modernOracle, 'Oracle');
+    // Override only the side whose wire changed; inherit the other from the modern entry.
+    const paramOverride = legacy.params;
+    const paramSource = paramOverride ? makeEntry({ params: [...paramOverride.legacyType] }) : modernEntry;
+    const returnOverride = legacy.returnType;
+    const returnSource = returnOverride ? makeEntry({ returnType: returnOverride.legacyType }) : modernEntry;
+    target[legacyKey] = async (...inputs: ACVMField[][]) => {
+      assertHandlerSupportsScope(handler, scope);
+      const legacyArgs = paramSource.deserializeParams(inputs).map(p => p.value);
+      const positional = paramOverride ? await paramOverride.mapping(legacyArgs) : legacyArgs;
+      const result = await (handler as any)[methodName](...positional);
+      return returnSource.serializeReturn(returnOverride ? returnOverride.mapping(result) : result);
+    };
+  }
+
+  return new Proxy(target, makeUnknownOracleTrap(handler));
+}
+
+/** Parses an `aztec_{scope}_{method}` oracle name into its parts, throwing if it doesn't follow the convention. */
+function parseOracleName(key: string, label: string): { scope: string; methodName: string } {
+  const match = key.match(/^aztec_(\w+?)_(.+)$/);
+  if (!match) {
+    throw new Error(`${label} "${key}" does not follow the aztec_{scope}_{method} convention`);
+  }
+  return { scope: match[1], methodName: match[2] };
+}
+
+/**
+ * Proxy trap for the callback table: a known oracle name passes through; an unknown one throws a diagnostic keyed on
+ * the contract's oracle version (version unknown, contract newer than this environment, or a same-version mismatch).
+ */
+function makeUnknownOracleTrap(handler: OracleHandler): ProxyHandler<ACIRCallback> {
+  return {
     get(obj, prop: string) {
-      if (prop in obj) {
+      // Own-property check only: `in` would match inherited `Object.prototype` keys (e.g. `constructor`, `toString`)
+      // and return the built-in instead of falling through to the unknown-oracle diagnostic below.
+      if (Object.hasOwn(obj, prop)) {
         return (obj as Record<string, unknown>)[prop];
       }
 
@@ -76,7 +122,7 @@ export function buildACIRCallback(handler: OracleHandler): ACIRCallback {
         }
       };
     },
-  });
+  };
 }
 
 type OracleHandler = IMiscOracle & (IUtilityExecutionOracle | IPrivateExecutionOracle);

package/src/contract_function_simulator/oracle/legacy_oracle_registry.ts

@@ -0,0 +1,147 @@
+/* eslint-disable camelcase */
+import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_CIPHERTEXT_LEN, PRIVATE_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
+import { computeFeeJuiceMessageNullifier } from '@aztec/stdlib/messaging';
+
+import type { EphemeralArray } from '../noir-structs/ephemeral_array.js';
+import type { LogRetrievalResponse } from '../noir-structs/log_retrieval_response.js';
+import { Option } from '../noir-structs/option.js';
+import type { PendingTaggedLog } from '../noir-structs/pending_tagged_log.js';
+import type { ResolvedTx } from '../noir-structs/resolved_tx.js';
+import {
+  type InferDeserializedParams,
+  ORACLE_REGISTRY,
+  type OracleRegistryEntry,
+  type ParamTypes,
+  type RegistryParam,
+} from './oracle_registry.js';
+import {
+  AZTEC_ADDRESS,
+  EPHEMERAL_ARRAY,
+  FIELD,
+  FIXED_BOUNDED_VEC,
+  STRUCT,
+  TX_HASH,
+  type TypeMapping,
+} from './oracle_type_mappings.js';
+
+const LEGACY_LOG_RETRIEVAL_RESPONSE: TypeMapping<LegacyLogRetrievalResponse> = STRUCT([
+  { name: 'logPayload', type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_CIPHERTEXT_LEN) },
+  { name: 'txHash', type: TX_HASH },
+  { name: 'uniqueNoteHashesInTx', type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX) },
+  { name: 'firstNullifierInTx', type: FIELD },
+]);
+
+// Block-less transaction context: the prefix of `ResolvedTx`'s wire carried by the original `getPendingTaggedLogs`
+// oracle. Known as `MessageContext` in the Aztec.nr versions that call that oracle.
+const LEGACY_MESSAGE_CONTEXT: TypeMapping<LegacyMessageContext> = STRUCT<LegacyMessageContext>([
+  { name: 'txHash', type: TX_HASH },
+  { name: 'uniqueNoteHashesInTx', type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX) },
+  { name: 'firstNullifierInTx', type: FIELD },
+]);
+
+const LEGACY_PENDING_TAGGED_LOG: TypeMapping<LegacyPendingTaggedLog> = STRUCT<LegacyPendingTaggedLog>([
+  { name: 'log', type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS) },
+  { name: 'context', type: LEGACY_MESSAGE_CONTEXT },
+]);
+
+/**
+ * Wire shapes that already-deployed contracts still call by their original oracle name, keyed by that retired name.
+ * New Aztec.nr calls the current name in `ORACLE_REGISTRY`; old bytecode keeps calling the name compiled into it and
+ * is served from here, so versioning an oracle's wire (e.g. adding return fields) stops being a breaking change.
+ *
+ * Append-only. Drop an entry only once the `ORACLE_VERSION_MAJOR` that introduced its successor is retired, since
+ * older contracts can no longer run against this environment.
+ */
+export const LEGACY_ORACLE_REGISTRY: Record<string, LegacyOracleEntry> = {
+  aztec_utl_getL1ToL2MembershipWitness: legacyOracle({
+    modernOracle: 'aztec_utl_getL1ToL2MembershipWitnessV2',
+    // The old wire passed the contract address and secret, the modern oracle takes the unsiloed nullifier (plus the
+    // address to silo it with) instead. We derive it here so already-deployed contracts that still emit the old call
+    // keep working.
+    //
+    // This is the fee juice message nullifier derivation: only contracts using that scheme call this retired oracle.
+    params: {
+      legacyType: [
+        { name: 'contractAddress', type: AZTEC_ADDRESS },
+        { name: 'messageHash', type: FIELD },
+        { name: 'secret', type: FIELD },
+      ],
+      mapping: async ([contractAddress, messageHash, secret]) => [
+        messageHash,
+        Option.some({ contractAddress, nullifier: await computeFeeJuiceMessageNullifier(messageHash, secret) }),
+      ],
+    },
+  }),
+  aztec_utl_getLogsByTag: legacyOracle({
+    modernOracle: 'aztec_utl_getLogsByTagV2',
+    returnType: {
+      legacyType: EPHEMERAL_ARRAY(EPHEMERAL_ARRAY(LEGACY_LOG_RETRIEVAL_RESPONSE)),
+      // We can map this directly, since the new type is a superset of the old type
+      mapping: result => result as unknown as EphemeralArray<EphemeralArray<LegacyLogRetrievalResponse>>,
+    },
+  }),
+  aztec_utl_getPendingTaggedLogs: legacyOracle({
+    modernOracle: 'aztec_utl_getPendingTaggedLogsV2',
+    returnType: {
+      legacyType: EPHEMERAL_ARRAY(LEGACY_PENDING_TAGGED_LOG),
+      // We can map this directly, since `ResolvedTx` carries the legacy context's fields under the same names
+      mapping: result => result as unknown as EphemeralArray<LegacyPendingTaggedLog>,
+    },
+  }),
+};
+
+type LegacyLogRetrievalResponse = Pick<
+  LogRetrievalResponse,
+  'logPayload' | 'txHash' | 'uniqueNoteHashesInTx' | 'firstNullifierInTx'
+>;
+
+type LegacyMessageContext = Pick<ResolvedTx, 'txHash' | 'uniqueNoteHashesInTx' | 'firstNullifierInTx'>;
+
+type LegacyPendingTaggedLog = {
+  log: PendingTaggedLog['log'];
+  context: LegacyMessageContext;
+};
+
+type Registry = typeof ORACLE_REGISTRY;
+
+/** The handler return value type of a modern oracle entry. */
+type ReturnValueOf<K extends keyof Registry> = Registry[K] extends OracleRegistryEntry<any, infer R> ? R : never;
+
+/** The modern handler's positional argument tuple, derived from the oracle's declared params. */
+type HandlerArgsOf<K extends keyof Registry> = ParamTypes<ReturnType<Registry[K]['deserializeParams']>>;
+
+/**
+ * A legacy oracle adapter, stored under the retired oracle name that already-deployed contracts still call. It reuses
+ * the handler of `modernOracle` and overrides only the wire side(s) that changed; an omitted side falls back to that
+ * modern entry.
+ */
+export interface LegacyOracleEntry {
+  /** The current oracle whose handler this reuses and whose param/return wire it inherits by default. */
+  modernOracle: keyof Registry;
+  /**
+   * Old param wire. `legacyType` deserializes the old wire; `mapping` bridges the deserialized legacy args to the
+   * modern handler's args. The mapping may be async. Omit when the param wire is unchanged.
+   */
+  params?: {
+    legacyType: readonly RegistryParam[];
+    mapping: (legacyArgs: any) => readonly unknown[] | Promise<readonly unknown[]>;
+  };
+  /**
+   * Old return wire. `legacyType` serializes the subset the old contract reads; `mapping` bridges the handler's
+   * current result to that subset's value type. Omit when the return wire is unchanged.
+   */
+  returnType?: { legacyType: TypeMapping; mapping: (result: any) => unknown };
+}
+
+function legacyOracle<K extends keyof Registry, W = never, const TLegacyParams extends RegistryParam[] = []>(entry: {
+  modernOracle: K;
+  params?: {
+    legacyType: [...TLegacyParams];
+    mapping: (
+      legacyArgs: ParamTypes<InferDeserializedParams<TLegacyParams>>,
+    ) => HandlerArgsOf<K> | Promise<HandlerArgsOf<K>>;
+  };
+  returnType?: { legacyType: TypeMapping<W>; mapping: (result: ReturnValueOf<K>) => W };
+}): LegacyOracleEntry {
+  return entry;
+}

package/src/contract_function_simulator/oracle/oracle_registry.ts

@@ -3,6 +3,7 @@ import { ARCHIVE_HEIGHT, NOTE_HASH_TREE_HEIGHT } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { FieldReader } from '@aztec/foundation/serialize';
 import { toACVMField } from '@aztec/simulator/client';
+import type { UnsiloedMessageNullifier } from '@aztec/stdlib/messaging';
 
 import {
   ARRAY,
@@ -45,6 +46,7 @@ import {
   RESOLVED_TAGGING_STRATEGY,
   RESOLVED_TX,
   STR,
+  STRUCT,
   TX_EFFECT,
   TX_HASH,
   type TypeMapping,
@@ -139,6 +141,14 @@ export const ORACLE_REGISTRY = {
     returnType: OPTION(MEMBERSHIP_WITNESS(ARCHIVE_HEIGHT)),
   }),
 
+  aztec_utl_areBlockHashesInArchive: makeEntry({
+    params: [
+      { name: 'anchorBlockHash', type: BLOCK_HASH },
+      { name: 'blockHashes', type: EPHEMERAL_ARRAY(BLOCK_HASH) },
+    ],
+    returnType: EPHEMERAL_ARRAY(BOOL),
+  }),
+
   aztec_utl_getNullifierMembershipWitness: makeEntry({
     params: [
       { name: 'blockHash', type: BLOCK_HASH },
@@ -183,11 +193,18 @@ export const ORACLE_REGISTRY = {
     returnType: BOOL,
   }),
 
-  aztec_utl_getL1ToL2MembershipWitness: makeEntry({
+  aztec_utl_getL1ToL2MembershipWitnessV2: makeEntry({
     params: [
-      { name: 'contractAddress', type: AZTEC_ADDRESS },
       { name: 'messageHash', type: FIELD },
-      { name: 'secret', type: FIELD },
+      {
+        name: 'nullifier',
+        type: OPTION(
+          STRUCT<UnsiloedMessageNullifier>([
+            { name: 'contractAddress', type: AZTEC_ADDRESS },
+            { name: 'nullifier', type: FIELD },
+          ]),
+        ),
+      },
     ],
     returnType: MESSAGE_LOAD_ORACLE_INPUTS,
   }),
@@ -225,7 +242,7 @@ export const ORACLE_REGISTRY = {
     returnType: BOUNDED_VEC(NOTE),
   }),
 
-  aztec_utl_getPendingTaggedLogs: makeEntry({
+  aztec_utl_getPendingTaggedLogsV2: makeEntry({
     params: [
       { name: 'scope', type: AZTEC_ADDRESS },
       { name: 'providedSecrets', type: EPHEMERAL_ARRAY(PROVIDED_SECRET) },
@@ -241,7 +258,7 @@ export const ORACLE_REGISTRY = {
     ],
   }),
 
-  aztec_utl_getLogsByTag: makeEntry({
+  aztec_utl_getLogsByTagV2: makeEntry({
     params: [{ name: 'requests', type: EPHEMERAL_ARRAY(LOG_RETRIEVAL_REQUEST) }],
     returnType: EPHEMERAL_ARRAY(EPHEMERAL_ARRAY(LOG_RETRIEVAL_RESPONSE)),
   }),
@@ -256,6 +273,11 @@ export const ORACLE_REGISTRY = {
     returnType: OPTION(TX_EFFECT),
   }),
 
+  aztec_utl_getTxEffects: makeEntry({
+    params: [{ name: 'txHashes', type: EPHEMERAL_ARRAY(TX_HASH) }],
+    returnType: EPHEMERAL_ARRAY(OPTION(TX_EFFECT)),
+  }),
+
   aztec_utl_setCapsule: makeEntry({
     params: [
       { name: 'contractAddress', type: AZTEC_ADDRESS },
@@ -562,6 +584,14 @@ export const ORACLE_REGISTRY = {
     ],
     returnType: RESOLVED_TAGGING_STRATEGY,
   }),
+
+  aztec_prv_resolveCustomRequest: makeEntry({
+    params: [
+      { name: 'kind', type: FIELD },
+      { name: 'payload', type: ARRAY(FIELD) },
+    ],
+    returnType: ARRAY(FIELD),
+  }),
 } satisfies Record<string, OracleRegistryEntry>;
 
 // ─── Registry Infrastructure ─────────────────────────────────────────────────
@@ -635,7 +665,7 @@ export function makeEntry<const TParams extends RegistryParam[] = [], TReturnVal
 }
 
 /** A named oracle parameter with its TypeMapping. */
-interface RegistryParam<TName extends string = string, T = any> {
+export interface RegistryParam<TName extends string = string, T = any> {
   name: TName;
   type: TypeMapping<T>;
 }
@@ -661,7 +691,7 @@ export type ParamTypes<T extends readonly NamedValue[]> = {
  * @example `InferDeserializedParams<[RegistryParam<'addr', AztecAddress>, RegistryParam<'slot', Fr>]>`
  *        → `[NamedValue<'addr', AztecAddress>, NamedValue<'slot', Fr>]`
  */
-type InferDeserializedParams<T extends RegistryParam[]> = {
+export type InferDeserializedParams<T extends RegistryParam[]> = {
   [K in keyof T]: T[K] extends RegistryParam<infer N, infer V> ? NamedValue<N, V> : never;
 };