@aztec/stdlib 5.0.0-nightly.20260611 → 5.0.0-nightly.20260613

package/src/block/l2_block_stream/l2_tips_store_base.ts

@@ -1,6 +1,5 @@
 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 {
@@ -8,7 +7,7 @@ import {
   GENESIS_CHECKPOINT_HEADER_HASH,
   type L2BlockId,
   type L2BlockTag,
-  type L2Tips,
+  type LocalL2Tips,
 } from '../l2_block_source.js';
 import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
 
@@ -26,6 +25,12 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
   /** Sets the block number for a given tag. */
   protected abstract setTip(tag: L2BlockTag, blockNumber: BlockNumber): Promise<void>;
 
+  /** Gets the checkpoint id recorded for a given tag, if any. */
+  protected abstract getTipCheckpoint(tag: L2BlockTag): Promise<CheckpointId | undefined>;
+
+  /** Records the checkpoint id for a given tag. */
+  protected abstract setTipCheckpoint(tag: L2BlockTag, checkpoint: CheckpointId): Promise<void>;
+
   /** Gets the block hash for a given block number. */
   protected abstract getStoredBlockHash(blockNumber: BlockNumber): Promise<string | undefined>;
 
@@ -35,27 +40,6 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
   /** Deletes all block hashes for blocks before the given block number. */
   protected abstract deleteBlockHashesBefore(blockNumber: BlockNumber): Promise<void>;
 
-  /** Gets the checkpoint number for a given block number. */
-  protected abstract getCheckpointNumberForBlock(blockNumber: BlockNumber): Promise<CheckpointNumber | undefined>;
-
-  /** Sets the checkpoint number for a given block number. */
-  protected abstract setCheckpointNumberForBlock(
-    blockNumber: BlockNumber,
-    checkpointNumber: CheckpointNumber,
-  ): Promise<void>;
-
-  /** Deletes all block-to-checkpoint mappings for blocks before the given block number. */
-  protected abstract deleteBlockToCheckpointBefore(blockNumber: BlockNumber): Promise<void>;
-
-  /** Gets a checkpoint by its number. */
-  protected abstract getCheckpoint(checkpointNumber: CheckpointNumber): Promise<PublishedCheckpoint | undefined>;
-
-  /** Saves a checkpoint. */
-  protected abstract saveCheckpointData(checkpoint: PublishedCheckpoint): Promise<void>;
-
-  /** Deletes all checkpoints before the given checkpoint number. */
-  protected abstract deleteCheckpointsBefore(checkpointNumber: CheckpointNumber): Promise<void>;
-
   /** Runs the given function in a transaction. Memory stores can just execute immediately. */
   protected abstract runInTransaction<T>(fn: () => Promise<T>): Promise<T>;
 
@@ -68,31 +52,26 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     return this.getStoredBlockHash(number);
   }
 
-  public getL2Tips(): Promise<L2Tips> {
+  public getL2Tips(): Promise<LocalL2Tips> {
     return this.runInTransaction(async () => {
-      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 [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId] = await Promise.all([
+        this.getBlockId('proposed'),
+        this.getBlockId('finalized'),
+        this.getBlockId('proven'),
+        this.getBlockId('checkpointed'),
+      ]);
 
-      const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId, proposedCheckpointId] =
-        await Promise.all([
-          this.getCheckpointId('finalized'),
-          this.getCheckpointId('proven'),
-          this.getCheckpointId('checkpointed'),
-          this.getCheckpointId('proposedCheckpoint'),
-        ]);
+      const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId] = await Promise.all([
+        this.getCheckpointId('finalized'),
+        this.getCheckpointId('proven'),
+        this.getCheckpointId('checkpointed'),
+      ]);
 
       return {
         proposed: proposedBlockId,
         finalized: { block: finalizedBlockId, checkpoint: finalizedCheckpointId },
         proven: { block: provenBlockId, checkpoint: provenCheckpointId },
         checkpointed: { block: checkpointedBlockId, checkpoint: checkpointedCheckpointId },
-        proposedCheckpoint: { block: proposedCheckpointBlockId, checkpoint: proposedCheckpointId },
       };
     });
   }
