@aztec/stdlib 0.0.1-commit.fce3e4f → 0.0.1-commit.ff7989d6c

package/src/logs/tag.ts

@@ -0,0 +1,42 @@
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { schemas } from '../schemas/schemas.js';
+import type { PreTag } from './pre_tag.js';
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+export interface Tag {
+  /** Brand. */
+  _branding: 'Tag';
+}
+
+/**
+ * Represents a tag of a private log. This is not the tag that "appears" on the chain as this tag is first siloed
+ * with a contract address by kernels before being included in the final log.
+ */
+export class Tag {
+  constructor(public readonly value: Fr) {}
+
+  static async compute(preTag: PreTag): Promise<Tag> {
+    const tag = await poseidon2Hash([preTag.secret.value, preTag.index]);
+    return new Tag(tag);
+  }
+
+  toString(): string {
+    return this.value.toString();
+  }
+
+  toJSON(): string {
+    return this.value.toString();
+  }
+
+  equals(other: Tag): boolean {
+    return this.value.equals(other.value);
+  }
+
+  static get schema(): ZodFor<Tag> {
+    return schemas.Fr.transform((fr: Fr) => new Tag(fr));
+  }
+}

package/src/logs/tx_scoped_l2_log.ts

@@ -1,12 +1,19 @@
-import { BufferReader, boolToBuffer, numToUInt32BE } from '@aztec/foundation/serialize';
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas as foundationSchemas } from '@aztec/foundation/schemas';
+import {
+  BufferReader,
+  bigintToUInt64BE,
+  numToUInt32BE,
+  serializeArrayOfBufferableToVector,
+} from '@aztec/foundation/serialize';
 
 import { z } from 'zod';
 
+import { schemas } from '../schemas/schemas.js';
 import { TxHash } from '../tx/tx_hash.js';
-import { PrivateLog } from './private_log.js';
-import { PublicLog } from './public_log.js';
+import type { UInt64 } from '../types/shared.js';
 
-// TODO(#14460): Split to private and public versions instead of having this weird mix.
 export class TxScopedL2Log {
   constructor(
     /*
@@ -14,82 +21,78 @@ export class TxScopedL2Log {
      */
     public txHash: TxHash,
     /*
-     * The next available leaf index for the note hash tree for this transaction. It is stored
-     * with the log so the noteHashIndex can be reconstructed after decryption.
+     * The block this log is included in
      */
-    public dataStartIndexForTx: number,
+    public blockNumber: BlockNumber,
     /*
-     * The index of the log in the transaction. Note that public and private logs are in separate arrays in the tx
-     * effect and for this reason these indices are independent (a private and public log can have the same index).
+     * The timestamp of the block this log is included in
      */
-    public logIndexInTx: number,
+    public blockTimestamp: UInt64,
     /*
-     * The block this log is included in
+     * The log data as an array of field elements
+     */
+    public logData: Fr[],
+    /*
+     * The note hashes from the tx effect
      */
-    public blockNumber: number,
+    public noteHashes: Fr[],
     /*
-     * The log data as either a PrivateLog or PublicLog
+     * The first nullifier from the tx effect. Used for nonce discovery when processing notes from logs.
+     *
+     * (Note nonces are computed as `hash(firstNullifier, noteIndexInTx)`.)
      */
-    public log: PrivateLog | PublicLog,
+    public firstNullifier: Fr,
   ) {}
 
-  get isFromPublic() {
-    return this.log instanceof PublicLog;
-  }
-
   static get schema() {
     return z
       .object({
         txHash: TxHash.schema,
-        dataStartIndexForTx: z.number(),
-        logIndexInTx: z.number(),
-        blockNumber: z.number(),
-        log: z.union([PrivateLog.schema, PublicLog.schema]),
+        blockNumber: BlockNumberSchema,
+        blockTimestamp: schemas.UInt64,
+        logData: z.array(foundationSchemas.Fr),
+        noteHashes: z.array(foundationSchemas.Fr),
+        firstNullifier: foundationSchemas.Fr,
       })
       .transform(
-        ({ txHash, dataStartIndexForTx, logIndexInTx, blockNumber, log }) =>
-          new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, log),
+        ({ txHash, blockNumber, blockTimestamp, logData, noteHashes, firstNullifier }) =>
+          new TxScopedL2Log(txHash, blockNumber, blockTimestamp, logData, noteHashes, firstNullifier),
       );
   }
 
   toBuffer() {
-    const isFromPublic = this.log instanceof PublicLog;
     return Buffer.concat([
       this.txHash.toBuffer(),
-      numToUInt32BE(this.dataStartIndexForTx),
-      numToUInt32BE(this.logIndexInTx),
       numToUInt32BE(this.blockNumber),
-      boolToBuffer(isFromPublic),
-      this.log.toBuffer(),
+      bigintToUInt64BE(this.blockTimestamp),
+      serializeArrayOfBufferableToVector(this.logData),
+      serializeArrayOfBufferableToVector(this.noteHashes),
+      this.firstNullifier.toBuffer(),
     ]);
   }
 
   static fromBuffer(buffer: Buffer) {
     const reader = BufferReader.asReader(buffer);
     const txHash = reader.readObject(TxHash);
-    const dataStartIndexForTx = reader.readNumber();
-    const logIndexInTx = reader.readNumber();
-    const blockNumber = reader.readNumber();
-    const isFromPublic = reader.readBoolean();
-    const log = isFromPublic ? PublicLog.fromBuffer(reader) : PrivateLog.fromBuffer(reader);
-
-    return new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, log);
-  }
+    const blockNumber = BlockNumber(reader.readNumber());
+    const blockTimestamp = reader.readUInt64();
+    const logData = reader.readVector(Fr);
+    const noteHashes = reader.readVector(Fr);
+    const firstNullifier = reader.readObject(Fr);
 
