@aztec/pxe 0.0.1-commit.b9865e97 → 0.0.1-commit.be03c316

package/src/contract_function_simulator/oracle/acir_callback.ts

@@ -0,0 +1,154 @@
+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 { 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) {
+    super(`${oracleName} oracles not available with the current handler`);
+  }
+}
+
+/**
+ * Builds an ACIR callback from the oracle registry and a handler object.
+ *
+ * Each oracle call is dispatched by matching the oracle name against the registry for serialization, parsing the
+ * `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,
+  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(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: NamedValue) => p.value);
+      const result = await (handler as any)[methodName](...positional);
+      return entry.serializeReturn(result);
+    };
+  }
+
+  // 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) {
+      // 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];
+      }
+
+      return () => {
+        let contractVersion = undefined;
+        if ('nonOracleFunctionGetContractOracleVersion' in handler) {
+          contractVersion = (
+            handler as unknown as NonOracleFunctionGetContractOracleVersion
+          ).nonOracleFunctionGetContractOracleVersion();
+        }
+        if (!contractVersion) {
+          throw new Error(
+            `Oracle '${prop}' not found and the contract's oracle version is unknown (the version check oracle ` +
+              `was not called before '${prop}'). This usually means the contract was not compiled with the ` +
+              `#[aztec] macro, which injects the version check as the first oracle call in every private/utility ` +
+              `external function. If you're using a custom entry point, ensure assert_compatible_oracle_version() ` +
+              `is called before any other oracle calls. See https://docs.aztec.network/errors/8`,
+          );
+        } else if (contractVersion.minor > ORACLE_VERSION_MINOR) {
+          throw new Error(
+            `Oracle '${prop}' not found.` +
+              ` This usually means the contract requires a newer private execution environment than you have.` +
+              ` Upgrade your private execution environment to a compatible version. The contract was compiled with` +
+              ` Aztec.nr oracle version ${contractVersion.major}.${contractVersion.minor}, but this private` +
+              ` execution environment only supports up to ${ORACLE_VERSION_MAJOR}.${ORACLE_VERSION_MINOR}.` +
+              ` See https://docs.aztec.network/errors/8`,
+          );
+        } else {
+          throw new Error(
+            `Oracle '${prop}' not found.` +
+              ` The contract's oracle version (${contractVersion.major}.${contractVersion.minor}) is compatible` +
+              ` with this private execution environment (${ORACLE_VERSION_MAJOR}.${ORACLE_VERSION_MINOR}), so all` +
+              ` standard oracles should be available. This could mean the contract was compiled against a modified` +
+              ` version of Aztec.nr, or that it references an oracle that does not exist.` +
+              ` See https://docs.aztec.network/errors/8`,
+          );
+        }
+      };
+    },
+  };
+}
+
+type OracleHandler = IMiscOracle & (IUtilityExecutionOracle | IPrivateExecutionOracle);
+
+type NonOracleFunctionGetContractOracleVersion = {
+  nonOracleFunctionGetContractOracleVersion(): { major: number; minor: number } | undefined;
+};
+
+function assertHandlerSupportsScope(handler: OracleHandler, scope: string): void {
+  switch (scope) {
+    case 'misc':
+      if (!('isMisc' in handler)) {
+        throw new UnavailableOracleError('Misc');
+      }
+      break;
+    case 'utl':
+      if (!('isUtility' in handler)) {
+        throw new UnavailableOracleError('Utility');
+      }
+      break;
+    case 'prv':
+      if (!('isPrivate' in handler)) {
+        throw new UnavailableOracleError('Private');
+      }
+      break;
+    default:
+      throw new Error(`Unknown oracle scope: ${scope}`);
+  }
+}

package/src/contract_function_simulator/oracle/index.ts

@@ -1,16 +1,2 @@
-import type { Oracle } from './oracle.js';
-
-export * from './oracle.js';
+export * from './acir_callback.js';
 export * from './interfaces.js';
-
-/**
- * A conditional type that takes a type `T` and returns a union of its method names.
- */
-type MethodNames<T> = {
-  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
-}[keyof T];
-
-/**
- * Available oracle function names.
- */
-export type ORACLE_NAMES = MethodNames<Oracle>;

package/src/contract_function_simulator/oracle/interfaces.ts

@@ -1,5 +1,4 @@
-import type { HandlersForPrefix } from './oracle_registry.js';
-import type { ORACLE_REGISTRY } from './oracle_registry.js';
+import type { HandlersForPrefix, ORACLE_REGISTRY } from './oracle_registry.js';
 
 /**
  * Miscellaneous oracle methods, not very Aztec-specific and expected to be available in all scenarios in which aztec-nr

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/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>;
+};