@aztec/stdlib 0.0.1-commit.86469d5 → 0.0.1-commit.8655d4a

package/src/messaging/l2_to_l1_membership.ts

@@ -1,8 +1,26 @@
-import { OUT_HASH_TREE_LEAF_COUNT } from '@aztec/constants';
+import { MAX_CHECKPOINTS_PER_EPOCH, 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';
 
+import type { AztecNode } from '../interfaces/aztec-node.js';
+import { TxHash } from '../tx/tx_hash.js';
+import { 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 +50,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 +110,151 @@ 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>;
 };
 
+/**
+ * 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' | 'getTxEffect' | 'getBlock' | 'getCheckpointsData'>,
+  outboxOrRoots: OutboxRootsReader | Fr[],
   message: Fr,
+  txHashOrReceipt: TxHash | Pick<TxReceipt, 'txHash' | 'epochNumber' | 'blockNumber'>,
+  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);
+  const { txHash, epochNumber, blockNumber } = receipt;
+  if (epochNumber === undefined || blockNumber === undefined) {
     return undefined;
   }
 
-  return computeL2ToL1MembershipWitnessFromMessagesInEpoch(messagesInEpoch, message);
+  const [messagesInEpoch, block, txEffect, checkpointsData] = await Promise.all([
+    node.getL2ToL1Messages(epochNumber),
+    node.getBlock(blockNumber),
+    node.getTxEffect(txHash),
+    node.getCheckpointsData({ epoch: epochNumber }),
+  ]);
+
+  if (messagesInEpoch.length === 0 || !block || !txEffect) {
+    return undefined;
+  }
+
+  const checkpointIndex = checkpointsData.findIndex(c => c.checkpointNumber === block.checkpointNumber);
+  if (checkpointIndex === -1) {
+    return undefined;
+  }
+
+  const blockIndex = block.indexWithinCheckpoint;
+  const txIndex = txEffect.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 };
+}
+
+/**
+ * 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;
 }
 
-// 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.
+/**
+ * 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 +273,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 +299,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 +317,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);

package/src/messaging/l2_to_l1_message.ts

@@ -1,7 +1,7 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 
 import { z } from 'zod';
 
@@ -54,8 +54,13 @@ export class L2ToL1Message {
    * Serialize this as a buffer.
    * @returns The buffer.
    */
-  toBuffer(): Buffer {
-    return serializeToBuffer(this.recipient, this.content);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.recipient, this.content);
   }
 
   /**
@@ -127,8 +132,13 @@ export class CountedL2ToL1Message {
     return new CountedL2ToL1Message(reader.readObject(L2ToL1Message), reader.readNumber());
   }
 
-  toBuffer(): Buffer {
-    return serializeToBuffer(this.message, this.counter);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.message, this.counter);
   }
 
   static fromFields(fields: Fr[] | FieldReader) {
@@ -187,8 +197,13 @@ export class ScopedL2ToL1Message {
     return new ScopedL2ToL1Message(reader.readObject(L2ToL1Message), reader.readObject(AztecAddress));
   }
 
-  toBuffer(): Buffer {
-    return serializeToBuffer(this.message, this.contractAddress);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.message, this.contractAddress);
   }
 
   static fromFields(fields: Fr[] | FieldReader) {
@@ -229,8 +244,13 @@ export class ScopedCountedL2ToL1Message {
     return new ScopedCountedL2ToL1Message(reader.readObject(CountedL2ToL1Message), reader.readObject(AztecAddress));
   }
 
-  toBuffer(): Buffer {
-    return serializeToBuffer(this.inner, this.contractAddress);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.inner, this.contractAddress);
   }
 
   static fromFields(fields: Fr[] | FieldReader) {

package/src/noir/index.ts

@@ -19,7 +19,7 @@ export const AZTEC_VIEW_ATTRIBUTE = 'abi_view';
 export interface NoirFunctionAbi {
   /** The parameters of the function. */
   parameters: ABIParameter[];
-  /** The return type of the function. */
+  /** The return type of the function, or null for void functions. */
   return_type: {
     /**
      * The type of the return value.
@@ -29,7 +29,7 @@ export interface NoirFunctionAbi {
      * The visibility of the return value.
      */
     visibility: ABIParameterVisibility;
-  };
+  } | null;
   /** Mapping of error selector => error type */
   error_types: Partial<Record<string, AbiErrorType>>;
 }
@@ -64,6 +64,8 @@ interface NoirFunctionEntry {
 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. */

package/src/note/index.ts

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

package/src/note/note_dao.ts

@@ -1,6 +1,5 @@
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { Point } from '@aztec/foundation/curves/grumpkin';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { Note } from '@aztec/stdlib/note';
@@ -148,9 +147,7 @@ export class NoteDao {
    * @returns - Its size in bytes.
    */
   public getSize() {
-    const noteSize = 4 + this.note.items.length * Fr.SIZE_IN_BYTES;
-    // 2 numbers for txIndexInBlock and noteIndexInTx (4 bytes each)
-    return noteSize + AztecAddress.SIZE_IN_BYTES * 2 + Fr.SIZE_IN_BYTES * 4 + TxHash.SIZE + Point.SIZE_IN_BYTES + 8;
+    return this.toBuffer().length;
   }
 
   static async random({

package/src/p2p/attestation_utils.ts

@@ -33,3 +33,59 @@ export function orderAttestations(
 
   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;
+}