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

package/dest/block/l2_block_stream/l2_tips_store_base.js

@@ -17,18 +17,16 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
     }
     getL2Tips() {
         return this.runInTransaction(async ()=>{
-            const [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId, proposedCheckpointBlockId] = await Promise.all([
+            const [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId] = await Promise.all([
                 this.getBlockId('proposed'),
                 this.getBlockId('finalized'),
                 this.getBlockId('proven'),
-                this.getBlockId('checkpointed'),
-                this.getBlockId('proposedCheckpoint')
+                this.getBlockId('checkpointed')
             ]);
-            const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId, proposedCheckpointId] = await Promise.all([
+            const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId] = await Promise.all([
                 this.getCheckpointId('finalized'),
                 this.getCheckpointId('proven'),
-                this.getCheckpointId('checkpointed'),
-                this.getCheckpointId('proposedCheckpoint')
+                this.getCheckpointId('checkpointed')
             ]);
             return {
                 proposed: proposedBlockId,
@@ -43,10 +41,6 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
                 checkpointed: {
                     block: checkpointedBlockId,
                     checkpoint: checkpointedCheckpointId
-                },
-                proposedCheckpoint: {
-                    block: proposedCheckpointBlockId,
-                    checkpoint: proposedCheckpointId
                 }
             };
         });
@@ -95,25 +89,22 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
     async getCheckpointId(tag) {
         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;
         }
+        throw new Error(`No checkpoint id recorded for ${tag} tip at block ${blockNumber}; the L2 tips store is corrupted`);
+    }
+    genesisCheckpointId() {
         return {
-            number: checkpointNumber,
-            hash: checkpoint.checkpoint.hash().toString()
+            number: CheckpointNumber.ZERO,
+            hash: GENESIS_CHECKPOINT_HEADER_HASH.toString()
         };
     }
     async handleBlocksAdded(event) {
@@ -133,14 +124,12 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
             return;
         }
         await this.runInTransaction(async ()=>{
+            const 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);
         });
     }
     async handleChainPruned(event) {
@@ -148,12 +137,32 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
             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
+                }
+            ]){
+                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);
+                }
             }
         });
     }
