@aztec/pxe 5.0.0-rc.2 → 5.0.0

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)),
   }),
@@ -562,6 +579,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 +660,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 +686,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;
 };
 

package/src/contract_function_simulator/oracle/oracle_type_mappings.ts

@@ -24,15 +24,13 @@ import { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
 import { PublicDataWrite, RevertCode } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { BlockHash } from '@aztec/stdlib/block';
-import type { ContractInstance, PartialAddress } from '@aztec/stdlib/contract';
+import type { ContractInstancePreimage, PartialAddress } from '@aztec/stdlib/contract';
 import type { GasFees } from '@aztec/stdlib/gas';
 import { KeyValidationRequest } from '@aztec/stdlib/kernel';
 import type { PublicKeys } from '@aztec/stdlib/keys';
 import {
   type AppTaggingSecretKind,
   type FlatPublicLogs,
-  type MessageContext,
-  type PendingTaggedLog,
   PrivateLog,
   Tag,
   appTaggingSecretKindFromDeliveryMode,
@@ -54,7 +52,7 @@ import {
   TxHash,
 } from '@aztec/stdlib/tx';
 
-import type { OriginBlock } from '../../storage/fact_store/index.js';
+import type { OriginBlock, RetractableFactOrigin } from '../../storage/fact_store/index.js';
 import { BoundedVec } from '../noir-structs/bounded_vec.js';
 import type { ContractClassLogData } from '../noir-structs/contract_class_log_data.js';
 import type { EmbeddedCurvePoint } from '../noir-structs/embedded_curve_point.js';
@@ -67,6 +65,7 @@ import type { LogRetrievalResponse } from '../noir-structs/log_retrieval_respons
 import type { NoteData } from '../noir-structs/note_data.js';
 import { NoteValidationRequest } from '../noir-structs/note_validation_request.js';
 import { Option } from '../noir-structs/option.js';
+import type { PendingTaggedLog } from '../noir-structs/pending_tagged_log.js';
 import type { ProvidedSecret } from '../noir-structs/provided_secret.js';
 import {
   type ResolvedTaggingStrategy,
@@ -86,9 +85,8 @@ export type {
   AppTaggingSecretKind,
   BlockHash,
   BlockHeader,
-  ContractInstance,
+  ContractInstancePreimage,
   MembershipWitness,
-  MessageContext,
   NullifierMembershipWitness,
   PendingTaggedLog,
   PublicDataWitness,
@@ -294,7 +292,7 @@ export const ETH_ADDRESS: TypeMapping<EthAddress> = {
   shape: ['scalar'],
 };
 
-const SLOT_NUMBER: TypeMapping<SlotNumber> = {
+export const SLOT_NUMBER: TypeMapping<SlotNumber> = {
   serialization: { fn: v => [new Fr(v)] },
   shape: ['scalar'],
 };
@@ -354,7 +352,7 @@ const PUBLIC_KEYS: TypeMapping<PublicKeys> = STRUCT<PublicKeys>([
   { name: 'fbpkMHash', type: FIELD },
 ]);
 
-export const CONTRACT_INSTANCE: TypeMapping<ContractInstance> = STRUCT<ContractInstance>([
+export const CONTRACT_INSTANCE: TypeMapping<ContractInstancePreimage> = STRUCT<ContractInstancePreimage>([
   { name: 'salt', type: FIELD },
   { name: 'deployer', type: AZTEC_ADDRESS },
   // Note that the nr side of this struct does not contain the current class, only original
@@ -518,17 +516,9 @@ export const LOG_RETRIEVAL_RESPONSE: TypeMapping<LogRetrievalResponse> = STRUCT<
   { name: 'txHash', type: TX_HASH },
   { name: 'uniqueNoteHashesInTx', type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX) },
   { name: 'firstNullifierInTx', type: FIELD },
-]);
-
-export const MESSAGE_CONTEXT: TypeMapping<MessageContext> = STRUCT<MessageContext>([
-  { name: 'txHash', type: TX_HASH },
-  { name: 'uniqueNoteHashesInTx', type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX) },
-  { name: 'firstNullifierInTx', type: FIELD },
-]);
-
-export const PENDING_TAGGED_LOG: TypeMapping<PendingTaggedLog> = STRUCT<PendingTaggedLog>([
-  { name: 'log', type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS) },
-  { name: 'context', type: MESSAGE_CONTEXT },
+  { name: 'blockNumber', type: BLOCK_NUMBER },
+  { name: 'blockTimestamp', type: BIGINT },
+  { name: 'blockHash', type: BLOCK_HASH },
 ]);
 
 // `ResolvedTx.toFields()` packs the whole struct into a single slot: txHash, the uniqueNoteHashesInTx BoundedVec
@@ -538,6 +528,11 @@ export const RESOLVED_TX: TypeMapping<ResolvedTx> = {
   shape: [{ len: MAX_NOTE_HASHES_PER_TX + 5 }],
 };
 
+export const PENDING_TAGGED_LOG: TypeMapping<PendingTaggedLog> = STRUCT([
+  { name: 'log', type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS) },
+  { name: 'context', type: RESOLVED_TX },
+]);
+
 export const ORIGIN_BLOCK: TypeMapping<OriginBlock> = {
   serialization: { fn: ob => [new Fr(ob.blockNumber), ob.blockHash] },
   deserialization: {
@@ -549,17 +544,23 @@ export const ORIGIN_BLOCK: TypeMapping<OriginBlock> = {
   shape: ['scalar', 'scalar'],
 };
 
+/** Read-side origin of a retractable fact, carrying the chain state of its origin block. */
+export const RETRACTABLE_FACT_ORIGIN: TypeMapping<RetractableFactOrigin> = {
+  serialization: { fn: o => [new Fr(o.blockNumber), o.blockHash, new Fr(o.blockState)] },
+  shape: ['scalar', 'scalar', 'scalar'],
+};
+
 // `facts` and `payload` each materialize to a single service-slot id, so a Fact occupies: factTypeId, the payload
-// array slot, and `OPTION(ORIGIN_BLOCK)` (its discriminant plus ORIGIN_BLOCK's two slots).
+// array slot, and `OPTION(RETRACTABLE_FACT_ORIGIN)` (its discriminant plus RETRACTABLE_FACT_ORIGIN's three slots).
 export const FACT: TypeMapping<Fact> = {
   serialization: {
     fn: f => [
       f.factTypeId,
       f.payload.materializeSlot(v => FIELD.serialization!.fn(v).flat() as Fr[]),
-      ...OPTION(ORIGIN_BLOCK).serialization!.fn(f.originBlock),
+      ...OPTION(RETRACTABLE_FACT_ORIGIN).serialization!.fn(f.originBlock),
     ],
   },
-  shape: ['scalar', 'scalar', 'scalar', 'scalar', 'scalar'],
+  shape: ['scalar', 'scalar', 'scalar', 'scalar', 'scalar', 'scalar'],
 };
 
 export const FACT_COLLECTION: TypeMapping<FactCollection> = {
@@ -618,20 +619,26 @@ export function ARRAY<T>(inner: TypeMapping<T>): TypeMapping<T[]> & { kind: 'arr
 }
 
 /**
- * Noir's fixed-length array `[T; maxLength]` in one slot: serializes `values` (each flattened via `element`)
- * zero-padded to exactly `maxLength * elementWidth` fields, and deserializes all `maxLength` elements back. An absent
+ * Noir's fixed-length array `[T; length]` in one slot: serializes `values` (each flattened via `element`)
+ * zero-padded to exactly `length * elementWidth` fields, and deserializes all `length` elements back. An absent
  * element is the zero encoding, so the padding is derived from the shape.
  */
-function FIXED_ARRAY<T>(element: TypeMapping<T>, maxLength: number): TypeMapping<T[]> {
+export function FIXED_ARRAY<T>(
+  element: TypeMapping<T>,
+  length: number,
+): TypeMapping<T[]> & { kind: 'fixed-array'; inner: TypeMapping<T>; length: number } {
   const elementWidth = fieldWidth(element.shape);
   return {
+    kind: 'fixed-array',
+    inner: element,
+    length,
     serialization: element.serialization
-      ? { fn: values => [padArrayEnd(packElements(element, values), Fr.ZERO, maxLength * elementWidth)] }
+      ? { fn: values => [padArrayEnd(packElements(element, values), Fr.ZERO, length * elementWidth)] }
       : undefined,
     deserialization: element.deserialization
-      ? { fn: ([reader]) => unpackElements(element, reader, maxLength) }
+      ? { fn: ([reader]) => unpackElements(element, reader, length) }
       : undefined,
-    shape: [{ len: maxLength * elementWidth }],
+    shape: [{ len: length * elementWidth }],
   };
 }
 
@@ -691,9 +698,15 @@ export function BOUNDED_VEC<T>(
  * (zero-padded) followed by the actual length, with no length prefix, so the width is statically known. Serialize-only.
  * Throws if the input exceeds `maxLength`.
  */
-function FIXED_BOUNDED_VEC<T>(element: TypeMapping<T>, maxLength: number): TypeMapping<T[]> {
+export function FIXED_BOUNDED_VEC<T>(
+  element: TypeMapping<T>,
+  maxLength: number,
+): TypeMapping<T[]> & { kind: 'fixed-bounded-vec'; inner: TypeMapping<T>; maxLength: number } {
   const width = fieldWidth(element.shape);
   return {
+    kind: 'fixed-bounded-vec',
+    inner: element,
+    maxLength,
     serialization: element.serialization
       ? {
           fn: values => {
@@ -804,15 +817,19 @@ export function EPHEMERAL_ARRAY<T>(element: TypeMapping<T>): TypeMapping<Ephemer
 }
 
 /** A named field within a {@link STRUCT}: it owns however many wire slots its {@link TypeMapping} declares. */
-type StructField<TName extends string = string, T = any> = { name: TName; type: TypeMapping<T> };
+export type StructField<TName extends string = string, T = any> = { name: TName; type: TypeMapping<T> };
 
 /**
  * A Noir struct: its `shape` and (de)serialization are the concatenation of its fields', so callers never hand-write a
  * `shape`. `T` is the struct's TS value type and must match the field layout — serialization reads each field by name
  * off the value, deserialization returns the decoded bag as `T`; convert in the handler, not here, when `T` differs.
  */
-function STRUCT<T>(fields: readonly StructField[]): TypeMapping<T> {
+export function STRUCT<T>(
+  fields: readonly StructField[],
+): TypeMapping<T> & { kind: 'struct'; fields: readonly StructField[] } {
   return {
+    kind: 'struct',
+    fields,
     serialization: fields.every(f => f.type.serialization)
       ? {
           fn: (value: T) => {
@@ -845,7 +862,7 @@ export function slotsOf(mapping: TypeMapping): number {
 }
 
 /** Number of fields a fully-static shape occupies, or `undefined` if any slot is variable-width. */
-function tryFieldWidth(shape: SlotShape[]): number | undefined {
+export function tryFieldWidth(shape: SlotShape[]): number | undefined {
   let total = 0;
   for (const slot of shape) {
     if (slot === 'scalar') {