@aztec/stdlib 0.0.1-commit.3469e52 → 0.0.1-commit.350e0a4d

package/src/logs/query_all_logs_by_tags.ts

@@ -0,0 +1,98 @@
+import { MAX_LOGS_PER_TAG } from '../interfaces/api_limit.js';
+import { LogCursor } from './log_cursor.js';
+import type { LogResult } from './log_result.js';
+import type { PrivateLogsQuery, PublicLogsQuery, TagQuery } from './logs_query.js';
+import type { SiloedTag } from './siloed_tag.js';
+import type { Tag } from './tag.js';
+
+/** Minimal node surface needed by {@link queryAllPrivateLogsByTags}. */
+export type PrivateLogsByTagsFetcher = {
+  getPrivateLogsByTags(query: PrivateLogsQuery): Promise<LogResult[][]>;
+};
+
+/** Minimal node surface needed by {@link queryAllPublicLogsByTags}. */
+export type PublicLogsByTagsFetcher = {
+  getPublicLogsByTags(query: PublicLogsQuery): Promise<LogResult[][]>;
+};
+
+/**
+ * Drives the per-tag `afterLog` cursor loop for {@link PrivateLogsByTagsFetcher.getPrivateLogsByTags}.
+ *
+ * Each round re-queries only the tags whose previous page was full (`length === effective limit`), passing
+ * the cursor of the last seen log. Tags drop out as soon as they return a short page. Results are stitched
+ * back into one inner array per input tag, preserving the original input order.
+ *
+ * Honors {@link PrivateLogsQuery.limitPerTag} when set (caller is responsible for keeping it `<=`
+ * {@link MAX_LOGS_PER_TAG}; the query schema enforces this on the RPC boundary).
+ */
+export function queryAllPrivateLogsByTags(
+  node: PrivateLogsByTagsFetcher,
+  query: PrivateLogsQuery,
+): Promise<LogResult[][]> {
+  return queryAllByTags(
+    query.tags,
+    tagQueries => node.getPrivateLogsByTags({ ...query, tags: tagQueries }),
+    query.limitPerTag,
+  );
+}
+
+/** {@inheritDoc queryAllPrivateLogsByTags} */
+export function queryAllPublicLogsByTags(
+  node: PublicLogsByTagsFetcher,
+  query: PublicLogsQuery,
+): Promise<LogResult[][]> {
+  return queryAllByTags(
+    query.tags,
+    tagQueries => node.getPublicLogsByTags({ ...query, tags: tagQueries }),
+    query.limitPerTag,
+  );
+}
+
+/**
+ * Generic per-tag pagination loop, abstracted over the query shape (private vs public). Caller supplies
+ * a `fetchPage` that runs one round against the node with the still-active subset of tag queries.
+ *
+ * @param tags - Input tag queries in original order. Returned outer array has the same length and order.
+ * @param fetchPage - Per-round fetch hook; receives the active subset and returns one page per active tag.
+ * @param limitPerTag - Effective page cap used to detect "full page" → keep paginating; defaults to
+ *   {@link MAX_LOGS_PER_TAG} (the server-side cap when the query doesn't override).
+ */
+async function queryAllByTags<T extends Tag | SiloedTag>(
+  tags: TagQuery<T>[],
+  fetchPage: (tagQueries: TagQuery<T>[]) => Promise<LogResult[][]>,
+  limitPerTag: number | undefined,
+): Promise<LogResult[][]> {
+  const effectiveLimit = limitPerTag ?? MAX_LOGS_PER_TAG;
+  const allResultsPerTag: LogResult[][] = tags.map(() => []);
+  let activeIndexes = tags.map((_, i) => i);
+  let nextQueries: TagQuery<T>[] = tags.slice();
+
+  while (activeIndexes.length > 0) {
+    const pageResults = await fetchPage(nextQueries);
+
+    const stillActive: number[] = [];
+    const followups: TagQuery<T>[] = [];
+    for (let i = 0; i < activeIndexes.length; i++) {
+      const originalIdx = activeIndexes[i];
+      const pageForTag = pageResults[i];
+      allResultsPerTag[originalIdx].push(...pageForTag);
+      if (pageForTag.length === effectiveLimit) {
+        const lastLog = pageForTag[pageForTag.length - 1];
+        stillActive.push(originalIdx);
+        followups.push({ tag: tagOf(tags[originalIdx]), afterLog: LogCursor.fromLog(lastLog) });
+      }
+    }
+    activeIndexes = stillActive;
+    nextQueries = followups;
+  }
+
+  return allResultsPerTag;
+}
+
+/** Unwraps a `TagQuery` to its underlying `Tag` / `SiloedTag` regardless of the bare-vs-object form. */
+function tagOf<T extends Tag | SiloedTag>(entry: TagQuery<T>): T {
+  if (typeof entry === 'object' && entry !== null && 'tag' in entry) {
+    return entry.tag;
+  }
+  return entry as T;
+}

