@aztec/pxe 0.0.1-commit.24de95ac → 0.0.1-commit.2606882

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

@@ -1,16 +1,13 @@
 import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_CIPHERTEXT_LEN } from '@aztec/constants';
 import { range } from '@aztec/foundation/array';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { TxHash } from '@aztec/stdlib/tx';
 
-import { MAX_NOTE_PACKED_LEN } from './note_validation_request.js';
-
-const MAX_PUBLIC_LOG_LEN_FOR_NOTE_COMPLETION = MAX_NOTE_PACKED_LEN;
-const MAX_LOG_CONTENT_LEN = Math.max(MAX_PUBLIC_LOG_LEN_FOR_NOTE_COMPLETION, PRIVATE_LOG_CIPHERTEXT_LEN);
+const MAX_LOG_CONTENT_LEN = PRIVATE_LOG_CIPHERTEXT_LEN;
 
 /**
  * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle stores values of this
- * type in a `CapsuleArray`.
+ * type in a `EphemeralArray`.
  */
 export class LogRetrievalResponse {
   constructor(
@@ -42,7 +39,7 @@ export class LogRetrievalResponse {
     return range(serializationLen).map(_ => Fr.zero());
   }
 
-  static toSerializedOption(response?: LogRetrievalResponse): Fr[] {
+  static toSerializedOption(response: LogRetrievalResponse | null): Fr[] {
     if (response) {
       return [new Fr(1), ...response.toFields()];
     } else {

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

@@ -0,0 +1,27 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { Note } from '@aztec/stdlib/note';
+
+/**
+ * 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;
+}

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

@@ -1,52 +1,59 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { FieldReader } from '@aztec/foundation/serialize';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { TxHash } from '@aztec/stdlib/tx';
 
-// TODO(#14617): should we compute this from constants? This value is aztec-nr specific.
-export const MAX_NOTE_PACKED_LEN = 12;
-
 /**
- * Intermediate struct used to perform batch note validation by PXE. The `utilityValidateEnqueuedNotesAndEvents` oracle
- * expects for values of this type to be stored in a `CapsuleArray`.
+ * Intermediate struct used to perform batch note validation by PXE. The `utilityValidateAndStoreEnqueuedNotesAndEvents` oracle
+ * expects for values of this type to be stored in a `EphemeralArray`.
  */
 export class NoteValidationRequest {
   constructor(
     public contractAddress: AztecAddress,
+    public owner: AztecAddress,
     public storageSlot: Fr,
+    public randomness: Fr,
     public noteNonce: Fr,
     public content: Fr[],
     public noteHash: Fr,
     public nullifier: Fr,
     public txHash: TxHash,
-    public recipient: AztecAddress,
   ) {}
 
   static fromFields(fields: Fr[] | FieldReader): NoteValidationRequest {
     const reader = FieldReader.asReader(fields);
 
     const contractAddress = AztecAddress.fromField(reader.readField());
+    const owner = AztecAddress.fromField(reader.readField());
     const storageSlot = reader.readField();
+    const randomness = reader.readField();
     const noteNonce = reader.readField();
 
-    const contentStorage = reader.readFieldArray(MAX_NOTE_PACKED_LEN);
+    const maxNotePackedLen = reader.readField().toNumber();
+    const contentStorage = reader.readFieldArray(maxNotePackedLen);
     const contentLen = reader.readField().toNumber();
     const content = contentStorage.slice(0, contentLen);
 
     const noteHash = reader.readField();
     const nullifier = reader.readField();
     const txHash = TxHash.fromField(reader.readField());
-    const recipient = AztecAddress.fromField(reader.readField());
+
+    if (reader.remainingFields() !== 0) {
+      throw new Error(
+        `Error converting array of fields to NoteValidationRequest: expected ${reader.cursor} fields but received ${reader.cursor + reader.remainingFields()} (maxNotePackedLen=${maxNotePackedLen}).`,
+      );
+    }
 
     return new NoteValidationRequest(
       contractAddress,
+      owner,
       storageSlot,
+      randomness,
       noteNonce,
       content,
       noteHash,
       nullifier,
       txHash,
-      recipient,
     );
   }
 }

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

@@ -0,0 +1,69 @@
+/**
+ * TypeScript counterpart of Noir's `Option<T>`.
+ *
+ * Wraps a value that may or may not be present. Use {@link Option.some} to wrap a present value and
+ * {@link Option.none} for an absent one. The type guards {@link isSome} and {@link isNone} narrow
+ * `value` in conditional branches.
+ */
+export class Option<T> {
+  private constructor(
+    public readonly value: T | undefined,
+    public readonly template: T | undefined,
+  ) {}
+
+  /**
+   * Wrap a present value.
+   *
+   * @example
+   * ```ts
+   * return Option.some(values);
+   * ```
+   */
+  static some<T>(value: T): Option<T> {
+    return new Option<T>(value, undefined);
+  }
+
+  /**
+   * Construct an absent Option.
+   *
+   * When serialized back to ACVM, the `None` case must produce the same number of fields as `Some`.
+   * For types whose wire size varies per call site (`BoundedVec`, `FixedArray`), pass a `template` so the
+   * serializer knows how many zero fields to emit. Omit the template when the Option will not be
+   * re-serialized (e.g. deserialized input params).
+   *
+   * @param template - A representative empty `T` whose serialization determines the zero-filled wire format.
+   *
+   * @example None for a fixed-size type:
+   * ```ts
+   * return Option.none(AztecAddress.ZERO);
+   * ```
+   *
+   * @example None for a dynamic-size type:
+   * ```ts
+   * return Option.none(BoundedVec.empty<number>({ maxLength: ciphertext.maxLength }));
+   * ```
+   */
+  static none<T>(template?: T): Option<T> {
+    return new Option<T>(undefined, template);
+  }
+
+  /**
+   * Type guard: narrows `value` to `T` in the truthy branch.
+   *
+   * @example
+   * ```ts
+   * const opt = await handler.getSenderForTags();
+   * if (opt.isSome()) {
+   *   console.log(opt.value); // narrowed to T
+   * }
+   * ```
+   */
+  isSome(): this is Option<T> & { value: T } {
+    return this.value !== undefined;
+  }
+
+  /** Type guard: narrows `value` to `undefined` in the truthy branch. */
+  isNone(): this is Option<T> & { value: undefined } {
+    return this.value === undefined;
+  }
+}

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

@@ -0,0 +1,27 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { AppTaggingSecretKind } from '@aztec/stdlib/logs';
+
+/** A tagging secret an app supplies explicitly to `getPendingTaggedLogs` when PXE cannot derive it internally. */
+export class ProvidedSecret {
+  constructor(
+    public secret: Fr,
+    public mode: AppTaggingSecretKind,
+  ) {}
+
+  static fromFields(fields: Fr[] | FieldReader): ProvidedSecret {
+    const reader = FieldReader.asReader(fields);
+    return new ProvidedSecret(reader.readField(), kindFromField(reader.readField()));
+  }
+}
+
+function kindFromField(mode: Fr): AppTaggingSecretKind {
+  switch (mode.toBigInt()) {
+    case 0n:
+      return AppTaggingSecretKind.UNCONSTRAINED;
+    case 1n:
+      return AppTaggingSecretKind.CONSTRAINED;
+    default:
+      throw new Error(`Invalid app tagging secret kind: ${mode.toString()}`);
+  }
+}

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

@@ -1,42 +1,23 @@
-import { Fr } from '@aztec/foundation/fields';
-import type { FieldsOf } from '@aztec/foundation/types';
+import { toACVMField } from '@aztec/simulator/client';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import type { UInt64 } from '@aztec/stdlib/types';
+import type { BlockHeader } from '@aztec/stdlib/tx';
 
 /**
  * TypeScript counterpart of utility_context.nr. Used only as a return value for the utilityGetUtilityContext oracle.
  */
 export class UtilityContext {
-  private constructor(
-    public readonly blockNumber: number,
-    public readonly timestamp: UInt64,
+  constructor(
+    public readonly blockHeader: BlockHeader,
     public readonly contractAddress: AztecAddress,
-    public readonly version: Fr,
-    public readonly chainId: Fr,
   ) {}
 
-  static from(fields: FieldsOf<UtilityContext>) {
-    return new UtilityContext(
-      fields.blockNumber,
-      fields.timestamp,
-      fields.contractAddress,
-      fields.version,
-      fields.chainId,
-    );
-  }
-
   /**
    * Returns a representation of the utility context as expected by intrinsic Noir deserialization.
    * The order of the fields has to be the same as the order of the fields in the utility_context.nr.
    */
   public toNoirRepresentation(): (string | string[])[] {
     // TODO(#12874): remove the stupid as string conversion by modifying ForeignCallOutput type in acvm.js
-    return [
-      new Fr(this.blockNumber).toString() as string,
-      new Fr(this.timestamp).toString() as string,
-      this.contractAddress.toString() as string,
-      this.version.toString() as string,
-      this.chainId.toString() as string,
-    ];
+    const blockHeaderFields = this.blockHeader.toFields().map(toACVMField);
+    return [...blockHeaderFields, this.contractAddress.toString() as string];
   }
 }

package/src/contract_function_simulator/oracle/interfaces.ts

@@ -1,160 +1,21 @@
-import type { L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/constants';
-import { Fr, Point } from '@aztec/foundation/fields';
-import type { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import type { CompleteAddress, ContractInstance } from '@aztec/stdlib/contract';
-import type { KeyValidationRequest } from '@aztec/stdlib/kernel';
-import type { ContractClassLog } from '@aztec/stdlib/logs';
-import type { Note, NoteStatus } from '@aztec/stdlib/note';
-import { type MerkleTreeId, type NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
-import type { BlockHeader } from '@aztec/stdlib/tx';
-
-import type { Tag } from '../../tagging/tag.js';
-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 storage slot of the note. */
-  storageSlot: 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;
-  /** The corresponding nullifier of the note. Undefined for pending notes. */
-  siloedNullifier?: Fr;
-  /** The note's leaf index in the note hash tree. Undefined for pending notes. */
-  index?: bigint;
-}
-
-// 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 } from './oracle_registry.js';
+import type { 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[]): 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(): Promise<UtilityContext>;
-  utilityGetKeyValidationRequest(pkMHash: Fr): Promise<KeyValidationRequest>;
-  utilityGetContractInstance(address: AztecAddress): Promise<ContractInstance>;
-  utilityGetMembershipWitness(blockNumber: number, treeId: MerkleTreeId, leafValue: Fr): Promise<Fr[] | undefined>;
-  utilityGetNullifierMembershipWitness(
-    blockNumber: number,
-    nullifier: Fr,
-  ): Promise<NullifierMembershipWitness | undefined>;
-  utilityGetPublicDataWitness(blockNumber: number, leafSlot: Fr): Promise<PublicDataWitness | undefined>;
-  utilityGetLowNullifierMembershipWitness(
-    blockNumber: number,
-    nullifier: Fr,
-  ): Promise<NullifierMembershipWitness | undefined>;
-  utilityGetBlockHeader(blockNumber: number): Promise<BlockHeader | undefined>;
-  utilityGetPublicKeysAndPartialAddress(account: AztecAddress): Promise<CompleteAddress>;
-  utilityGetAuthWitness(messageHash: Fr): Promise<Fr[] | undefined>;
-  utilityGetNotes(
-    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(
-    contractAddress: AztecAddress,
-    startStorageSlot: Fr,
-    blockNumber: number,
-    numberOfElements: number,
-  ): Promise<Fr[]>;
-  utilityFetchTaggedLogs(pendingTaggedLogArrayBaseSlot: Fr): Promise<void>;
-  utilityValidateEnqueuedNotesAndEvents(
-    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(storageSlot: Fr, noteTypeId: NoteSelector, note: Fr[], noteHash: Fr, counter: number): void;
-  privateNotifyNullifiedNote(innerNullifier: Fr, noteHash: Fr, counter: number): Promise<void>;
-  privateNotifyCreatedNullifier(innerNullifier: Fr): Promise<void>;
-  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>;
-  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/message_load_oracle_inputs.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { SiblingPath } from '@aztec/foundation/trees';
 
 export class MessageLoadOracleInputs<N extends number> {

package/src/contract_function_simulator/oracle/note_packing_utils.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { Note } from '@aztec/stdlib/note';
 
@@ -18,35 +18,51 @@ function fromRawData(nonzeroNoteHashCounter: boolean, maybeNoteNonce: Fr): { sta
 }
 
 /**
- * Packs a note in a format that is compatible with the default Packable implementation of the retrieved note.
+ * Packs a note in a format that is compatible with the default Packable implementation of the hinted note.
  *
  * @dev Unlike the default Packable implementation, this function first constructs the note metadata from the inputs
- * and only after that it packs the retrieved note. Hence it doesn't map one to one with `RetrievedNote::pack()`.
+ * and only after that it packs the hinted note. Hence it doesn't map one to one with `HintedNote::pack()`.
  *
  * @param contractAddress - The address of the contract that owns the note
+ * @param owner - The owner of the note
+ * @param randomness - The randomness injected into the note to get the hiding property of commitments
+ * @param storageSlot - The storage slot of the note
  * @param noteNonce - The nonce injected into the note hash preimage by kernels.
- * @param index - Optional index in the note hash tree. If undefined, indicates a transient note
+ * @param isPending - True if the note is pending, false if settled
  * @param note - The note content containing the actual note data
  * @returns The packed note as an array of field elements
  */
-export function packAsRetrievedNote({
+export function packAsHintedNote({
   contractAddress,
+  owner,
+  randomness,
+  storageSlot,
   noteNonce,
-  index,
+  isPending,
   note,
 }: {
   contractAddress: AztecAddress;
+  owner: AztecAddress;
+  randomness: Fr;
+  storageSlot: Fr;
   noteNonce: Fr;
-  index?: bigint;
+  isPending: boolean;
   note: Note;
-}) {
-  // If index is undefined, the note is transient which implies that the nonzero_note_hash_counter has to be true
-  const noteIsTransient = index === undefined;
-  const nonzeroNoteHashCounter = noteIsTransient ? true : false;
+}): Fr[] {
+  // If the note is pending it means it has a non-zero note hash counter associated with it.
+  const nonZeroNoteHashCounter = isPending;
 
-  // To pack the note as retrieved note we first need to reconstruct the note metadata.
-  const noteMetadata = fromRawData(nonzeroNoteHashCounter, noteNonce);
+  // To pack the note as hinted note we first need to reconstruct the note metadata.
+  const noteMetadata = fromRawData(nonZeroNoteHashCounter, noteNonce);
 
-  // Pack metadata first (stage and maybe_note_nonce), followed by the rest
-  return [...note.items, contractAddress, new Fr(noteMetadata.stage), noteMetadata.maybeNoteNonce];
+  // Pack in order: note, contract_address, owner, randomness, storage_slot, metadata (stage, maybe_note_nonce)
+  return [
+    ...note.items,
+    contractAddress.toField(),
+    owner.toField(),
+    randomness,
+    storageSlot,
+    new Fr(noteMetadata.stage),
+    noteMetadata.maybeNoteNonce,
+  ];
 }