@aztec/stdlib 5.0.0-private.20260319 → 5.0.0-rc.1

package/src/block/test/l2_tips_store_test_suite.ts

@@ -1,4 +1,3 @@
-import { GENESIS_BLOCK_HEADER_HASH } from '@aztec/constants';
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
 import { times } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
@@ -7,12 +6,14 @@ import {
   GENESIS_CHECKPOINT_HEADER_HASH,
   L2Block,
   type L2BlockId,
+  type L2BlockTag,
   type L2TipId,
 } from '@aztec/stdlib/block';
 import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 
-import { jestExpect as expect } from '@jest/expect';
+import { expect } from 'vitest';
 
+import { GENESIS_BLOCK_HEADER_HASH } from '../block_hash.js';
 import type { L2TipsStore } from '../l2_block_stream/index.js';
 
 export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
@@ -146,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));
@@ -166,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));
@@ -222,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();
@@ -243,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();
@@ -267,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();
@@ -332,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();
@@ -396,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();
@@ -433,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));
@@ -474,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();
@@ -523,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/checkpoint/checkpoint.ts

@@ -14,7 +14,7 @@ import type { FieldsOf } from '@aztec/foundation/types';
 import { z } from 'zod';
 
 import { L2Block } from '../block/l2_block.js';
-import { MAX_BLOCKS_PER_CHECKPOINT } from '../deserialization/index.js';
+import { MAX_CAPACITY_BLOCKS_PER_CHECKPOINT } from '../deserialization/index.js';
 import { computeCheckpointOutHash } from '../messaging/out_hash.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import { schemas } from '../schemas/schemas.js';
