@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/messaging/out_hash.ts

@@ -0,0 +1,77 @@
+import { OUT_HASH_TREE_LEAF_COUNT } from '@aztec-labs/constants';
+import { padArrayEnd } from '@aztec-labs/foundation/collection';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { computeBalancedShaRoot, computeUnbalancedShaRoot, computeWonkyShaRoot } from '@aztec-labs/foundation/trees';
+
+/**
+ * Computes the out hash of a tx. It's the root of the unbalanced tree of all the L2-to-L1 messages emitted by the tx.
+ * @param messages - The L2-to-L1 messages emitted by the tx.
+ * @returns The out hash of the tx.
+ */
+export function computeTxOutHash(messages: Fr[]): Fr {
+  // Must match the implementation in `tx_base_public_inputs_composer.nr > compute_kernel_out_hash()`
+  if (!messages.length) {
+    return Fr.ZERO;
+  }
+  // It's an unbalanced tree because zero hashes (which should not happen) will be included.
+  return Fr.fromBuffer(computeUnbalancedShaRoot(messages.map(msg => msg.toBuffer())));
+}
+
+/**
+ * Computes the out hash of a block. It's the root of the wonky tree of all the tx out hashes.
+ * @param messagesPerTx - The L2-to-L1 messages emitted by the txs in the block. This is an array of message arrays.
+ * The array at index 0 contains the messages emitted by the first tx, the array at index 1 contains the messages
+ * emitted by the second tx, and so on.
+ * @returns The out hash of the block.
+ */
+export function computeBlockOutHash(messagesPerTx: Fr[][]): Fr {
+  // See how the tx out hashes are aggregated into a block out hash in `merge_tx_rollups.nr > accumulate_out_hash()`.
+  const txOutHashes = messagesPerTx.map(messages => computeTxOutHash(messages));
+  return Fr.fromBuffer(computeWonkyShaRoot(txOutHashes.map(hash => hash.toBuffer())));
+}
+
+/**
+ * Computes the out hash of a checkpoint. It's the root of the wonky tree of all the block out hashes.
+ * @param messagesPerBlock - The L2-to-L1 messages emitted by the txs in the blocks in the checkpoint. This is an array
+ * of arrays of messages. The array at index 0 contains the arrays of messages emitted by the first block, the array at
+ * index 1 contains the arrays of messages emitted by the second block, and so on.
+ * @returns The out hash of the checkpoint.
+ */
+export function computeCheckpointOutHash(messagesPerBlock: Fr[][][]): Fr {
+  // See how the block out hashes are aggregated into a checkpoint out hash in `merge_block_rollups.nr > accumulate_out_hash()`.
+  const blockOutHashes = messagesPerBlock.map(block => computeBlockOutHash(block));
+  return Fr.fromBuffer(computeWonkyShaRoot(blockOutHashes.map(hash => hash.toBuffer())));
+}
+
+/**
+ * Computes the accumulated (epoch) out hash of a checkpoint. It's the root of the balanced tree of all the out hashes
+ * from the first checkpoint in an epoch to the current checkpoint.
+ * It's this value that's set to the checkpoint header and validated on L1 instead of the checkpoint out hash.
+ * @param checkpointOutHashes - The out hashes of all checkpoints in the epoch.
+ * @returns The accumulated (epoch) out hash.
+ */
+export function accumulateCheckpointOutHashes(checkpointOutHashes: Fr[]): Fr {
+  // See how the checkpoint out hashes are accumulated in `checkpoint_rollup_public_inputs_composer.nr > accumulate_checkpoint_out_hash()`.
+  const paddedOutHashes = padArrayEnd(
+    checkpointOutHashes.map(hash => hash.toBuffer()),
+    Buffer.alloc(32),
+    OUT_HASH_TREE_LEAF_COUNT,
+  );
+  return Fr.fromBuffer(computeBalancedShaRoot(paddedOutHashes));
+}
+
+/**
+ * Computes the epoch out hash. It's the root of the balanced tree of all the checkpoint out hashes.
+ * It should match the **accumulated** out hash of the last checkpoint in the epoch.
+ * This value will be inserted into the Outbox on L1.
+ * @param messagesPerCheckpoint - The L2-to-L1 messages emitted by the txs in the blocks in the checkpoints in the epoch.
+ * This is an array of arrays of arrays of messages. The array at index 0 contains the arrays of arrays of messages
+ * emitted by the first checkpoint, the array at index 1 contains the arrays of arrays of messages emitted by the second
+ * checkpoint, and so on.
+ * @returns The epoch out hash.
+ */
+export function computeEpochOutHash(messagesPerCheckpoint: Fr[][][][]): Fr {
+  // See how the accumulated out hash is assigned to the root rollup's public inputs in `root_rollup.nr`.
+  const checkpointOutHashes = messagesPerCheckpoint.map(checkpoint => computeCheckpointOutHash(checkpoint));
+  return accumulateCheckpointOutHashes(checkpointOutHashes);
+}

