@aztec/stdlib 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

package/src/block/validate_block_result.ts

@@ -1,61 +1,68 @@
+import { EpochNumber, EpochNumberSchema } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type ZodFor, schemas } from '@aztec/foundation/schemas';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
 import { z } from 'zod';
 
-import { BlockInfoSchema, type L2BlockInfo, deserializeBlockInfo, serializeBlockInfo } from './l2_block_info.js';
+import {
+  type CheckpointInfo,
+  CheckpointInfoSchema,
+  deserializeCheckpointInfo,
+  serializeCheckpointInfo,
+} from '../checkpoint/checkpoint_info.js';
+import { MAX_COMMITTEE_SIZE } from '../deserialization/index.js';
 import { CommitteeAttestation } from './proposal/committee_attestation.js';
 
-/** Subtype for invalid block validation results */
-export type ValidateBlockNegativeResult =
+/** Subtype for invalid checkpoint validation results */
+export type ValidateCheckpointNegativeResult =
   | {
       valid: false;
-      /** Identifiers from the invalid block */
-      block: L2BlockInfo;
-      /** Committee members at the epoch this block was proposed */
+      /** Identifiers from the invalid checkpoint */
+      checkpoint: CheckpointInfo;
+      /** Committee members at the epoch this checkpoint was proposed */
       committee: EthAddress[];
-      /** Epoch in which this block was proposed */
-      epoch: bigint;
+      /** Epoch in which this checkpoint was proposed */
+      epoch: EpochNumber;
       /** Proposer selection seed for the epoch */
       seed: bigint;
-      /** List of committee members who signed this block proposal */
+      /** List of committee members who signed this checkpoint proposal */
       attestors: EthAddress[];
-      /** Committee attestations for this block as they were posted to L1 */
+      /** Committee attestations for this checkpoint as they were posted to L1 */
       attestations: CommitteeAttestation[];
-      /** Reason for the block being invalid: not enough attestations were posted */
+      /** Reason for the checkpoint being invalid: not enough attestations were posted */
       reason: 'insufficient-attestations';
     }
   | {
       valid: false;
-      /** Identifiers from the invalid block */
-      block: L2BlockInfo;
-      /** Committee members at the epoch this block was proposed */
+      /** Identifiers from the invalid checkpoint */
+      checkpoint: CheckpointInfo;
+      /** Committee members at the epoch this checkpoint was proposed */
       committee: EthAddress[];
-      /** Epoch in which this block was proposed */
-      epoch: bigint;
+      /** Epoch in which this checkpoint was proposed */
+      epoch: EpochNumber;
       /** Proposer selection seed for the epoch */
       seed: bigint;
-      /** List of committee members who signed this block proposal */
+      /** List of committee members who signed this checkpoint proposal */
       attestors: EthAddress[];
-      /** Committee attestations for this block as they were posted to L1 */
+      /** Committee attestations for this checkpoint as they were posted to L1 */
       attestations: CommitteeAttestation[];
-      /** Reason for the block being invalid: an invalid attestation was posted */
+      /** Reason for the checkpoint being invalid: an invalid attestation was posted */
       reason: 'invalid-attestation';
       /** Index in the attestations array of the invalid attestation posted */
       invalidIndex: number;
     };
 
-/** Result type for validating a block attestations */
-export type ValidateBlockResult = { valid: true } | ValidateBlockNegativeResult;
+/** Result type for validating checkpoint attestations */
+export type ValidateCheckpointResult = { valid: true } | ValidateCheckpointNegativeResult;
 
