feat(pxe): origin block number timestamp log oracle in log retrieval (#24398)

Author: vezenovm

noir-projects/aztec-nr/aztec/src/messages/delivery/handshake.nr

@@ -81,8 +81,8 @@ pub(crate) unconstrained fn get_existing_app_siloed_handshake_secrets(
 /// Establishes a non-interactive handshake for `(sender, recipient)` and returns its app-siloed secrets.
 ///
 /// The registry inserts a fresh handshake note and returns the app-siloed secrets. The constrained return value is the
-/// source of truth for the secrets, so constrained delivery anchoring a freshly bootstrapped handshake needs no separate
-/// `validate_handshake`.
+/// source of truth for the secrets, so constrained delivery anchoring a freshly bootstrapped handshake needs no
+/// separate `validate_handshake`.
 ///
 /// Any handshake already registered for the pair is overwritten.
 pub(crate) fn create_non_interactive_handshake(

noir-projects/aztec-nr/aztec/src/oracle/message_processing.nr

@@ -54,6 +54,8 @@ pub unconstrained fn get_logs_by_tag(
     get_logs_by_tag_oracle(requests)
 }
 
+// TODO: PXE also exposes `getLogsByTagV2`, whose response additionally carries the origin block number and timestamp
+// of each log. Switch this oracle (and `LogRetrievalResponse`) over to it once a consumer needs that context.
 #[oracle(aztec_utl_getLogsByTag)]
 unconstrained fn get_logs_by_tag_oracle(
     requests: EphemeralArray<LogRetrievalRequest>,

noir-projects/aztec-nr/aztec/src/oracle/version.nr

@@ -11,7 +11,7 @@
 /// immediately if AZTEC_NR_MINOR > PXE_MINOR because if a contract is updated to use a newer Aztec.nr dependency
 /// without actually using any of the new oracles then there is no reason to throw.
 pub global ORACLE_VERSION_MAJOR: Field = 30;
-pub global ORACLE_VERSION_MINOR: Field = 2;
+pub global ORACLE_VERSION_MINOR: Field = 3;
 
 /// Asserts that the version of the oracle is compatible with the version expected by the contract.
 pub fn assert_compatible_oracle_version() {

noir-projects/noir-protocol-circuits/crates/types/src/constants_tests.nr

@@ -15,14 +15,14 @@ use crate::{
         DOM_SEP__ECDH_SUBKEY, DOM_SEP__EVENT_COMMITMENT, DOM_SEP__EVENT_LOG_TAG, DOM_SEP__FBSK_M,
         DOM_SEP__FUNCTION_ARGS, DOM_SEP__INITIALIZATION_NULLIFIER, DOM_SEP__INITIALIZER,
         DOM_SEP__IVSK_M, DOM_SEP__MERKLE_HASH, DOM_SEP__MESSAGE_NULLIFIER, DOM_SEP__MSSK_M,
-        DOM_SEP__NHK_M,
-        DOM_SEP__NON_INTERACTIVE_HANDSHAKE_LOG_TAG, DOM_SEP__NOTE_COMPLETION_LOG_TAG,
-        DOM_SEP__NOTE_HASH, DOM_SEP__NOTE_HASH_NONCE, DOM_SEP__NOTE_NULLIFIER,
-        DOM_SEP__NULLIFIER_MERKLE, DOM_SEP__OVSK_M, DOM_SEP__PARTIAL_ADDRESS,
-        DOM_SEP__PARTIAL_NOTE_COMMITMENT, DOM_SEP__PARTIAL_NOTE_VALIDITY_COMMITMENT,
-        DOM_SEP__PRIVATE_FUNCTION_LEAF, DOM_SEP__PRIVATE_INITIALIZATION_NULLIFIER,
-        DOM_SEP__PRIVATE_LOG_FIRST_FIELD, DOM_SEP__PRIVATE_TX_HASH, DOM_SEP__PROTOCOL_CONTRACTS,
-        DOM_SEP__PUBLIC_BYTECODE, DOM_SEP__PUBLIC_CALLDATA, DOM_SEP__PUBLIC_DATA_MERKLE,
+        DOM_SEP__NHK_M, DOM_SEP__NON_INTERACTIVE_HANDSHAKE_LOG_TAG,
+        DOM_SEP__NOTE_COMPLETION_LOG_TAG, DOM_SEP__NOTE_HASH, DOM_SEP__NOTE_HASH_NONCE,
+        DOM_SEP__NOTE_NULLIFIER, DOM_SEP__NULLIFIER_MERKLE, DOM_SEP__OVSK_M,
+        DOM_SEP__PARTIAL_ADDRESS, DOM_SEP__PARTIAL_NOTE_COMMITMENT,
+        DOM_SEP__PARTIAL_NOTE_VALIDITY_COMMITMENT, DOM_SEP__PRIVATE_FUNCTION_LEAF,
+        DOM_SEP__PRIVATE_INITIALIZATION_NULLIFIER, DOM_SEP__PRIVATE_LOG_FIRST_FIELD,
+        DOM_SEP__PRIVATE_TX_HASH, DOM_SEP__PROTOCOL_CONTRACTS, DOM_SEP__PUBLIC_BYTECODE,
+        DOM_SEP__PUBLIC_CALLDATA, DOM_SEP__PUBLIC_DATA_MERKLE,
         DOM_SEP__PUBLIC_INITIALIZATION_NULLIFIER, DOM_SEP__PUBLIC_KEYS_HASH,
         DOM_SEP__PUBLIC_LEAF_SLOT, DOM_SEP__PUBLIC_STORAGE_MAP_SLOT, DOM_SEP__PUBLIC_TX_HASH,
         DOM_SEP__RETRIEVED_BYTECODES_MERKLE, DOM_SEP__SALTED_INITIALIZATION_HASH,

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

@@ -53,6 +53,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';

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

@@ -1,5 +1,7 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
 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 +12,6 @@ export type LogRetrievalResponse = {
   txHash: TxHash;
   uniqueNoteHashesInTx: Fr[];
   firstNullifierInTx: Fr;
+  blockNumber: BlockNumber;
+  blockTimestamp: UInt64;
 };

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

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

@@ -0,0 +1,75 @@
+/* eslint-disable camelcase */
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { toACVMField } from '@aztec/simulator/client';
+
+import { buildACIRCallback } from './acir_callback.js';
+import type { LegacyOracleEntry } from './legacy_oracle_registry.js';
+import { FIELD, U32 } from './oracle_registry.js';
+
+type Handler = Parameters<typeof buildACIRCallback>[0];
+
+describe('legacy oracle dispatch', () => {
+  it('adapts the return wire: handler runs, result is mapped, then serialized through the legacy type', async () => {
+    // Fixture scenario: the return override maps the handler's current result to the legacy value the old bytecode
+    // expects, then serializes it through the legacy type.
+    const handler = { isMisc: true, getRandomField: () => Promise.resolve(new Fr(41)) } as Handler;
+
+    const legacyRegistry: Record<string, LegacyOracleEntry> = {
+      aztec_misc_legacyReturn: {
+        modernOracle: 'aztec_misc_getRandomField',
+        returnType: { legacyType: FIELD, mapping: (result: Fr) => new Fr(result.toBigInt() + 1n) },
+      },
+    };
+
+    const callback = buildACIRCallback(handler, { legacy: legacyRegistry });
+
+    // Handler produces 41; the override maps it to the legacy value (41 + 1) the old bytecode expects.
+    const wire = await callback['aztec_misc_legacyReturn']();
+
+    expect(wire).toEqual([toACVMField(new Fr(42))]);
+  });
+
+  it('adapts the param wire: legacy args are deserialized, mapped, then passed to the modern handler', async () => {
+    // Fixture scenario: the retired wire carried a single `major` field, but the current handler signature is
+    // (major, minor). The param override deserializes that one-field wire and reshapes it into the modern arg tuple,
+    // defaulting the `minor` the old bytecode never sent.
+    const DEFAULTED_MINOR = 0;
+
+    let handlerArgs: unknown[] | undefined;
+    const handler = {
+      isMisc: true,
+      assertCompatibleOracleVersion: (...args: unknown[]) => {
+        handlerArgs = args;
+      },
+    } as Handler;
+
+    const legacyRegistry: Record<string, LegacyOracleEntry> = {
+      aztec_misc_legacyParams: {
+        modernOracle: 'aztec_misc_assertCompatibleOracleVersion',
+        params: {
+          legacyType: [{ name: 'major', type: U32 }],
+          mapping: ([major]: number[]) => [major, DEFAULTED_MINOR],
+        },
+      },
+    };
+
+    const callback = buildACIRCallback(handler, { legacy: legacyRegistry });
+
+    // Old bytecode sends one field (major = 5); the handler must still receive the full (major, minor) tuple.
+    await callback['aztec_misc_legacyParams']([toACVMField(new Fr(5))]);
+
+    expect(handlerArgs).toEqual([5, DEFAULTED_MINOR]);
+  });
+
+  it('rejects a legacy name that collides with a live oracle', () => {
+    const handler = { isMisc: true, getRandomField: () => Promise.resolve(new Fr(0)) } as Handler;
+    const legacyRegistry: Record<string, LegacyOracleEntry> = {
+      aztec_misc_getRandomField: {
+        modernOracle: 'aztec_misc_getRandomField',
+        returnType: { legacyType: FIELD, mapping: (result: Fr) => result },
+      },
+    };
+
+    expect(() => buildACIRCallback(handler, { legacy: legacyRegistry })).toThrow('collides with a live oracle');
+  });
+});

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

@@ -0,0 +1,90 @@
+/* eslint-disable camelcase */
+import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_CIPHERTEXT_LEN } from '@aztec/constants';
+
+import type { EphemeralArray } from '../noir-structs/ephemeral_array.js';
+import type { LogRetrievalResponse } from '../noir-structs/log_retrieval_response.js';
+import {
+  type InferDeserializedParams,
+  ORACLE_REGISTRY,
+  type OracleRegistryEntry,
+  type ParamTypes,
+  type RegistryParam,
+} from './oracle_registry.js';
+import {
+  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 },
+]);
+
+/**
+ * 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_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>>,
+    },
+  }),
+};
+
+type LegacyLogRetrievalResponse = Pick<
+  LogRetrievalResponse,
+  'logPayload' | 'txHash' | 'uniqueNoteHashesInTx' | 'firstNullifierInTx'
+>;
+
+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. Omit when the param wire is unchanged.
+   */
+  params?: { legacyType: readonly RegistryParam[]; mapping: (legacyArgs: any) => 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>;
+  };
+  returnType?: { legacyType: TypeMapping<W>; mapping: (result: ReturnValueOf<K>) => W };
+}): LegacyOracleEntry {
+  return entry;
+}

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

@@ -241,7 +241,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)),
   }),
@@ -643,7 +643,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>;
 }
@@ -669,7 +669,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;
 };