package/src/noir/index.ts

@@ -0,0 +1,173 @@
+import type {
+  ABIParameter,
+  ABIParameterVisibility,
+  AbiErrorType,
+  AbiNamedValue,
+  AbiType,
+  DebugFileMap,
+  DebugInfo,
+} from '../abi/abi.js';
+
+export const AZTEC_PRIVATE_ATTRIBUTE = 'abi_private';
+export const AZTEC_PUBLIC_ATTRIBUTE = 'abi_public';
+export const AZTEC_UTILITY_ATTRIBUTE = 'abi_utility';
+export const AZTEC_ONLY_SELF_ATTRIBUTE = 'abi_only_self';
+export const AZTEC_INITIALIZER_ATTRIBUTE = 'abi_initializer';
+export const AZTEC_VIEW_ATTRIBUTE = 'abi_view';
+
+/** The ABI of an Aztec.nr function. */
+export interface NoirFunctionAbi {
+  /** The parameters of the function. */
+  parameters: ABIParameter[];
+  /** The return type of the function, or null for void functions. */
+  return_type: {
+    /**
+     * The type of the return value.
+     */
+    abi_type: AbiType;
+    /**
+     * The visibility of the return value.
+     */
+    visibility: ABIParameterVisibility;
+  } | null;
+  /** Mapping of error selector => error type */
+  error_types: Partial<Record<string, AbiErrorType>>;
+}
+
+/**
+ * The compilation result of an Aztec.nr function.
+ */
+interface NoirFunctionEntry {
+  /** The name of the function. */
+  name: string;
+  /** Whether the function is unconstrained. */
+  is_unconstrained: boolean;
+  /** Custom attributes attached to function */
+  custom_attributes: string[];
+  /** The ABI of the function. */
+  abi: NoirFunctionAbi;
+  /** The bytecode of the function in base64. */
+  bytecode: string;
+  /** The proving key. */
+  proving_key?: string;
+  /** The verification key. */
+  verification_key?: string;
+  /** The debug information, compressed and base64 encoded. */
+  debug_symbols: string;
+  /** Map opcode index to assert message for public functions */
+  assert_messages?: Record<number, string>;
+}
+
+/**
+ * The compilation result of an Aztec.nr contract.
+ */
+export interface NoirCompiledContract {
+  /** The name of the contract. */
+  name: string;
+  /** The version of the Aztec stack that compiled this contract. */
+  aztec_version: string;
+  /** Is the contract's public bytecode transpiled? */
+  transpiled?: boolean;
+  /** The functions of the contract. */
+  functions: NoirFunctionEntry[];
+  /** The events of the contract */
+  outputs: {
+    structs: Record<string, AbiType[]>;
+    globals: Record<string, AbiNamedValue[]>;
+  };
+  /** The map of file ID to the source code and path of the file. */
+  file_map: DebugFileMap;
+}
+
+/**
+ * The compilation result of a protocol (non-contract) circuit.
+ */
+export interface NoirCompiledCircuit {
+  /** The hash of the circuit. */
+  hash?: number;
+  /**
+   * The ABI of the function.
+   */
+  abi: NoirFunctionAbi;
+  /** The bytecode of the circuit in base64. */
+  bytecode: string;
+  /** The verification key of the circuit. */
+  verificationKey: {
+    /** hex-encoded binary */
+    bytes: string;
+    /** list of hex-encoded fields */
+    fields: string[];
+    /** The hex-encoded hash. */
+    hash: string;
+  };
+  /** The debug information, compressed and base64 encoded. */
+  debug_symbols: string;
+  /** The map of file ID to the source code and path of the file. */
+  file_map: DebugFileMap;
+}
+
+export interface NoirCompiledCircuitWithName extends NoirCompiledCircuit {
+  /** The name of the circuit. */
+  name: string;
+}
+
+/**
+ * The debug metadata of an Aztec.nr contract.
+ */
+export interface NoirDebugMetadata {
+  /**
+   * The debug information for each function.
+   */
+  debug_symbols: DebugInfo[];
+  /**
+   * The map of file ID to the source code and path of the file.
+   */
+  file_map: DebugFileMap;
+}
+
+/**
+ * The compilation artifacts of a given contract.
+ */
+export interface NoirContractCompilationArtifacts {
+  /**
+   * The compiled contract.
+   */
+  contract: NoirCompiledContract;
+}
+
+/**
+ * The compilation artifacts of a given program.
+ */
+export interface NoirProgramCompilationArtifacts {
+  /**
+   * not part of the compilation output, injected later
+   */
+  name: string;
+  /**
+   * The compiled contract.
+   */
+  program: NoirCompiledCircuit;
+}
+
+/**
+ * output of Noir Wasm compilation, can be for a contract or lib/binary
+ */
+export type NoirCompilationResult = NoirContractCompilationArtifacts | NoirProgramCompilationArtifacts;
+
+/**
+ * Check if it has Contract unique property
+ */
+export function isNoirContractCompilationArtifacts(
+  artifact: NoirCompilationResult,
+): artifact is NoirContractCompilationArtifacts {
+  return (artifact as NoirContractCompilationArtifacts).contract !== undefined;
+}
+
+/**
+ * Check if it has Contract unique property
+ */
+export function isNoirProgramCompilationArtifacts(
+  artifact: NoirCompilationResult,
+): artifact is NoirProgramCompilationArtifacts {
+  return (artifact as NoirProgramCompilationArtifacts).program !== undefined;
+}