-  static async random(isFromPublic = Math.random() < 0.5) {
-    const log = isFromPublic ? await PublicLog.random() : PrivateLog.random();
-    return new TxScopedL2Log(TxHash.random(), 1, 1, 1, log);
+    return new TxScopedL2Log(txHash, blockNumber, blockTimestamp, logData, noteHashes, firstNullifier);
   }
 
   equals(other: TxScopedL2Log) {
     return (
       this.txHash.equals(other.txHash) &&
-      this.dataStartIndexForTx === other.dataStartIndexForTx &&
-      this.logIndexInTx === other.logIndexInTx &&
       this.blockNumber === other.blockNumber &&
-      ((this.log instanceof PublicLog && other.log instanceof PublicLog) ||
-        (this.log instanceof PrivateLog && other.log instanceof PrivateLog)) &&
-      this.log.equals(other.log as any)
+      this.blockTimestamp === other.blockTimestamp &&
+      this.logData.length === other.logData.length &&
+      this.logData.every((f, i) => f.equals(other.logData[i])) &&
+      this.noteHashes.length === other.noteHashes.length &&
+      this.noteHashes.every((h, i) => h.equals(other.noteHashes[i])) &&
+      this.firstNullifier.equals(other.firstNullifier)
     );
   }
 }

package/src/messaging/in_hash.ts

