@aztec/stdlib 5.0.0-nightly.20260616 → 5.0.0-nightly.20260618

package/dest/block/l2_block_stream/l2_block_stream.js

@@ -1,9 +1,8 @@
-import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { AbortError } from '@aztec/foundation/error';
 import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 import { makeL2BlockId } from '../l2_block_source.js';
-/** Maximum number of checkpoints to prefetch at once during sync. Matches MAX_RPC_CHECKPOINTS_LEN. */ export const CHECKPOINT_PREFETCH_LIMIT = 50;
 /** Creates a stream of events for new blocks, chain tips updates, and reorgs, out of polling an archiver or a node. */ export class L2BlockStream {
     l2BlockSource;
     localData;
@@ -21,6 +20,9 @@ import { makeL2BlockId } from '../l2_block_source.js';
         this.opts = opts;
         this.isSyncing = false;
         this.hasStarted = false;
+        if (opts.tipsOnly && (opts.startingBlock !== undefined || opts.batchSize !== undefined || opts.skipFinalized)) {
+            throw new Error('tipsOnly is incompatible with startingBlock, batchSize, and skipFinalized: all three are ' + 'block-download options and there is no download loop in tips-only mode.');
+        }
         // Note that RunningPromise is in stopped state by default. This promise won't run until someone invokes `start`,
         // which makes it run periodically, or `sync`, which triggers it once.
         // Users of L2BlockStream decide what mode to run it in (_periodically_ vs _manually triggered_).
@@ -48,7 +50,8 @@ import { makeL2BlockId } from '../l2_block_source.js';
     }
     async work() {
         try {
-            const sourceTips = await this.l2BlockSource.getL2Tips();
+            // The source tips snapshot is the plan for this pass; it is re-read after the walk-back if a divergence is found.
+            let sourceTips = await this.l2BlockSource.getL2Tips();
             const localTips = await this.localData.getL2Tips();
             this.log.trace(`Running L2 block stream`, {
                 sourceTips,
@@ -57,29 +60,52 @@ import { makeL2BlockId } from '../l2_block_source.js';
             if (!this.opts.ignoreCheckpoints && localTips.checkpointed === undefined) {
                 throw new Error('Local data provider does not expose a checkpointed tip; checkpoint events require one ' + '(set ignoreCheckpoints or provide checkpointed tips).');
             }
-            // Check if there was a reorg and emit a chain-pruned event if so.
+            // Baseline for the chain-proposed event; captured before the local store mutates during the pass.
+            const prePassProposed = localTips.proposed;
+            // Walk back to find a reorg, floored at the local finalized tip (a legitimate reorg can never reach it, since
+            // finalized means the proving tx is itself L1-finalized). Seed the cache with ONLY the proposed tip: a stale
+            // tier seed at a reorged height equals the local old-fork hash, faking agreement and stopping the walk above the
+            // true divergence (an under-deep prune no later pass re-detects), whereas a stale proposed seed only masks the
+            // tip for one pass.
             let latestBlockNumber = localTips.proposed.number;
             const sourceCache = new BlockHashCache([
                 sourceTips.proposed
             ]);
+            const walkFloor = localTips.finalized.block.number;
             while(!await this.areBlockHashesEqualAt(latestBlockNumber, {
-                sourceCache
+                sourceCache,
+                sourceProposed: sourceTips.proposed.number
             })){
                 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.
+                    // Walked back to genesis and the hashes still differ: the two sides disagree on block 0 itself (usually
+                    // different genesisTimestamp/prefilled state). Fail loudly rather than underflow into negative heights.
                     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).');
                 }
+                if (latestBlockNumber <= walkFloor) {
+                    // A mismatch at or below the finalized tip cannot be a reorg (it contradicts L1-finalized state), so stop
+                    // here and prune at most to the finalized tip rather than pruning finalized state on non-reorg evidence.
+                    this.log.warn(`Block hash mismatch at or below the local finalized tip; stopping the walk-back here`, {
+                        blockNumber: latestBlockNumber,
+                        finalizedBlockNumber: walkFloor,
+                        localBlockHash: await this.localData.getL2BlockHash(latestBlockNumber),
+                        sourceBlockHash: sourceCache.get(latestBlockNumber) ?? await this.getBlockHashFromSource(latestBlockNumber)
+                    });
+                    break;
+                }
                 latestBlockNumber--;
             }
+            let pruned = false;
             if (latestBlockNumber < localTips.proposed.number) {
+                // Re-read the source tips after the (possibly slow) walk-back so the prune event carries fresh checkpointed
+                // and proven tips, and the prune-target clamp, download plan, and tier reconciliation track the post-prune
+                // source chain. Append only the re-read proposed tip: it is a fresh entry that cannot poison the (already
+                // finished) walk and serves the prune-event hash lookup below.
+                sourceTips = await this.l2BlockSource.getL2Tips();
+                sourceCache.add(sourceTips.proposed);
                 latestBlockNumber = BlockNumber(Math.min(latestBlockNumber, sourceTips.proposed.number)); // see #13471
                 const hash = sourceCache.get(latestBlockNumber) ?? await this.getBlockHashFromSource(latestBlockNumber);
                 if (latestBlockNumber !== 0 && !hash) {
@@ -92,160 +118,39 @@ import { makeL2BlockId } from '../l2_block_source.js';
                     checkpointed: sourceTips.checkpointed,
                     proven: sourceTips.proven
                 });
+                pruned = true;
             }
-            // If we are just starting, use the starting block number from the options.
-            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)
-            if (!this.hasStarted) {
-                this.log.verbose(`Starting sync from block number ${latestBlockNumber}`);
-                this.hasStarted = true;
-            }
-            let nextBlockNumber = latestBlockNumber + 1;
-            // When checkpoints are ignored the local provider may omit `checkpointed`; in that case the fallback to
-            // CheckpointNumber.ZERO is harmless because `nextCheckpointToEmit` is never consumed for emission (Loop 1 and
-            // the startingBlock/skipFinalized adjustments below only feed checkpoint emission, which is gated off).
-            let nextCheckpointToEmit = CheckpointNumber((localTips.checkpointed?.checkpoint.number ?? CheckpointNumber.ZERO) + 1);
-            // When startingBlock is set, also skip ahead for checkpoints.
-            if (startingBlock !== undefined && startingBlock >= 1 && nextCheckpointToEmit <= sourceTips.checkpointed.checkpoint.number) {
-                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));
-                    }
-                }
-            }
-            if (this.opts.skipFinalized) {
-                // When skipping finalized blocks we need to provide reliable reorg detection while fetching as few blocks as
-                // possible. Finalized blocks cannot be reorged by definition, so we can skip most of them. We do need the very
-                // last finalized block however in order to guarantee that we will eventually find a block in which our local
-                // store matches the source.
-                // If the last finalized block is behind our local tip, there is nothing to skip.
-                nextBlockNumber = Math.max(sourceTips.finalized.block.number, nextBlockNumber);
-                // If the next checkpoint to emit is behind the finalized tip then skip forward
-                nextCheckpointToEmit = CheckpointNumber(Math.max(nextCheckpointToEmit, sourceTips.finalized.checkpoint.number));
-            }
-            // Loop 1: Emit checkpoint events for checkpoints whose blocks are already in local storage.
-            // This handles the case where blocks were synced as uncheckpointed and later became checkpointed.
-            // The guard `lastBlockInCheckpoint.number > localTips.proposed.number` ensures we don't emit
-            // checkpoints for blocks we don't have (e.g., when startingBlock skips earlier blocks).
-            // Since only one checkpoint can ever be uncheckpointed, this loop should iterate at most once.
-            if (!this.opts.ignoreCheckpoints) {
-                let loop1Iterations = 0;
-                while(nextCheckpointToEmit <= sourceTips.checkpointed.checkpoint.number){
-                    const checkpoints = await this.l2BlockSource.getCheckpoints({
-                        from: nextCheckpointToEmit,
-                        limit: 1
-                    });
-                    if (checkpoints.length === 0) {
-                        break;
-                    }
-                    const lastBlockInCheckpoint = checkpoints[0].checkpoint.blocks.at(-1);
-                    // If this checkpoint has blocks we haven't seen yet, stop - they need to be fetched first
-                    if (lastBlockInCheckpoint.number > localTips.proposed.number) {
-                        break;
-                    }
-                    loop1Iterations++;
-                    if (loop1Iterations > 1) {
-                        this.log.warn(`Emitting multiple checkpoints (${loop1Iterations}) for already-local blocks. ` + `Next checkpoint: ${nextCheckpointToEmit}, source checkpointed: ${sourceTips.checkpointed.checkpoint.number}`);
-                    }
-                    const lastBlockHash = await lastBlockInCheckpoint.hash();
-                    await this.emitEvent({
-                        type: 'chain-checkpointed',
-                        checkpoint: checkpoints[0],
-                        block: makeL2BlockId(lastBlockInCheckpoint.number, lastBlockHash.toString())
-                    });
-                    nextCheckpointToEmit = CheckpointNumber(nextCheckpointToEmit + 1);
-                }
-            }
-            // Loop 2: Fetch new checkpointed blocks. For each checkpoint, emit all blocks
-            // from that checkpoint that we need, then emit the checkpoint event.
-            // We prefetch multiple checkpoints, then process them one by one.
-            let prefetchedCheckpoints = [];
-            let prefetchIdx = 0;
-            let nextCheckpointNumber;
-            // Find the starting checkpoint number
-            if (nextBlockNumber <= sourceTips.checkpointed.block.number) {
-                const blockData = await this.l2BlockSource.getBlockData({
-                    number: BlockNumber(nextBlockNumber)
-                });
-                if (blockData) {
-                    nextCheckpointNumber = blockData.checkpointNumber;
-                }
+            // Pass atomicity: a prune mid-download leaves the source unable to serve the planned blocks, so the snapshot's
+            // tier tips may reference blocks the consumer never saw — skip tier reconciliation in that case. Tips-only mode
+            // has no download plan (the snapshot is one atomic getL2Tips read), so it always reconciles.
+            if (!this.opts.tipsOnly && !await this.downloadBlocks(latestBlockNumber, sourceTips)) {
+                return;
             }
-            while(nextBlockNumber <= sourceTips.checkpointed.block.number && nextCheckpointNumber !== undefined){
-                // Refill the prefetch buffer when exhausted
-                if (prefetchIdx >= prefetchedCheckpoints.length) {
-                    const prefetchLimit = this.opts.checkpointPrefetchLimit ?? CHECKPOINT_PREFETCH_LIMIT;
-                    prefetchedCheckpoints = await this.l2BlockSource.getCheckpoints({
-                        from: nextCheckpointNumber,
-                        limit: prefetchLimit
-                    });
-                    prefetchIdx = 0;
-                    if (prefetchedCheckpoints.length === 0) {
-                        break;
-                    }
-                }
-                const checkpoint = prefetchedCheckpoints[prefetchIdx];
-                // Get all blocks from this checkpoint that we need, respecting batchSize
-                const limit = Math.min(this.opts.batchSize ?? 50, sourceTips.checkpointed.block.number - nextBlockNumber + 1);
-                const blocksForCheckpoint = checkpoint.checkpoint.blocks.filter((b)=>b.number >= nextBlockNumber).slice(0, limit);
-                if (blocksForCheckpoint.length === 0) {
-                    break;
-                }
+            // End-of-pass reconciliation: chain-proposed fires against the pre-pass baseline (a post-prune re-read would
+            // equal the source tip and suppress it), then the tiers highest-to-lowest so the finalized <= proven <=
+            // checkpointed <= proposed invariant holds mid-pass.
+            if (this.blockTipDiffers(prePassProposed, sourceTips.proposed)) {
                 await this.emitEvent({
-                    type: 'blocks-added',
-                    blocks: blocksForCheckpoint
+                    type: 'chain-proposed',
+                    block: sourceTips.proposed
                 });
-                nextBlockNumber = blocksForCheckpoint.at(-1).number + 1;
-                // If we've reached the end of this checkpoint, emit the checkpoint event and move to next
-                const lastBlockInCheckpoint = checkpoint.checkpoint.blocks.at(-1);
-                if (nextBlockNumber > lastBlockInCheckpoint.number) {
-                    if (!this.opts.ignoreCheckpoints) {
-                        const lastBlockHash = await lastBlockInCheckpoint.hash();
-                        await this.emitEvent({
-                            type: 'chain-checkpointed',
-                            checkpoint,
-                            block: makeL2BlockId(lastBlockInCheckpoint.number, lastBlockHash.toString())
-                        });
-                    }
-                    prefetchIdx++;
-                    nextCheckpointNumber = CheckpointNumber(nextCheckpointNumber + 1);
-                }
             }
-            // Loop 3: Fetch any remaining uncheckpointed (proposed) blocks.
-            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({
-                    from: BlockNumber(nextBlockNumber),
-                    limit
-                });
-                if (blocks.length === 0) {
-                    break;
-                }
+            const reconcileTips = pruned ? await this.localData.getL2Tips() : localTips;
+            if (!this.opts.ignoreCheckpoints && this.tipDiffers(reconcileTips.checkpointed?.block, sourceTips.checkpointed)) {
                 await this.emitEvent({
-                    type: 'blocks-added',
-                    blocks
+                    type: 'chain-checkpointed',
+                    block: sourceTips.checkpointed.block,
+                    checkpoint: sourceTips.checkpointed.checkpoint
                 });
-                nextBlockNumber = blocks.at(-1).number + 1;
             }
-            // Update the proven and finalized tips.
-            if (localTips.proven !== undefined && sourceTips.proven.block.number !== localTips.proven.block.number) {
+            if (reconcileTips.proven !== undefined && this.tipDiffers(reconcileTips.proven.block, sourceTips.proven)) {
                 await this.emitEvent({
                     type: 'chain-proven',
                     block: sourceTips.proven.block,
                     checkpoint: sourceTips.proven.checkpoint
                 });
             }
-            if (localTips.finalized !== undefined && sourceTips.finalized.block.number !== localTips.finalized.block.number) {
+            if (reconcileTips.finalized !== undefined && this.tipDiffers(reconcileTips.finalized.block, sourceTips.finalized)) {
                 await this.emitEvent({
                     type: 'chain-finalized',
                     block: sourceTips.finalized.block,
@@ -260,9 +165,101 @@ import { makeL2BlockId } from '../l2_block_source.js';
         }
     }
     /**
+   * Downloads every block from the post-prune cursor through the source's proposed tip, emitting `blocks-added`
+   * events. The return value gates tier-cursor advancement (pass atomicity): tier tips may only be reconciled when
+   * the plan that backs them ran to the proposed tip.
+   * @returns `true` if the plan completed (caught up, or delivered the proposed tip with a matching hash); `false` if
+   * the source no longer has a promised block, or served a fork at the proposed height mid-pass.
+   */ async downloadBlocks(latestBlockNumber, sourceTips) {
+        // The post-prune cursor: the highest block number both sides agree on. Block downloads resume from here.
+        let nextBlockNumber = latestBlockNumber + 1;
+        // From a fresh local store, fast-forward past history the consumer doesn't care about.
+        const startingBlock = this.opts.startingBlock !== undefined ? BlockNumber(this.opts.startingBlock) : undefined;
+        if (latestBlockNumber === 0 && startingBlock !== undefined) {
+            nextBlockNumber = Math.max(startingBlock, 1);
+        }
+        if (this.opts.skipFinalized) {
+            // Finalized blocks cannot be reorged, so skip them — but keep the last finalized block as the guaranteed point
+            // where local and source agree, the floor the walk-back terminates against.
+            nextBlockNumber = Math.max(sourceTips.finalized.block.number, nextBlockNumber);
+        }
+        if (!this.hasStarted) {
+            this.log.verbose(`Starting sync from block number ${nextBlockNumber - 1}`);
+            this.hasStarted = true;
+        }
+        let lastDeliveredBlock;
+        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({
+                from: BlockNumber(nextBlockNumber),
+                limit
+            });
+            if (blocks.length === 0) {
+                // The source no longer has a block the snapshot promised: the snapshot is provably stale, so report the plan
+                // incomplete and skip reconciliation this pass.
+                this.log.warn(`Block source returned no blocks for a promised range; skipping reconciliation this pass`, {
+                    from: nextBlockNumber,
+                    limit,
+                    sourceProposed: sourceTips.proposed.number
+                });
+                return false;
+            }
+            await this.emitEvent({
+                type: 'blocks-added',
+                blocks
+            });
+            lastDeliveredBlock = blocks.at(-1);
+            nextBlockNumber = lastDeliveredBlock.number + 1;
+        }
+        if (lastDeliveredBlock === undefined) {
+            // Loop never ran: caught up before the plan started, or startingBlock past the tip (A-1061). Trivially complete.
+            return true;
+        }
+        // Complete iff the block delivered at the proposed height carries the snapshot's proposed hash; a different hash
+        // means a same-height fork swap happened mid-pass, so the snapshot is stale.
+        const deliveredHash = (await lastDeliveredBlock.hash()).toString();
+        if (deliveredHash !== sourceTips.proposed.hash) {
+            this.log.warn(`Delivered proposed-block hash differs from snapshot; skipping reconciliation this pass`, {
+                blockNumber: lastDeliveredBlock.number,
+                deliveredHash,
+                snapshotHash: sourceTips.proposed.hash
+            });
+            return false;
+        }
+        return true;
+    }
+    /**
+   * Returns whether the source tip differs from the local one and therefore warrants a tier event. Compares block
+   * number and, when both hashes are known, block hash. The hash comparison is skipped when the local hash is
+   * undefined or missing: world-state legitimately reports `undefined` hashes for tips ahead of its synced range,
+   * and comparing against an undefined hash would re-emit the event on every poll.
+   */ tipDiffers(localBlock, sourceTip) {
+        return this.blockTipDiffers(localBlock, sourceTip.block);
+    }
+    /**
+   * Block-only variant of {@link tipDiffers} for the proposed tip (an {@link L2BlockId}, with no checkpoint). Compares
+   * block number and, when the local hash is known, block hash. The hash comparison is skipped when the local hash is
+   * undefined: world-state reports `undefined` for its proposed hash, and a strict comparison would re-emit
+   * `chain-proposed` on every poll for it. ({@link L2TipsStoreBase} consumers always carry a hash, so the leniency is
+   * inert for them.)
+   */ blockTipDiffers(localBlock, sourceBlock) {
+        if (localBlock === undefined) {
+            return true;
+        }
+        if (sourceBlock.number !== localBlock.number) {
+            return true;
+        }
+        if (localBlock.hash === undefined) {
+            return false;
+        }
+        return sourceBlock.hash !== localBlock.hash;
+    }
+    /**
    * Returns whether the source and local agree on the block hash at a given height.
    * @param blockNumber - The block number to test.
-   * @param args - A cache of data already requested from source, to avoid re-requesting it.
+   * @param args - A cache of data already requested from source (to avoid re-requesting it) and the source's
+   * advertised proposed tip from the pass snapshot (to detect an incoherent source).
    */ async areBlockHashesEqualAt(blockNumber, args) {
         const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
         if (!localBlockHash && this.opts.skipFinalized) {
@@ -273,6 +270,13 @@ import { makeL2BlockId } from '../l2_block_source.js';
             this.log.error(`No local block hash for block number ${blockNumber}`);
             throw new AbortError();
         }
+        if (!localBlockHash) {
+            // A missing local hash compares UNEQUAL: treating both-undefined as equal would stop the walk above the true
+            // divergence (an under-deep prune no later pass re-detects). Over-deep is the safe direction, and block 0 always
+            // resolves via the store's initialBlockHash so the walk always terminates.
+            this.log.trace(`No local block hash for block number ${blockNumber}; treating as unequal`);
+            return false;
+        }
         const sourceBlockHashFromCache = args.sourceCache.get(blockNumber);
         const sourceBlockHash = args.sourceCache.get(blockNumber) ?? await this.getBlockHashFromSource(blockNumber);
         if (!sourceBlockHashFromCache && sourceBlockHash) {
@@ -281,6 +285,15 @@ import { makeL2BlockId } from '../l2_block_source.js';
                 hash: sourceBlockHash
             });
         }
+        if (!sourceBlockHash && blockNumber !== 0 && blockNumber <= args.sourceProposed) {
+            // No source data at or below the source's own proposed tip: the source contradicts itself (mid-reorg unwind or
+            // a transient read failure), so skip this pass.
+            this.log.warn(`Source has no data for a block at or below its proposed tip; skipping this sync pass`, {
+                blockNumber,
+                sourceProposed: args.sourceProposed
+            });
+            throw new AbortError();
+        }
         this.log.trace(`Comparing block hashes for block ${blockNumber}`, {
             localBlockHash,
             sourceBlockHash
@@ -293,7 +306,7 @@ import { makeL2BlockId } from '../l2_block_source.js';
         }).then((d)=>d?.header.hash()).then((hash)=>hash?.toString());
     }
     async emitEvent(event) {
-        this.log.debug(`Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.type === 'chain-checkpointed' ? event.checkpoint.checkpoint.number : event.block.number})`);
+        this.log.debug(`Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.type === 'chain-checkpointed' ? event.checkpoint.number : event.block.number})`);
         await this.handler.handleBlockStreamEvent(event);
         if (!this.isRunning() && !this.isSyncing) {
             throw new AbortError();

package/dest/block/l2_block_stream/l2_tips_store_base.d.ts

@@ -1,7 +1,7 @@
 import { BlockNumber } from '@aztec/foundation/branded-types';
 import type { BlockHash } from '../block_hash.js';
 import type { L2Block } from '../l2_block.js';
-import { type CheckpointId, type L2BlockTag, type LocalL2Tips } from '../l2_block_source.js';
+import { type CheckpointId, type L2BlockId, type L2BlockTag, type LocalL2Tips } from '../l2_block_source.js';
 import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
 /**
  * Abstract base class for L2 tips stores. Provides common event handling logic
@@ -28,16 +28,24 @@ export declare abstract class L2TipsStoreBase implements L2BlockStreamEventHandl
     protected abstract runInTransaction<T>(fn: () => Promise<T>): Promise<T>;
     getL2BlockHash(number: BlockNumber): Promise<string | undefined>;
     getL2Tips(): Promise<LocalL2Tips>;
+    /**
+     * Records `(number → hash)` witnesses into the block-hash index without moving any tip cursor. In tips-only mode
+     * the hash history is sparse (one anchor per tip-moving poll), so a consumer that materializes per-height state
+     * should witness those heights or its prunes are over-deep by the gap to the nearest anchor. Witnesses are compared
+     * against the source, not trusted, so they cannot cause under-deep prunes; this is always safe to call.
+     */
+    recordBlockHashes(blocks: L2BlockId[]): Promise<void>;
     handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
     protected computeBlockHash(block: L2Block): Promise<string>;
     private getBlockId;
     private getCheckpointId;
     private genesisCheckpointId;
     private handleBlocksAdded;
+    private handleChainProposed;
     private handleChainCheckpointed;
     private handleChainPruned;
     private handleChainProven;
     private handleChainFinalized;
     private saveTag;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibDJfdGlwc19zdG9yZV9iYXNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmxvY2svbDJfYmxvY2tfc3RyZWFtL2wyX3RpcHNfc3RvcmVfYmFzZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFvQixNQUFNLGlDQUFpQyxDQUFDO0FBRWhGLE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ2xELE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBQzlDLE9BQU8sRUFDTCxLQUFLLFlBQVksRUFHakIsS0FBSyxVQUFVLEVBQ2YsS0FBSyxXQUFXLEVBQ2pCLE1BQU0sdUJBQXVCLENBQUM7QUFDL0IsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQUUseUJBQXlCLEVBQUUsOEJBQThCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUVySDs7O0dBR0c7QUFDSCw4QkFBc0IsZUFBZ0IsWUFBVyx5QkFBeUIsRUFBRSw4QkFBOEI7SUFDNUYsU0FBUyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsRUFBRSxTQUFTO0lBQTFELFlBQStCLGdCQUFnQixFQUFFLFNBQVMsRUFBSTtJQUc5RCw2Q0FBNkM7SUFDN0MsU0FBUyxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsR0FBRyxFQUFFLFVBQVUsR0FBRyxPQUFPLENBQUMsV0FBVyxHQUFHLFNBQVMsQ0FBQyxDQUFDO0lBRTdFLDZDQUE2QztJQUM3QyxTQUFTLENBQUMsUUFBUSxDQUFDLE1BQU0sQ0FBQyxHQUFHLEVBQUUsVUFBVSxFQUFFLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRXBGLCtEQUErRDtJQUMvRCxTQUFTLENBQUMsUUFBUSxDQUFDLGdCQUFnQixDQUFDLEdBQUcsRUFBRSxVQUFVLEdBQUcsT0FBTyxDQUFDLFlBQVksR0FBRyxTQUFTLENBQUMsQ0FBQztJQUV4RixpREFBaUQ7SUFDakQsU0FBUyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsQ0FBQyxHQUFHLEVBQUUsVUFBVSxFQUFFLFVBQVUsRUFBRSxZQUFZLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRTlGLG9EQUFvRDtJQUNwRCxTQUFTLENBQUMsUUFBUSxDQUFDLGtCQUFrQixDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FBQztJQUU3RixvREFBb0Q7SUFDcEQsU0FBUyxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQUMsV0FBVyxFQUFFLFdBQVcsRUFBRSxJQUFJLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUV2Rix5RUFBeUU7SUFDekUsU0FBUyxDQUFDLFFBQVEsQ0FBQyx1QkFBdUIsQ0FBQyxXQUFXLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUVwRiw0RkFBNEY7SUFDNUYsU0FBUyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDLEVBQUUsRUFBRSxFQUFFLE1BQU0sT0FBTyxDQUFDLENBQUMsQ0FBQyxHQUFHLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUk1RCxjQUFjLENBQUMsTUFBTSxFQUFFLFdBQVcsR0FBRyxPQUFPLENBQUMsTUFBTSxHQUFHLFNBQVMsQ0FBQyxDQUs1RTtJQUVNLFNBQVMsSUFBSSxPQUFPLENBQUMsV0FBVyxDQUFDLENBc0J2QztJQUVZLHNCQUFzQixDQUFDLEtBQUssRUFBRSxrQkFBa0IsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBa0I1RTtJQUdELFNBQVMsQ0FBQyxnQkFBZ0IsQ0FBQyxLQUFLLEVBQUUsT0FBTyxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FFMUQ7WUFJYSxVQUFVO1lBWVYsZUFBZTtJQWdCN0IsT0FBTyxDQUFDLG1CQUFtQjtZQUliLGlCQUFpQjtZQWFqQix1QkFBdUI7WUFjdkIsaUJBQWlCO1lBOEJqQixpQkFBaUI7WUFVakIsb0JBQW9CO1lBbUJwQixPQUFPO0NBTXRCIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibDJfdGlwc19zdG9yZV9iYXNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmxvY2svbDJfYmxvY2tfc3RyZWFtL2wyX3RpcHNfc3RvcmVfYmFzZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFvQixNQUFNLGlDQUFpQyxDQUFDO0FBRWhGLE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ2xELE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBQzlDLE9BQU8sRUFDTCxLQUFLLFlBQVksRUFFakIsS0FBSyxTQUFTLEVBQ2QsS0FBSyxVQUFVLEVBQ2YsS0FBSyxXQUFXLEVBQ2pCLE1BQU0sdUJBQXVCLENBQUM7QUFDL0IsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQUUseUJBQXlCLEVBQUUsOEJBQThCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUVySDs7O0dBR0c7QUFDSCw4QkFBc0IsZUFBZ0IsWUFBVyx5QkFBeUIsRUFBRSw4QkFBOEI7SUFDNUYsU0FBUyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsRUFBRSxTQUFTO0lBQTFELFlBQStCLGdCQUFnQixFQUFFLFNBQVMsRUFBSTtJQUc5RCw2Q0FBNkM7SUFDN0MsU0FBUyxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsR0FBRyxFQUFFLFVBQVUsR0FBRyxPQUFPLENBQUMsV0FBVyxHQUFHLFNBQVMsQ0FBQyxDQUFDO0lBRTdFLDZDQUE2QztJQUM3QyxTQUFTLENBQUMsUUFBUSxDQUFDLE1BQU0sQ0FBQyxHQUFHLEVBQUUsVUFBVSxFQUFFLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRXBGLCtEQUErRDtJQUMvRCxTQUFTLENBQUMsUUFBUSxDQUFDLGdCQUFnQixDQUFDLEdBQUcsRUFBRSxVQUFVLEdBQUcsT0FBTyxDQUFDLFlBQVksR0FBRyxTQUFTLENBQUMsQ0FBQztJQUV4RixpREFBaUQ7SUFDakQsU0FBUyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsQ0FBQyxHQUFHLEVBQUUsVUFBVSxFQUFFLFVBQVUsRUFBRSxZQUFZLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRTlGLG9EQUFvRDtJQUNwRCxTQUFTLENBQUMsUUFBUSxDQUFDLGtCQUFrQixDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FBQztJQUU3RixvREFBb0Q7SUFDcEQsU0FBUyxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQUMsV0FBVyxFQUFFLFdBQVcsRUFBRSxJQUFJLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUV2Rix5RUFBeUU7SUFDekUsU0FBUyxDQUFDLFFBQVEsQ0FBQyx1QkFBdUIsQ0FBQyxXQUFXLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUVwRiw0RkFBNEY7SUFDNUYsU0FBUyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDLEVBQUUsRUFBRSxFQUFFLE1BQU0sT0FBTyxDQUFDLENBQUMsQ0FBQyxHQUFHLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUk1RCxjQUFjLENBQUMsTUFBTSxFQUFFLFdBQVcsR0FBRyxPQUFPLENBQUMsTUFBTSxHQUFHLFNBQVMsQ0FBQyxDQUs1RTtJQUVNLFNBQVMsSUFBSSxPQUFPLENBQUMsV0FBVyxDQUFDLENBc0J2QztJQUVEOzs7OztPQUtHO0lBQ1UsaUJBQWlCLENBQUMsTUFBTSxFQUFFLFNBQVMsRUFBRSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FRakU7SUFFWSxzQkFBc0IsQ0FBQyxLQUFLLEVBQUUsa0JBQWtCLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQXFCNUU7SUFHRCxTQUFTLENBQUMsZ0JBQWdCLENBQUMsS0FBSyxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLENBRTFEO1lBSWEsVUFBVTtZQVlWLGVBQWU7SUFnQjdCLE9BQU8sQ0FBQyxtQkFBbUI7WUFJYixpQkFBaUI7WUFhakIsbUJBQW1CO1lBU25CLHVCQUF1QjtZQVV2QixpQkFBaUI7WUEyQmpCLGlCQUFpQjtZQVVqQixvQkFBb0I7WUFtQnBCLE9BQU87Q0FNdEIifQ==

package/dest/block/l2_block_stream/l2_tips_store_base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"l2_tips_store_base.d.ts","sourceRoot":"","sources":["../../../src/block/l2_block_stream/l2_tips_store_base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,iCAAiC,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAErH;;;GAGG;AACH,8BAAsB,eAAgB,YAAW,yBAAyB,EAAE,8BAA8B;IAC5F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS;IAA1D,YAA+B,gBAAgB,EAAE,SAAS,EAAI;IAG9D,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAE7E,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpF,+DAA+D;IAC/D,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAExF,iDAAiD;IACjD,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9F,oDAAoD;IACpD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE7F,oDAAoD;IACpD,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvF,yEAAyE;IACzE,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpF,4FAA4F;IAC5F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAI5D,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK5E;IAEM,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,CAsBvC;IAEY,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5E;IAGD,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1D;YAIa,UAAU;YAYV,eAAe;IAgB7B,OAAO,CAAC,mBAAmB;YAIb,iBAAiB;YAajB,uBAAuB;YAcvB,iBAAiB;YA8BjB,iBAAiB;YAUjB,oBAAoB;YAmBpB,OAAO;CAMtB"}
+{"version":3,"file":"l2_tips_store_base.d.ts","sourceRoot":"","sources":["../../../src/block/l2_block_stream/l2_tips_store_base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,iCAAiC,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAErH;;;GAGG;AACH,8BAAsB,eAAgB,YAAW,yBAAyB,EAAE,8BAA8B;IAC5F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS;IAA1D,YAA+B,gBAAgB,EAAE,SAAS,EAAI;IAG9D,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAE7E,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpF,+DAA+D;IAC/D,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAExF,iDAAiD;IACjD,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9F,oDAAoD;IACpD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE7F,oDAAoD;IACpD,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvF,yEAAyE;IACzE,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpF,4FAA4F;IAC5F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAI5D,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK5E;IAEM,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,CAsBvC;IAED;;;;;OAKG;IACU,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjE;IAEY,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB5E;IAGD,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1D;YAIa,UAAU;YAYV,eAAe;IAgB7B,OAAO,CAAC,mBAAmB;YAIb,iBAAiB;YAajB,mBAAmB;YASnB,uBAAuB;YAUvB,iBAAiB;YA2BjB,iBAAiB;YAUjB,oBAAoB;YAmBpB,OAAO;CAMtB"}

package/dest/block/l2_block_stream/l2_tips_store_base.js

@@ -45,11 +45,28 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
             };
         });
     }
+    /**
+   * Records `(number → hash)` witnesses into the block-hash index without moving any tip cursor. In tips-only mode
+   * the hash history is sparse (one anchor per tip-moving poll), so a consumer that materializes per-height state
+   * should witness those heights or its prunes are over-deep by the gap to the nearest anchor. Witnesses are compared
+   * against the source, not trusted, so they cannot cause under-deep prunes; this is always safe to call.
+   */ async recordBlockHashes(blocks) {
+        await this.runInTransaction(async ()=>{
+            for (const block of blocks){
+                if (block.hash) {
+                    await this.setBlockHash(block.number, block.hash);
+                }
+            }
+        });
+    }
     async handleBlockStreamEvent(event) {
         switch(event.type){
             case 'blocks-added':
                 await this.handleBlocksAdded(event);
                 break;
+            case 'chain-proposed':
+                await this.handleChainProposed(event);
+                break;
             case 'chain-checkpointed':
                 await this.handleChainCheckpointed(event);
                 break;
@@ -119,17 +136,21 @@ import { GENESIS_CHECKPOINT_HEADER_HASH } from '../l2_block_source.js';
             await this.setTip('proposed', blocks.at(-1).number);
         });
     }