-export const ValidateBlockResultSchema = z.union([
+export const ValidateCheckpointResultSchema: ZodFor<ValidateCheckpointResult> = z.union([
   z.object({ valid: z.literal(true) }),
   z.object({
     valid: z.literal(false),
-    block: BlockInfoSchema,
+    checkpoint: CheckpointInfoSchema,
     committee: z.array(schemas.EthAddress),
-    epoch: schemas.BigInt,
+    epoch: EpochNumberSchema,
     seed: schemas.BigInt,
     attestors: z.array(schemas.EthAddress),
     attestations: z.array(CommitteeAttestation.schema),
@@ -63,28 +70,28 @@ export const ValidateBlockResultSchema = z.union([
   }),
   z.object({
     valid: z.literal(false),
-    block: BlockInfoSchema,
+    checkpoint: CheckpointInfoSchema,
     committee: z.array(schemas.EthAddress),
-    epoch: schemas.BigInt,
+    epoch: EpochNumberSchema,
     seed: schemas.BigInt,
     attestors: z.array(schemas.EthAddress),
     attestations: z.array(CommitteeAttestation.schema),
     reason: z.literal('invalid-attestation'),
     invalidIndex: z.number(),
   }),
-]) satisfies ZodFor<ValidateBlockResult>;
+]);
 
-export function serializeValidateBlockResult(result: ValidateBlockResult): Buffer {
+export function serializeValidateCheckpointResult(result: ValidateCheckpointResult): Buffer {
   if (result.valid) {
     return serializeToBuffer(true);
   }
 
-  const l2Block = serializeBlockInfo(result.block);
+  const checkpointBuffer = serializeCheckpointInfo(result.checkpoint);
   return serializeToBuffer(
     result.valid,
     result.reason,
-    l2Block.length,
-    l2Block,
+    checkpointBuffer.length,
+    checkpointBuffer,
     result.committee.length,
     result.committee,
     result.epoch,
@@ -97,24 +104,24 @@ export function serializeValidateBlockResult(result: ValidateBlockResult): Buffe
   );
 }
 
-export function deserializeValidateBlockResult(bufferOrReader: Buffer | BufferReader): ValidateBlockResult {
+export function deserializeValidateCheckpointResult(bufferOrReader: Buffer | BufferReader): ValidateCheckpointResult {
   const reader = BufferReader.asReader(bufferOrReader);
   const valid = reader.readBoolean();
   if (valid) {
     return { valid };
   }
-  const reason = reader.readString() as 'insufficient-attestations' | 'invalid-attestation';
-  const block = deserializeBlockInfo(reader.readBuffer());
-  const committee = reader.readVector(EthAddress);
-  const epoch = reader.readBigInt();
+  const reason = reader.readString(64) as 'insufficient-attestations' | 'invalid-attestation';
+  const checkpoint = deserializeCheckpointInfo(reader.readBuffer());
+  const committee = reader.readVector(EthAddress, MAX_COMMITTEE_SIZE);
+  const epoch = EpochNumber(reader.readNumber());
   const seed = reader.readBigInt();
-  const attestors = reader.readVector(EthAddress);
-  const attestations = reader.readVector(CommitteeAttestation);
+  const attestors = reader.readVector(EthAddress, MAX_COMMITTEE_SIZE);
+  const attestations = reader.readVector(CommitteeAttestation, MAX_COMMITTEE_SIZE);
   const invalidIndex = reader.readNumber();
   if (reason === 'insufficient-attestations') {
-    return { valid, reason, block, committee, epoch, seed, attestors, attestations: attestations };
+    return { valid, reason, checkpoint, committee, epoch, seed, attestors, attestations };
   } else if (reason === 'invalid-attestation') {
-    return { valid, reason, block, committee, epoch, seed, attestors, invalidIndex, attestations: attestations };
+    return { valid, reason, checkpoint, committee, epoch, seed, attestors, invalidIndex, attestations };
   } else {
     const _: never = reason;
     throw new Error(`Unknown reason: ${reason}`);

package/src/checkpoint/checkpoint.ts

@@ -0,0 +1,195 @@
+import { encodeCheckpointBlobDataFromBlocks } from '@aztec/blob-lib/encoding';
+import {
+  BlockNumber,
+  CheckpointNumber,
+  CheckpointNumberSchema,
+  IndexWithinCheckpoint,
+  SlotNumber,
+} from '@aztec/foundation/branded-types';
+import { pick, sum } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, serializeSignedBigInt, serializeToBuffer } from '@aztec/foundation/serialize';
+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 { computeCheckpointOutHash } from '../messaging/out_hash.js';
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { schemas } from '../schemas/schemas.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import type { CheckpointInfo } from './checkpoint_info.js';
+
+type FieldsOfCheckpoint = Omit<FieldsOf<Checkpoint>, 'slot'>;
+
+export class Checkpoint {
+  constructor(
+    /** Snapshot of archive tree after the checkpoint is added. */
+    public archive: AppendOnlyTreeSnapshot,
+    /** Header of the checkpoint. */
+    public header: CheckpointHeader,
+    /** L2 blocks in the checkpoint. */
+    public blocks: L2Block[],
+    /** Number of the checkpoint. */
+    public number: CheckpointNumber,
+    /** Fee asset price modifier in basis points (from oracle). Defaults to 0 (no change). */
+    public feeAssetPriceModifier: bigint = 0n,
+  ) {}
+
+  get slot(): SlotNumber {
+    return this.header.slotNumber;
+  }
+
+  static get schema() {
+    return z
+      .object({
+        archive: AppendOnlyTreeSnapshot.schema,
+        header: CheckpointHeader.schema,
+        blocks: z.array(L2Block.schema),
+        number: CheckpointNumberSchema,
+        feeAssetPriceModifier: schemas.BigInt,
+      })
+      .transform(
+        ({ archive, header, blocks, number, feeAssetPriceModifier }) =>
+          new Checkpoint(archive, header, blocks, number, feeAssetPriceModifier),
+      );
+  }
+
+  static from(fields: FieldsOfCheckpoint) {
+    return new Checkpoint(...Checkpoint.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOfCheckpoint) {
+    return [fields.archive, fields.header, fields.blocks, fields.number, fields.feeAssetPriceModifier] as const;
+  }
+
+  static fromBuffer(buf: Buffer | BufferReader) {
+    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 number = CheckpointNumber(reader.readNumber());
+    const feeAssetPriceModifier = reader.readInt256();
+    return new Checkpoint(archive, header, blocks, number, feeAssetPriceModifier);
+  }
+
+  public toBuffer() {
+    return serializeToBuffer(
+      this.archive,
+      this.header,
+      this.blocks.length,
+      this.blocks,
+      this.number,
+      serializeSignedBigInt(this.feeAssetPriceModifier),
+    );
+  }
+
+  public toBlobFields(): Fr[] {
+    const blocks = this.blocks.map(block => block.toBlockBlobData());
+    return encodeCheckpointBlobDataFromBlocks(blocks);
+  }
+
+  public hash(): Fr {
+    return this.header.hash();
+  }
+
+  /**
+   * 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.
+   */
+  public getCheckpointOutHash(): Fr {
+    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);
+  }
+
+  public getState() {
+    return this.blocks.at(-1)!.header.state;
+  }
+
+  public toCheckpointInfo(): CheckpointInfo {
+    return {
+      archive: this.archive.root,
+      lastArchive: this.header.lastArchiveRoot,
+      slotNumber: this.header.slotNumber,
+      checkpointNumber: this.number,
+      timestamp: this.header.timestamp,
+    };
+  }
+
+  /** Returns stats used for logging */
+  public getStats() {
+    const txEffects = this.blocks.flatMap(block => block.body.txEffects);
+
+    const logsStats = {
+      privateLogCount: sum(txEffects.map(tx => tx.privateLogs.length)),
+      publicLogCount: sum(txEffects.map(tx => tx.publicLogs.length)),
+      contractClassLogCount: sum(txEffects.map(tx => tx.contractClassLogs.length)),
+      contractClassLogSize: sum(txEffects.map(tx => sum(tx.contractClassLogs.map(log => log.emittedLength)))),
+    };
+
+    return {
+      txCount: txEffects.length,
+      blockCount: this.blocks.length,
+      slotNumber: this.header.slotNumber,
+      checkpointNumber: this.number,
+      timestamp: this.header.timestamp,
+      ...logsStats,
+    };
+  }
+
+  static async random(
+    checkpointNumber = CheckpointNumber(1),
+    {
+      numBlocks = 1,
+      startBlockNumber = 1,
+      previousArchive,
+      feeAssetPriceModifier = 0n,
+      ...options
+    }: {
+      numBlocks?: number;
+      startBlockNumber?: number;
+      previousArchive?: AppendOnlyTreeSnapshot;
+      feeAssetPriceModifier?: bigint;
+      archive?: AppendOnlyTreeSnapshot;
+    } & Partial<Parameters<typeof CheckpointHeader.random>[0]> &
+      Partial<Parameters<typeof L2Block.random>[1]> = {},
+  ) {
+    const headerOptions = previousArchive ? { lastArchiveRoot: previousArchive.root, ...options } : options;
+    const header = CheckpointHeader.random(headerOptions);
+
+    // Create blocks sequentially to chain archive roots properly.
+    // Each block's header.lastArchive must equal the previous block's archive.
+    const blocks: L2Block[] = [];
+    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 } : {}),
+        ...pick(header, 'slotNumber', 'timestamp', 'coinbase', 'feeRecipient', 'gasFees'),
+      });
+      lastArchive = block.archive;
+      blocks.push(block);
+    }
+
+    return new Checkpoint(
+      options.archive ?? AppendOnlyTreeSnapshot.random(),
+      header,
+      blocks,
+      checkpointNumber,
+      feeAssetPriceModifier,
+    );
+  }
+}