@@ -139,17 +118,21 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
   private async getCheckpointId(tag: L2BlockTag): Promise<CheckpointId> {
     const blockNumber = await this.getTip(tag);
     if (blockNumber === undefined || blockNumber === 0) {
-      return { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() };
-    }
-    const checkpointNumber = await this.getCheckpointNumberForBlock(blockNumber);
-    if (checkpointNumber === undefined) {
-      return { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() };
+      return this.genesisCheckpointId();
     }
-    const checkpoint = await this.getCheckpoint(checkpointNumber);
-    if (!checkpoint) {
-      throw new Error(`Checkpoint not found for checkpoint number ${checkpointNumber}`);
+    // The checkpoint id recorded for this cursor when it was last advanced is the single source of truth.
+    // The writers (handleChainCheckpointed/Proven/Finalized/Pruned) always record an id alongside any
+    // non-genesis cursor advance, so a missing id on a real block is genuine store corruption. Fail loudly
+    // rather than silently reporting checkpoint zero, which would drive a checkpoint-replay storm.
+    const storedCheckpoint = await this.getTipCheckpoint(tag);
+    if (storedCheckpoint !== undefined) {
+      return storedCheckpoint;
     }
-    return { number: checkpointNumber, hash: checkpoint.checkpoint.hash().toString() };
+    throw new Error(`No checkpoint id recorded for ${tag} tip at block ${blockNumber}; the L2 tips store is corrupted`);
+  }
+
+  private genesisCheckpointId(): CheckpointId {
+    return { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() };
   }
 
   private async handleBlocksAdded(event: L2BlockStreamEvent): Promise<void> {
@@ -170,14 +153,12 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
       return;
     }
     await this.runInTransaction(async () => {
+      const checkpointId: CheckpointId = {
+        number: event.checkpoint.checkpoint.number,
+        hash: event.checkpoint.checkpoint.hash().toString(),
+      };
       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);
-      }
+      await this.setTipCheckpoint('checkpointed', checkpointId);
     });
   }
 
@@ -186,12 +167,27 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
       return;
     }
     await this.runInTransaction(async () => {
+      // A prune is a rollback: the proposed tip moves to the prune target unconditionally, but
+      // checkpoint-bearing cursors may only move backward. Forward-advancing them onto an
+      // uncheckpointed block leaves them on a block with no recorded checkpoint id, which getCheckpointId
+      // would then throw on.
       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);
+
+      // Clamp each checkpoint-bearing cursor down to its OWN source tip when it leads it. Clamping the proven
+      // cursor onto the checkpointed tip would transiently report unproven blocks as proven (the source's proven
+      // tip can sit below its checkpointed tip after a proof-tx reorg), until the corrective chain-proven event
+      // lands at the end of the same sync iteration. The event carries a valid (block, id) pair for each
+      // boundary, so the clamped cursor always resolves to a recorded id. The source guarantees proven <=
+      // checkpointed, so clamping each cursor to its own tip preserves the local proven <= checkpointed invariant.
+      for (const { tag, sourceTip } of [
+        { tag: 'checkpointed', sourceTip: event.checkpointed },
+        { tag: 'proven', sourceTip: event.proven },
+      ] as const) {
+        const current = await this.getTip(tag);
+        if (current !== undefined && current > sourceTip.block.number) {
+          await this.saveTag(tag, sourceTip.block);
+          await this.setTipCheckpoint(tag, sourceTip.checkpoint);
+        }
       }
     });
   }
@@ -202,6 +198,7 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     }
     await this.runInTransaction(async () => {
       await this.saveTag('proven', event.block);
+      await this.setTipCheckpoint('proven', event.checkpoint);
     });
   }
 
@@ -211,33 +208,16 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     }
     await this.runInTransaction(async () => {
       await this.saveTag('finalized', event.block);
-      const finalizedCheckpointNumber = await this.getCheckpointNumberForBlock(event.block.number);
+      await this.setTipCheckpoint('finalized', event.checkpoint);
 
-      // 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`
+      // Prune block hashes below the lowest live tip. Cap the deletion bound at the lowest live tip rather
+      // than the finalized tip alone: this should always be the finalized tip, but we have hit bugs where
+      // this is not the case. Deleting the block hash for a live tip would dangle subsequent `getBlockId`
       // 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 tips = await Promise.all([this.getTip('proposed'), 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) {
-        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);
-      }
     });
   }
 
@@ -247,14 +227,4 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
       await this.setBlockHash(block.number, block.hash);
     }
   }