+    async handleChainProposed(event) {
+        if (event.type !== 'chain-proposed') {
+            return;
+        }
+        // Records the proposed tip into the block-hash index the walk-back reads. In tips-only mode this is the sole
+        // writer of proposed-tip history, leaving one sparse anchor per tip-moving pass for reorg detection.
+        await this.runInTransaction(()=>this.saveTag('proposed', event.block));
+    }
     async handleChainCheckpointed(event) {
         if (event.type !== 'chain-checkpointed') {
             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.setTipCheckpoint('checkpointed', checkpointId);
+            await this.setTipCheckpoint('checkpointed', event.checkpoint);
         });
     }
     async handleChainPruned(event) {
@@ -137,17 +158,14 @@ 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.
+            // A prune is a rollback: the proposed tip moves to the prune target unconditionally, but checkpoint-bearing
+            // cursors may only move backward (advancing one onto an uncheckpointed block would leave it without a recorded
+            // checkpoint id, which getCheckpointId throws on).
             await this.saveTag('proposed', 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.
+            // Clamp each checkpoint-bearing cursor down to its OWN source tip when it leads it; the event carries a valid
+            // (block, id) pair for each. Clamping the proven cursor onto the (possibly higher) checkpointed tip instead
+            // would transiently report unproven blocks as proven. The source guarantees proven <= checkpointed, so per-tip
+            // clamping preserves the local invariant.
             for (const { tag, sourceTip } of [
                 {
                     tag: 'checkpointed',

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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibDJfdGlwc19zdG9yZV90ZXN0X3N1aXRlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmxvY2svdGVzdC9sMl90aXBzX3N0b3JlX3Rlc3Rfc3VpdGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBZ0JBLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRS9ELHdCQUFnQixlQUFlLENBQUMsYUFBYSxFQUFFLE1BQU0sT0FBTyxDQUFDLFdBQVcsQ0FBQyxRQTByQnhFIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibDJfdGlwc19zdG9yZV90ZXN0X3N1aXRlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYmxvY2svdGVzdC9sMl90aXBzX3N0b3JlX3Rlc3Rfc3VpdGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBZ0JBLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRS9ELHdCQUFnQixlQUFlLENBQUMsYUFBYSxFQUFFLE1BQU0sT0FBTyxDQUFDLFdBQVcsQ0FBQyxRQSt2QnhFIn0=

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":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,QA0rBxE"}
+{"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,QA+vBxE"}