@@ -1,9 +1,11 @@
 import { NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
 import { padArrayEnd } from '@aztec/foundation/collection';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { computeBalancedShaRoot } from '@aztec/foundation/trees';
 
-/** Computes the inHash for a block's ContentCommitment given its l1 to l2 messages. */
+/**
+ * Computes the inHash for a checkpoint (or the first block in a checkpoint) given its l1 to l2 messages.
+ */
 export function computeInHashFromL1ToL2Messages(unpaddedL1ToL2Messages: Fr[]): Fr {
   const l1ToL2Messages = padArrayEnd<Fr, number>(unpaddedL1ToL2Messages, Fr.ZERO, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP);
   return new Fr(computeBalancedShaRoot(l1ToL2Messages.map(msg => msg.toBuffer())));

package/src/messaging/inbox_leaf.ts

@@ -1,6 +1,7 @@
-import { INITIAL_L2_BLOCK_NUM, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
+import { INITIAL_CHECKPOINT_NUMBER, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
 import { toBigIntBE } from '@aztec/foundation/bigint-buffer';
-import { Fr } from '@aztec/foundation/fields';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
 export class InboxLeaf {
@@ -22,22 +23,22 @@ export class InboxLeaf {
     return new InboxLeaf(index, leaf);
   }
 
-  static smallestIndexFromL2Block(l2blockNumber: number): bigint {
-    return BigInt(l2blockNumber - INITIAL_L2_BLOCK_NUM) * BigInt(NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP);
+  static smallestIndexForCheckpoint(checkpointNumber: CheckpointNumber): bigint {
+    return BigInt(checkpointNumber - INITIAL_CHECKPOINT_NUMBER) * BigInt(NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP);
   }
 
   /**
-   * Returns the range of valid indices for a given L2 block.
+   * Returns the range of valid indices for a given checkpoint.
    * Start index is inclusive, end index is exclusive.
    */
-  static indexRangeFromL2Block(l2blockNumber: number): [bigint, bigint] {
-    const start = this.smallestIndexFromL2Block(l2blockNumber);
+  static indexRangeForCheckpoint(checkpointNumber: CheckpointNumber): [bigint, bigint] {
+    const start = this.smallestIndexForCheckpoint(checkpointNumber);
     const end = start + BigInt(NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP);
     return [start, end];
   }
 
-  /** Returns the L2 block number for a given leaf index */
-  static l2BlockFromIndex(index: bigint): number {
-    return Number(index / BigInt(NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP)) + INITIAL_L2_BLOCK_NUM;
+  /** Returns the checkpoint number for a given leaf index */
+  static checkpointNumberFromIndex(index: bigint): CheckpointNumber {
+    return CheckpointNumber(Number(index / BigInt(NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP)) + INITIAL_CHECKPOINT_NUMBER);
   }
 }

package/src/messaging/l1_actor.ts

@@ -1,6 +1,6 @@
-import { randomInt } from '@aztec/foundation/crypto';
+import { randomInt } from '@aztec/foundation/crypto/random';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { Fr } from '@aztec/foundation/fields';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
 /**

package/src/messaging/l1_to_l2_message.ts

@@ -1,6 +1,6 @@
 import type { L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/constants';
-import { sha256ToField } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import { sha256ToField } from '@aztec/foundation/crypto/sha256';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import { bufferToHex } from '@aztec/foundation/string';
 import { SiblingPath } from '@aztec/foundation/trees';
@@ -84,6 +84,7 @@ export async function getNonNullifiedL1ToL2MessageWitness(
   if (!response) {
     throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
   }
+
   const [messageIndex, siblingPath] = response;
 
   const messageNullifier = await computeL1ToL2MessageNullifier(contractAddress, messageHash, secret);

package/src/messaging/l1_to_l2_message_source.ts

@@ -1,4 +1,5 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 
 import type { L2Tips } from '../block/l2_block_source.js';
 
@@ -7,11 +8,11 @@ import type { L2Tips } from '../block/l2_block_source.js';
  */
 export interface L1ToL2MessageSource {
   /**
-   * Gets new L1 to L2 message (to be) included in a given block.
-   * @param blockNumber - L2 block number to get messages for.
+   * Gets new L1 to L2 message (to be) included in a given checkpoint.
+   * @param checkpointNumber - Checkpoint number to get messages for.
    * @returns The L1 to L2 messages/leaves of the messages subtree (throws if not found).
    */
-  getL1ToL2Messages(blockNumber: number): Promise<Fr[]>;
+  getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]>;
 
   /**
    * Gets the L1 to L2 message index in the L1 to L2 message tree.
@@ -20,12 +21,6 @@ export interface L1ToL2MessageSource {
    */
   getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined>;
 
-  /**
-   * Gets the number of the latest L2 block processed by the implementation.
-   * @returns The number of the latest L2 block processed by the implementation.
-   */
-  getBlockNumber(): Promise<number>;
-
   /**
    * Returns the tips of the L2 chain.
    */

package/src/messaging/l2_actor.ts

@@ -1,5 +1,5 @@
-import { randomInt } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import { randomInt } from '@aztec/foundation/crypto/random';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
 import { AztecAddress } from '../aztec-address/index.js';

package/src/messaging/l2_to_l1_membership.ts

@@ -1,8 +1,99 @@
-import { Fr } from '@aztec/foundation/fields';
+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 OUT_HASH_TREE_LEAF_COUNT)
+ *    - 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 OUT_HASH_TREE_LEAF_COUNT 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(l2BlockNumber: number): Promise<Fr[][] | undefined>;
+  getL2ToL1Messages(epoch: EpochNumber): Promise<Fr[][][][]>;
 }
 
 export type L2ToL1MembershipWitness = {
@@ -13,76 +104,101 @@ export type L2ToL1MembershipWitness = {
 
 export async function computeL2ToL1MembershipWitness(
   messageRetriever: MessageRetrieval,
-  l2BlockNumber: number,
+  epoch: EpochNumber,
   message: Fr,
 ): Promise<L2ToL1MembershipWitness | undefined> {
-  const messagesForAllTxs = await messageRetriever.getL2ToL1Messages(l2BlockNumber);
-  if (!messagesForAllTxs) {
+  const messagesInEpoch = await messageRetriever.getL2ToL1Messages(epoch);
+  if (messagesInEpoch.length === 0) {
     return undefined;
   }
 
-  return computeL2ToL1MembershipWitnessFromMessagesForAllTxs(messagesForAllTxs, message);
+  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 computeL2ToL1MembershipWitnessFromMessagesForAllTxs(
-  messagesForAllTxs: Fr[][],
+export function computeL2ToL1MembershipWitnessFromMessagesInEpoch(
+  messagesInEpoch: Fr[][][][],
   message: Fr,
 ): L2ToL1MembershipWitness {
-  // Find index of message in subtree and index of tx in a block.
+  // 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;
-  const txIndex = messagesForAllTxs.findIndex(messages => {
-    messageIndexInTx = messages.findIndex(msg => msg.equals(message));
-    return 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 (txIndex === -1) {
+  if (checkpointIndex === -1) {
     throw new Error('The L2ToL1Message you are trying to prove inclusion of does not exist');
   }
 
-  // Get the txOutHash and the sibling path of the message in the tx subtree.
-  const txMessages = messagesForAllTxs[txIndex];
-  const txOutHashTree = UnbalancedMerkleTreeCalculator.create(txMessages.map(msg => msg.toBuffer()));
-  const txOutHash = txOutHashTree.getRoot();
-  const messagePathInSubtree = txOutHashTree.getSiblingPath(message.toBuffer());
-
-  // Calculate txOutHash for all txs.
-  const txSubtreeRoots = messagesForAllTxs.map((messages, i) => {
-    // For a tx with no messages, we have to set an out hash of 0 to match what the circuit does.
-    if (messages.length === 0) {
-      return Fr.ZERO;
-    }
+  // 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);
 
-    if (i === txIndex) {
-      return Fr.fromBuffer(txOutHash);
-    }
+  // 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);
 
-    const root = computeUnbalancedShaRoot(messages.map(msg => msg.toBuffer()));
-    return Fr.fromBuffer(root);
-  });
+  // 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);
 
-  // Construct the top tree.
-  // The leaves of this tree are the `txOutHashes`.
-  // The root of this tree should match the `out_hash` calculated in the circuits. Zero hashes are compressed to reduce
-  // cost if the non-zero leaves result in a shorter path.
-  const valueToCompress = Buffer.alloc(32);
-  const topTree = UnbalancedMerkleTreeCalculator.create(
-    txSubtreeRoots.map(root => root.toBuffer()),
-    valueToCompress,
+  // 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 OUT_HASH_TREE_LEAF_COUNT with zeros.
+  checkpointOutHashes = checkpointOutHashes.concat(
+    Array.from({ length: OUT_HASH_TREE_LEAF_COUNT - messagesInEpoch.length }, () => Buffer.alloc(32)),
   );
-  const root = Fr.fromBuffer(topTree.getRoot());
 
-  // Compute the combined sibling path by appending the tx subtree path to the top tree path.
-  const txPathInTopTree = topTree.getSiblingPath(txOutHash);
-  const combinedPath = messagePathInSubtree.toBufferArray().concat(txPathInTopTree.toBufferArray());
+  // 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 at its current height.
-  const txLeafIndexAtLevel = topTree.getLeafLocation(txIndex).index;
-  const messageLeafPosition = txOutHashTree.getLeafLocation(messageIndexInTx);
-  const numLeavesInLeftSubtrees = txLeafIndexAtLevel * (1 << messageLeafPosition.level);
-  const combinedIndex = numLeavesInLeftSubtrees + messageLeafPosition.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,
@@ -91,8 +207,19 @@ export function computeL2ToL1MembershipWitnessFromMessagesForAllTxs(
   };
 }
 
-export function getL2ToL1MessageLeafId(
-  membershipWitness: Pick<L2ToL1MembershipWitness, 'leafIndex' | 'siblingPath'>,
-): bigint {
-  return 2n ** BigInt(membershipWitness.siblingPath.pathSize) + membershipWitness.leafIndex;
+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,5 +1,5 @@
+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';
 
@@ -160,6 +160,10 @@ export class ScopedL2ToL1Message {
     return new ScopedL2ToL1Message(L2ToL1Message.empty(), AztecAddress.ZERO);
   }
 
+  equals(other: ScopedL2ToL1Message): boolean {
+    return this.message.equals(other.message) && this.contractAddress.equals(other.contractAddress);
+  }
+
   /**
    * Creates a ScopedL2ToL1Message instance from a plain object without Zod validation.
    * This method is optimized for performance and skips validation, making it suitable