package/src/checkpoint/checkpoint_data.ts

@@ -0,0 +1,91 @@
+import {
+  BlockNumber,
+  BlockNumberSchema,
+  CheckpointNumber,
+  CheckpointNumberSchema,
+} from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { L1PublishedData } from './published_checkpoint.js';
+
+/** Base type for checkpoint data */
+export type CommonCheckpointData = {
+  checkpointNumber: CheckpointNumber;
+  header: CheckpointHeader;
+  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,
+    header: CheckpointHeader.schema,
+    archive: AppendOnlyTreeSnapshot.schema,
+    checkpointOutHash: schemas.Fr,
+    startBlock: BlockNumberSchema,
+    blockCount: schemas.Integer,
+    feeAssetPriceModifier: schemas.BigInt,
+    attestations: z.array(CommitteeAttestation.schema),
+    l1: L1PublishedData.schema,
+  })
+  .transform(
+    (obj): CheckpointData => ({
+      checkpointNumber: obj.checkpointNumber,
+      header: obj.header,
+      archive: obj.archive,
+      checkpointOutHash: obj.checkpointOutHash,
+      startBlock: obj.startBlock,
+      blockCount: obj.blockCount,
+      feeAssetPriceModifier: obj.feeAssetPriceModifier,
+      attestations: obj.attestations,
+      l1: obj.l1,
+    }),
+  );