@@ -68,7 +68,7 @@ export class Checkpoint {
     const reader = BufferReader.asReader(buf);
     const archive = reader.readObject(AppendOnlyTreeSnapshot);
     const header = reader.readObject(CheckpointHeader);
-    const blocks = reader.readVector(L2Block, MAX_BLOCKS_PER_CHECKPOINT);
+    const blocks = reader.readVector(L2Block, MAX_CAPACITY_BLOCKS_PER_CHECKPOINT);
     const number = CheckpointNumber(reader.readNumber());
     const feeAssetPriceModifier = reader.readInt256();
     return new Checkpoint(archive, header, blocks, number, feeAssetPriceModifier);
@@ -100,7 +100,16 @@ export class Checkpoint {
    * checkpoints up to and including this one in the epoch.
    */
   public getCheckpointOutHash(): Fr {
-    const msgs = this.blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
+    return Checkpoint.getCheckpointOutHash(this.blocks);
+  }
+
+  /**
+   * Returns the out hash computed from all l2-to-l1 messages in this checkpoint.
+   * Note: This value is different from the out hash in the header, which is the **accumulated** out hash over all
+   * checkpoints up to and including this one in the epoch.
+   */
+  static getCheckpointOutHash(blocks: L2Block[]): Fr {
+    const msgs = blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
     return computeCheckpointOutHash(msgs);
   }
 
@@ -165,6 +174,7 @@ export class Checkpoint {
     let lastArchive = previousArchive;
     for (let i = 0; i < numBlocks; i++) {
       const block = await L2Block.random(BlockNumber(startBlockNumber + i), {
+        checkpointNumber,
         indexWithinCheckpoint: IndexWithinCheckpoint(i),
         ...options,
         ...(lastArchive ? { lastArchive } : {}),

package/src/checkpoint/checkpoint_data.ts

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

package/src/checkpoint/checkpoint_reexecution_tracker.ts

@@ -0,0 +1,167 @@
+import type { CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+/**
+ * Outcome of attempting to re-execute a checkpoint proposal locally.
+ *
+ * - `valid`        — re-execution succeeded and the computed checkpoint matched the proposal.
+ * - `invalid`      — the proposal disagreed with the computed checkpoint, or violated a deterministic
+ *                    constraint (limits, signatures, etc).
+ * - `unvalidated`  — the local node could not complete validation for non-deterministic reasons
+ *                    (missing blocks/txs, timeouts, infra errors). Treated as proposer-fault for
+ *                    slashing but surfaced separately for telemetry.
+ */
+export type ReexecutionOutcome = 'valid' | 'invalid' | 'unvalidated';
+
+/**
+ * Tracks two pieces of per-slot state collected during proposal handling:
+ *
+ *  1. Whether each block proposal's transactions were successfully collected locally
+ *     (keyed by `slot` + `indexWithinCheckpoint`). Consumed by the data-withholding watcher.
+ *  2. The outcome of locally re-executing each checkpoint proposal (keyed by
+ *     `(checkpointNumber, archiveRoot)` and by `slot`). Consumed by the data-withholding
+ *     watcher (via `hasReexecuted`) and the sentinel (via `getOutcomeForSlot`).
+ *
+ * Both pieces of state live on the same per-slot `Entry`, so cleanup via `removeBefore`
+ * naturally drops everything for a pruned slot in one step.
+ */
+interface Entry {
+  // Set by recordOutcome — these may be undefined until the checkpoint proposal has been
+  // evaluated. recordTxsCollected may create an Entry before any of them are known.
+  checkpointNumber: CheckpointNumber | undefined;
+  archiveRoot: string | undefined;
+  outcome: ReexecutionOutcome | undefined;
+
+  slot: SlotNumber;
+
+  // Per block-proposal at this slot: indexWithinCheckpoint → true (collected) | false (failed to collect).
+  txsCollected: Map<number, boolean>;
+}
+
+export class CheckpointReexecutionTracker {
+  private readonly byCheckpoint = new Map<CheckpointNumber, Map<string, Entry>>();
+  private readonly bySlot = new Map<SlotNumber, Entry>();
+
+  /**
+   * Record the outcome of evaluating a checkpoint proposal.
+   * @param slot - Slot the proposal was for. Always required.
+   * @param archiveRoot - Archive root in the proposal.
+   * @param outcome - Outcome of evaluation.
+   * @param checkpointNumber - Checkpoint number, if known. Required for `valid` outcomes; optional
+   *   for `invalid`/`unvalidated` because some early rejections fire before blocks are loaded.
+   */
+  public recordOutcome(
+    slot: SlotNumber,
+    archiveRoot: Fr,
+    outcome: ReexecutionOutcome,
+    checkpointNumber?: CheckpointNumber,
+  ): void {
+    const archiveRootStr = archiveRoot.toString();
+
+    // Preserve any per-block txsCollected already accumulated for this slot.
+    const existing = this.bySlot.get(slot);
+    const entry: Entry = {
+      checkpointNumber,
+      archiveRoot: archiveRootStr,
+      slot,
+      outcome,
+      txsCollected: existing?.txsCollected ?? new Map(),
+    };
+
+    if (checkpointNumber !== undefined) {
+      let archives = this.byCheckpoint.get(checkpointNumber);
+      if (!archives) {
+        archives = new Map();
+        this.byCheckpoint.set(checkpointNumber, archives);
+      }
+      archives.set(archiveRootStr, entry);
+    }
+
+    this.bySlot.set(slot, entry);
+  }
+
+  /**
+   * Record whether the local node successfully collected the transactions for a block proposal.
+   * Called from the validator's proposal handler immediately after tx collection completes
+   * (regardless of whether re-execution will subsequently succeed). The data-withholding
+   * watcher consults these records as an authoritative signal: tx availability now is too
+   * weak (txs may have been evicted from the mempool by the time the watcher runs), but a
+   * record that the txs *were* available at proposal time still vouches for the proposer.
+   *
+   * @param slot - Slot the block proposal was for.
+   * @param indexWithinCheckpoint - Index of the block within its enclosing checkpoint.
+   * @param collected - True if every tx in the proposal was collected locally before deadline.
+   */
+  public recordTxsCollected(slot: SlotNumber, indexWithinCheckpoint: number, collected: boolean): void {
+    let entry = this.bySlot.get(slot);
+    if (!entry) {
+      entry = {
+        checkpointNumber: undefined,
+        archiveRoot: undefined,
+        slot,
+        outcome: undefined,
+        txsCollected: new Map(),
+      };
+      this.bySlot.set(slot, entry);
+    }
+    entry.txsCollected.set(indexWithinCheckpoint, collected);
+  }
+
+  /**
+   * Returns true if the given (checkpoint number, archive root) has been successfully
+   * re-executed locally (outcome `valid`).
+   */
+  public hasReexecuted(checkpointNumber: CheckpointNumber, archiveRoot: Fr): boolean {
+    return this.byCheckpoint.get(checkpointNumber)?.get(archiveRoot.toString())?.outcome === 'valid';
+  }
+
+  /** Returns the recorded outcome for a given slot, or undefined if no proposal was evaluated. */
+  public getOutcomeForSlot(slot: SlotNumber): ReexecutionOutcome | undefined {
+    return this.bySlot.get(slot)?.outcome;
+  }
+
+  /**
+   * Returns the recorded tx-collection result for a block proposal at the given slot and
+   * `indexWithinCheckpoint`, or `undefined` if no record exists.
+   *
+   * Three-valued by design:
+   *   - `true`      — we collected every tx for this block proposal before the deadline.
+   *   - `false`     — we tried and failed (missing txs at the deadline).
+   *   - `undefined` — no record (e.g. we never saw the block proposal). Callers should fall
+   *                   back to a current-state check (e.g. mempool probe) for this case.
+   */
+  public getTxsCollectedRecord(slot: SlotNumber, indexWithinCheckpoint: number): boolean | undefined {
+    return this.bySlot.get(slot)?.txsCollected.get(indexWithinCheckpoint);
+  }
+
+  /** Drops entries for checkpoints with `number < checkpointNumber`. */
+  public removeBefore(checkpointNumber: CheckpointNumber): void {
+    // Track the highest slot among checkpoints we're pruning. Once we know it, any slot
+    // strictly below that watermark is older than the most recently pruned checkpoint and
+    // can be dropped from `bySlot` too — including slot-only entries (no checkpoint number)
+    // which would otherwise leak, because removing by checkpoint number can't reach them.
+    let maxRemovedSlot: SlotNumber | undefined;
+    for (const [n, archives] of this.byCheckpoint) {
+      if (n < checkpointNumber) {
+        for (const entry of archives.values()) {
+          // Only drop the slot index if it still points at the entry we're removing.
+          if (this.bySlot.get(entry.slot) === entry) {
+            this.bySlot.delete(entry.slot);
+          }
+          if (maxRemovedSlot === undefined || entry.slot > maxRemovedSlot) {
+            maxRemovedSlot = entry.slot;
+          }
+        }
+        this.byCheckpoint.delete(n);
+      }
+    }
+
+    if (maxRemovedSlot !== undefined) {
+      for (const slot of [...this.bySlot.keys()]) {
+        if (slot < maxRemovedSlot) {
+          this.bySlot.delete(slot);
+        }
+      }
+    }
+  }
+}

package/src/checkpoint/digest.ts

@@ -0,0 +1,28 @@
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import { ConsensusPayload } from '../p2p/consensus_payload.js';
+import { type CoordinationSignatureContext, getHashedSignaturePayloadTypedData } from '../p2p/signature_utils.js';
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+
+/**
+ * Computes the EIP-712 payload digest for a checkpoint proposal — the digest validators sign
+ * and the L1 contract verifies during `propose()`. Mirrors `ProposeLib.digest(ProposePayload)` on L1.
+ *
+ * The result is the same `bytes32` that gets stored in `tempCheckpointLogs[checkpointNumber].payloadDigest`,
+ * so this helper is also reused when constructing simulation state overrides for pipelined proposals.
+ */
+export function computeCheckpointPayloadDigest(args: {
+  header: CheckpointHeader;
+  archiveRoot: Fr;
+  feeAssetPriceModifier: bigint;
+  signatureContext: CoordinationSignatureContext;
+}): Buffer32 {
+  const consensusPayload = new ConsensusPayload(
+    args.header,
+    args.archiveRoot,
+    args.feeAssetPriceModifier,
+    args.signatureContext,
+  );
+  return getHashedSignaturePayloadTypedData(consensusPayload);
+}

package/src/checkpoint/index.ts

@@ -1,5 +1,8 @@
 export * from './checkpoint.js';
 export * from './checkpoint_data.js';
 export * from './checkpoint_info.js';
+export * from './checkpoint_reexecution_tracker.js';
+export * from './digest.js';
+export * from './previous_checkpoint_out_hashes.js';
 export * from './published_checkpoint.js';
 export * from './validate.js';