-
-  private async saveCheckpoint(publishedCheckpoint: PublishedCheckpoint): Promise<void> {
-    const checkpoint = publishedCheckpoint.checkpoint;
-    const lastBlock = checkpoint.blocks.at(-1)!;
-    // Only store the mapping for the last block since tips only point to checkpoint boundaries
-    await Promise.all([
-      this.setCheckpointNumberForBlock(lastBlock.number, checkpoint.number),
-      this.saveCheckpointData(publishedCheckpoint),
-    ]);
-  }
 }

package/src/block/test/l2_tips_store_test_suite.ts

@@ -6,6 +6,7 @@ import {
   GENESIS_CHECKPOINT_HEADER_HASH,
   L2Block,
   type L2BlockId,
+  type L2BlockTag,
   type L2TipId,
 } from '@aztec/stdlib/block';
 import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
@@ -67,18 +68,11 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     checkpoint: makeCheckpointIdForBlock(blockNumber),
   });
 
-  const makeTips = (
-    proposed: number,
-    proven: number,
-    finalized: number,
-    checkpointed: number = 0,
-    proposedCheckpoint: number = 0,
-  ) => ({
+  const makeTips = (proposed: number, proven: number, finalized: number, checkpointed: 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> => {
@@ -153,7 +147,11 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(checkpoint1));
 
     // Prove up to block 5
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(5) });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(5),
+      checkpoint: makeCheckpointIdForBlock(5),
+    });
 
     const tips = await tipsStore.getL2Tips();
     expect(tips.proposed).toEqual(makeTip(5));
@@ -173,8 +171,16 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(checkpoint1));
 
     // Prove and finalize
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(5) });
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-finalized', block: makeBlockId(5) });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(5),
+      checkpoint: makeCheckpointIdForBlock(5),
+    });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-finalized',
+      block: makeBlockId(5),
+      checkpoint: makeCheckpointIdForBlock(5),
+    });
 
     const tips = await tipsStore.getL2Tips();
     expect(tips.proposed).toEqual(makeTip(5));
@@ -229,8 +235,16 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(checkpoint2));
 
     // Prove and finalize up to block 3 (checkpoint 1)
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-finalized', block: makeBlockId(3) });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(3),
+      checkpoint: makeCheckpointIdForBlock(3),
+    });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-finalized',
+      block: makeBlockId(3),
+      checkpoint: makeCheckpointIdForBlock(3),
+    });
 
     // Blocks before finalized should be cleared
     expect(await tipsStore.getL2BlockHash(1)).toBeUndefined();
@@ -250,7 +264,8 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-pruned',
       block: makeBlockId(5),
-      checkpoint: { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() },
+      checkpointed: makeTipId(0),
+      proven: makeTipId(0),
     });
 
     const tips = await tipsStore.getL2Tips();
@@ -274,7 +289,8 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-pruned',
       block: makeTip(0),
-      checkpoint: { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() },
+      checkpointed: makeTipId(0),
+      proven: makeTipId(0),
     });
 
     tips = await tipsStore.getL2Tips();
@@ -339,7 +355,8 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-pruned',
       block: makeBlockId(5),
-      checkpoint: { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() },
+      checkpointed: makeTipId(5),
+      proven: makeTipId(0),
     });
 
     tips = await tipsStore.getL2Tips();
@@ -403,7 +420,8 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-pruned',
       block: makeBlockId(3),
-      checkpoint: { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() },
+      checkpointed: makeTipId(3),
+      proven: makeTipId(0),
     });
 
     tips = await tipsStore.getL2Tips();
@@ -440,7 +458,11 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(checkpoint1));
 
     // Prove up to block 3
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(3),
+      checkpoint: makeCheckpointIdForBlock(3),
+    });
 
     let tips = await tipsStore.getL2Tips();
     expect(tips.proposed).toEqual(makeTip(3));
@@ -481,7 +503,8 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-pruned',
       block: makeBlockId(3),
-      checkpoint: { number: CheckpointNumber.ZERO, hash: GENESIS_CHECKPOINT_HEADER_HASH.toString() },
+      checkpointed: makeTipId(3),
+      proven: makeTipId(3),
     });
 
     tips = await tipsStore.getL2Tips();
@@ -530,15 +553,165 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     expect(await tipsStore.getL2BlockHash(7)).not.toEqual(originalHash7);
   });
 