package/src/logs/shared_secret_derivation.ts

@@ -1,22 +1,18 @@
+import { DomainSeparator } from '@aztec/constants';
 import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { GrumpkinScalar, Point } from '@aztec/foundation/curves/grumpkin';
 
+import type { AztecAddress } from '../aztec-address/index.js';
 import type { PublicKey } from '../keys/public_key.js';
 
 /**
- * Derive an Elliptic Curve Diffie-Hellman (ECDH) Shared Secret.
- * The function takes in an ECDH public key, a private key, and a Grumpkin instance to compute
- * the shared secret.
+ * Derives the raw ECDH shared secret point `S = secretKey * publicKey`.
  *
- * @param secretKey - The secret key used to derive shared secret.
- * @param publicKey - The public key used to derive shared secret.
- * @returns A derived shared secret.
  * @throws If the publicKey is zero.
- *
- * TODO(#12656): This function is kept around because of the utilityGetSharedSecret oracle. Nuke this once returning
- * the app-siloed secret.
  */
-export function deriveEcdhSharedSecret(secretKey: GrumpkinScalar, publicKey: PublicKey): Promise<Point> {
+export function deriveEcdhSharedSecretPoint(secretKey: GrumpkinScalar, publicKey: PublicKey): Promise<Point> {
   if (publicKey.isZero()) {
     throw new Error(
       `Attempting to derive a shared secret with a zero public key. You have probably passed a zero public key in your Noir code somewhere thinking that the note won't be broadcast... but it was.`,
@@ -24,3 +20,34 @@ export function deriveEcdhSharedSecret(secretKey: GrumpkinScalar, publicKey: Pub
   }
   return Grumpkin.mul(publicKey, secretKey);
 }
+
+/**
+ * Derives an app-siloed ECDH shared secret from keys: ECDHs `S = secretKey * publicKey` via
+ * {@link deriveEcdhSharedSecretPoint}, then app-silos it via {@link appSiloEcdhSharedSecretPoint}.
+ *
+ * @param secretKey - The secret key used to derive shared secret.
+ * @param publicKey - The public key used to derive shared secret.
+ * @param contractAddress - The address of the calling contract, used for app-siloing.
+ * @returns The app-siloed shared secret as a Field.
+ * @throws If the publicKey is zero.
+ */
+export async function appSiloEcdhSharedSecret(
+  secretKey: GrumpkinScalar,
+  publicKey: PublicKey,
+  contractAddress: AztecAddress,
+): Promise<Fr> {
+  const rawSharedSecret = await deriveEcdhSharedSecretPoint(secretKey, publicKey);
+  return appSiloEcdhSharedSecretPoint(rawSharedSecret, contractAddress);
+}
+
+/**
+ * App-silos a shared secret point: `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, app)`.
+ *
+ * Mirrors `compute_app_siloed_shared_secret` in aztec-nr.
+ *
+ * @param point - The raw shared secret point `S`.
+ * @param app - The contract address to silo to.
+ */
+export function appSiloEcdhSharedSecretPoint(point: Point, app: AztecAddress): Promise<Fr> {
+  return poseidon2HashWithSeparator([point.x, point.y, app], DomainSeparator.APP_SILOED_ECDH_SHARED_SECRET);
+}

package/src/logs/siloed_tag.ts

@@ -1,28 +1,39 @@
-import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
-import type { Fr } from '@aztec/foundation/curves/bn254';
+import { DomainSeparator } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { ZodFor } from '@aztec/foundation/schemas';
 
 import type { AztecAddress } from '../aztec-address/index.js';
+import { computeLogTag, computeSiloedPrivateLogFirstField } from '../hash/hash.js';
 import { schemas } from '../schemas/schemas.js';
-import type { Tag } from './tag.js';
-
-/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
-
-/** Branding to ensure fields are not interchangeable types. */
-export interface SiloedTag {
-  /** Brand. */
-  _branding: 'SiloedTag';
-}
+import { AppTaggingSecretKind } from './app_tagging_secret_kind.js';
+import type { PreTag } from './pre_tag.js';
+import { Tag } from './tag.js';
 
 /**
  * Represents a tag used in private log as it "appears on the chain" - that is the tag is siloed with a contract
  * address that emitted the log.
  */
 export class SiloedTag {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'SiloedTag';
+
   constructor(public readonly value: Fr) {}
 
-  static async compute(tag: Tag, app: AztecAddress): Promise<SiloedTag> {
-    const siloedTag = await poseidon2Hash([app, tag.value]);
+  static async compute(preTag: PreTag): Promise<SiloedTag> {
+    const tag = await Tag.compute(preTag);
+    const domainSeparator =
+      preTag.extendedSecret.kind === AppTaggingSecretKind.CONSTRAINED
+        ? DomainSeparator.CONSTRAINED_MSG_LOG_TAG
+        : DomainSeparator.UNCONSTRAINED_MSG_LOG_TAG;
+    const logTag = await computeLogTag(tag.value, domainSeparator);
+    return SiloedTag.computeFromTagAndApp(new Tag(logTag), preTag.extendedSecret.app);
+  }
+
+  /**
+   * Unlike `compute`, this expects a tag whose value is already domain-separated.
+   */
+  static async computeFromTagAndApp(tag: Tag, app: AztecAddress): Promise<SiloedTag> {
+    const siloedTag = await computeSiloedPrivateLogFirstField(app, tag.value);
     return new SiloedTag(siloedTag);
   }
 
@@ -38,6 +49,10 @@ export class SiloedTag {
     return this.value.equals(other.value);
   }
 
+  static random(): SiloedTag {
+    return new SiloedTag(Fr.random());
+  }
+
   static get schema(): ZodFor<SiloedTag> {
     return schemas.Fr.transform((fr: Fr) => new SiloedTag(fr));
   }

package/src/logs/tag.ts

@@ -1,26 +1,22 @@
 import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
-import type { Fr } from '@aztec/foundation/curves/bn254';
+import { 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 {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Tag';
+
   constructor(public readonly value: Fr) {}
 
   static async compute(preTag: PreTag): Promise<Tag> {
-    const tag = await poseidon2Hash([preTag.secret.value, preTag.index]);
+    const tag = await poseidon2Hash([preTag.extendedSecret.secret, preTag.index]);
     return new Tag(tag);
   }
 
@@ -36,6 +32,10 @@ export class Tag {
     return this.value.equals(other.value);
   }
 
+  static random(): Tag {
+    return new Tag(Fr.random());
+  }
+
   static get schema(): ZodFor<Tag> {
     return schemas.Fr.transform((fr: Fr) => new Tag(fr));
   }

package/src/logs/tagging_index_range.ts

@@ -0,0 +1,18 @@
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { type AppTaggingSecret, AppTaggingSecretSchema } from './app_tagging_secret.js';
+
+/** Represents a range of tagging indexes for a given app tagging secret. */
+export type TaggingIndexRange = {
+  extendedSecret: AppTaggingSecret;
+  lowestIndex: number;
+  highestIndex: number;
+};
+
+export const TaggingIndexRangeSchema = z.object({
+  extendedSecret: AppTaggingSecretSchema,
+  lowestIndex: schemas.Integer,
+  highestIndex: schemas.Integer,
+});

package/src/messaging/append_l1_to_l2_messages.ts

@@ -0,0 +1,21 @@
+import { NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { MerkleTreeWriteOperations } from '../interfaces/merkle_tree_operations.js';
+import { MerkleTreeId } from '../trees/merkle_tree_id.js';
+
+/**
+ * Pads `l1ToL2Messages` to `NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP` and appends them to the
+ * L1→L2 message tree of `db`. Use whenever a fork at "state before the first block of a
+ * checkpoint" needs to mirror what the world-state synchronizer inserts at sync time.
+ */
+export async function appendL1ToL2MessagesToTree(db: MerkleTreeWriteOperations, l1ToL2Messages: Fr[]): Promise<void> {
+  const padded = padArrayEnd<Fr, number>(
+    l1ToL2Messages,
+    Fr.ZERO,
+    NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP,
+    'Too many L1 to L2 messages',
+  );
+  await db.appendLeaves(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, padded);
+}

package/src/messaging/index.ts

@@ -1,3 +1,4 @@
+export * from './append_l1_to_l2_messages.js';
 export * from './in_hash.js';
 export * from './inbox_leaf.js';
 export * from './l1_to_l2_message.js';

package/src/messaging/l1_to_l2_message.ts

@@ -6,6 +6,7 @@ import { bufferToHex } from '@aztec/foundation/string';
 import { SiblingPath } from '@aztec/foundation/trees';
 
 import type { AztecAddress } from '../aztec-address/index.js';
+import type { BlockParameter } from '../block/block_parameter.js';
 import { computeL1ToL2MessageNullifier } from '../hash/hash.js';
 import type { AztecNode } from '../interfaces/aztec-node.js';
 import { MerkleTreeId } from '../trees/merkle_tree_id.js';
@@ -79,20 +80,22 @@ export async function getNonNullifiedL1ToL2MessageWitness(
   contractAddress: AztecAddress,
   messageHash: Fr,
   secret: Fr,
+  referenceBlock: BlockParameter = 'latest',
 ): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>]> {
-  const response = await node.getL1ToL2MessageMembershipWitness('latest', messageHash);
-  if (!response) {
-    throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
-  }
+  const messageNullifier = await computeL1ToL2MessageNullifier(contractAddress, messageHash, secret);
 
-  const [messageIndex, siblingPath] = response;
+  const [l1ToL2Response, nullifierResponse] = await Promise.all([
+    node.getL1ToL2MessageMembershipWitness(referenceBlock, messageHash),
+    node.findLeavesIndexes(referenceBlock, MerkleTreeId.NULLIFIER_TREE, [messageNullifier]),
+  ]);
 
-  const messageNullifier = await computeL1ToL2MessageNullifier(contractAddress, messageHash, secret);
+  if (!l1ToL2Response) {
+    throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
+  }
 
-  const [nullifierIndex] = await node.findLeavesIndexes('latest', MerkleTreeId.NULLIFIER_TREE, [messageNullifier]);
-  if (nullifierIndex !== undefined) {
+  if (nullifierResponse[0] !== undefined) {
     throw new Error(`No non-nullified L1 to L2 message found for message hash ${messageHash.toString()}`);
   }
 
-  return [messageIndex, siblingPath];
+  return l1ToL2Response;
 }

package/src/messaging/l1_to_l2_message_source.ts

@@ -10,7 +10,9 @@ export interface L1ToL2MessageSource {
   /**
    * 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).
+   * @returns The L1 to L2 messages/leaves of the messages subtree.
+   * @throws If the message tree for the given checkpoint has not yet been sealed on L1
+   * (i.e., checkpointNumber >= inbox treeInProgress).
    */
   getL1ToL2Messages(checkpointNumber: CheckpointNumber): Promise<Fr[]>;
 

package/src/messaging/l2_to_l1_membership.ts

@@ -1,8 +1,29 @@
-import { OUT_HASH_TREE_LEAF_COUNT } from '@aztec/constants';
-import type { EpochNumber } from '@aztec/foundation/branded-types';
+import { MAX_CHECKPOINTS_PER_EPOCH, OUT_HASH_TREE_LEAF_COUNT } from '@aztec/constants';
+import { type EpochNumber, EpochNumberSchema } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { SiblingPath, UnbalancedMerkleTreeCalculator, computeUnbalancedShaRoot } from '@aztec/foundation/trees';
 
+import { z } from 'zod';
+
+import type { AztecNode } from '../interfaces/aztec-node.js';
+import { schemas } from '../schemas/schemas.js';
+import { TxHash } from '../tx/tx_hash.js';
+import type { TxReceipt } from '../tx/tx_receipt.js';
+
+/**
+ * Provides access to the L1 Outbox's per-epoch roots so the witness helper can pick the smallest
+ * partial-proof root that covers a tx's checkpoint. Implemented by `OutboxContract` in the
+ * ethereum package.
+ */
+export interface OutboxRootsReader {
+  /**
+   * Returns the array of roots stored for `epoch`. Slot `i` holds the root inserted for
+   * `numCheckpointsInEpoch = i + 1`, or `Fr.ZERO` if no proof of that depth has landed yet. The
+   * returned array length is `MAX_CHECKPOINTS_PER_EPOCH`.
+   */
+  getRoots(epoch: EpochNumber): Promise<Fr[]>;
+}
+
 /**
  * # L2-to-L1 Message Tree Structure and Leaf IDs
  *
@@ -32,10 +53,10 @@ import { SiblingPath, UnbalancedMerkleTreeCalculator, computeUnbalancedShaRoot }
  *    - 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)
+ *    - 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 AZTEC_MAX_EPOCH_DURATION to allow for proofs of partial epochs
+ *    - **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:
@@ -92,59 +113,165 @@ export function getL2ToL1MessageLeafId(
   return 2n ** BigInt(membershipWitness.siblingPath.pathSize) + membershipWitness.leafIndex;
 }
 
-export interface MessageRetrieval {
-  getL2ToL1Messages(epoch: EpochNumber): Promise<Fr[][][][]>;
-}
-
 export type L2ToL1MembershipWitness = {
+  epochNumber: EpochNumber;
+  /**
+   * The number of checkpoints covered by the partial-proof root this witness was built against
+   * (1-indexed; equal to `roots-array-index + 1` on the Outbox). Pass this through to
+   * `Outbox.consume` so the contract reads the matching root slot.
+   */
+  numCheckpointsInEpoch: number;
   root: Fr;
   leafIndex: bigint;
   siblingPath: SiblingPath<number>;
 };
 
+/**
+ * Zod schema for {@link L2ToL1MembershipWitness}. The sibling-path length varies with the shape of
+ * the per-epoch tree, so we use the unsized `SiblingPath.schema` here rather than a fixed-height
+ * `schemaFor`.
+ */
+export const L2ToL1MembershipWitnessSchema = z.object({
+  epochNumber: EpochNumberSchema,
+  numCheckpointsInEpoch: schemas.Integer,
+  root: schemas.Fr,
+  leafIndex: schemas.BigInt,
+  siblingPath: SiblingPath.schema,
+}) as unknown as z.ZodType<L2ToL1MembershipWitness>;
+
+/**
+ * Computes the L2 to L1 membership witness for a given message in a transaction.
+ *
+ * Queries the L1 Outbox to find the smallest partial-proof root that covers the tx's checkpoint,
+ * then builds the witness against that root by including only the first `numCheckpointsInEpoch`
+ * checkpoints of the epoch in the tree (the remaining slots are zero-padded, matching the shape
+ * the rollup proved). Returns `undefined` if the tx is not yet in a block/epoch or if the Outbox
+ * holds no root yet that covers the tx's checkpoint.
+ *
+ * @param node - The Aztec node to query for block/tx/epoch data.
+ * @param outboxOrRoots - Either an `OutboxRootsReader` (the helper will fetch the per-epoch roots),
+ *   or an already-resolved roots array of length `MAX_CHECKPOINTS_PER_EPOCH`. Pass the array when
+ *   you already read the outbox (e.g. inside a tight loop that resolves witnesses for many
+ *   messages in the same epoch) to avoid redundant L1 reads.
+ * @param message - The L2 to L1 message hash to prove membership of.
+ * @param txHashOrReceipt - Either the tx hash, or the already-fetched `TxReceipt`. Passing the
+ *   receipt skips an internal `getTxReceipt` call.
+ * @param messageIndexInTx - Optional index of the message within the transaction's L2-to-L1 messages.
+ *   If not provided, the message is found by scanning the tx's messages (throws if duplicates exist).
+ */
 export async function computeL2ToL1MembershipWitness(
-  messageRetriever: MessageRetrieval,
-  epoch: EpochNumber,
+  node: Pick<AztecNode, 'getL2ToL1Messages' | 'getTxReceipt' | 'getBlock' | 'getCheckpointsData'>,
+  outboxOrRoots: OutboxRootsReader | Fr[],
   message: Fr,
+  txHashOrReceipt: TxHash | Pick<TxReceipt, 'txHash' | 'epochNumber' | 'blockNumber' | 'txIndexInBlock'>,
+  messageIndexInTx?: number,
 ): Promise<L2ToL1MembershipWitness | undefined> {
-  const messagesInEpoch = await messageRetriever.getL2ToL1Messages(epoch);
-  if (messagesInEpoch.length === 0) {
+  const receipt =
+    'txHash' in txHashOrReceipt ? txHashOrReceipt : await node.getTxReceipt(txHashOrReceipt, { includeTxEffect: true });
+
+  const { epochNumber, blockNumber, txIndexInBlock } = receipt;
+  if (epochNumber === undefined || blockNumber === undefined || txIndexInBlock === undefined) {
+    return undefined;
+  }
+
+  const [messagesInEpoch, block, checkpointsData] = await Promise.all([
+    node.getL2ToL1Messages(epochNumber),
+    node.getBlock(blockNumber),
+    node.getCheckpointsData({ epoch: epochNumber }),
+  ]);
+
+  if (messagesInEpoch.length === 0 || !block) {
     return undefined;
   }
 
-  return computeL2ToL1MembershipWitnessFromMessagesInEpoch(messagesInEpoch, message);
+  const checkpointIndex = checkpointsData.findIndex(c => c.checkpointNumber === block.checkpointNumber);
+  if (checkpointIndex === -1) {
+    return undefined;
+  }
+
+  const blockIndex = block.indexWithinCheckpoint;
+  const txIndex = txIndexInBlock;
+
+  // Pick the smallest partial-proof root on the Outbox that covers checkpointIndex. The Outbox
+  // stores roots keyed by `numCheckpointsInEpoch - 1`, so to cover a tx in checkpoint at index
+  // `checkpointIndex` we need a non-zero entry at array index >= checkpointIndex.
+  const roots = Array.isArray(outboxOrRoots)
+    ? (outboxOrRoots as Fr[])
+    : await (outboxOrRoots as OutboxRootsReader).getRoots(epochNumber);
+  const numCheckpointsInEpoch = findSmallestCoveringRootCount(roots, checkpointIndex);
+  if (numCheckpointsInEpoch === undefined) {
+    return undefined;
+  }
+
+  // Build the witness against the first `numCheckpointsInEpoch` checkpoints. The inner builder
+  // pads to OUT_HASH_TREE_LEAF_COUNT internally, so slicing the outer array narrows the real-leaf
+  // prefix and grows the zero suffix — exactly the shape the rollup proved against.
+  const messagesInPartialEpoch = messagesInEpoch.slice(0, numCheckpointsInEpoch);
+
+  const { root, leafIndex, siblingPath } = computeL2ToL1MembershipWitnessFromMessagesInEpoch(
+    messagesInPartialEpoch,
+    message,
+    checkpointIndex,
+    blockIndex,
+    txIndex,
+    messageIndexInTx,
+  );
+
+  // Cross-check: the recomputed root must equal the root the Outbox is holding for this depth.
+  // A mismatch means the node and L1 disagree about the epoch's contents; fail loud rather than
+  // return a witness that will revert on chain.
+  const expected = roots[numCheckpointsInEpoch - 1];
+  if (!root.equals(expected)) {
+    throw new Error(
+      `Local epoch out-hash does not match Outbox at epoch ${epochNumber} numCheckpointsInEpoch ` +
+        `${numCheckpointsInEpoch}: local=${root.toString()} outbox=${expected.toString()}`,
+    );
+  }
+
+  return { epochNumber, numCheckpointsInEpoch, root, leafIndex, siblingPath };
 }
 
-// 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.
+/**
+ * Returns the smallest `numCheckpointsInEpoch` (1-indexed) for which the Outbox holds a root that
+ * covers the message at `checkpointIndex` (0-indexed). Returns `undefined` if no covering root has
+ * been inserted yet.
+ */
+function findSmallestCoveringRootCount(roots: Fr[], checkpointIndex: number): number | undefined {
+  for (let i = checkpointIndex; i < Math.min(roots.length, MAX_CHECKPOINTS_PER_EPOCH); i++) {
+    if (!roots[i].isZero()) {
+      return i + 1;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Computes a membership witness for a message in the epoch's L2-to-L1 message tree, given explicit position indices.
+ *
+ * @param messagesInEpoch - All L2-to-L1 messages in the epoch, organized as checkpoints → blocks → txs → messages.
+ * @param message - The message hash to prove membership of.
+ * @param checkpointIndex - Index of the checkpoint within the epoch's message array.
+ * @param blockIndex - Index of the block within the checkpoint.
+ * @param txIndex - Index of the transaction within the block.
+ * @param messageIndexInTx - Optional index of the message within the transaction's messages.
+ *   If not provided, the message is found by scanning (throws if duplicates exist within the tx).
+ */
+/** @internal Exported for testing only. */
 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');
-  }
+  checkpointIndex: number,
+  blockIndex: number,
+  txIndex: number,
+  messageIndexInTx?: number,
+): { root: Fr; leafIndex: bigint; siblingPath: SiblingPath<number> } {
+  const messagesInTx = messagesInEpoch[checkpointIndex][blockIndex][txIndex];
+  const resolvedMessageIndex = resolveMessageIndex(messagesInTx, message, messageIndexInTx);
 
   // 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);
+  const pathToMessageInTxSubtree = txTree.getSiblingPathByLeafIndex(resolvedMessageIndex);
 
   // Build the tree of the block containing the target message.
   const blockTree = buildBlockTree(messagesInEpoch[checkpointIndex][blockIndex]);
@@ -163,7 +290,7 @@ export function computeL2ToL1MembershipWitnessFromMessagesInEpoch(
     }
     return buildCheckpointTree(messagesInCheckpoint).getRoot();
   });
-  // Pad to AZTEC_MAX_EPOCH_DURATION with zeros.
+  // 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)),
   );
@@ -189,7 +316,7 @@ export function computeL2ToL1MembershipWitnessFromMessagesInEpoch(
   // 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 messageLeafPosition = txTree.getLeafLocation(resolvedMessageIndex);
   const txLeafPosition = blockTree.getLeafLocation(txIndex);
   const blockLeafPosition = checkpointTree.getLeafLocation(blockIndex);
   const checkpointLeafPosition = epochTree.getLeafLocation(checkpointIndex);
@@ -207,6 +334,33 @@ export function computeL2ToL1MembershipWitnessFromMessagesInEpoch(
   };
 }
 
+function resolveMessageIndex(messagesInTx: Fr[], message: Fr, messageIndexInTx?: number): number {
+  if (messageIndexInTx !== undefined) {
+    if (!messagesInTx[messageIndexInTx]?.equals(message)) {
+      throw new Error(`Message at index ${messageIndexInTx} in tx does not match the expected message ${message}`);
+    }
+    return messageIndexInTx;
+  }
+
+  const indices = messagesInTx.reduce<number[]>((acc, msg, i) => {
+    if (msg.equals(message)) {
+      acc.push(i);
+    }
+    return acc;
+  }, []);
+
+  if (indices.length === 0) {
+    throw new Error('The L2ToL1Message you are trying to prove inclusion of does not exist');
+  }
+  if (indices.length > 1) {
+    throw new Error(
+      `Multiple messages with the same value ${message} found in tx (indices: ${indices.join(', ')}). ` +
+        `Provide messageIndexInTx to disambiguate.`,
+    );
+  }
+  return indices[0];
+}
+
 function buildCheckpointTree(messagesInCheckpoint: Fr[][][]) {
   const blockOutHashes = messagesInCheckpoint.map(messagesInBlock => buildBlockTree(messagesInBlock).getRoot());
   return buildCompressedTree(blockOutHashes);