package/src/note/comparator.ts

@@ -0,0 +1,11 @@
+/**
+ * The comparator to use to compare.
+ */
+export enum Comparator {
+  EQ = 1,
+  NEQ = 2,
+  LT = 3,
+  LTE = 4,
+  GT = 5,
+  GTE = 6,
+}

package/src/note/index.ts

@@ -0,0 +1,4 @@
+export * from './comparator.js';
+export * from './note_dao.js';
+export * from './note_status.js';
+export * from './note.js';

package/src/note/note.ts

@@ -0,0 +1,75 @@
+import { randomInt } from '@aztec-labs/foundation/crypto/random';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader } from '@aztec-labs/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec-labs/foundation/string';
+
+import { schemas } from '../schemas/index.js';
+import { Vector } from '../types/shared.js';
+
+/**
+ * The Note class represents a Note emitted from a Noir contract as a vector of Fr (finite field) elements.
+ * This data also represents a preimage to a note hash.
+ */
+export class Note extends Vector<Fr> {
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  static get schema() {
+    return schemas.Buffer.transform(Note.fromBuffer);
+  }
+
+  /**
+   * Create a Note instance from a Buffer or BufferReader.
+   * The input 'buffer' can be either a Buffer containing the serialized Fr elements or a BufferReader instance.
+   * This function reads the Fr elements in the buffer and constructs a Note with them.
+   *
+   * @param buffer - The Buffer or BufferReader containing the serialized Fr elements.
+   * @returns A Note instance containing the deserialized Fr elements.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Note(reader.readVector(Fr));
+  }
+
+  /**
+   * Generates a random Note instance with a variable number of items.
+   * The number of items is determined by a random value between 1 and 10 (inclusive).
+   * Each item in the Note is generated using the Fr.random() method.
+   *
+   * @returns A randomly generated Note instance.
+   */
+  static random() {
+    const numItems = randomInt(10) + 1;
+    const items = Array.from({ length: numItems }, () => Fr.random());
+    return new Note(items);
+  }
+
+  /**
+   * Returns a hex representation of the note.
+   * @returns A hex string with the vector length as first element.
+   */
+  override toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  /**
+   * Creates a new Note instance from a hex string.
+   * @param str - Hex representation.
+   * @returns A Note instance.
+   */
+  static fromString(str: string) {
+    return Note.fromBuffer(hexToBuffer(str));
+  }
+
+  get length() {
+    return this.items.length;
+  }
+
+  equals(other: Note) {
+    if (this.items.length !== other.items.length) {
+      return false;
+    }
+    return this.items.every((item, index) => item.equals(other.items[index]));
+  }
+}