-  // Regression test for #13142
-  it('does not blow up when setting proven chain on an unseen block number', async () => {
+  // Regression test for #13142: proving an unseen block number (one with no local block->checkpoint
+  // mapping) must not blow up. With per-cursor checkpoint ids, the proven tip resolves to the
+  // checkpoint id carried by the event rather than falling back to checkpoint zero.
+  it('resolves the proven checkpoint from the carried id when setting proven on an unseen block number', async () => {
     await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: [await makeBlock(5)] });
-    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
+    // Block 3 has no local block->checkpoint mapping, but the event carries a real checkpoint id.
+    const carriedCheckpoint: CheckpointId = { number: CheckpointNumber(1), hash: new Fr(42).toString() };
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(3),
+      checkpoint: carriedCheckpoint,
+    });
 
     const tips = await tipsStore.getL2Tips();
     expect(tips.proposed).toEqual(makeTip(5));
     expect(tips.proven.block).toEqual(makeTip(3));
-    // No checkpoint for block 3 since it wasn't checkpointed
-    expect(tips.proven.checkpoint.number).toEqual(CheckpointNumber.ZERO);
+    // Resolved from the carried id, not the (missing) local mapping.
+    expect(tips.proven.checkpoint).toEqual(carriedCheckpoint);
+  });
+
+  // proven/finalized resolve to the carried checkpoint id even when the block has no local
+  // block->checkpoint mapping (the cursor legitimately leads the locally-checkpointed frontier).
+  it('resolves proven and finalized checkpoints from carried ids without a local mapping', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: [await makeBlock(7)] });
+    const provenCheckpoint: CheckpointId = { number: CheckpointNumber(2), hash: new Fr(101).toString() };
+    const finalizedCheckpoint: CheckpointId = { number: CheckpointNumber(1), hash: new Fr(100).toString() };
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(5),
+      checkpoint: provenCheckpoint,
+    });
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-finalized',
+      block: makeBlockId(3),
+      checkpoint: finalizedCheckpoint,
+    });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips.proven.checkpoint).toEqual(provenCheckpoint);
+    expect(tips.finalized.checkpoint).toEqual(finalizedCheckpoint);
+  });
+
+  // Genuine corruption: a cursor points at a real (non-genesis) block that has a block hash but
+  // neither a stored per-cursor checkpoint id nor a block->checkpoint mapping. getL2Tips must throw
+  // loudly rather than silently report checkpoint zero. We reach this state by reaching past the
+  // event API to place the tip directly, since the normal writers always record an id.
+  it('throws when a cursor points at a real block with neither a stored id nor a mapping', async () => {
+    // blocks-added records the block hash for block 5 (so getBlockId succeeds) but no checkpoint id.
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: [await makeBlock(5)] });
+    // Corrupt the proven cursor to point at block 5 without any id or mapping.
+    const internal = tipsStore as unknown as { setTip(tag: L2BlockTag, blockNumber: BlockNumber): Promise<void> };
+    await internal.setTip('proven', BlockNumber(5));
+
+    await expect(tipsStore.getL2Tips()).rejects.toThrow(/checkpoint/i);
+  });
+
+  // Backward prune of a leading cursor: a checkpoint-bearing cursor that legitimately leads the source's
+  // confirmed checkpointed tip is clamped down to that tip, resolving to the id the prune event carries
+  // (never genesis, never a throw). This is the skipped-history shape where the cursor sits on a block
+  // ahead of the checkpointed frontier.
+  it('clamps a leading checkpoint cursor down to the source checkpointed tip carried by the prune event', async () => {
+    // Checkpoint blocks 1-5 (checkpointed = block 5 / ckpt 1), then add uncheckpointed blocks 6-10.
+    const blocks1to5 = await Promise.all(times(5, i => makeBlock(i + 1)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks1to5 });
+    const checkpoint1 = await makeCheckpoint(1, blocks1to5);
+    await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(checkpoint1));
+    const blocks6to10 = await Promise.all(times(5, i => makeBlock(i + 6)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks6to10 });
+
+    // Advance the proven cursor onto an uncheckpointed block (8) via a carried id, so it LEADS the
+    // source checkpointed tip (block 5) and will be clamped down to it on prune.
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(8),
+      checkpoint: { number: CheckpointNumber(2), hash: new Fr(202).toString() },
+    });
+
+    // Prune to block 7, carrying the source's confirmed checkpointed and proven tips (both block 5 / ckpt 1
+    // here, the source's proven tip having rolled back together with its checkpointed tip).
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-pruned',
+      block: makeBlockId(7),
+      checkpointed: makeTipId(5),
+      proven: makeTipId(5),
+    });
+
+    // Must not throw; the proven cursor is clamped to the carried proven tip, resolving to ckpt 1.
+    const tips = await tipsStore.getL2Tips();
+    expect(tips.proposed).toEqual(makeTip(7));
+    expect(tips.proven.block).toEqual(makeTip(5));
+    expect(tips.proven.checkpoint.number).toEqual(CheckpointNumber(1));
+  });
+
+  it('keeps the checkpointed tip when pruning to an uncheckpointed block ahead of it', async () => {
+    const blocks1to5 = await Promise.all(times(5, i => makeBlock(i + 1)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks1to5 });
+    const checkpoint1 = await makeCheckpoint(1, blocks1to5);
+    await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(checkpoint1)); // checkpointed = block 5 / ckpt 1
+
+    const blocks6to7 = await Promise.all(times(2, i => makeBlock(i + 6)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks6to7 }); // proposed = 7
+
+    // Prune to block 6: an uncheckpointed block AHEAD of the checkpointed tip (block 5). The source
+    // checkpointed tip is still block 5 / ckpt 1, so the checkpointed cursor must not move.
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-pruned',
+      block: makeBlockId(6),
+      checkpointed: makeTipId(5),
+      proven: makeTipId(0),
+    });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips.proposed).toEqual(makeTip(6));
+    expect(tips.checkpointed.block).toEqual(makeTip(5));
+    expect(tips.checkpointed.checkpoint.number).toEqual(CheckpointNumber(1)); // must NOT be zero
+  });
+
+  // Per-cursor clamping on prune: when the source rolls back its proven tip below its checkpointed tip
+  // (e.g. a proof tx dropped by an L1 reorg), the prune event carries both source tips and each local
+  // cursor must clamp to its OWN source tip. Clamping the proven cursor onto the (higher) checkpointed
+  // tip would transiently report unproven blocks as proven until the corrective chain-proven event lands.
+  it('clamps the proven cursor to the source proven tip, separately from the checkpointed cursor, on prune', async () => {
+    // Checkpoint blocks 1-15 across three checkpoints (ckpt 1 = 1-5, ckpt 2 = 6-10, ckpt 3 = 11-15).
+    const blocks1to5 = await Promise.all(times(5, i => makeBlock(i + 1)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks1to5 });
+    await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(await makeCheckpoint(1, blocks1to5)));
+    const blocks6to10 = await Promise.all(times(5, i => makeBlock(i + 6)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks6to10 });
+    await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(await makeCheckpoint(2, blocks6to10)));
+    const blocks11to15 = await Promise.all(times(5, i => makeBlock(i + 11)));
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: blocks11to15 });
+    await tipsStore.handleBlockStreamEvent(await makeCheckpointedEvent(await makeCheckpoint(3, blocks11to15)));
+
+    // Prove the whole chain up to block 15 (ckpt 3), so the local proven cursor leads both source tips below.
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-proven',
+      block: makeBlockId(15),
+      checkpoint: makeCheckpointIdForBlock(15),
+    });
+
+    let tips = await tipsStore.getL2Tips();
+    expect(tips.checkpointed.block).toEqual(makeTip(15));
+    expect(tips.proven.block).toEqual(makeTip(15));
+
+    // Prune arrives with the source's proven tip (block 5 / ckpt 1) BELOW its checkpointed tip (block 10 /
+    // ckpt 2) and below the local proven cursor (block 15). Each cursor must clamp to its own source tip.
+    await tipsStore.handleBlockStreamEvent({
+      type: 'chain-pruned',
+      block: makeBlockId(10),
+      checkpointed: makeTipId(10),
+      proven: makeTipId(5),
+    });
+
+    tips = await tipsStore.getL2Tips();
+    // The proven cursor lands exactly on the source proven tip, NOT on the (higher) checkpointed tip.
+    expect(tips.proven.block).toEqual(makeTip(5));
+    expect(tips.proven.checkpoint.number).toEqual(CheckpointNumber(1));
+    // The checkpointed cursor lands on the source checkpointed tip.
+    expect(tips.checkpointed.block).toEqual(makeTip(10));
+    expect(tips.checkpointed.checkpoint.number).toEqual(CheckpointNumber(2));
   });
 }

package/src/config/index.ts

@@ -1,3 +1,4 @@
 export * from './chain-config.js';
+export * from './network-consensus-config.js';
 export * from './node-rpc-config.js';
 export * from './sequencer-config.js';