@@ -163,6 +172,7 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
         }
         await this.runInTransaction(async ()=>{
             await this.saveTag('proven', event.block);
+            await this.setTipCheckpoint('proven', event.checkpoint);
         });
     }
     async handleChainFinalized(event) {
@@ -171,26 +181,19 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
         }
         await this.runInTransaction(async ()=>{
             await this.saveTag('finalized', event.block);
-            const finalizedCheckpointNumber = await this.getCheckpointNumberForBlock(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`
+            await this.setTipCheckpoint('finalized', event.checkpoint);
+            // 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 liveTipBlocks = tips.filter((t)=>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 !== undefined && c > 0)));
-                await this.deleteCheckpointsBefore(safeCheckpointBound);
-            }
         });
     }
     async saveTag(name, block) {
@@ -199,13 +202,4 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
             await this.setBlockHash(block.number, block.hash);
         }
     }
-    async saveCheckpoint(publishedCheckpoint) {
-        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/dest/block/test/l2_tips_store_test_suite.d.ts

@@ -1,3 +1,3 @@
 import type { L2TipsStore } from '../l2_block_stream/index.js';
 export declare function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>): void;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibDJfdGlwc19zdG9yZV90ZXN0X3N1aXRlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmxvY2svdGVzdC9sMl90aXBzX3N0b3JlX3Rlc3Rfc3VpdGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBZUEsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFFL0Qsd0JBQWdCLGVBQWUsQ0FBQyxhQUFhLEVBQUUsTUFBTSxPQUFPLENBQUMsV0FBVyxDQUFDLFFBOGdCeEUifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibDJfdGlwc19zdG9yZV90ZXN0X3N1aXRlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmxvY2svdGVzdC9sMl90aXBzX3N0b3JlX3Rlc3Rfc3VpdGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBZ0JBLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRS9ELHdCQUFnQixlQUFlLENBQUMsYUFBYSxFQUFFLE1BQU0sT0FBTyxDQUFDLFdBQVcsQ0FBQyxRQTByQnhFIn0=

package/dest/block/test/l2_tips_store_test_suite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"l2_tips_store_test_suite.d.ts","sourceRoot":"","sources":["../../../src/block/test/l2_tips_store_test_suite.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,QA8gBxE"}
+{"version":3,"file":"l2_tips_store_test_suite.d.ts","sourceRoot":"","sources":["../../../src/block/test/l2_tips_store_test_suite.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,QA0rBxE"}

package/dest/block/test/l2_tips_store_test_suite.js

@@ -62,12 +62,11 @@ export function testL2TipsStore(makeTipsStore) {
             block: makeTip(blockNumber),
             checkpoint: makeCheckpointIdForBlock(blockNumber)
         });
-    const makeTips = (proposed, proven, finalized, checkpointed = 0, proposedCheckpoint = 0)=>({
+    const makeTips = (proposed, proven, finalized, checkpointed = 0)=>({
             proposed: makeTip(proposed),
             proven: makeTipId(proven),
             finalized: makeTipId(finalized),
-            checkpointed: makeTipId(checkpointed),
-            proposedCheckpoint: makeTipId(proposedCheckpoint)
+            checkpointed: makeTipId(checkpointed)
         });
     const makeCheckpoint = async (checkpointNumber, blocks)=>{
         const checkpoint = await Checkpoint.random(CheckpointNumber(checkpointNumber), {
@@ -139,7 +138,8 @@ export function testL2TipsStore(makeTipsStore) {
         // Prove up to block 5
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-proven',
-            block: makeBlockId(5)
+            block: makeBlockId(5),
+            checkpoint: makeCheckpointIdForBlock(5)
         });
         const tips = await tipsStore.getL2Tips();
         expect(tips.proposed).toEqual(makeTip(5));
@@ -161,11 +161,13 @@ export function testL2TipsStore(makeTipsStore) {
         // Prove and finalize
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-proven',
-            block: makeBlockId(5)
+            block: makeBlockId(5),
+            checkpoint: makeCheckpointIdForBlock(5)
         });
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-finalized',
-            block: makeBlockId(5)
+            block: makeBlockId(5),
+            checkpoint: makeCheckpointIdForBlock(5)
         });
         const tips = await tipsStore.getL2Tips();
         expect(tips.proposed).toEqual(makeTip(5));
@@ -223,11 +225,13 @@ export function testL2TipsStore(makeTipsStore) {
         // Prove and finalize up to block 3 (checkpoint 1)
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-proven',
-            block: makeBlockId(3)
+            block: makeBlockId(3),
+            checkpoint: makeCheckpointIdForBlock(3)
         });
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-finalized',
-            block: makeBlockId(3)
+            block: makeBlockId(3),
+            checkpoint: makeCheckpointIdForBlock(3)
         });
         // Blocks before finalized should be cleared
         expect(await tipsStore.getL2BlockHash(1)).toBeUndefined();
@@ -247,10 +251,8 @@ export function testL2TipsStore(makeTipsStore) {
         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();
         expect(tips.proposed).toEqual(makeTip(5));
@@ -272,10 +274,8 @@ export function testL2TipsStore(makeTipsStore) {
         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();
         expect(tips.proposed).toEqual(makeTip(0));
@@ -336,10 +336,8 @@ export function testL2TipsStore(makeTipsStore) {
         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();
         expect(tips.proposed).toEqual(makeTip(5));
@@ -399,10 +397,8 @@ export function testL2TipsStore(makeTipsStore) {
         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();
         expect(tips.proposed).toEqual(makeTip(3));
@@ -439,7 +435,8 @@ export function testL2TipsStore(makeTipsStore) {
         // Prove up to block 3
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-proven',
-            block: makeBlockId(3)
+            block: makeBlockId(3),
+            checkpoint: makeCheckpointIdForBlock(3)
         });
         let tips = await tipsStore.getL2Tips();
         expect(tips.proposed).toEqual(makeTip(3));
@@ -479,10 +476,8 @@ export function testL2TipsStore(makeTipsStore) {
         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();
         expect(tips.proposed).toEqual(makeTip(3));
@@ -525,22 +520,195 @@ export function testL2TipsStore(makeTipsStore) {
         expect(await tipsStore.getL2BlockHash(6)).not.toEqual(originalHash6);
         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)
             ]
         });
+        // Block 3 has no local block->checkpoint mapping, but the event carries a real checkpoint id.
+        const carriedCheckpoint = {
+            number: CheckpointNumber(1),
+            hash: new Fr(42).toString()
+        };
         await tipsStore.handleBlockStreamEvent({
             type: 'chain-proven',
-            block: makeBlockId(3)
+            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 = {
+            number: CheckpointNumber(2),
+            hash: new Fr(101).toString()
+        };
+        const finalizedCheckpoint = {
+            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;
+        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/dest/config/index.d.ts

@@ -1,4 +1,5 @@
 export * from './chain-config.js';
+export * from './network-consensus-config.js';
 export * from './node-rpc-config.js';
 export * from './sequencer-config.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb25maWcvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsdUJBQXVCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb25maWcvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLCtCQUErQixDQUFDO0FBQzlDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyx1QkFBdUIsQ0FBQyJ9

package/dest/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/dest/config/index.js

@@ -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';

package/dest/config/network-consensus-config.d.ts

@@ -0,0 +1,72 @@
+import { type L1ContractsConfig } from '@aztec/ethereum/config';
+import type { SequencerConfig } from '../interfaces/configs.js';
+/**
+ * Environment variables whose values must be identical across every node of a network. They fall into three
+ * categories, all consensus-critical:
+ *
+ * - Timing/protocol consensus: slot and epoch durations, block sub-slot duration, max blocks per checkpoint, and
+ *   the checkpoint-proposal materialization grace. Proposers and validators must agree on these to land on the
+ *   same proposed chain and the same checkpoint-proposal receive/handoff deadlines.
+ * - Network identity and L1-posted deployment params: the L1 chain id and the staking/governance/slashing
+ *   parameters baked into the deployed rollup contract (committee size, lags, thresholds, mana target, fee
+ *   pricing, governance/slashing round sizes, quorums, slash amounts, etc.). A node disagreeing with the rollup
+ *   it points at would compute the wrong epoch geometry, fees, or slashing rounds.
+ * - Node-side slashing offense consensus: the offense detection/penalty parameters validators apply locally to
+ *   decide which payloads to sign. Validators must agree on these to reach the on-chain slashing quorum.
+ *
+ * Deliberately excluded: bootnodes, P2P/store/OTEL/sentinel settings, SEQ_MIN_TX_PER_BLOCK, SEQ_MAX_TX_PER_*,
+ * AZTEC_SLASHER_ENABLED, PROVER_REAL_PROOFS, TRANSACTIONS_DISABLED, and AZTEC_ENTRY_QUEUE_* (mainnet-only genesis
+ * params enforced by L1).
+ */
+export declare const NETWORK_CONSENSUS_ENV_VARS: readonly ["ETHEREUM_SLOT_DURATION", "AZTEC_SLOT_DURATION", "AZTEC_EPOCH_DURATION", "SEQ_BLOCK_DURATION_MS", "MAX_BLOCKS_PER_CHECKPOINT", "CHECKPOINT_PROPOSAL_SYNC_GRACE_SECONDS", "L1_CHAIN_ID", "AZTEC_TARGET_COMMITTEE_SIZE", "AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET", "AZTEC_LAG_IN_EPOCHS_FOR_RANDAO", "AZTEC_ACTIVATION_THRESHOLD", "AZTEC_EJECTION_THRESHOLD", "AZTEC_LOCAL_EJECTION_THRESHOLD", "AZTEC_EXIT_DELAY_SECONDS", "AZTEC_INBOX_LAG", "AZTEC_PROOF_SUBMISSION_EPOCHS", "AZTEC_MANA_TARGET", "AZTEC_PROVING_COST_PER_MANA", "AZTEC_INITIAL_ETH_PER_FEE_ASSET", "AZTEC_GOVERNANCE_PROPOSER_ROUND_SIZE", "AZTEC_GOVERNANCE_PROPOSER_QUORUM", "AZTEC_SLASHING_QUORUM", "AZTEC_SLASHING_ROUND_SIZE_IN_EPOCHS", "AZTEC_SLASHING_LIFETIME_IN_ROUNDS", "AZTEC_SLASHING_OFFSET_IN_ROUNDS", "AZTEC_SLASHING_EXECUTION_DELAY_IN_ROUNDS", "AZTEC_SLASHING_VETOER", "AZTEC_SLASHING_DISABLE_DURATION", "AZTEC_SLASH_AMOUNT_SMALL", "AZTEC_SLASH_AMOUNT_MEDIUM", "AZTEC_SLASH_AMOUNT_LARGE", "SLASH_OFFENSE_EXPIRATION_ROUNDS", "SLASH_MAX_PAYLOAD_SIZE", "SLASH_EXECUTE_ROUNDS_LOOK_BACK", "SLASH_DATA_WITHHOLDING_TOLERANCE_SLOTS", "SLASH_DATA_WITHHOLDING_PENALTY", "SLASH_INACTIVITY_TARGET_PERCENTAGE", "SLASH_INACTIVITY_CONSECUTIVE_EPOCH_THRESHOLD", "SLASH_INACTIVITY_PENALTY", "SLASH_PROPOSE_INVALID_ATTESTATIONS_PENALTY", "SLASH_DUPLICATE_PROPOSAL_PENALTY", "SLASH_DUPLICATE_ATTESTATION_PENALTY", "SLASH_PROPOSE_DESCENDANT_OF_CHECKPOINT_WITH_INVALID_ATTESTATIONS_PENALTY", "SLASH_ATTEST_INVALID_CHECKPOINT_PROPOSAL_PENALTY", "SLASH_UNKNOWN_PENALTY", "SLASH_INVALID_BLOCK_PENALTY", "SLASH_INVALID_CHECKPOINT_PROPOSAL_PENALTY", "SLASH_GRACE_PERIOD_L2_SLOTS"];
+/** A consensus-critical environment variable name; see {@link NETWORK_CONSENSUS_ENV_VARS}. */
+export type ConsensusEnvVar = (typeof NETWORK_CONSENSUS_ENV_VARS)[number];
+/**
+ * The subset of consensus-critical timing config whose geometry can be validated in isolation. Composed by
+ * picking the canonical fields from their owning config types so the field set never drifts from the config
+ * layer: slot durations from {@link L1ContractsConfig}, block sub-slot/checkpoint timings from
+ * {@link SequencerConfig} (whose fields are optional there, hence `Required`).
+ */
+export type NetworkConsensusConfig = Pick<L1ContractsConfig, 'aztecSlotDuration' | 'ethereumSlotDuration'> & Required<Pick<SequencerConfig, 'blockDurationMs' | 'maxBlocksPerCheckpoint' | 'checkpointProposalSyncGraceSeconds'>>;
+/**
+ * Extracts the timing {@link NetworkConsensusConfig} from a generated network config object. The env-var names
+ * and the per-field parsing both come from the canonical config mappings (`l1ContractsConfigMappings` and
+ * `sharedSequencerConfigMappings`), so each field is parsed exactly as the node's config layer would parse it.
+ * A field whose env var is absent becomes `NaN`, which {@link validateNetworkConsensusConfig} reports as an
+ * error. Never throws: parse helpers that would throw or yield `undefined` are coerced to `NaN`.
+ */
+export declare function getConsensusConfigFromNetworkEnv(values: Record<string, string | number | boolean>): NetworkConsensusConfig;
+/**
+ * Validates a {@link NetworkConsensusConfig} for self-consistency, returning a list of error messages (empty
+ * when valid). Used by the cli unit test that gates the generated network configs.
+ *
+ * The check requires `maxBlocksPerCheckpoint` to be *exactly* what a {@link ProposerTimetable} built from the
+ * same slot timings and the production default budgets derives. This exact-equality requirement ensures the
+ * published network value is precisely what the production default budgets produce, so every node running those
+ * defaults agrees on the per-checkpoint block count without clamping.
+ */
+export declare function validateNetworkConsensusConfig(config: NetworkConsensusConfig): string[];
+/**
+ * Enforces that operators do not silently override consensus-critical values diverging from the network config.
+ *
+ * For each var in {@link NETWORK_CONSENSUS_ENV_VARS} present in `networkConfig`: if the operator set it in `env`
+ * to a conflicting value, this throws unless `ALLOW_OVERRIDING_NETWORK_CONFIG` is truthy (in which case it logs
+ * and keeps the operator value).
+ *
+ * This function is pure: it never writes to `env`. Instead it returns the canonical env writes the caller
+ * should apply — a map of env-var name to canonical string value for every numeric var whose env value matched
+ * the network value numerically. Applying these closes a bypass where the config layer parses some vars with
+ * `parseInt` (which reads '6e3' as 6); rewriting them to the network value's string form keeps the operator's
+ * numerically-equal value but in canonical form. Vars kept under `ALLOW_OVERRIDING_NETWORK_CONFIG` (genuine
+ * conflicts) are not included, so the operator value is preserved untouched.
+ *
+ * @returns Canonical env writes (env-var name -> canonical string value) for the caller to apply.
+ */
+export declare function checkConsensusEnvOverrides(networkConfig: Record<string, string | number | boolean>, env?: {
+    [key: string]: string | undefined;
+}, log?: (msg: string) => void): Record<string, string>;
+/** Whether the env opts into overriding network-wide consensus values (`ALLOW_OVERRIDING_NETWORK_CONFIG`). */
+export declare function allowsNetworkConfigOverride(env?: {
+    [key: string]: string | undefined;
+}): boolean;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV0d29yay1jb25zZW5zdXMtY29uZmlnLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29uZmlnL25ldHdvcmstY29uc2Vuc3VzLWNvbmZpZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsS0FBSyxpQkFBaUIsRUFBNkIsTUFBTSx3QkFBd0IsQ0FBQztBQUczRixPQUFPLEtBQUssRUFBRSxlQUFlLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQVVoRTs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FpQkc7QUFDSCxlQUFPLE1BQU0sMEJBQTBCLDJsREFzREQsQ0FBQztBQUV2Qyw4RkFBOEY7QUFDOUYsTUFBTSxNQUFNLGVBQWUsR0FBRyxDQUFDLE9BQU8sMEJBQTBCLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQztBQUUxRTs7Ozs7R0FLRztBQUNILE1BQU0sTUFBTSxzQkFBc0IsR0FBRyxJQUFJLENBQUMsaUJBQWlCLEVBQUUsbUJBQW1CLEdBQUcsc0JBQXNCLENBQUMsR0FDeEcsUUFBUSxDQUFDLElBQUksQ0FBQyxlQUFlLEVBQUUsaUJBQWlCLEdBQUcsd0JBQXdCLEdBQUcsb0NBQW9DLENBQUMsQ0FBQyxDQUFDO0FBWXZIOzs7Ozs7R0FNRztBQUNILHdCQUFnQixnQ0FBZ0MsQ0FDOUMsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNLEVBQUUsTUFBTSxHQUFHLE1BQU0sR0FBRyxPQUFPLENBQUMsR0FDaEQsc0JBQXNCLENBaUJ4QjtBQUVEOzs7Ozs7OztHQVFHO0FBQ0gsd0JBQWdCLDhCQUE4QixDQUFDLE1BQU0sRUFBRSxzQkFBc0IsR0FBRyxNQUFNLEVBQUUsQ0E4RXZGO0FBRUQ7Ozs7Ozs7Ozs7Ozs7OztHQWVHO0FBQ0gsd0JBQWdCLDBCQUEwQixDQUN4QyxhQUFhLEVBQUUsTUFBTSxDQUFDLE1BQU0sRUFBRSxNQUFNLEdBQUcsTUFBTSxHQUFHLE9BQU8sQ0FBQyxFQUN4RCxHQUFHLEdBQUU7SUFBRSxDQUFDLEdBQUcsRUFBRSxNQUFNLEdBQUcsTUFBTSxHQUFHLFNBQVMsQ0FBQTtDQUFnQixFQUN4RCxHQUFHLENBQUMsRUFBRSxDQUFDLEdBQUcsRUFBRSxNQUFNLEtBQUssSUFBSSxHQUMxQixNQUFNLENBQUMsTUFBTSxFQUFFLE1BQU0sQ0FBQyxDQWlEeEI7QUFFRCw4R0FBOEc7QUFDOUcsd0JBQWdCLDJCQUEyQixDQUFDLEdBQUcsR0FBRTtJQUFFLENBQUMsR0FBRyxFQUFFLE1BQU0sR0FBRyxNQUFNLEdBQUcsU0FBUyxDQUFBO0NBQWdCLEdBQUcsT0FBTyxDQUc3RyJ9

package/dest/config/network-consensus-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-consensus-config.d.ts","sourceRoot":"","sources":["../../src/config/network-consensus-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAA6B,MAAM,wBAAwB,CAAC;AAG3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAUhE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,2lDAsDD,CAAC;AAEvC,8FAA8F;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,iBAAiB,EAAE,mBAAmB,GAAG,sBAAsB,CAAC,GACxG,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,iBAAiB,GAAG,wBAAwB,GAAG,oCAAoC,CAAC,CAAC,CAAC;AAYvH;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAChD,sBAAsB,CAiBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,CA8EvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACxD,GAAG,GAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAgB,EACxD,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiDxB;AAED,8GAA8G;AAC9G,wBAAgB,2BAA2B,CAAC,GAAG,GAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAgB,GAAG,OAAO,CAG7G"}