@aztec/stdlib 0.0.1-commit.7d4e6cd → 0.0.1-commit.7ffbba4

package/src/p2p/checkpoint_proposal.ts

@@ -1,13 +1,15 @@
-import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { BlockNumber, IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
 import { Buffer32 } from '@aztec/foundation/buffer';
 import { keccak256 } from '@aztec/foundation/crypto/keccak';
 import { tryRecoverAddress } from '@aztec/foundation/crypto/secp256k1-signer';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import { Signature } from '@aztec/foundation/eth-signature';
-import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, serializeSignedBigInt, serializeToBuffer } from '@aztec/foundation/serialize';
 
 import type { L2BlockInfo } from '../block/l2_block_info.js';
+import { MAX_TXS_PER_BLOCK } from '../deserialization/index.js';
+import { DutyType, type SigningContext } from '../ha-signing/index.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import { BlockHeader } from '../tx/block_header.js';
 import { TxHash } from '../tx/index.js';
@@ -30,8 +32,15 @@ export class CheckpointProposalHash extends Buffer32 {
 }
 
 export type CheckpointProposalOptions = {
-  publishFullTxs: boolean;
-  /** Whether to generate an invalid checkpoint proposal for broadcasting. Use only for testing. */
+  /**
+   * Whether to include the tx objects along with the block proposal.
+   * Dramatically increases size of the payload but eliminates failed reexecutions due to missing txs.
+   */
+  publishFullTxs?: boolean;
+  /**
+   * Whether to generate an invalid checkpoint proposal for broadcasting.
+   * Use only for testing.
+   */
   broadcastInvalidCheckpointProposal?: boolean;
 };
 
