@aztec/pxe 0.0.0-test.1 → 0.0.1-commit.5476d83

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

@@ -0,0 +1,47 @@
+import { Fr } from '@aztec/foundation/fields';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { EventSelector } from '@aztec/stdlib/abi';
+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.
+const MAX_EVENT_SERIALIZED_LEN = 12;
+
+/**
+ * Intermediate struct used to perform batch event validation by PXE. The `utilityValidateEnqueuedNotesAndEvents` oracle
+ * expects for values of this type to be stored in a `CapsuleArray`.
+ */
+export class EventValidationRequest {
+  constructor(
+    public contractAddress: AztecAddress,
+    public eventTypeId: EventSelector,
+    public serializedEvent: Fr[],
+    public eventCommitment: Fr,
+    public txHash: TxHash,
+    public recipient: AztecAddress,
+  ) {}
+
+  static fromFields(fields: Fr[] | FieldReader): EventValidationRequest {
+    const reader = FieldReader.asReader(fields);
+
+    const contractAddress = AztecAddress.fromField(reader.readField());
+    const eventTypeId = EventSelector.fromField(reader.readField());
+
+    const eventStorage = reader.readFieldArray(MAX_EVENT_SERIALIZED_LEN);
+    const eventLen = reader.readField().toNumber();
+    const serializedEvent = eventStorage.slice(0, eventLen);
+
+    const eventCommitment = reader.readField();
+    const txHash = TxHash.fromField(reader.readField());
+    const recipient = AztecAddress.fromField(reader.readField());
+
+    return new EventValidationRequest(
+      contractAddress,
+      eventTypeId,
+      serializedEvent,
+      eventCommitment,
+      txHash,
+      recipient,
+    );
+  }
+}

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

@@ -0,0 +1,27 @@
+import { Fr } from '@aztec/foundation/fields';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+/**
+ * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle expects values of this
+ * type to be stored in a `CapsuleArray`.
+ */
+export class LogRetrievalRequest {
+  constructor(
+    public contractAddress: AztecAddress,
+    public unsiloedTag: Fr,
+  ) {}
+
+  toFields(): Fr[] {
+    return [this.contractAddress.toField(), this.unsiloedTag];
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): LogRetrievalRequest {
+    const reader = FieldReader.asReader(fields);
+
+    const contractAddress = AztecAddress.fromField(reader.readField());
+    const unsiloedTag = reader.readField();
+
+    return new LogRetrievalRequest(contractAddress, unsiloedTag);
+  }
+}

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

@@ -0,0 +1,69 @@
+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 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);
+
+/**
+ * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle stores values of this
+ * type in a `CapsuleArray`.
+ */
+export class LogRetrievalResponse {
+  constructor(
+    public logPayload: Fr[],
+    public txHash: TxHash,
+    public uniqueNoteHashesInTx: Fr[],
+    public firstNullifierInTx: Fr,
+  ) {}
+
+  toFields(): Fr[] {
+    return [
+      // We need to trim the payload since public logs can be larger than MAX_LOG_CONTENT_LEN.
+      // This is currently not a problem since this class is only used with public logs for note completion.
+      ...serializeBoundedVec(this.logPayload.slice(0, MAX_LOG_CONTENT_LEN), MAX_LOG_CONTENT_LEN),
+      this.txHash.hash,
+      ...serializeBoundedVec(this.uniqueNoteHashesInTx, MAX_NOTE_HASHES_PER_TX),
+      this.firstNullifierInTx,
+    ];
+  }
+
+  static toEmptyFields(): Fr[] {
+    const serializationLen =
+      MAX_LOG_CONTENT_LEN +
+      1 /* logPayload BVec */ +
+      1 /* txHash */ +
+      MAX_NOTE_HASHES_PER_TX +
+      1 /* uniqueNoteHashesInTx BVec */ +
+      1; /* firstNullifierInTx */
+    return range(serializationLen).map(_ => Fr.zero());
+  }
+
+  static toSerializedOption(response: LogRetrievalResponse | null): Fr[] {
+    if (response) {
+      return [new Fr(1), ...response.toFields()];
+    } else {
+      return [new Fr(0), ...LogRetrievalResponse.toEmptyFields()];
+    }
+  }
+}
+
+/**
+ * Helper function to serialize a bounded vector according to Noir's BoundedVec format
+ * @param values - The values to serialize
+ * @param maxLength - The maximum length of the bounded vector
+ * @returns The serialized bounded vector as Fr[]
+ */
+function serializeBoundedVec(values: Fr[], maxLength: number): Fr[] {
+  if (values.length > maxLength) {
+    throw new Error(`Attempted to serialize ${values} values into a BoundedVec with max length ${maxLength}`);
+  }
+
+  const lengthDiff = maxLength - values.length;
+  const zeroPaddingArray = Array(lengthDiff).fill(Fr.ZERO);
+  const storage = values.concat(zeroPaddingArray);
+  return [...storage, new Fr(values.length)];
+}

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

