@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.0b941701

package/src/messaging/l2_to_l1_membership.ts

@@ -0,0 +1,225 @@
+import { OUT_HASH_TREE_LEAF_COUNT } from '@aztec/constants';
+import type { EpochNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { SiblingPath, UnbalancedMerkleTreeCalculator, computeUnbalancedShaRoot } from '@aztec/foundation/trees';
+
+/**
+ * # L2-to-L1 Message Tree Structure and Leaf IDs
+ *
+ * ## Overview
+ * L2-to-L1 messages are organized in a hierarchical 4-level tree structure within each epoch:
+ *   Epoch → Checkpoints → Blocks → Transactions → Messages
+ *
+ * Each level uses an unbalanced Merkle tree, and some levels use compression (skipping zero hashes).
+ *
+ * ## Tree Levels
+ *
+ * 1. **Message Tree (TX Out Hash)**
+ *    - Leaves: Individual L2-to-L1 messages within a transaction
+ *    - Root: TX out hash
+ *    - Type: Unbalanced, non-compressed (the circuits ensure that all messages are not empty.)
+ *
+ * 2. **Block Tree**
+ *    - Leaves: TX out hashes from all transactions in a block
+ *    - Root: Block out hash
+ *    - Type: Unbalanced, compressed (zero hashes are skipped)
+ *    - Compression: If a tx has no messages (out hash = 0), that branch is ignored
+ *
+ * 3. **Checkpoint Tree**
+ *    - Leaves: Block out hashes from all blocks in a checkpoint
+ *    - Root: Checkpoint out hash
+ *    - Type: Unbalanced, compressed (zero hashes are skipped)
+ *    - Compression: If a block has no messages (out hash = 0), that branch is ignored
+ *
+ * 4. **Epoch Tree**
+ *    - Leaves: Checkpoint out hashes from all checkpoints in an epoch (padded to AZTEC_MAX_EPOCH_DURATION)
+ *    - Root: Epoch out hash (set in the root rollup's public inputs and inserted into the Outbox on L1 when the epoch is proven)
+ *    - Type: Unbalanced, non-compressed
+ *    - **Important**: Padded with zeros up to AZTEC_MAX_EPOCH_DURATION to allow for proofs of partial epochs
+ *
+ * ## Combined Membership Proof
+ * To prove a message exists in an epoch, we combine the sibling paths from all 4 trees:
+ *   [message siblings] + [tx siblings] + [block siblings] + [checkpoint siblings]
+ *
+ * ## Leaf ID: Stable Message Identification
+ *
+ * Each message gets a unique, stable **leaf ID** that identifies its position in the combined tree.
+ * The leaf ID is computed as:
+ *   leafId = 2^pathSize + leafIndex
+ *
+ * Where:
+ * - `pathSize`: Total length of the combined sibling path (from all 4 tree levels)
+ * - `leafIndex`: The message's index in a balanced tree representation at that height
+ *
+ * ### Why Leaf IDs Are Stable
+ *
+ * The leaf ID is based on the message's position in the tree structure, which is determined by:
+ * - The checkpoint index within the epoch
+ * - The block index within the checkpoint
+ * - The transaction index within the block
+ * - The message index within the transaction
+ *
+ * These indices are structural and do NOT depend on the total number of blocks/checkpoints in the epoch.
+ *
+ * ### Critical Property: Preserving Consumed Status
+ *
+ * **Problem**: On L1, epoch proofs can be submitted incrementally. For example:
+ * - First, a proof for checkpoints 1-10 of epoch 0 is submitted (proves the first 10 checkpoints)
+ * - Later, a proof for checkpoints 1-20 of epoch 0 is submitted (proves all 20 checkpoints)
+ *
+ * When the longer proof is submitted, it updates the epoch's out hash root on L1 to reflect the complete epoch (all 20
+ * checkpoints). However, some messages from checkpoints 1-10 may have already been consumed.
+ *
+ * **Solution**: The Outbox on L1 tracks consumed messages using a bitmap indexed by leaf ID.
+ * Because leaf IDs are stable (they don't change when more checkpoints are added to the epoch), messages that were consumed
+ * under the shorter proof remain marked as consumed under the longer proof.
+ *
+ * This prevents double-spending of L2-to-L1 messages when longer epoch proofs are submitted.
+ */
+
+/**
+ * Computes the unique leaf ID for an L2-to-L1 message.
+ *
+ * The leaf ID is stable across different epoch proof lengths and is used by the Outbox
+ * on L1 to track which messages have been consumed.
+ *
+ * @param membershipWitness - Contains the leafIndex and siblingPath for the message
+ * @returns The unique leaf ID used for tracking message consumption on L1
+ */
+export function getL2ToL1MessageLeafId(
+  membershipWitness: Pick<L2ToL1MembershipWitness, 'leafIndex' | 'siblingPath'>,
+): bigint {
+  return 2n ** BigInt(membershipWitness.siblingPath.pathSize) + membershipWitness.leafIndex;
+}
+
+export interface MessageRetrieval {
+  getL2ToL1Messages(epoch: EpochNumber): Promise<Fr[][][][]>;
+}
+
+export type L2ToL1MembershipWitness = {
+  root: Fr;
+  leafIndex: bigint;
+  siblingPath: SiblingPath<number>;
+};
+
+export async function computeL2ToL1MembershipWitness(
+  messageRetriever: MessageRetrieval,
+  epoch: EpochNumber,
+  message: Fr,
+): Promise<L2ToL1MembershipWitness | undefined> {
+  const messagesInEpoch = await messageRetriever.getL2ToL1Messages(epoch);
+  if (messagesInEpoch.length === 0) {
+    return undefined;
+  }
+
+  return computeL2ToL1MembershipWitnessFromMessagesInEpoch(messagesInEpoch, message);
+}
+
+// TODO: Allow to specify the message to consume by its index or by an offset, in case there are multiple messages with
+// the same value.
+export function computeL2ToL1MembershipWitnessFromMessagesInEpoch(
+  messagesInEpoch: Fr[][][][],
+  message: Fr,
+): L2ToL1MembershipWitness {
+  // Find the index of the message in the tx, index of the tx in the block, and index of the block in the epoch.
+  let messageIndexInTx = -1;
+  let txIndex = -1;
+  let blockIndex = -1;
+  const checkpointIndex = messagesInEpoch.findIndex(messagesInCheckpoint => {
+    blockIndex = messagesInCheckpoint.findIndex(messagesInBlock => {
+      txIndex = messagesInBlock.findIndex(messagesInTx => {
+        messageIndexInTx = messagesInTx.findIndex(msg => msg.equals(message));
+        return messageIndexInTx !== -1;
+      });
+      return txIndex !== -1;
+    });
+    return blockIndex !== -1;
+  });
+
+  if (checkpointIndex === -1) {
+    throw new Error('The L2ToL1Message you are trying to prove inclusion of does not exist');
+  }
+
+  // Build the tx tree.
+  const messagesInTx = messagesInEpoch[checkpointIndex][blockIndex][txIndex];
+  const txTree = UnbalancedMerkleTreeCalculator.create(messagesInTx.map(msg => msg.toBuffer()));
+  // Get the sibling path of the target message in the tx tree.
+  const pathToMessageInTxSubtree = txTree.getSiblingPathByLeafIndex(messageIndexInTx);
+
+  // Build the tree of the block containing the target message.
+  const blockTree = buildBlockTree(messagesInEpoch[checkpointIndex][blockIndex]);
+  // Get the sibling path of the tx out hash in the block tree.
+  const pathToTxOutHashInBlockTree = blockTree.getSiblingPathByLeafIndex(txIndex);
+
+  // Build the tree of the checkpoint containing the target message.
+  const checkpointTree = buildCheckpointTree(messagesInEpoch[checkpointIndex]);
+  // Get the sibling path of the block out hash in the checkpoint tree.
+  const pathToBlockOutHashInCheckpointTree = checkpointTree.getSiblingPathByLeafIndex(blockIndex);
+
+  // Compute the out hashes of all checkpoints in the epoch.
+  let checkpointOutHashes = messagesInEpoch.map((messagesInCheckpoint, i) => {
+    if (i === checkpointIndex) {
+      return checkpointTree.getRoot();
+    }
+    return buildCheckpointTree(messagesInCheckpoint).getRoot();
+  });
+  // Pad to AZTEC_MAX_EPOCH_DURATION with zeros.
+  checkpointOutHashes = checkpointOutHashes.concat(
+    Array.from({ length: OUT_HASH_TREE_LEAF_COUNT - messagesInEpoch.length }, () => Buffer.alloc(32)),
+  );
+
+  // Build the epoch tree with all the checkpoint out hashes, including the padded zeros.
+  // Note: The epoch tree is actually a balanced tree, but we use an unbalanced tree calculator here to avoid turning
+  // this function into async.
+  const epochTree = UnbalancedMerkleTreeCalculator.create(checkpointOutHashes);
+  // Get the sibling path of the checkpoint out hash in the epoch tree.
+  const pathToCheckpointOutHashInEpochTree = epochTree.getSiblingPathByLeafIndex(checkpointIndex);
+
+  // The root of the epoch tree should match the `out_hash` in the root rollup's public inputs.
+  const root = Fr.fromBuffer(epochTree.getRoot());
+
+  // Compute the combined sibling path by appending the tx subtree path to the block tree path, then to the checkpoint
+  // tree path, then to the epoch tree path.
+  const combinedPath = pathToMessageInTxSubtree
+    .toBufferArray()
+    .concat(pathToTxOutHashInBlockTree.toBufferArray())
+    .concat(pathToBlockOutHashInCheckpointTree.toBufferArray())
+    .concat(pathToCheckpointOutHashInEpochTree.toBufferArray());
+
+  // Compute the combined index.
+  // It is the index of the message in the balanced tree (by filling up the wonky tree with empty nodes) at its current
+  // height. It's used to validate the membership proof.
+  const messageLeafPosition = txTree.getLeafLocation(messageIndexInTx);
+  const txLeafPosition = blockTree.getLeafLocation(txIndex);
+  const blockLeafPosition = checkpointTree.getLeafLocation(blockIndex);
+  const checkpointLeafPosition = epochTree.getLeafLocation(checkpointIndex);
+  const numLeavesInLeftCheckpoints = checkpointLeafPosition.index * (1 << blockLeafPosition.level);
+  const indexAtCheckpointLevel = numLeavesInLeftCheckpoints + blockLeafPosition.index;
+  const numLeavesInLeftBlocks = indexAtCheckpointLevel * (1 << txLeafPosition.level);
+  const indexAtTxLevel = numLeavesInLeftBlocks + txLeafPosition.index;
+  const numLeavesInLeftTxs = indexAtTxLevel * (1 << messageLeafPosition.level);
+  const combinedIndex = numLeavesInLeftTxs + messageLeafPosition.index;
+
+  return {
+    root,
+    leafIndex: BigInt(combinedIndex),
+    siblingPath: new SiblingPath(combinedPath.length, combinedPath),
+  };
+}
+
+function buildCheckpointTree(messagesInCheckpoint: Fr[][][]) {
+  const blockOutHashes = messagesInCheckpoint.map(messagesInBlock => buildBlockTree(messagesInBlock).getRoot());
+  return buildCompressedTree(blockOutHashes);
+}
+
+function buildBlockTree(messagesInBlock: Fr[][]) {
+  const txOutHashes = messagesInBlock.map(messages => computeUnbalancedShaRoot(messages.map(msg => msg.toBuffer())));
+  return buildCompressedTree(txOutHashes);
+}
+
+function buildCompressedTree(leaves: Buffer[]) {
+  // Note: If a block or tx has no messages (i.e. leaf == Buffer.alloc(32)), we ignore that branch and only accumulate
+  // the non-zero hashes to match what the circuits do.
+  const valueToCompress = Buffer.alloc(32);
+  return UnbalancedMerkleTreeCalculator.create(leaves, valueToCompress);
+}

package/src/messaging/l2_to_l1_message.ts

@@ -1,25 +1,25 @@
-import { L2_TO_L1_MESSAGE_LENGTH, SCOPED_L2_TO_L1_MESSAGE_LENGTH } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { Fr } from '@aztec/foundation/fields';
 import { schemas } from '@aztec/foundation/schemas';
 import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
-import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
 import { AztecAddress } from '../aztec-address/index.js';
 
 export class L2ToL1Message {
-  constructor(public recipient: EthAddress, public content: Fr, public counter: number) {}
+  constructor(
+    public recipient: EthAddress,
+    public content: Fr,
+  ) {}
 
   static get schema() {
     return z
       .object({
         recipient: schemas.EthAddress,
         content: schemas.Fr,
-        counter: z.number().int().nonnegative(),
       })
-      .transform(({ recipient, content, counter }) => new L2ToL1Message(recipient, content, counter));
+      .transform(({ recipient, content }) => new L2ToL1Message(recipient, content));
   }
 
   /**
@@ -27,7 +27,18 @@ export class L2ToL1Message {
    * @returns An instance of L2ToL1Message with empty fields.
    */
   static empty(): L2ToL1Message {
-    return new L2ToL1Message(EthAddress.ZERO, Fr.zero(), 0);
+    return new L2ToL1Message(EthAddress.ZERO, Fr.zero());
+  }
+
+  /**
+   * Creates an L2ToL1Message instance from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing L2ToL1Message fields
+   * @returns An L2ToL1Message instance
+   */
+  static fromPlainObject(obj: any): L2ToL1Message {
+    return new L2ToL1Message(EthAddress.fromPlainObject(obj.recipient), Fr.fromPlainObject(obj.content));
   }
 
   /**
@@ -36,9 +47,7 @@ export class L2ToL1Message {
    * @returns True if both recipient and content are equal.
    */
   equals(other: L2ToL1Message): boolean {
-    return (
-      this.recipient.equals(other.recipient) && this.content.equals(other.content) && this.counter === other.counter
-    );
+    return this.recipient.equals(other.recipient) && this.content.equals(other.content);
   }
 
   /**
@@ -46,7 +55,7 @@ export class L2ToL1Message {
    * @returns The buffer.
    */
   toBuffer(): Buffer {
-    return serializeToBuffer(this.recipient, this.content, this.counter);
+    return serializeToBuffer(this.recipient, this.content);
   }
 
   /**
@@ -54,13 +63,7 @@ export class L2ToL1Message {
    * @returns An array of fields representing the serialized message.
    */
   toFields(): Fr[] {
-    const fields = [this.recipient.toField(), this.content, new Fr(this.counter)];
-    if (fields.length !== L2_TO_L1_MESSAGE_LENGTH) {
-      throw new Error(
-        `Invalid number of fields for L2ToL1Message. Expected ${L2_TO_L1_MESSAGE_LENGTH}, got ${fields.length}`,
-      );
-    }
-    return fields;
+    return [this.recipient.toField(), this.content];
   }
 
   /**
@@ -70,7 +73,7 @@ export class L2ToL1Message {
    */
   static fromFields(fields: Fr[] | FieldReader): L2ToL1Message {
     const reader = FieldReader.asReader(fields);
-    return new L2ToL1Message(reader.readObject(EthAddress), reader.readField(), reader.readU32());
+    return new L2ToL1Message(reader.readObject(EthAddress), reader.readField());
   }
 
   /**
@@ -80,7 +83,7 @@ export class L2ToL1Message {
    */
   static fromBuffer(buffer: Buffer | BufferReader): L2ToL1Message {
     const reader = BufferReader.asReader(buffer);
-    return new L2ToL1Message(reader.readObject(EthAddress), reader.readObject(Fr), reader.readNumber());
+    return new L2ToL1Message(reader.readObject(EthAddress), reader.readObject(Fr));
   }
 
   /**
@@ -88,16 +91,61 @@ export class L2ToL1Message {
    * @returns True if both recipient and content are zero.
    */
   isEmpty(): boolean {
-    return this.recipient.isZero() && this.content.isZero() && !this.counter;
+    return this.recipient.isZero() && this.content.isZero();
   }
 
-  scope(contractAddress: AztecAddress) {
+  scope(contractAddress: AztecAddress): ScopedL2ToL1Message {
     return new ScopedL2ToL1Message(this, contractAddress);
   }
 }
 
+export class CountedL2ToL1Message {
+  constructor(
+    public message: L2ToL1Message,
+    public counter: number,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        message: L2ToL1Message.schema,
+        counter: z.number().int().nonnegative(),
+      })
+      .transform(({ message, counter }) => new CountedL2ToL1Message(message, counter));
+  }
+
+  static empty() {
+    return new CountedL2ToL1Message(L2ToL1Message.empty(), 0);
+  }
+
+  isEmpty(): boolean {
+    return this.message.isEmpty() && !this.counter;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new CountedL2ToL1Message(reader.readObject(L2ToL1Message), reader.readNumber());
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer(this.message, this.counter);
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new CountedL2ToL1Message(reader.readObject(L2ToL1Message), reader.readU32());
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields(this.message, this.counter);
+  }
+}
+
 export class ScopedL2ToL1Message {
-  constructor(public message: L2ToL1Message, public contractAddress: AztecAddress) {}
+  constructor(
+    public message: L2ToL1Message,
+    public contractAddress: AztecAddress,
+  ) {}
 
   static get schema() {
     return z
@@ -108,10 +156,6 @@ export class ScopedL2ToL1Message {
       .transform(({ message, contractAddress }) => new ScopedL2ToL1Message(message, contractAddress));
   }
 
-  static getFields(fields: FieldsOf<ScopedL2ToL1Message>) {
-    return [fields.message, fields.contractAddress] as const;
-  }
-
   static empty() {
     return new ScopedL2ToL1Message(L2ToL1Message.empty(), AztecAddress.ZERO);
   }
@@ -120,8 +164,22 @@ export class ScopedL2ToL1Message {
     return this.message.equals(other.message) && this.contractAddress.equals(other.contractAddress);
   }
 
-  toBuffer(): Buffer {
-    return serializeToBuffer(this.message, this.contractAddress);
+  /**
+   * Creates a ScopedL2ToL1Message instance from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing ScopedL2ToL1Message fields
+   * @returns A ScopedL2ToL1Message instance
+   */
+  static fromPlainObject(obj: any): ScopedL2ToL1Message {
+    return new ScopedL2ToL1Message(
+      L2ToL1Message.fromPlainObject(obj.message),
+      AztecAddress.fromPlainObject(obj.contractAddress),
+    );
+  }
+
+  isEmpty(): boolean {
+    return this.message.isEmpty() && this.contractAddress.isZero();
   }
 
   static fromBuffer(buffer: Buffer | BufferReader) {
@@ -129,22 +187,58 @@ export class ScopedL2ToL1Message {
     return new ScopedL2ToL1Message(reader.readObject(L2ToL1Message), reader.readObject(AztecAddress));
   }
 
+  toBuffer(): Buffer {
+    return serializeToBuffer(this.message, this.contractAddress);
+  }
+
   static fromFields(fields: Fr[] | FieldReader) {
     const reader = FieldReader.asReader(fields);
     return new ScopedL2ToL1Message(reader.readObject(L2ToL1Message), reader.readObject(AztecAddress));
   }
 
   toFields(): Fr[] {
-    const fields = serializeToFields(...ScopedL2ToL1Message.getFields(this));
-    if (fields.length !== SCOPED_L2_TO_L1_MESSAGE_LENGTH) {
-      throw new Error(
-        `Invalid number of fields for ScopedL2ToL1Message. Expected ${SCOPED_L2_TO_L1_MESSAGE_LENGTH}, got ${fields.length}`,
-      );
-    }
-    return fields;
+    return serializeToFields(this.message, this.contractAddress);
+  }
+}
+
+export class ScopedCountedL2ToL1Message {
+  constructor(
+    public inner: CountedL2ToL1Message,
+    public contractAddress: AztecAddress,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        inner: CountedL2ToL1Message.schema,
+        contractAddress: AztecAddress.schema,
+      })
+      .transform(({ inner, contractAddress }) => new ScopedCountedL2ToL1Message(inner, contractAddress));
+  }
+
+  static empty() {
+    return new ScopedCountedL2ToL1Message(CountedL2ToL1Message.empty(), AztecAddress.ZERO);
   }
 
   isEmpty(): boolean {
-    return this.message.isEmpty() && this.contractAddress.isZero();
+    return this.inner.isEmpty() && this.contractAddress.isZero();
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new ScopedCountedL2ToL1Message(reader.readObject(CountedL2ToL1Message), reader.readObject(AztecAddress));
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer(this.inner, this.contractAddress);
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new ScopedCountedL2ToL1Message(reader.readObject(CountedL2ToL1Message), reader.readObject(AztecAddress));
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields(this.inner, this.contractAddress);
   }
 }

package/src/messaging/out_hash.ts

@@ -0,0 +1,77 @@
+import { OUT_HASH_TREE_LEAF_COUNT } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { computeBalancedShaRoot, computeUnbalancedShaRoot, computeWonkyShaRoot } from '@aztec/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

@@ -8,11 +8,12 @@ import type {
   DebugInfo,
 } from '../abi/abi.js';
 
-export const AZTEC_PRIVATE_ATTRIBUTE = 'private';
-export const AZTEC_PUBLIC_ATTRIBUTE = 'public';
-export const AZTEC_INTERNAL_ATTRIBUTE = 'internal';
-export const AZTEC_INITIALIZER_ATTRIBUTE = 'initializer';
-export const AZTEC_VIEW_ATTRIBUTE = 'view';
+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 {
@@ -36,7 +37,7 @@ export interface NoirFunctionAbi {
 /**
  * The compilation result of an Aztec.nr function.
  */
-export interface NoirFunctionEntry {
+interface NoirFunctionEntry {
   /** The name of the function. */
   name: string;
   /** Whether the function is unconstrained. */
@@ -63,6 +64,8 @@ export interface NoirFunctionEntry {
 export interface NoirCompiledContract {
   /** The name of the contract. */
   name: string;
+  /** Is the contract's public bytecode transpiled? */
+  transpiled?: boolean;
   /** The functions of the contract. */
   functions: NoirFunctionEntry[];
   /** The events of the contract */
@@ -75,7 +78,7 @@ export interface NoirCompiledContract {
 }
 
 /**
- * The compilation result of an Aztec.nr contract.
+ * The compilation result of a protocol (non-contract) circuit.
  */
 export interface NoirCompiledCircuit {
   /** The hash of the circuit. */
@@ -86,12 +89,26 @@ export interface NoirCompiledCircuit {
   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.
  */

package/src/note/index.ts

@@ -1,5 +1,5 @@
 export * from './comparator.js';
-export * from './extended_note.js';
+export * from './note_dao.js';
 export * from './notes_filter.js';
 export * from './note_status.js';
 export * from './note.js';