package/src/note/note_dao.ts

@@ -0,0 +1,184 @@
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { Note } from '@aztec-labs/stdlib/note';
+import { TxHash } from '@aztec-labs/stdlib/tx';
+
+/**
+ * A Note Data Access Object, representing a note that was committed to the note hash tree, holding all of the
+ * information required to use it during execution and manage its state.
+ */
+export class NoteDao {
+  constructor(
+    // Note information
+
+    /** The packed content of the note, as will be returned in the getNotes oracle. */
+    public note: Note,
+    /** The address of the contract that created the note (i.e. the address used by the kernel during siloing). */
+    public contractAddress: AztecAddress,
+    /** The owner of the note - generally the account that can spend the note. */
+    public owner: AztecAddress,
+    /**
+     * The storage location of the note. This value is not used for anything in PXE, but we do index by storage slot
+     * since contracts typically make queries based on it.
+     */
+    public storageSlot: Fr,
+    /**
+     * The randomness injected to the note hash preimage.
+     */
+    public randomness: Fr,
+    /** The nonce that was injected into the note hash preimage in order to guarantee uniqueness. */
+    public noteNonce: Fr,
+
+    // Computed values
+    /**
+     * The inner hash (non-unique, non-siloed) of the note. Each contract determines how the note is hashed. Can
+     * be used alongside contractAddress and nonce to compute the uniqueNoteHash and the siloedNoteHash.
+     */
+    public noteHash: Fr,
+    /**
+     * The nullifier of the note, siloed by contract address.
+     * Note: Might be set as 0 if the note was added to PXE as nullified.
+     */
+    public siloedNullifier: Fr,
+
+    // Metadata
+    /** The hash of the tx in which this note was created. Knowing the tx hash allows for efficient node queries e.g.
+     *  when searching for txEffects.
+     */
+    public txHash: TxHash,
+    /** The L2 block number in which the tx with this note was included. Used for note management while processing
+     * reorgs.*/
+    public l2BlockNumber: BlockNumber,
+    /** The L2 block hash in which the tx with this note was included. Used for note management while processing
+     * reorgs.*/
+    public l2BlockHash: string,
+    /** The index of the tx within the block, used for ordering notes. */
+    public txIndexInBlock: number,
+    /** The index of the note within the tx (based on note hash position), used for ordering notes. */
+    public noteIndexInTx: number,
+  ) {}
+
+  toBuffer(): Buffer {
+    return serializeToBuffer([
+      this.note,
+      this.contractAddress,
+      this.owner,
+      this.storageSlot,
+      this.randomness,
+      this.noteNonce,
+      this.noteHash,
+      this.siloedNullifier,
+      this.txHash,
+      this.l2BlockNumber,
+      Fr.fromHexString(this.l2BlockHash),
+      this.txIndexInBlock,
+      this.noteIndexInTx,
+    ]);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+
+    const note = Note.fromBuffer(reader);
+    const contractAddress = AztecAddress.fromBuffer(reader);
+    const owner = AztecAddress.fromBuffer(reader);
+    const storageSlot = Fr.fromBuffer(reader);
+    const randomness = Fr.fromBuffer(reader);
+    const noteNonce = Fr.fromBuffer(reader);
+    const noteHash = Fr.fromBuffer(reader);
+    const siloedNullifier = Fr.fromBuffer(reader);
+    const txHash = reader.readObject(TxHash);
+    const l2BlockNumber = BlockNumber(reader.readNumber());
+    const l2BlockHash = Fr.fromBuffer(reader).toString();
+    const txIndexInBlock = reader.readNumber();
+    const noteIndexInTx = reader.readNumber();
+
+    return new NoteDao(
+      note,
+      contractAddress,
+      owner,
+      storageSlot,
+      randomness,
+      noteNonce,
+      noteHash,
+      siloedNullifier,
+      txHash,
+      l2BlockNumber,
+      l2BlockHash,
+      txIndexInBlock,
+      noteIndexInTx,
+    );
+  }
+
+  toString() {
+    return '0x' + this.toBuffer().toString('hex');
+  }
+
+  static fromString(str: string) {
+    const hex = str.replace(/^0x/, '');
+    return NoteDao.fromBuffer(Buffer.from(hex, 'hex'));
+  }
+
+  /**
+   * Returns true if this note is equal to the `other` one.
+   */
+  equals(other: NoteDao): boolean {
+    return (
+      this.note.equals(other.note) &&
+      this.contractAddress.equals(other.contractAddress) &&
+      this.owner.equals(other.owner) &&
+      this.storageSlot.equals(other.storageSlot) &&
+      this.randomness.equals(other.randomness) &&
+      this.noteNonce.equals(other.noteNonce) &&
+      this.noteHash.equals(other.noteHash) &&
+      this.siloedNullifier.equals(other.siloedNullifier) &&
+      this.txHash.equals(other.txHash) &&
+      this.l2BlockNumber === other.l2BlockNumber &&
+      this.l2BlockHash === other.l2BlockHash &&
+      this.txIndexInBlock === other.txIndexInBlock &&
+      this.noteIndexInTx === other.noteIndexInTx
+    );
+  }
+
+  /**
+   * Returns the size in bytes of the Note Dao.
+   * @returns - Its size in bytes.
+   */
+  public getSize() {
+    return this.toBuffer().length;
+  }
+
+  static async random({
+    note = Note.random(),
+    contractAddress = undefined,
+    owner = undefined,
+    storageSlot = Fr.random(),
+    randomness = Fr.random(),
+    noteNonce = Fr.random(),
+    noteHash = Fr.random(),
+    siloedNullifier = Fr.random(),
+    txHash = TxHash.random(),
+    l2BlockNumber = BlockNumber(Math.floor(Math.random() * 1000)),
+    l2BlockHash = Fr.random().toString(),
+    txIndexInBlock = Math.floor(Math.random() * 100),
+    noteIndexInTx = Math.floor(Math.random() * 100),
+  }: Partial<NoteDao> = {}) {
+    return new NoteDao(
+      note,
+      contractAddress ?? (await AztecAddress.random()),
+      owner ?? (await AztecAddress.random()),
+      storageSlot,
+      randomness,
+      noteNonce,
+      noteHash,
+      siloedNullifier,
+      txHash,
+      l2BlockNumber,
+      l2BlockHash,
+      txIndexInBlock,
+      noteIndexInTx,
+    );
+  }
+}

