@aztec/pxe 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5a9928

package/src/contract_function_simulator/oracle/interfaces.ts

@@ -1,185 +1,20 @@
-import type { ARCHIVE_HEIGHT, L1_TO_L2_MSG_TREE_HEIGHT, NOTE_HASH_TREE_HEIGHT } from '@aztec/constants';
-import type { BlockNumber } from '@aztec/foundation/branded-types';
-import { Fr } from '@aztec/foundation/curves/bn254';
-import { Point } from '@aztec/foundation/curves/grumpkin';
-import { MembershipWitness } from '@aztec/foundation/trees';
-import type { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { BlockHash } from '@aztec/stdlib/block';
-import type { CompleteAddress, ContractInstance } from '@aztec/stdlib/contract';
-import type { KeyValidationRequest } from '@aztec/stdlib/kernel';
-import type { ContractClassLog, Tag } from '@aztec/stdlib/logs';
-import type { Note, NoteStatus } from '@aztec/stdlib/note';
-import { type NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
-import type { BlockHeader } from '@aztec/stdlib/tx';
-
-import type { UtilityContext } from '../noir-structs/utility_context.js';
-import type { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
-
-/**
- * Information about a note needed during execution.
- */
-export interface NoteData {
-  /** The actual note content (the fields of the Noir #[note] struct). */
-  note: Note;
-  /** The address of the contract that owns the note. */
-  contractAddress: AztecAddress;
-  /** The owner of the note. */
-  owner: AztecAddress;
-  /** The storage slot of the note. */
-  storageSlot: Fr;
-  /** The randomness injected to the note */
-  randomness: Fr;
-  /** The nonce injected into the note hash preimage by kernels. */
-  noteNonce: Fr;
-  /** A hash of the note as it gets stored in the note hash tree. */
-  noteHash: Fr;
-  /** True if the note is pending, false if settled. */
-  isPending: boolean;
-  /** The corresponding nullifier of the note. Undefined for pending notes. */
-  siloedNullifier?: Fr;
-}
-
-// These interfaces contain the list of oracles required by aztec-nr in order to simulate and execute transactions, i.e.
-// in order to call #[external("utility")] and #[external("private")] contract functions.
-// The full list of aztec-nr oracles is larger and includes the oracles also required to run Noir tests - these reside
-// in the TXE package.
+import type { HandlersForPrefix, ORACLE_REGISTRY } from './oracle_registry.js';
 
 /**
- * Miscellaneous oracle methods, not very Aztec-specific and expected to be available all scenarios in which aztec-nr
- * code runs, except #[external("public")] functions (since those are transpiled to AVM bytecode, where there are no oracles).
+ * Miscellaneous oracle methods, not very Aztec-specific and expected to be available in all scenarios in which aztec-nr
+ * code runs, except #[external("public")] functions (since those are transpiled to AVM bytecode, where there are no
+ * oracles).
  */
-export interface IMiscOracle {
-  isMisc: true;
-
-  utilityGetRandomField(): Fr;
-  utilityAssertCompatibleOracleVersion(version: number): void;
-  utilityDebugLog(level: number, message: string, fields: Fr[]): Promise<void>;
-}
+export type IMiscOracle = HandlersForPrefix<typeof ORACLE_REGISTRY, 'misc'> & { isMisc: true };
 
 /**
- * Oracle methods associated with the execution of an Aztec #[external("utility")] function. Note that the IMiscOracles are also
- * expected to be available in these contexts.
+ * Oracle methods associated with the execution of an Aztec #[external("utility")] function. Note that the IMiscOracle
+ * methods are also expected to be available in these contexts.
  */
-export interface IUtilityExecutionOracle {
-  isUtility: true;
-
-  utilityGetUtilityContext(): UtilityContext;
-  utilityGetKeyValidationRequest(pkMHash: Fr): Promise<KeyValidationRequest>;
-  utilityGetContractInstance(address: AztecAddress): Promise<ContractInstance>;
-  utilityGetNoteHashMembershipWitness(
-    anchorBlockHash: BlockHash,
-    noteHash: Fr,
-  ): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT> | undefined>;
-  utilityGetBlockHashMembershipWitness(
-    anchorBlockHash: BlockHash,
-    blockHash: BlockHash,
-  ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined>;
-  utilityGetNullifierMembershipWitness(
-    anchorBlockHash: BlockHash,
-    nullifier: Fr,
-  ): Promise<NullifierMembershipWitness | undefined>;
-  utilityGetPublicDataWitness(anchorBlockHash: BlockHash, leafSlot: Fr): Promise<PublicDataWitness | undefined>;
-  utilityGetLowNullifierMembershipWitness(
-    anchorBlockHash: BlockHash,
-    nullifier: Fr,
-  ): Promise<NullifierMembershipWitness | undefined>;
-  utilityGetBlockHeader(blockNumber: BlockNumber): Promise<BlockHeader | undefined>;
-  utilityTryGetPublicKeysAndPartialAddress(account: AztecAddress): Promise<CompleteAddress | undefined>;
-  utilityGetAuthWitness(messageHash: Fr): Promise<Fr[] | undefined>;
-  utilityGetNotes(
-    owner: AztecAddress | undefined,
-    storageSlot: Fr,
-    numSelects: number,
-    selectByIndexes: number[],
-    selectByOffsets: number[],
-    selectByLengths: number[],
-    selectValues: Fr[],
-    selectComparators: number[],
-    sortByIndexes: number[],
-    sortByOffsets: number[],
-    sortByLengths: number[],
-    sortOrder: number[],
-    limit: number,
-    offset: number,
-    status: NoteStatus,
-  ): Promise<NoteData[]>;
-  utilityCheckNullifierExists(innerNullifier: Fr): Promise<boolean>;
-  utilityGetL1ToL2MembershipWitness(
-    contractAddress: AztecAddress,
-    messageHash: Fr,
-    secret: Fr,
-  ): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>>;
-  utilityStorageRead(
-    anchorBlockHash: BlockHash,
-    contractAddress: AztecAddress,
-    startStorageSlot: Fr,
-    numberOfElements: number,
-  ): Promise<Fr[]>;
-  utilityFetchTaggedLogs(pendingTaggedLogArrayBaseSlot: Fr): Promise<void>;
-  utilityValidateAndStoreEnqueuedNotesAndEvents(
-    contractAddress: AztecAddress,
-    noteValidationRequestsArrayBaseSlot: Fr,
-    eventValidationRequestsArrayBaseSlot: Fr,
-  ): Promise<void>;
-  utilityBulkRetrieveLogs(
-    contractAddress: AztecAddress,
-    logRetrievalRequestsArrayBaseSlot: Fr,
-    logRetrievalResponsesArrayBaseSlot: Fr,
-  ): Promise<void>;
-  utilityStoreCapsule(contractAddress: AztecAddress, key: Fr, capsule: Fr[]): Promise<void>;
-  utilityLoadCapsule(contractAddress: AztecAddress, key: Fr): Promise<Fr[] | null>;
-  utilityDeleteCapsule(contractAddress: AztecAddress, key: Fr): Promise<void>;
-  utilityCopyCapsule(contractAddress: AztecAddress, srcKey: Fr, dstKey: Fr, numEntries: number): Promise<void>;
-  utilityAes128Decrypt(ciphertext: Buffer, iv: Buffer, symKey: Buffer): Promise<Buffer>;
-  utilityGetSharedSecret(address: AztecAddress, ephPk: Point): Promise<Point>;
-}
+export type IUtilityExecutionOracle = HandlersForPrefix<typeof ORACLE_REGISTRY, 'utl'> & { isUtility: true };
 
 /**
- * Oracle methods associated with the execution of an Aztec #[external("private")] function. Note that both the IMiscOracles and
- * IUtilityExecutionOracle are also expected to be available in these contexts.
+ * Oracle methods associated with the execution of an Aztec #[external("private")] function. Note that both the
+ * IMiscOracle and IUtilityExecutionOracle methods are also expected to be available in these contexts.
  */
-export interface IPrivateExecutionOracle {
-  isPrivate: true;
-
-  privateStoreInExecutionCache(values: Fr[], hash: Fr): void;
-  privateLoadFromExecutionCache(hash: Fr): Promise<Fr[]>;
-  privateNotifyCreatedNote(
-    owner: AztecAddress,
-    storageSlot: Fr,
-    randomness: Fr,
-    noteTypeId: NoteSelector,
-    note: Fr[],
-    noteHash: Fr,
-    counter: number,
-  ): void;
-  privateNotifyNullifiedNote(innerNullifier: Fr, noteHash: Fr, counter: number): Promise<void>;
-  privateNotifyCreatedNullifier(innerNullifier: Fr): Promise<void>;
-  privateIsNullifierPending(innerNullifier: Fr, contractAddress: AztecAddress): Promise<boolean>;
-  privateNotifyCreatedContractClassLog(log: ContractClassLog, counter: number): void;
-  privateCallPrivateFunction(
-    targetContractAddress: AztecAddress,
-    functionSelector: FunctionSelector,
-    argsHash: Fr,
-    sideEffectCounter: number,
-    isStaticCall: boolean,
-  ): Promise<{ endSideEffectCounter: Fr; returnsHash: Fr }>;
-  privateNotifyEnqueuedPublicFunctionCall(
-    targetContractAddress: AztecAddress,
-    calldataHash: Fr,
-    sideEffectCounter: number,
-    isStaticCall: boolean,
-  ): Promise<void>;
-  privateNotifySetPublicTeardownFunctionCall(
-    targetContractAddress: AztecAddress,
-    calldataHash: Fr,
-    sideEffectCounter: number,
-    isStaticCall: boolean,
-  ): Promise<void>;
-  privateNotifySetMinRevertibleSideEffectCounter(minRevertibleSideEffectCounter: number): Promise<void>;
-  privateIsSideEffectCounterRevertible(sideEffectCounter: number): Promise<boolean>;
-  privateGetSenderForTags(): Promise<AztecAddress | undefined>;
-  privateSetSenderForTags(senderForTags: AztecAddress): Promise<void>;
-  privateGetNextAppTagAsSender(sender: AztecAddress, recipient: AztecAddress): Promise<Tag>;
-  utilityEmitOffchainEffect(data: Fr[]): Promise<void>;
-}
+export type IPrivateExecutionOracle = HandlersForPrefix<typeof ORACLE_REGISTRY, 'prv'> & { isPrivate: true };

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

package/src/contract_function_simulator/oracle/note_packing_utils.ts

@@ -48,7 +48,7 @@ export function packAsHintedNote({
   noteNonce: Fr;
   isPending: boolean;
   note: Note;
-}) {
+}): Fr[] {
   // If the note is pending it means it has a non-zero note hash counter associated with it.
   const nonZeroNoteHashCounter = isPending;
 
@@ -58,8 +58,8 @@ export function packAsHintedNote({
   // Pack in order: note, contract_address, owner, randomness, storage_slot, metadata (stage, maybe_note_nonce)
   return [
     ...note.items,
-    contractAddress,
-    owner,
+    contractAddress.toField(),
+    owner.toField(),
     randomness,
     storageSlot,
     new Fr(noteMetadata.stage),