@@ -40,7 +49,7 @@ export type CheckpointLastBlockData = {
   /** The per-block header for the last block in the checkpoint */
   blockHeader: BlockHeader;
   /** Index of this block within the checkpoint (should be the last index, e.g., numBlocks - 1) */
-  indexWithinCheckpoint: number; // REFACTOR(palla): Use branded type
+  indexWithinCheckpoint: IndexWithinCheckpoint;
   /** The sequence of transactions in the last block */
   txHashes: TxHash[];
   /** The tx in the last block (optional, for DA guarantees) */
@@ -72,7 +81,10 @@ export class CheckpointProposal extends Gossipable {
     /** Archive root after this checkpoint is applied */
     public readonly archive: Fr,
 
-    /** The proposer's signature over the checkpoint payload (checkpointHeader + archive) */
+    /** The fee asset price modifier in basis points (from oracle) */
+    public readonly feeAssetPriceModifier: bigint,
+
+    /** The proposer's signature over the checkpoint payload (checkpointHeader + archive + feeAssetPriceModifier) */
     public readonly signature: Signature,
 
     /** Optional last block info, including its own signature for BlockProposal extraction */
@@ -89,23 +101,6 @@ export class CheckpointProposal extends Gossipable {
     return this.checkpointHeader.slotNumber;
   }
 
-  get blockNumber(): BlockNumber {
-    if (!this.lastBlock) {
-      throw new Error('Cannot get blockNumber without lastBlock');
-    }
-    return this.lastBlock.blockHeader.getBlockNumber();
-  }
-
-  /** Convenience getter for txHashes from lastBlock */
-  get txHashes(): TxHash[] {
-    return this.lastBlock?.txHashes ?? [];
-  }
-
-  /** Convenience getter for txs from lastBlock */
-  get txs(): Tx[] | undefined {
-    return this.lastBlock?.signedTxs?.txs;
-  }
-
   /**
    * Extract a BlockProposal from the last block info.
    * Uses inHash from checkpointHeader.contentCommitment.inHash
@@ -139,28 +134,54 @@ export class CheckpointProposal extends Gossipable {
     };
   }
 
+  toCheckpointInfo() {
+    return {
+      slotNumber: this.slotNumber,
+      archive: this.archive,
+      lastBlockNumber: this.lastBlock?.blockHeader.getBlockNumber(),
+      lastBlockIndex: this.lastBlock?.indexWithinCheckpoint,
+      blockHeadersHash: this.checkpointHeader.blockHeadersHash,
+    };
+  }
+
   /**
    * Get the payload to sign for this checkpoint proposal.
-   * The signature is over the checkpoint header + archive root (for consensus).
+   * The signature is over the checkpoint header + archive root + feeAssetPriceModifier (for consensus).
    */
   getPayloadToSign(domainSeparator: SignatureDomainSeparator): Buffer {
-    return serializeToBuffer([domainSeparator, this.checkpointHeader, this.archive]);
+    return serializeToBuffer([
+      domainSeparator,
+      this.checkpointHeader,
+      this.archive,
+      serializeSignedBigInt(this.feeAssetPriceModifier),
+    ]);
   }
 
   static async createProposalFromSigner(
     checkpointHeader: CheckpointHeader,
     archiveRoot: Fr,
+    feeAssetPriceModifier: bigint,
     lastBlockInfo: CheckpointLastBlockData | undefined,
-    payloadSigner: (payload: Buffer32) => Promise<Signature>,
+    payloadSigner: (payload: Buffer32, context: SigningContext) => Promise<Signature>,
   ): Promise<CheckpointProposal> {
-    // Sign the checkpoint payload
-    const tempProposal = new CheckpointProposal(checkpointHeader, archiveRoot, Signature.empty(), undefined);
-
+    // Sign the checkpoint payload with CHECKPOINT_PROPOSAL duty type
+    const tempProposal = new CheckpointProposal(
+      checkpointHeader,
+      archiveRoot,
+      feeAssetPriceModifier,
+      Signature.empty(),
+    );
     const checkpointHash = getHashedSignaturePayload(tempProposal, SignatureDomainSeparator.checkpointProposal);
-    const checkpointSignature = await payloadSigner(checkpointHash);
+
+    const checkpointContext: SigningContext = {
+      slot: checkpointHeader.slotNumber,
+      blockNumber: lastBlockInfo?.blockHeader?.globalVariables.blockNumber ?? BlockNumber(0),
+      dutyType: DutyType.CHECKPOINT_PROPOSAL,
+    };
+    const checkpointSignature = await payloadSigner(checkpointHash, checkpointContext);
 
     if (!lastBlockInfo) {
-      return new CheckpointProposal(checkpointHeader, archiveRoot, checkpointSignature);
+      return new CheckpointProposal(checkpointHeader, archiveRoot, feeAssetPriceModifier, checkpointSignature);
     }
 
     const lastBlockProposal = await BlockProposal.createProposalFromSigner(
@@ -173,7 +194,7 @@ export class CheckpointProposal extends Gossipable {
       payloadSigner,
     );
 
-    return new CheckpointProposal(checkpointHeader, archiveRoot, checkpointSignature, {
+    return new CheckpointProposal(checkpointHeader, archiveRoot, feeAssetPriceModifier, checkpointSignature, {
       blockHeader: lastBlockInfo.blockHeader,
       indexWithinCheckpoint: lastBlockInfo.indexWithinCheckpoint,
       txHashes: lastBlockInfo.txHashes,
@@ -213,7 +234,12 @@ export class CheckpointProposal extends Gossipable {
   }
 
   toBuffer(): Buffer {
-    const buffer: any[] = [this.checkpointHeader, this.archive, this.signature];
+    const buffer: any[] = [
+      this.checkpointHeader,
+      this.archive,
+      serializeSignedBigInt(this.feeAssetPriceModifier),
+      this.signature,
+    ];
 
     if (this.lastBlock) {
       buffer.push(1); // hasLastBlock = true
@@ -240,15 +266,20 @@ export class CheckpointProposal extends Gossipable {
 
     const checkpointHeader = reader.readObject(CheckpointHeader);
     const archive = reader.readObject(Fr);
+    const feeAssetPriceModifier = reader.readInt256();
     const signature = reader.readObject(Signature);
 
     const hasLastBlock = reader.readNumber();
 
     if (hasLastBlock) {
       const blockHeader = reader.readObject(BlockHeader);
-      const indexWithinCheckpoint = reader.readNumber();
+      const indexWithinCheckpoint = IndexWithinCheckpoint(reader.readNumber());
       const blockSignature = reader.readObject(Signature);
-      const txHashes = reader.readArray(reader.readNumber(), TxHash);
+      const txHashCount = reader.readNumber();
+      if (txHashCount > MAX_TXS_PER_BLOCK) {
+        throw new Error(`txHashes count ${txHashCount} exceeds maximum ${MAX_TXS_PER_BLOCK}`);
+      }
+      const txHashes = reader.readArray(txHashCount, TxHash);
 
       let signedTxs: SignedTxs | undefined;
       if (!reader.isEmpty()) {
@@ -258,7 +289,7 @@ export class CheckpointProposal extends Gossipable {
         }
       }
 
-      return new CheckpointProposal(checkpointHeader, archive, signature, {
+      return new CheckpointProposal(checkpointHeader, archive, feeAssetPriceModifier, signature, {
         blockHeader,
         indexWithinCheckpoint,
         txHashes,
@@ -267,7 +298,7 @@ export class CheckpointProposal extends Gossipable {
       });
     }
 
-    return new CheckpointProposal(checkpointHeader, archive, signature);
+    return new CheckpointProposal(checkpointHeader, archive, feeAssetPriceModifier, signature);
   }
 
   getSize(): number {
@@ -275,6 +306,7 @@ export class CheckpointProposal extends Gossipable {
       this.checkpointHeader.toBuffer().length +
       this.archive.size +
       this.signature.getSize() +
+      8 /* feeAssetPriceModifier */ +
       4; /* hasLastBlock flag */
 
     if (this.lastBlock) {
@@ -292,13 +324,13 @@ export class CheckpointProposal extends Gossipable {
   }
 
   static empty(): CheckpointProposal {
-    return new CheckpointProposal(CheckpointHeader.empty(), Fr.ZERO, Signature.empty());
+    return new CheckpointProposal(CheckpointHeader.empty(), Fr.ZERO, 0n, Signature.empty());
   }
 
   static random(): CheckpointProposal {
-    return new CheckpointProposal(CheckpointHeader.random(), Fr.random(), Signature.random(), {
+    return new CheckpointProposal(CheckpointHeader.random(), Fr.random(), 0n, Signature.random(), {
       blockHeader: BlockHeader.random(),
-      indexWithinCheckpoint: Math.floor(Math.random() * 5),
+      indexWithinCheckpoint: IndexWithinCheckpoint(Math.floor(Math.random() * 5)),
       txHashes: [TxHash.random(), TxHash.random()],
       signature: Signature.random(),
     });
@@ -309,6 +341,7 @@ export class CheckpointProposal extends Gossipable {
       checkpointHeader: this.checkpointHeader.toInspect(),
       archive: this.archive.toString(),
       signature: this.signature.toString(),
+      feeAssetPriceModifier: this.feeAssetPriceModifier.toString(),
       lastBlock: this.lastBlock
         ? {
             blockHeader: this.lastBlock.blockHeader.toInspect(),
@@ -325,7 +358,7 @@ export class CheckpointProposal extends Gossipable {
    * Used when the lastBlock has been extracted and stored separately.
    */
   toCore(): CheckpointProposalCore {
-    return new CheckpointProposal(this.checkpointHeader, this.archive, this.signature);
+    return new CheckpointProposal(this.checkpointHeader, this.archive, this.feeAssetPriceModifier, this.signature);
   }
 }
 

package/src/p2p/client_type.ts

@@ -1,6 +0,0 @@
-export enum P2PClientType {
-  // Full p2p clients will subscribe to all gossip topics
-  Full,
-  // Prove p2p clients will only subscribe to transaction and proving topics
-  Prover,
-}

package/src/p2p/consensus_payload.ts

@@ -1,13 +1,12 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, serializeSignedBigInt, serializeToBuffer } from '@aztec/foundation/serialize';
 import { hexToBuffer } from '@aztec/foundation/string';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { encodeAbiParameters, parseAbiParameters } from 'viem';
 import { z } from 'zod';
 
-import type { L2Block } from '../block/l2_block.js';
 import type { Checkpoint } from '../checkpoint/checkpoint.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import type { CheckpointProposal, CheckpointProposalCore } from './checkpoint_proposal.js';
@@ -22,6 +21,8 @@ export class ConsensusPayload implements Signable {
     public readonly header: CheckpointHeader,
     /** The archive root after the block is added */
     public readonly archive: Fr,
+    /** The fee asset price modifier in basis points (from oracle) */
+    public readonly feeAssetPriceModifier: bigint = 0n,
   ) {}
 
   static get schema() {
@@ -29,12 +30,13 @@ export class ConsensusPayload implements Signable {
       .object({
         header: CheckpointHeader.schema,
         archive: schemas.Fr,
+        feeAssetPriceModifier: schemas.BigInt,
       })
-      .transform(obj => new ConsensusPayload(obj.header, obj.archive));
+      .transform(obj => new ConsensusPayload(obj.header, obj.archive, obj.feeAssetPriceModifier));
   }
 
   static getFields(fields: FieldsOf<ConsensusPayload>) {
-    return [fields.header, fields.archive] as const;
+    return [fields.header, fields.archive, fields.feeAssetPriceModifier] as const;
   }
 
   getPayloadToSign(domainSeparator: SignatureDomainSeparator): Buffer {
@@ -51,45 +53,50 @@ export class ConsensusPayload implements Signable {
     const headerHash = this.header.hash().toString();
     const encodedData = encodeAbiParameters(abi, [
       domainSeparator,
-      [archiveRoot, [0n] /* @todo See #9963 */, headerHash],
+      [archiveRoot, [this.feeAssetPriceModifier], headerHash],
     ] as const);
 
     return hexToBuffer(encodedData);
   }
 
   toBuffer(): Buffer {
-    return serializeToBuffer([this.header, this.archive]);
+    return serializeToBuffer([this.header, this.archive, serializeSignedBigInt(this.feeAssetPriceModifier)]);
   }
 
   public equals(other: ConsensusPayload | CheckpointProposal | CheckpointProposalCore): boolean {
     const otherHeader = 'checkpointHeader' in other ? other.checkpointHeader : other.header;
-    return this.header.equals(otherHeader) && this.archive.equals(other.archive);
+    const otherModifier = 'feeAssetPriceModifier' in other ? other.feeAssetPriceModifier : 0n;
+    return (
+      this.header.equals(otherHeader) &&
+      this.archive.equals(other.archive) &&
+      this.feeAssetPriceModifier === otherModifier
+    );
   }
 
   static fromBuffer(buf: Buffer | BufferReader): ConsensusPayload {
     const reader = BufferReader.asReader(buf);
-    const payload = new ConsensusPayload(reader.readObject(CheckpointHeader), reader.readObject(Fr));
+    const payload = new ConsensusPayload(
+      reader.readObject(CheckpointHeader),
+      reader.readObject(Fr),
+      reader.readInt256(),
+    );
     return payload;
   }
 
   static fromFields(fields: FieldsOf<ConsensusPayload>): ConsensusPayload {
-    return new ConsensusPayload(fields.header, fields.archive);
-  }
-
-  static fromBlock(block: L2Block): ConsensusPayload {
-    return new ConsensusPayload(block.header.toCheckpointHeader(), block.archive.root);
+    return new ConsensusPayload(fields.header, fields.archive, fields.feeAssetPriceModifier);
   }
 
   static fromCheckpoint(checkpoint: Checkpoint): ConsensusPayload {
-    return new ConsensusPayload(checkpoint.header, checkpoint.archive.root);
+    return new ConsensusPayload(checkpoint.header, checkpoint.archive.root, checkpoint.feeAssetPriceModifier);
   }
 
   static empty(): ConsensusPayload {
-    return new ConsensusPayload(CheckpointHeader.empty(), Fr.ZERO);
+    return new ConsensusPayload(CheckpointHeader.empty(), Fr.ZERO, 0n);
   }
 
   static random(): ConsensusPayload {
-    return new ConsensusPayload(CheckpointHeader.random(), Fr.random());
+    return new ConsensusPayload(CheckpointHeader.random(), Fr.random(), 0n);
   }
 
   /**
@@ -109,10 +116,11 @@ export class ConsensusPayload implements Signable {
     return {
       header: this.header.toInspect(),
       archive: this.archive.toString(),
+      feeAssetPriceModifier: this.feeAssetPriceModifier.toString(),
     };
   }
 
   toString() {
-    return `header: ${this.header.toString()}, archive: ${this.archive.toString()}}`;
+    return `header: ${this.header.toString()}, archive: ${this.archive.toString()}, feeAssetPriceModifier: ${this.feeAssetPriceModifier}}`;
   }
 }

package/src/p2p/constants.ts

@@ -0,0 +1,6 @@
+export const MAX_TX_SIZE_KB: number = 512;
+
+export const MAX_MESSAGE_SIZE_KB: number = 10 * 1024;
+
+/** Maximum size for L2Block response (contains TxEffects, not full Txs with proofs) */
+export const MAX_L2_BLOCK_SIZE_KB: number = 3 * 1024; // 3 MB

package/src/p2p/index.ts

@@ -8,6 +8,6 @@ export * from './interface.js';
 export * from './signature_utils.js';
 export * from './signed_txs.js';
 export * from './topic_type.js';
-export * from './client_type.js';
 export * from './message_validator.js';
 export * from './peer_error.js';
+export * from './constants.js';

package/src/p2p/message_validator.ts

@@ -1,10 +1,22 @@
 import type { PeerErrorSeverity } from './peer_error.js';
 
+/**
+ * Result of validating a P2P message.
+ * - 'accept': Message is valid and should be accepted and processed
+ * - 'ignore': Message should be ignored (not propagated or processed, but sender not penalized)
+ * - 'reject': Message is invalid (rejected and sender penalized)
+ */
+export type ValidationResult =
+  | { result: 'accept' }
+  | { result: 'ignore' }
+  | { result: 'reject'; severity: PeerErrorSeverity };
+
 /**
  * P2PValidator
  *
- * A validator for P2P messages, which returns a severity of error to be applied to the peer
+ * A validator for P2P messages, which returns a ValidationResult indicating
+ * whether to accept, ignore, or reject the message
  */
 export interface P2PValidator<T> {
-  validate(message: T): Promise<PeerErrorSeverity | undefined>;
+  validate(message: T): Promise<ValidationResult>;
 }

package/src/p2p/peer_error.ts

@@ -15,3 +15,10 @@ export enum PeerErrorSeverity {
    */
   HighToleranceError = 'HighToleranceError',
 }
+
+/** Severities ordered from mildest to harshest. */
+export const PeerErrorSeverityByHarshness = [
+  PeerErrorSeverity.HighToleranceError,
+  PeerErrorSeverity.MidToleranceError,
+  PeerErrorSeverity.LowToleranceError,
+] as const;

package/src/p2p/signed_txs.ts

@@ -4,6 +4,7 @@ import type { EthAddress } from '@aztec/foundation/eth-address';
 import { Signature } from '@aztec/foundation/eth-signature';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
+import { MAX_TXS_PER_BLOCK } from '../deserialization/index.js';
 import { Tx } from '../tx/tx.js';
 import {
   SignatureDomainSeparator,
@@ -64,7 +65,11 @@ export class SignedTxs {
 
   static fromBuffer(buf: Buffer | BufferReader): SignedTxs {
     const reader = BufferReader.asReader(buf);
-    const txs = reader.readArray(reader.readNumber(), Tx);
+    const txCount = reader.readNumber();
+    if (txCount > MAX_TXS_PER_BLOCK) {
+      throw new Error(`txs count ${txCount} exceeds maximum ${MAX_TXS_PER_BLOCK}`);
+    }
+    const txs = reader.readArray(txCount, Tx);
     const signature = reader.readObject(Signature);
     return new SignedTxs(txs, signature);
   }

package/src/p2p/topic_type.ts

@@ -1,5 +1,3 @@
-import { P2PClientType } from './client_type.js';
-
 /**
  * Creates the topic channel identifier string from a given topic type
  */
@@ -27,19 +25,14 @@ export enum TopicType {
   checkpoint_attestation = 'checkpoint_attestation',
 }
 
-export function getTopicTypeForClientType(clientType: P2PClientType) {
-  if (clientType === P2PClientType.Full) {
-    return [TopicType.tx, TopicType.block_proposal, TopicType.checkpoint_proposal, TopicType.checkpoint_attestation];
-  } else if (clientType === P2PClientType.Prover) {
-    return [TopicType.tx, TopicType.block_proposal];
-  } else {
-    const _: never = clientType;
-    return [TopicType.tx];
-  }
-}
-
-export function getTopicsForClientAndConfig(clientType: P2PClientType, disableTransactions: boolean) {
-  const topics = getTopicTypeForClientType(clientType);
+/** Returns all gossip topics, optionally filtering out transactions. */
+export function getTopicsForConfig(disableTransactions: boolean) {
+  const topics = [
+    TopicType.tx,
+    TopicType.block_proposal,
+    TopicType.checkpoint_proposal,
+    TopicType.checkpoint_attestation,
+  ];
   if (disableTransactions) {
     return topics.filter(topic => topic !== TopicType.tx);
   }

package/src/proofs/chonk_proof.ts

@@ -1,4 +1,5 @@
 import { CHONK_PROOF_LENGTH } from '@aztec/constants';
+import { times } from '@aztec/foundation/collection';
 import { randomBytes } from '@aztec/foundation/crypto/random';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { bufferSchemaFor } from '@aztec/foundation/schemas';
@@ -31,12 +32,15 @@ export class ChonkProof {
 
   static random() {
     // NB: Not using Fr.random here because it slows down some tests that require a large number of txs significantly.
+    // NB2: generate one fewer random bytes to not have to deal with buffers representing numbers greater than the field modulus
+    // NB3: a chonk proof can be compressed. Simulate this by filling 1/4 of the proof with zero data
     const reducedFrSize = Fr.SIZE_IN_BYTES - 1;
-    const randomFields = randomBytes(CHONK_PROOF_LENGTH * reducedFrSize);
-    const proof = Array.from(
-      { length: CHONK_PROOF_LENGTH },
-      (_, i) => new Fr(randomFields.subarray(i * reducedFrSize, (i + 1) * reducedFrSize)),
-    );
+    const nonZeroFields = Math.floor((3 * CHONK_PROOF_LENGTH) / 4);
+    const randomFields = randomBytes(nonZeroFields * Fr.SIZE_IN_BYTES);
+    const proof = [
+      ...times(nonZeroFields, i => new Fr(randomFields.subarray(i * reducedFrSize, (i + 1) * reducedFrSize))),
+      ...times(CHONK_PROOF_LENGTH - nonZeroFields, () => Fr.ZERO),
+    ];
     return new ChonkProof(proof);
   }
 

package/src/rollup/block_headers_hash.ts

@@ -5,7 +5,7 @@ import type { BlockHeader } from '../tx/block_header.js';
 
 export async function computeBlockHeadersHash(blockHeaders: BlockHeader[]): Promise<Fr> {
   const blockHeaderHashes = await Promise.all(blockHeaders.map(header => header.hash()));
-  // Must match the implementation in merge_block_rollups.nr, with the **wonky** rollup structure
+  // Must match the implementation in merge_block_rollups.nr, with the **unbalanced** rollup structure
   // (see validate_consecutive_block_rollups.nr > assert_rollups_filled_greedily.nr).
   const blockHeadersHash = await computeUnbalancedPoseidonRoot(blockHeaderHashes.map(hash => hash.toBuffer()));
   return Fr.fromBuffer(blockHeadersHash);

package/src/rollup/block_rollup_public_inputs.ts

@@ -48,8 +48,8 @@ export class BlockRollupPublicInputs {
     public timestamp: UInt64,
     /**
      * Hash of the headers of all blocks in this block range. It will be combined with the `blockHeadersHash` from
-     * other blocks in the same checkpoint to form a wonky tree. The root of that tree becomes the final hash stored in
-     * the checkpoint header, enabling validation of the blocks included in a checkpoint given their headers.
+     * other blocks in the same checkpoint to form an unbalanced tree. The root of that tree becomes the final hash
+     * stored in the checkpoint header, enabling validation of the blocks included in a checkpoint given their headers.
      */
     public blockHeadersHash: Fr,
     /**

package/src/rollup/checkpoint_header.ts

@@ -19,8 +19,8 @@ import type { UInt64 } from '../types/shared.js';
 
 /**
  * Header of a checkpoint. A checkpoint is a collection of blocks submitted to L1 all within the same slot.
- * TODO(palla/mbps): Should this include chainId and version as well? Is this used just in circuits?
- * TODO(palla/mbps): What about CheckpointNumber?
+ * This header is verified as-is in the rollup circuits, posted to the L1 rollup contract, stored in the archiver,
+ * and exposed via the Aztec Node API. See `CheckpointData` for a struct that includes the header plus extra metadata.
  */
 export class CheckpointHeader {
   constructor(
@@ -32,6 +32,14 @@ export class CheckpointHeader {
     public blobsHash: Fr,
     /** Root of the l1 to l2 messages subtree. */
     public inHash: Fr,
+    /**
+     * The root of the epoch out hash balanced tree. The out hash of the first checkpoint in the epoch is inserted at
+     * index 0, the second at index 1, and so on.
+     * Note: This is not necessarily the final epoch out hash. It includes only the out hashes of checkpoints up to and
+     * including the current checkpoint. Any subsequent checkpoints added to the same epoch are not reflected in this
+     * value.
+     */
+    public epochOutHash: Fr,
     /** Slot number of the L2 block */
     public slotNumber: SlotNumber,
     /** Timestamp of the L2 block. */
@@ -53,6 +61,7 @@ export class CheckpointHeader {
         blockHeadersHash: schemas.Fr,
         blobsHash: schemas.Fr,
         inHash: schemas.Fr,
+        epochOutHash: schemas.Fr,
         slotNumber: schemas.SlotNumber,
         timestamp: schemas.BigInt,
         coinbase: schemas.EthAddress,
@@ -69,6 +78,7 @@ export class CheckpointHeader {
       fields.blockHeadersHash,
       fields.blobsHash,
       fields.inHash,
+      fields.epochOutHash,
       fields.slotNumber,
       fields.timestamp,
       fields.coinbase,
@@ -90,6 +100,7 @@ export class CheckpointHeader {
       reader.readObject(Fr),
       reader.readObject(Fr),
       reader.readObject(Fr),
+      reader.readObject(Fr),
       SlotNumber(Fr.fromBuffer(reader).toNumber()),
       reader.readUInt64(),
       reader.readObject(EthAddress),
@@ -105,6 +116,7 @@ export class CheckpointHeader {
       this.blockHeadersHash.equals(other.blockHeadersHash) &&
       this.blobsHash.equals(other.blobsHash) &&
       this.inHash.equals(other.inHash) &&
+      this.epochOutHash.equals(other.epochOutHash) &&
       this.slotNumber === other.slotNumber &&
       this.timestamp === other.timestamp &&
       this.coinbase.equals(other.coinbase) &&
@@ -132,6 +144,7 @@ export class CheckpointHeader {
       this.blockHeadersHash,
       this.blobsHash,
       this.inHash,
+      this.epochOutHash,
       new Fr(this.slotNumber),
       bigintToUInt64BE(this.timestamp),
       this.coinbase,
@@ -151,6 +164,7 @@ export class CheckpointHeader {
       blockHeadersHash: Fr.ZERO,
       blobsHash: Fr.ZERO,
       inHash: Fr.ZERO,
+      epochOutHash: Fr.ZERO,
       slotNumber: SlotNumber.ZERO,
       timestamp: 0n,
       coinbase: EthAddress.ZERO,
@@ -167,6 +181,7 @@ export class CheckpointHeader {
       blockHeadersHash: Fr.random(),
       blobsHash: Fr.random(),
       inHash: Fr.random(),
+      epochOutHash: Fr.random(),
       slotNumber: SlotNumber(Math.floor(Math.random() * 1000) + 1),
       timestamp: BigInt(Math.floor(Date.now() / 1000)),
       coinbase: EthAddress.random(),
@@ -183,6 +198,7 @@ export class CheckpointHeader {
       this.blockHeadersHash.isZero() &&
       this.blobsHash.isZero() &&
       this.inHash.isZero() &&
+      this.epochOutHash.isZero() &&
       this.slotNumber === 0 &&
       this.timestamp === 0n &&
       this.coinbase.isZero() &&
@@ -210,6 +226,7 @@ export class CheckpointHeader {
       Fr.fromString(header.blockHeadersHash),
       Fr.fromString(header.blobsHash),
       Fr.fromString(header.inHash),
+      Fr.fromString(header.outHash),
       SlotNumber.fromBigInt(header.slotNumber),
       header.timestamp,
       new EthAddress(hexToBuffer(header.coinbase)),
@@ -233,6 +250,7 @@ export class CheckpointHeader {
       blockHeadersHash: this.blockHeadersHash.toString(),
       blobsHash: this.blobsHash.toString(),
       inHash: this.inHash.toString(),
+      outHash: this.epochOutHash.toString(),
       slotNumber: BigInt(this.slotNumber),
       timestamp: this.timestamp,
       coinbase: this.coinbase.toString(),
@@ -251,6 +269,7 @@ export class CheckpointHeader {
       blockHeadersHash: this.blockHeadersHash.toString(),
       blobsHash: this.blobsHash.toString(),
       inHash: this.inHash.toString(),
+      epochOutHash: this.epochOutHash.toString(),
       slotNumber: this.slotNumber,
       timestamp: this.timestamp,
       coinbase: this.coinbase.toString(),
@@ -266,6 +285,7 @@ export class CheckpointHeader {
   blockHeadersHash: ${this.blockHeadersHash.toString()},
   blobsHash: ${inspect(this.blobsHash)},
   inHash: ${inspect(this.inHash)},
+  epochOutHash: ${inspect(this.epochOutHash)},
   slotNumber: ${this.slotNumber},
   timestamp: ${this.timestamp},
   coinbase: ${this.coinbase.toString()},