@aztec/stdlib 0.0.1-commit.b33fc05d0 → 0.0.1-commit.b3d3157a

package/src/block/l2_block_stream/l2_block_stream.ts

@@ -17,10 +17,7 @@ export class L2BlockStream {
   private hasStarted = false;
 
   constructor(
-    private l2BlockSource: Pick<
-      L2BlockSource,
-      'getBlocks' | 'getBlockHeader' | 'getL2Tips' | 'getCheckpoints' | 'getCheckpointedBlocks'
-    >,
+    private l2BlockSource: Pick<L2BlockSource, 'getBlocks' | 'getBlockData' | 'getL2Tips' | 'getCheckpoints'>,
     private localData: L2BlockStreamLocalDataProvider,
     private handler: L2BlockStreamEventHandler,
     private readonly log = createLogger('types:block_stream'),
@@ -77,6 +74,22 @@ export class L2BlockStream {
       let latestBlockNumber = localTips.proposed.number;
       const sourceCache = new BlockHashCache([sourceTips.proposed]);
       while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache }))) {
+        if (latestBlockNumber === 0) {
+          // We walked all the way back to genesis and the hashes still differ. This means the
+          // local store and the source disagree on the genesis block itself — typically because
+          // they were configured with different `genesisTimestamp`/prefilled state. Continuing
+          // would underflow into negative block numbers and surface as "block hash not found
+          // for -1" further down. Fail loudly with a meaningful error instead.
+          this.log.error(`Genesis block hash mismatch between local store and source`, {
+            localBlockHash: await this.localData.getL2BlockHash(BlockNumber.ZERO),
+            sourceBlockHash: sourceCache.get(0) ?? (await this.getBlockHashFromSource(BlockNumber.ZERO)),
+          });
+          throw new Error(
+            'Genesis block hash mismatch between local store and source: refusing to walk past block 0. ' +
+              'This usually indicates the two sides were configured with different genesis values ' +
+              '(e.g. genesisTimestamp or prefilled public data).',
+          );
+        }
         latestBlockNumber--;
       }
 
@@ -97,8 +110,9 @@ export class L2BlockStream {
       }
 
       // If we are just starting, use the starting block number from the options.