package/src/note/note_status.ts

@@ -0,0 +1,8 @@
+/**
+ * The status of notes to retrieve.
+ */
+export enum NoteStatus {
+  ACTIVE = 1,
+  ACTIVE_OR_NULLIFIED = 2,
+  // TODO(#4217): add 'NULLIFIED'
+}

package/src/p2p/attestation_utils.ts

@@ -0,0 +1,98 @@
+import { normalizeSignature } from '@aztec-labs/foundation/crypto/secp256k1-signer';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+
+import { CommitteeAttestation } from '../block/index.js';
+import type { CheckpointAttestation } from './checkpoint_attestation.js';
+
+/**
+ * Returns attestation signatures in the order of a series of provided ethereum addresses
+ * The rollup smart contract expects attestations to appear in the order of the committee
+ * @todo: perform this logic within the memory attestation store instead?
+ */
+export function orderAttestations(
+  attestations: CheckpointAttestation[],
+  orderAddresses: EthAddress[],
+): CommitteeAttestation[] {
+  // Create a map of sender addresses to attestations
+  const attestationMap = new Map<string, CommitteeAttestation>();
+
+  for (const attestation of attestations) {
+    const sender = attestation.getSender();
+    if (sender) {
+      // Canonicalize the recovery byte to v ∈ {27, 28} before it reaches the L1 bundle. A committee
+      // member (or a peer mutating the byte in flight) can emit an equivalent signature in yParity form
+      // (v = 0/1); left as-is it makes `packAttestations` (empty iff v === 0) and `getSigners` (empty iff
+      // r,s,v all zero) disagree, reverting `propose()` with SignersSizeMismatch, and a v = 1 byte would
+      // later revert epoch proving in ECDSA.recover. `sender` recovered, so the signature is non-empty
+      // and low-s, and normalizeSignature preserves the recovered address.
+      attestationMap.set(
+        sender.toString(),
+        CommitteeAttestation.fromAddressAndSignature(sender, normalizeSignature(attestation.signature)),
+      );
+    }
+  }
+
+  // Create the ordered array based on the orderAddresses, else return an empty attestation
+  const orderedAttestations = orderAddresses.map(address => {
+    const addressString = address.toString();
+    return attestationMap.get(addressString) || CommitteeAttestation.fromAddress(address);
+  });
+
+  return orderedAttestations;
+}
+
+/**
+ * Trims attestations to the minimum required number to save L1 calldata gas.
+ * Each signature costs 65 bytes of calldata vs 20 bytes for just an address.
+ *
+ * Priority order for keeping attestations:
+ * 1. The proposer's attestation (required by L1 contract - MissingProposerSignature revert)
+ * 2. Attestations from the local node's validator keys
+ * 3. Remaining attestations filled to reach the required count
+ */
+export function trimAttestations(
+  attestations: CheckpointAttestation[],
+  required: number,
+  proposerAddress: EthAddress,
+  localAddresses: EthAddress[],
+): CheckpointAttestation[] {
+  if (attestations.length <= required) {
+    return attestations;
+  }
+
+  const proposerAttestation: CheckpointAttestation[] = [];
+  const localAttestations: CheckpointAttestation[] = [];
+  const otherAttestations: CheckpointAttestation[] = [];
+
+  for (const attestation of attestations) {
+    const sender = attestation.getSender();
+    if (!sender) {
+      continue;
+    }
+    if (sender.equals(proposerAddress)) {
+      proposerAttestation.push(attestation);
+    } else if (localAddresses.some(addr => addr.equals(sender))) {
+      localAttestations.push(attestation);
+    } else {
+      otherAttestations.push(attestation);
+    }
+  }
+
+  const result: CheckpointAttestation[] = [...proposerAttestation];
+
+  for (const att of localAttestations) {
+    if (result.length >= required) {
+      break;
+    }
+    result.push(att);
+  }
+
+  for (const att of otherAttestations) {
+    if (result.length >= required) {
+      break;
+    }
+    result.push(att);
+  }
+
+  return result;
+}