package/src/checkpoint/checkpoint_info.ts

@@ -0,0 +1,52 @@
+import {
+  CheckpointNumber,
+  CheckpointNumberSchema,
+  SlotNumber,
+  SlotNumberSchema,
+} from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+export type CheckpointInfo = {
+  archive: Fr;
+  lastArchive: Fr;
+  slotNumber: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  timestamp: bigint;
+};
+
+export function randomCheckpointInfo(checkpointNumber?: CheckpointNumber | number): CheckpointInfo {
+  return {
+    archive: Fr.random(),
+    lastArchive: Fr.random(),
+    slotNumber: SlotNumber(Math.floor(Math.random() * 100000) + 1),
+    checkpointNumber: CheckpointNumber(checkpointNumber ?? Math.floor(Math.random() * 100000) + 1),
+    timestamp: BigInt(Math.floor(Date.now() / 1000)),
+  };
+}
+
+export const CheckpointInfoSchema = z.object({
+  archive: schemas.Fr,
+  lastArchive: schemas.Fr,
+  slotNumber: SlotNumberSchema,
+  checkpointNumber: CheckpointNumberSchema,
+  timestamp: schemas.BigInt,
+});
+
+export function serializeCheckpointInfo(info: CheckpointInfo): Buffer {
+  return serializeToBuffer(info.archive, info.lastArchive, info.slotNumber, info.checkpointNumber, info.timestamp);
+}
+
+export function deserializeCheckpointInfo(buffer: Buffer | BufferReader): CheckpointInfo {
+  const reader = BufferReader.asReader(buffer);
+  return {
+    archive: reader.readObject(Fr),
+    lastArchive: reader.readObject(Fr),
+    slotNumber: SlotNumber(reader.readNumber()),
+    checkpointNumber: CheckpointNumber(reader.readNumber()),
+    timestamp: reader.readBigInt(),
+  };
+}

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);
+        }
+      }
+    }
+  }
+}