-      if (latestBlockNumber === 0 && this.opts.startingBlock !== undefined) {
-        latestBlockNumber = BlockNumber(Math.max(this.opts.startingBlock - 1, 0));
+      const startingBlock = this.opts.startingBlock !== undefined ? BlockNumber(this.opts.startingBlock) : undefined;
+      if (latestBlockNumber === 0 && startingBlock !== undefined) {
+        latestBlockNumber = BlockNumber(Math.max(startingBlock - 1, 0));
       }
 
       // Only log this entry once (for sanity)
@@ -112,21 +126,18 @@ export class L2BlockStream {
 
       // When startingBlock is set, also skip ahead for checkpoints.
       if (
-        this.opts.startingBlock !== undefined &&
-        this.opts.startingBlock >= 1 &&
+        startingBlock !== undefined &&
+        startingBlock >= 1 &&
         nextCheckpointToEmit <= sourceTips.checkpointed.checkpoint.number
       ) {
-        const startingBlockCheckpoints = await this.l2BlockSource.getCheckpointedBlocks(
-          BlockNumber(this.opts.startingBlock),
-          1,
-        );
-        if (startingBlockCheckpoints.length > 0) {
-          nextCheckpointToEmit = CheckpointNumber(
-            Math.max(nextCheckpointToEmit, startingBlockCheckpoints[0].checkpointNumber),
-          );
-        } else {
+        if (startingBlock > sourceTips.checkpointed.block.number) {
           // startingBlock is past all checkpointed blocks; skip Loop 1 entirely.
           nextCheckpointToEmit = CheckpointNumber(sourceTips.checkpointed.checkpoint.number + 1);
+        } else {
+          const startingBlockData = await this.l2BlockSource.getBlockData({ number: startingBlock });
+          if (startingBlockData) {
+            nextCheckpointToEmit = CheckpointNumber(Math.max(nextCheckpointToEmit, startingBlockData.checkpointNumber));
+          }
         }
       }
 
@@ -149,7 +160,7 @@ export class L2BlockStream {
       if (!this.opts.ignoreCheckpoints) {
         let loop1Iterations = 0;
         while (nextCheckpointToEmit <= sourceTips.checkpointed.checkpoint.number) {
-          const checkpoints = await this.l2BlockSource.getCheckpoints(nextCheckpointToEmit, 1);
+          const checkpoints = await this.l2BlockSource.getCheckpoints({ from: nextCheckpointToEmit, limit: 1 });
           if (checkpoints.length === 0) {
             break;
           }
@@ -184,9 +195,9 @@ export class L2BlockStream {
 
       // Find the starting checkpoint number
       if (nextBlockNumber <= sourceTips.checkpointed.block.number) {
-        const blocks = await this.l2BlockSource.getCheckpointedBlocks(BlockNumber(nextBlockNumber), 1);
-        if (blocks.length > 0) {
-          nextCheckpointNumber = blocks[0].checkpointNumber;
+        const blockData = await this.l2BlockSource.getBlockData({ number: BlockNumber(nextBlockNumber) });
+        if (blockData) {
+          nextCheckpointNumber = blockData.checkpointNumber;
         }
       }
 
@@ -194,7 +205,10 @@ export class L2BlockStream {
         // Refill the prefetch buffer when exhausted
         if (prefetchIdx >= prefetchedCheckpoints.length) {
           const prefetchLimit = this.opts.checkpointPrefetchLimit ?? CHECKPOINT_PREFETCH_LIMIT;
-          prefetchedCheckpoints = await this.l2BlockSource.getCheckpoints(nextCheckpointNumber, prefetchLimit);
+          prefetchedCheckpoints = await this.l2BlockSource.getCheckpoints({
+            from: nextCheckpointNumber,
+            limit: prefetchLimit,
+          });
           prefetchIdx = 0;
           if (prefetchedCheckpoints.length === 0) {
             break;
@@ -234,7 +248,7 @@ export class L2BlockStream {
       while (nextBlockNumber <= sourceTips.proposed.number) {
         const limit = Math.min(this.opts.batchSize ?? 50, sourceTips.proposed.number - nextBlockNumber + 1);
         this.log.trace(`Requesting blocks from ${nextBlockNumber} limit ${limit}`);
-        const blocks = await this.l2BlockSource.getBlocks(BlockNumber(nextBlockNumber), BlockNumber(limit));
+        const blocks = await this.l2BlockSource.getBlocks({ from: BlockNumber(nextBlockNumber), limit });
         if (blocks.length === 0) {
           break;
         }
@@ -266,9 +280,6 @@ export class L2BlockStream {
    * @param args - A cache of data already requested from source, to avoid re-requesting it.
    */
   private async areBlockHashesEqualAt(blockNumber: BlockNumber, args: { sourceCache: BlockHashCache }) {
-    if (blockNumber === 0) {
-      return true;
-    }
     const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
     if (!localBlockHash && this.opts.skipFinalized) {
       // Failing to find a block hash when skipping finalized blocks can be highly problematic as we'd potentially need
@@ -291,8 +302,8 @@ export class L2BlockStream {
 
   private getBlockHashFromSource(blockNumber: BlockNumber) {
     return this.l2BlockSource
-      .getBlockHeader(blockNumber)
-      .then(h => h?.hash())
+      .getBlockData({ number: blockNumber })
+      .then(d => d?.header.hash())
       .then(hash => hash?.toString());
   }
 

package/src/block/l2_block_stream/l2_tips_memory_store.ts

@@ -1,6 +1,7 @@
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
 
 import type { PublishedCheckpoint } from '../../checkpoint/published_checkpoint.js';
+import type { BlockHash } from '../block_hash.js';
 import type { L2BlockTag } from '../l2_block_source.js';
 import { L2TipsStoreBase } from './l2_tips_store_base.js';
 
@@ -9,6 +10,10 @@ import { L2TipsStoreBase } from './l2_tips_store_base.js';
  * @dev Tests in kv-store/src/stores/l2_tips_memory_store.test.ts
  */
 export class L2TipsMemoryStore extends L2TipsStoreBase {
+  constructor(initialBlockHash: BlockHash) {
+    super(initialBlockHash);
+  }
+
   private readonly tips = new Map<L2BlockTag, BlockNumber>();
   private readonly blockHashes = new Map<number, string>();
   private readonly blockToCheckpoint = new Map<number, CheckpointNumber>();

package/src/block/l2_block_stream/l2_tips_store_base.ts

@@ -1,7 +1,7 @@
-import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/constants';
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
 
 import type { PublishedCheckpoint } from '../../checkpoint/published_checkpoint.js';
+import type { BlockHash } from '../block_hash.js';
 import type { L2Block } from '../l2_block.js';
 import {
   type CheckpointId,
@@ -17,6 +17,7 @@ import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalD
  * while delegating storage operations to subclasses.
  */
 export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider {
+  constructor(protected readonly initialBlockHash: BlockHash) {}
   // Abstract storage primitives - subclasses implement these based on their backing store
 
   /** Gets the block number for a given tag. */
@@ -60,30 +61,38 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
 
   // Public interface implementation
 
-  public getL2BlockHash(number: BlockNumber): Promise<string | undefined> {
+  public async getL2BlockHash(number: BlockNumber): Promise<string | undefined> {
+    if (number === 0) {
+      return (await this.getStoredBlockHash(number)) ?? this.initialBlockHash.toString();
+    }
     return this.getStoredBlockHash(number);
   }
 
   public getL2Tips(): Promise<L2Tips> {
     return this.runInTransaction(async () => {
-      const [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId] = await Promise.all([
-        this.getBlockId('proposed'),
-        this.getBlockId('finalized'),
-        this.getBlockId('proven'),
-        this.getBlockId('checkpointed'),
-      ]);
-
-      const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId] = await Promise.all([
-        this.getCheckpointId('finalized'),
-        this.getCheckpointId('proven'),
-        this.getCheckpointId('checkpointed'),
-      ]);
+      const [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId, proposedCheckpointBlockId] =
+        await Promise.all([
+          this.getBlockId('proposed'),
+          this.getBlockId('finalized'),
+          this.getBlockId('proven'),
+          this.getBlockId('checkpointed'),
+          this.getBlockId('proposedCheckpoint'),
+        ]);
+
+      const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId, proposedCheckpointId] =
+        await Promise.all([
+          this.getCheckpointId('finalized'),
+          this.getCheckpointId('proven'),
+          this.getCheckpointId('checkpointed'),
+          this.getCheckpointId('proposedCheckpoint'),
+        ]);
 
       return {
         proposed: proposedBlockId,
         finalized: { block: finalizedBlockId, checkpoint: finalizedCheckpointId },
         proven: { block: provenBlockId, checkpoint: provenCheckpointId },
         checkpointed: { block: checkpointedBlockId, checkpoint: checkpointedCheckpointId },
+        proposedCheckpoint: { block: proposedCheckpointBlockId, checkpoint: proposedCheckpointId },
       };
     });
   }
@@ -118,7 +127,7 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
   private async getBlockId(tag: L2BlockTag): Promise<L2BlockId> {
     const blockNumber = await this.getTip(tag);
     if (blockNumber === undefined || blockNumber === 0) {
-      return { number: BlockNumber.ZERO, hash: GENESIS_BLOCK_HEADER_HASH.toString() };
+      return { number: BlockNumber.ZERO, hash: this.initialBlockHash.toString() };
     }
     const blockHash = await this.getStoredBlockHash(blockNumber);
     if (!blockHash) {
@@ -134,7 +143,6 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     }
     const checkpointNumber = await this.getCheckpointNumberForBlock(blockNumber);
     if (checkpointNumber === undefined) {
-      // No checkpoint associated with this block yet
       return { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() };
     }
     const checkpoint = await this.getCheckpoint(checkpointNumber);
@@ -164,6 +172,12 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     await this.runInTransaction(async () => {
       await this.saveTag('checkpointed', event.block);
       await this.saveCheckpoint(event.checkpoint);
+      // proposedCheckpoint is always >= checkpointed. If checkpointed has caught up
+      // or surpassed it, advance proposedCheckpoint to match.
+      const proposedCheckpointBlock = await this.getBlockId('proposedCheckpoint');
+      if (event.block.number > proposedCheckpointBlock.number) {
+        await this.saveTag('proposedCheckpoint', event.block);
+      }
     });
   }
 
@@ -174,6 +188,7 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     await this.runInTransaction(async () => {
       await this.saveTag('proposed', event.block);
       await this.saveTag('checkpointed', event.block);
+      await this.saveTag('proposedCheckpoint', event.block);
       const storeProven = await this.getBlockId('proven');
       if (storeProven.number > event.block.number) {
         await this.saveTag('proven', event.block);
@@ -198,11 +213,30 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
       await this.saveTag('finalized', event.block);
       const finalizedCheckpointNumber = await this.getCheckpointNumberForBlock(event.block.number);
 
-      await this.deleteBlockHashesBefore(event.block.number);
-      await this.deleteBlockToCheckpointBefore(event.block.number);
+      // Cap the deletion bound at the lowest live tip. This should always be the finalized tip, but
+      // we have hit bugs where this is not the case. Deleting the block hash, block-to-checkpoint mapping,
+      // or enclosing checkpoint object for a live tip would dangle subsequent `getBlockId`/`getCheckpointId`
+      // lookups and lock the block stream into an error loop.
+      const tips = await Promise.all([
+        this.getTip('proposed'),
+        this.getTip('proposedCheckpoint'),
+        this.getTip('checkpointed'),
+        this.getTip('proven'),
+      ]);
+      const liveTipBlocks = tips.filter((t): t is BlockNumber => t !== undefined && t > 0);
+      const safeBlockBound = BlockNumber(Math.min(event.block.number, ...liveTipBlocks));
+      await this.deleteBlockHashesBefore(safeBlockBound);
+      await this.deleteBlockToCheckpointBefore(safeBlockBound);
 
       if (finalizedCheckpointNumber !== undefined) {
-        await this.deleteCheckpointsBefore(finalizedCheckpointNumber);
+        const tipCheckpoints = await Promise.all(liveTipBlocks.map(b => this.getCheckpointNumberForBlock(b)));
+        const safeCheckpointBound = CheckpointNumber(
+          Math.min(
+            finalizedCheckpointNumber,
+            ...tipCheckpoints.filter((c): c is CheckpointNumber => c !== undefined && c > 0),
+          ),
+        );
+        await this.deleteCheckpointsBefore(safeCheckpointBound);
       }
     });
   }

package/src/block/proposal/attestations_and_signers.ts

@@ -4,26 +4,37 @@ import { hexToBuffer } from '@aztec/foundation/string';
 import { encodeAbiParameters, parseAbiParameters } from 'viem';
 import { z } from 'zod';
 
-import type { Signable, SignatureDomainSeparator } from '../../p2p/signature_utils.js';
+import {
+  type CoordinationSignatureContext,
+  type CoordinationSignatureType,
+  type Signable,
+  coordinationSignatureContextSchema,
+} from '../../p2p/signature_utils.js';
 import { CommitteeAttestation, EthAddress } from './committee_attestation.js';
 
 export class CommitteeAttestationsAndSigners implements Signable {
-  constructor(public attestations: CommitteeAttestation[]) {}
+  readonly primaryType: CoordinationSignatureType = 'AttestationsAndSigners';
+
+  constructor(
+    public attestations: CommitteeAttestation[],
+    public readonly signatureContext: CoordinationSignatureContext,
+  ) {}
 
   static get schema() {
     return z
       .object({
         attestations: CommitteeAttestation.schema.array(),
+        signatureContext: coordinationSignatureContextSchema,
       })
-      .transform(obj => new CommitteeAttestationsAndSigners(obj.attestations));
+      .transform(obj => new CommitteeAttestationsAndSigners(obj.attestations, obj.signatureContext));
   }
 
-  getPayloadToSign(domainSeparator: SignatureDomainSeparator): Buffer {
-    const abi = parseAbiParameters('uint8,(bytes,bytes),address[]');
+  getPayloadToSign(): Buffer {
+    // Matches the L1 abi.encode(attestations, signers) in AttestationLib.sol#getAttestationsAndSignersDigest.
+    const abi = parseAbiParameters('(bytes,bytes),address[]');
     const packed = this.getPackedAttestations();
 
     const encodedData = encodeAbiParameters(abi, [
-      domainSeparator,
       [packed.signatureIndices, packed.signaturesOrAddresses],
       this.getSigners().map(s => s.toString()),
     ]);
@@ -31,8 +42,8 @@ export class CommitteeAttestationsAndSigners implements Signable {
     return hexToBuffer(encodedData);
   }
 
-  static empty(): CommitteeAttestationsAndSigners {
-    return new CommitteeAttestationsAndSigners([]);
+  static empty(signatureContext: CoordinationSignatureContext): CommitteeAttestationsAndSigners {
+    return new CommitteeAttestationsAndSigners([], signatureContext);
   }
 
   toString() {
@@ -53,9 +64,9 @@ export class CommitteeAttestationsAndSigners implements Signable {
    * @param attestations - Array of committee attestations with addresses and signatures
    * @returns Packed attestations with bitmap and tightly packed signature/address data
    */
-  getPackedAttestations(): ViemCommitteeAttestations {
-    const length = this.attestations.length;
-    const attestations = this.attestations.map(a => a.toViem());
+  static packAttestations(attestations: CommitteeAttestation[]): ViemCommitteeAttestations {
+    const length = attestations.length;
+    const viemAttestations = attestations.map(a => a.toViem());
 
     // Calculate bitmap size (1 bit per attestation, rounded up to nearest byte)
     const bitmapSize = Math.ceil(length / 8);
@@ -63,8 +74,8 @@ export class CommitteeAttestationsAndSigners implements Signable {
 
     // Calculate total data size needed
     let totalDataSize = 0;
-    for (let i = 0; i < length; i++) {
-      const signature = attestations[i].signature;
+    for (const attestation of viemAttestations) {
+      const signature = attestation.signature;
       // Check if signature is empty (v = 0)
       const isEmpty = signature.v === 0;
 
@@ -79,8 +90,7 @@ export class CommitteeAttestationsAndSigners implements Signable {
     let dataIndex = 0;
 
     // Pack the data
-    for (let i = 0; i < length; i++) {
-      const attestation = attestations[i];
+    for (const [i, attestation] of viemAttestations.entries()) {
       const signature = attestation.signature;
 
       // Check if signature is empty
@@ -90,7 +100,7 @@ export class CommitteeAttestationsAndSigners implements Signable {
         // Set bit in bitmap (bit 7-0 in each byte, left to right)
         const byteIndex = Math.floor(i / 8);
         const bitIndex = 7 - (i % 8);
-        signatureIndices[byteIndex] |= 1 << bitIndex;
+        signatureIndices[byteIndex] = (signatureIndices[byteIndex] ?? 0) | (1 << bitIndex);
 
         // Pack signature: v + r + s
         signaturesOrAddresses[dataIndex] = signature.v;
@@ -118,6 +128,10 @@ export class CommitteeAttestationsAndSigners implements Signable {
       signaturesOrAddresses: `0x${Buffer.from(signaturesOrAddresses).toString('hex')}`,
     };
   }
+
+  getPackedAttestations(): ViemCommitteeAttestations {
+    return CommitteeAttestationsAndSigners.packAttestations(this.attestations);
+  }
 }
 
 /**
@@ -130,8 +144,9 @@ export class MaliciousCommitteeAttestationsAndSigners extends CommitteeAttestati
   constructor(
     attestations: CommitteeAttestation[],
     private signers: EthAddress[],
+    signatureContext: CoordinationSignatureContext,
   ) {
-    super(attestations);
+    super(attestations, signatureContext);
   }
 
   override getSigners(): EthAddress[] {

package/src/block/test/l2_tips_store_test_suite.ts

@@ -1,4 +1,3 @@
-import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/constants';
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
 import { times } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
@@ -11,8 +10,9 @@ import {
 } from '@aztec/stdlib/block';
 import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 
-import { jestExpect as expect } from '@jest/expect';
+import { expect } from 'vitest';
 
+import { GENESIS_BLOCK_HEADER_HASH } from '../block_hash.js';
 import type { L2TipsStore } from '../l2_block_stream/index.js';
 
 export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
@@ -67,11 +67,18 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     checkpoint: makeCheckpointIdForBlock(blockNumber),
   });
 
-  const makeTips = (proposed: number, proven: number, finalized: number, checkpointed: number = 0) => ({
+  const makeTips = (
+    proposed: number,
+    proven: number,
+    finalized: number,
+    checkpointed: number = 0,
+    proposedCheckpoint: number = 0,
+  ) => ({
     proposed: makeTip(proposed),
     proven: makeTipId(proven),
     finalized: makeTipId(finalized),
     checkpointed: makeTipId(checkpointed),
+    proposedCheckpoint: makeTipId(proposedCheckpoint),
   });
 
   const makeCheckpoint = async (checkpointNumber: number, blocks: L2Block[]): Promise<PublishedCheckpoint> => {

package/src/checkpoint/checkpoint.ts

@@ -100,7 +100,16 @@ export class Checkpoint {
    * checkpoints up to and including this one in the epoch.
    */
   public getCheckpointOutHash(): Fr {
-    const msgs = this.blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
+    return Checkpoint.getCheckpointOutHash(this.blocks);
+  }
+
+  /**
+   * Returns the out hash computed from all l2-to-l1 messages in this checkpoint.
+   * Note: This value is different from the out hash in the header, which is the **accumulated** out hash over all
+   * checkpoints up to and including this one in the epoch.
+   */
+  static getCheckpointOutHash(blocks: L2Block[]): Fr {
+    const msgs = blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
     return computeCheckpointOutHash(msgs);
   }
 
@@ -165,6 +174,7 @@ export class Checkpoint {
     let lastArchive = previousArchive;
     for (let i = 0; i < numBlocks; i++) {
       const block = await L2Block.random(BlockNumber(startBlockNumber + i), {
+        checkpointNumber,
         indexWithinCheckpoint: IndexWithinCheckpoint(i),
         ...options,
         ...(lastArchive ? { lastArchive } : {}),

package/src/checkpoint/checkpoint_data.ts

@@ -14,18 +14,56 @@ import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { L1PublishedData } from './published_checkpoint.js';
 
-/** Lightweight checkpoint metadata without full block data. */
-export type CheckpointData = {
+/** Base type for checkpoint data */
+export type CommonCheckpointData = {
   checkpointNumber: CheckpointNumber;
   header: CheckpointHeader;
-  archive: AppendOnlyTreeSnapshot;
-  checkpointOutHash: Fr;
   startBlock: BlockNumber;
   blockCount: number;
+};
+
+/** Data stored with checkpoint data after publishing on l1 */
+export type L1EnrichedCheckpointData = {
   attestations: CommitteeAttestation[];
   l1: L1PublishedData;
 };
 
+/** Data stored alongside checkpoint data in storage */
+export type StorageEnrichedCheckpointData = {
+  archive: AppendOnlyTreeSnapshot;
+  checkpointOutHash: Fr;
+  /** Fee asset price modifier in basis points. Defaults to 0 (no change) when not explicitly set. */
+  feeAssetPriceModifier: bigint;
+};
+
+/** Data stored only with proposed checkpoint data  */
+export type ProposedOnlyCheckpointData = {
+  totalManaUsed: bigint;
+  feeAssetPriceModifier: bigint;
+};
+
+/** Lightweight checkpoint metadata without full block data. */
+export type CheckpointData = CommonCheckpointData & StorageEnrichedCheckpointData & L1EnrichedCheckpointData;
+
+/** Input for setting a proposed checkpoint. The archive and checkpointOutHash are computed
+ *  internally by the block store from the stored blocks. */
+export type ProposedCheckpointInput = CommonCheckpointData & ProposedOnlyCheckpointData;
+
+/** Full data for a proposed checkpoint (proposed but not yet L1-confirmed).
+ *  Includes fee-relevant fields used during pipelining to compute the fee header override. */
+export type ProposedCheckpointData = ProposedCheckpointInput & StorageEnrichedCheckpointData;
+
+export const ProposedCheckpointDataSchema = z.object({
+  checkpointNumber: CheckpointNumberSchema,
+  header: CheckpointHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  checkpointOutHash: schemas.Fr,
+  startBlock: BlockNumberSchema,
+  blockCount: z.number(),
+  totalManaUsed: schemas.BigInt,
+  feeAssetPriceModifier: schemas.BigInt,
+});
+
 export const CheckpointDataSchema = z
   .object({
     checkpointNumber: CheckpointNumberSchema,
@@ -34,6 +72,7 @@ export const CheckpointDataSchema = z
     checkpointOutHash: schemas.Fr,
     startBlock: BlockNumberSchema,
     blockCount: schemas.Integer,
+    feeAssetPriceModifier: schemas.BigInt,
     attestations: z.array(CommitteeAttestation.schema),
     l1: L1PublishedData.schema,
   })
@@ -45,6 +84,7 @@ export const CheckpointDataSchema = z
       checkpointOutHash: obj.checkpointOutHash,
       startBlock: obj.startBlock,
       blockCount: obj.blockCount,
+      feeAssetPriceModifier: obj.feeAssetPriceModifier,
       attestations: obj.attestations,
       l1: obj.l1,
     }),