@aztec/pxe 0.0.0-test.1 → 0.0.1-commit.017a351

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

@@ -0,0 +1,61 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { Tag } from '@aztec/stdlib/logs';
+
+/** Discriminant for which log source to query. */
+export enum LogSource {
+  PRIVATE = 0,
+  PUBLIC = 1,
+  PUBLIC_AND_PRIVATE = 2,
+}
+
+/**
+ * Intermediate struct used to perform batch log retrieval by PXE. The `utilityBulkRetrieveLogs` oracle expects values of this
+ * type to be stored in a `EphemeralArray`.
+ */
+export class LogRetrievalRequest {
+  constructor(
+    public contractAddress: AztecAddress,
+    public tag: Tag,
+    public source: LogSource = LogSource.PUBLIC_AND_PRIVATE,
+    public fromBlock?: BlockNumber,
+    public toBlock?: BlockNumber,
+  ) {}
+
+  toFields(): Fr[] {
+    return [
+      this.contractAddress.toField(),
+      this.tag.value,
+      new Fr(this.source),
+      new Fr(this.fromBlock !== undefined ? 1 : 0),
+      new Fr(this.fromBlock ?? 0),
+      new Fr(this.toBlock !== undefined ? 1 : 0),
+      new Fr(this.toBlock ?? 0),
+    ];
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): LogRetrievalRequest {
+    const reader = FieldReader.asReader(fields);
+
+    const contractAddress = AztecAddress.fromField(reader.readField());
+    const tag = new Tag(reader.readField());
+    const sourceNum = reader.readField().toNumber();
+    if (!(sourceNum in LogSource)) {
+      const validNames = Object.keys(LogSource).filter(k => isNaN(Number(k)));
+      throw new Error(`Invalid LogSource value ${sourceNum}, expected one of ${validNames.join(', ')}`);
+    }
+    const source = sourceNum as LogSource;
+
+    const fromBlockIsSome = reader.readBoolean();
+    const fromBlockValue = reader.readField();
+    const fromBlock = fromBlockIsSome ? BlockNumber(fromBlockValue.toNumber()) : undefined;
+
+    const toBlockIsSome = reader.readBoolean();
+    const toBlockValue = reader.readField();
+    const toBlock = toBlockIsSome ? BlockNumber(toBlockValue.toNumber()) : undefined;
+
+    return new LogRetrievalRequest(contractAddress, tag, source, fromBlock, toBlock);
+  }
+}

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

@@ -0,0 +1,66 @@
+import { MAX_NOTE_HASHES_PER_TX, PRIVATE_LOG_CIPHERTEXT_LEN } from '@aztec/constants';
+import { range } from '@aztec/foundation/array';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+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 `EphemeralArray`.
+ */
+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_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

@@ -0,0 +1,59 @@
+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';
+
+/**
+ * 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,
+  ) {}
+
+  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 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());
+
+    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,
+    );
+  }
+}

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

@@ -0,0 +1,23 @@
+import { toACVMField } from '@aztec/simulator/client';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+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 {
+  constructor(
+    public readonly blockHeader: BlockHeader,
+    public readonly contractAddress: AztecAddress,
+  ) {}
+
+  /**
+   * 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
+    const blockHeaderFields = this.blockHeader.toFields().map(toACVMField);
+    return [...blockHeaderFields, this.contractAddress.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,21 @@
+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 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 type IMiscOracle = HandlersForPrefix<typeof ORACLE_REGISTRY, 'misc'> & { isMisc: true };
+
+/**
+ * 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 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
+ * IMiscOracle and IUtilityExecutionOracle methods are also expected to be available in these contexts.
+ */
+export type IPrivateExecutionOracle = HandlersForPrefix<typeof ORACLE_REGISTRY, 'prv'> & { isPrivate: true };

package/src/contract_function_simulator/oracle/message_load_oracle_inputs.ts

@@ -0,0 +1,23 @@
+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[]];
+  }
+}

package/src/contract_function_simulator/oracle/note_packing_utils.ts

@@ -0,0 +1,68 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+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 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 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 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 packAsHintedNote({
+  contractAddress,
+  owner,
+  randomness,
+  storageSlot,
+  noteNonce,
+  isPending,
+  note,
+}: {
+  contractAddress: AztecAddress;
+  owner: AztecAddress;
+  randomness: Fr;
+  storageSlot: Fr;
+  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;
+
+  // To pack the note as hinted note we first need to reconstruct the note metadata.
+  const noteMetadata = fromRawData(nonZeroNoteHashCounter, noteNonce);
+
+  // 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,
+  ];
+}