@@ -0,0 +1,61 @@
+import { Fr } from '@aztec/foundation/fields';
+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 = 11;
+
+/**
+ * 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`.
+ */
+export class NoteValidationRequest {
+  constructor(
+    public contractAddress: 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 storageSlot = reader.readField();
+    const randomness = reader.readField();
+    const noteNonce = reader.readField();
+
+    const contentStorage = reader.readFieldArray(MAX_NOTE_PACKED_LEN);
+    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. Hint: check that MAX_NOTE_PACKED_LEN is consistent with private_notes::MAX_NOTE_PACKED_LEN in Aztec-nr.`,
+      );
+    }
+
+    return new NoteValidationRequest(
+      contractAddress,
+      storageSlot,
+      randomness,
+      noteNonce,
+      content,
+      noteHash,
+      nullifier,
+      txHash,
+      recipient,
+    );
+  }
+}

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

@@ -0,0 +1,42 @@
+import { Fr } from '@aztec/foundation/fields';
+import type { FieldsOf } from '@aztec/foundation/types';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { UInt64 } from '@aztec/stdlib/types';
+
+/**
+ * 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,
+    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,
+    ];
+  }
+}

package/src/contract_function_simulator/oracle/index.ts

@@ -0,0 +1,16 @@
+import type { Oracle } from './oracle.js';
+
+export * from './oracle.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

@@ -0,0 +1,170 @@
+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 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;
+  /** 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.
+
+/**
+ * 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).
+ */
+export interface IMiscOracle {
+  isMisc: true;
+
+  utilityGetRandomField(): Fr;
+  utilityAssertCompatibleOracleVersion(version: number): void;
+  utilityDebugLog(level: number, message: string, fields: Fr[]): void;
+}
+
+/**
+ * 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.
+ */
+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>;
+}
+
+/**
+ * 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.
+ */
+export interface IPrivateExecutionOracle {
+  isPrivate: true;
+
+  privateStoreInExecutionCache(values: Fr[], hash: Fr): void;
+  privateLoadFromExecutionCache(hash: Fr): Promise<Fr[]>;
+  privateNotifyCreatedNote(
+    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>;
+  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>;
+}

package/src/contract_function_simulator/oracle/message_load_oracle_inputs.ts

@@ -0,0 +1,23 @@
+import { Fr } from '@aztec/foundation/fields';
+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[]];
+  }
+}

package/src/contract_function_simulator/oracle/note_packing_utils.ts

@@ -0,0 +1,54 @@
+import { Fr } from '@aztec/foundation/fields';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { Note } from '@aztec/stdlib/note';
+
+// TS equivalent of the `NoteMetadata::from_raw_data` function in `aztec/src/note/note_metadata.nr`
+function fromRawData(nonzeroNoteHashCounter: boolean, maybeNoteNonce: Fr): { stage: number; maybeNoteNonce: Fr } {
+  if (nonzeroNoteHashCounter) {
+    if (maybeNoteNonce.equals(Fr.ZERO)) {
+      return { stage: 1, maybeNoteNonce }; // PENDING_SAME_PHASE
+    } else {
+      return { stage: 2, maybeNoteNonce }; // PENDING_PREVIOUS_PHASE
+    }
+  } else if (!maybeNoteNonce.equals(Fr.ZERO)) {
+    return { stage: 3, maybeNoteNonce }; // SETTLED
+  } else {
+    throw new Error('Note has a zero note hash counter and no nonce - existence cannot be proven');
+  }
+}
+
+/**
+ * Packs a note in a format that is compatible with the default Packable implementation of the retrieved 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()`.
+ *
+ * @param contractAddress - The address of the contract that owns the note
+ * @param randomness - The randomness injected into the note to get the hiding property of commitments
+ * @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 note - The note content containing the actual note data
+ * @returns The packed note as an array of field elements
+ */
+export function packAsRetrievedNote({
+  contractAddress,
+  randomness,
+  noteNonce,
+  index,
+  note,
+}: {
+  contractAddress: AztecAddress;
+  randomness: Fr;
+  noteNonce: Fr;
+  index?: bigint;
+  note: Note;
+}) {
+  // If index is undefined, the note is transient which implies that the nonzero_note_hash_counter has to be true
+  const nonzeroNoteHashCounter = index === undefined;
+
+  // To pack the note as retrieved 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, randomness, new Fr(noteMetadata.stage), noteMetadata.maybeNoteNonce];
+}