@aztec-labs/prover-node 6.0.0-nightly.20260829

package/src/actions/rerun-epoch-proving-job.ts

@@ -0,0 +1,224 @@
+import { createArchiverStore, createContractDataSource } from '@aztec-labs/archiver';
+import type { L1ContractsConfig } from '@aztec-labs/ethereum/config';
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import type { Logger } from '@aztec-labs/foundation/log';
+import { DateProvider } from '@aztec-labs/foundation/timer';
+import { type ProverClientConfig, createProverClient } from '@aztec-labs/prover-client';
+import { ProverBrokerConfig, createAndStartProvingBroker } from '@aztec-labs/prover-client/broker';
+import { getLastSiblingPath } from '@aztec-labs/prover-client/helpers';
+import { type CheckpointSubTreeProofs, ChonkCache } from '@aztec-labs/prover-client/orchestrator';
+import { AvmSimulatorPool, PublicProcessorFactory } from '@aztec-labs/simulator/server';
+import type { L2Block } from '@aztec-labs/stdlib/block';
+import { getEpochAtSlot, getSlotRangeForEpoch } from '@aztec-labs/stdlib/epoch-helpers';
+import type { ITxProvider } from '@aztec-labs/stdlib/interfaces/server';
+import type { DataStoreConfig } from '@aztec-labs/stdlib/kv-store';
+import { MerkleTreeId } from '@aztec-labs/stdlib/trees';
+import type { Tx, TxHash } from '@aztec-labs/stdlib/tx';
+import type { GenesisData } from '@aztec-labs/stdlib/world-state';
+import { getTelemetryClient } from '@aztec-labs/telemetry-client';
+import { createWorldState } from '@aztec-labs/world-state';
+import { readFileSync } from 'fs';
+
+import { CheckpointProver } from '../job/checkpoint-prover.js';
+import { type EpochProvingJobData, deserializeEpochProvingJobData } from '../job/epoch-proving-job-data.js';
+import { EpochSession, type SessionSpec } from '../job/epoch-session.js';
+import { ProverNodeJobMetrics } from '../metrics.js';
+
+type RerunConfig = DataStoreConfig &
+  ProverBrokerConfig &
+  ProverClientConfig &
+  Pick<L1ContractsConfig, 'aztecEpochDuration'>;
+
+/**
+ * Given a local folder where `downloadEpochProvingJob` was called, creates a new archiver and world state
+ * using the state snapshots, and creates a new epoch proving session to prove the downloaded proving job.
+ * Proving is done with a local proving broker and agents as specified by the config.
+ */
+export async function rerunEpochProvingJob(localPath: string, log: Logger, config: RerunConfig, genesis?: GenesisData) {
+  await using ctx = await createRerunContext(localPath, log, config, genesis);
+  const { jobData, prover, metrics } = ctx;
+
+  log.info(`Rerunning epoch proving for epoch ${jobData.epochNumber}`);
+
+  const provers: CheckpointProver[] = [];
+  for (let i = 0; i < jobData.checkpoints.length; i++) {
+    provers.push(await buildCheckpointProver(ctx, i, log));
+  }
+
+  // Local rerun never publishes — stub the service so submit() always resolves 'published'
+  // and withdraw is a no-op.
+  const publishingService = {
+    submit: () => Promise.resolve('published' as const),
+    withdraw: () => {},
+  };
+
+  const l1Constants = { epochDuration: config.aztecEpochDuration };
+  const [fromSlot, toSlot] = getSlotRangeForEpoch(jobData.epochNumber, l1Constants);
+  const spec: SessionSpec = { kind: 'full', epochNumber: jobData.epochNumber, fromSlot, toSlot };
+
+  const session = new EpochSession(spec, provers, {
+    proverFactory: prover,
+    proverId: prover.getProverId(),
+    publishingService,
+    metrics,
+    dateProvider: new DateProvider(),
+    deadline: undefined,
+    config: {},
+    bindings: log.getBindings(),
+  });
+
+  const finalState = await session.start();
+  log.info(`Completed proving for epoch ${jobData.epochNumber} with status ${finalState}`, {
+    derivedEpoch: getEpochAtSlot(provers[0].slotNumber, l1Constants),
+  });
+  return finalState;
+}
+
+/**
+ * Re-proves a single downloaded checkpoint proving job (as uploaded by a `CheckpointProver` failure).
+ * Reconstructs just that checkpoint's sub-tree prover from the snapshot and awaits its block proofs — no
+ * epoch top-tree, no L1 submission — so a checkpoint-level failure can be reproduced offline in isolation.
+ * Returns the block-rollup proof outputs on success; throws if the checkpoint fails to prove again.
+ */
+export async function rerunCheckpointProvingJob(
+  localPath: string,
+  log: Logger,
+  config: RerunConfig,
+  genesis?: GenesisData,
+): Promise<CheckpointSubTreeProofs['blockProofOutputs']> {
+  await using ctx = await createRerunContext(localPath, log, config, genesis);
+  const { jobData } = ctx;
+  const checkpointNumber = jobData.checkpoints[0].number;
+
+  log.info(`Rerunning checkpoint proving for checkpoint ${checkpointNumber} (epoch ${jobData.epochNumber})`);
+
+  const prover = await buildCheckpointProver(ctx, 0, log);
+  try {
+    const { blockProofOutputs } = await prover.whenSubTreeProofsReady();
+    log.info(`Completed proving for checkpoint ${checkpointNumber} with ${blockProofOutputs.length} block proof(s)`);
+    return blockProofOutputs;
+  } finally {
+    prover.cancel({ routine: true });
+    await prover.whenDone();
+  }
+}
+
+/** Everything a rerun needs, reconstructed from the downloaded snapshot + job data. */
+type RerunContext = {
+  jobData: EpochProvingJobData;
+  metrics: ProverNodeJobMetrics;
+  worldState: Awaited<ReturnType<typeof createWorldState>>;
+  publicProcessorFactory: PublicProcessorFactory;
+  prover: Awaited<ReturnType<typeof createProverClient>>;
+  chonkCache: ChonkCache;
+  txProvider: ITxProvider;
+} & AsyncDisposable;
+
+/**
+ * Rebuilds the offline proving environment from a downloaded job: world state + archiver from the
+ * snapshots, a local proving broker + client, a chonk cache, and a tx provider that replays the job's txs.
+ */
+async function createRerunContext(
+  localPath: string,
+  log: Logger,
+  config: RerunConfig,
+  genesis?: GenesisData,
+): Promise<RerunContext> {
+  const jobData = deserializeEpochProvingJobData(readFileSync(localPath));
+  log.info(`Loaded proving job data for epoch ${jobData.epochNumber}`);
+
+  const telemetry = getTelemetryClient();
+  const metrics = new ProverNodeJobMetrics(telemetry.getMeter('prover-job'), telemetry.getTracer('prover-job'));
+  const worldState = await createWorldState(config, genesis);
+  const initialBlockHash = await worldState.getInitialHeader().hash();
+  const archiver = await createArchiverStore(config, initialBlockHash);
+  const avmSimulator = await AvmSimulatorPool.spawn({ wsdbIpcPath: worldState.getIpcPath() });
+  const publicProcessorFactory = new PublicProcessorFactory(
+    createContractDataSource(archiver),
+    avmSimulator,
+    undefined,
+    undefined,
+    log.getBindings(),
+  );
+  const broker = await createAndStartProvingBroker(config, telemetry);
+  const prover = await createProverClient(config, worldState, broker, telemetry);
+  const chonkCache = new ChonkCache(log.getBindings());
+  const txProvider = makeReplayingTxProvider(jobData.txs);
+
+  return {
+    jobData,
+    metrics,
+    worldState,
+    publicProcessorFactory,
+    prover,
+    chonkCache,
+    txProvider,
+    async [Symbol.asyncDispose]() {
+      await avmSimulator[Symbol.asyncDispose]();
+      await worldState[Symbol.asyncDispose]();
+    },
+  };
+}
+
+/** Reconstructs the `CheckpointProver` for the checkpoint at `index` in the job, ready to prove. */
+async function buildCheckpointProver(ctx: RerunContext, index: number, log: Logger): Promise<CheckpointProver> {
+  const { jobData, worldState, prover, chonkCache, publicProcessorFactory, txProvider, metrics } = ctx;
+  const checkpoint = jobData.checkpoints[index];
+  const previousBlockHeader =
+    index === 0 ? jobData.previousBlockHeader : jobData.checkpoints[index - 1].blocks.at(-1)!.header;
+  const previousInboxRollingHash =
+    index === 0 ? jobData.previousInboxRollingHash : jobData.checkpoints[index - 1].header.inboxRollingHash;
+  const l1ToL2Messages = jobData.l1ToL2Messages[checkpoint.number] ?? [];
+  const previousArchiveSiblingPath = await getLastSiblingPath(
+    MerkleTreeId.ARCHIVE,
+    worldState.getSnapshot(BlockNumber(checkpoint.blocks[0].number - 1)),
+  );
+  const attestations = checkpoint.number === jobData.checkpoints.at(-1)!.number ? jobData.attestations : [];
+  return new CheckpointProver(
+    {
+      checkpoint,
+      epochNumber: jobData.epochNumber,
+      attestations,
+      previousBlockHeader,
+      l1ToL2Messages,
+      previousInboxRollingHash,
+      previousArchiveSiblingPath,
+    },
+    {
+      proverFactory: prover,
+      chonkCache,
+      publicProcessorFactory,
+      dbProvider: worldState,
+      txProvider,
+      dateProvider: new DateProvider(),
+      proverId: prover.getProverId(),
+      metrics,
+      txGatheringTimeoutMs: 120_000,
+      deadline: undefined,
+      log,
+    },
+  );
+}
+
+/** Build a synthetic ITxProvider that returns the supplied txs map by lookup. */
+function makeReplayingTxProvider(txs: Map<string, Tx>): ITxProvider {
+  const lookup = (hashes: TxHash[]) => {
+    const found: Tx[] = [];
+    const missing: TxHash[] = [];
+    for (const hash of hashes) {
+      const tx = txs.get(hash.toString());
+      if (tx) {
+        found.push(tx);
+      } else {
+        missing.push(hash);
+      }
+    }
+    return { txs: found, missingTxs: missing };
+  };
+  return {
+    getAvailableTxs: hashes => Promise.resolve(lookup(hashes)),
+    hasTxs: hashes => Promise.resolve(hashes.map(h => txs.has(h.toString()))),
+    getTxsForBlockProposal: () => Promise.resolve({ txs: [], missingTxs: [] }),
+    getTxsForBlock: (block: L2Block) => Promise.resolve(lookup(block.body.txEffects.map(e => e.txHash))),
+  };
+}

package/src/actions/upload-epoch-proof-failure.ts

@@ -0,0 +1,87 @@
+import { ARCHIVER_DB_VERSION, type Archiver } from '@aztec-labs/archiver';
+import { tryRmDir } from '@aztec-labs/foundation/fs';
+import { jsonStringify } from '@aztec-labs/foundation/json-rpc';
+import type { Logger } from '@aztec-labs/foundation/log';
+import { isoDate } from '@aztec-labs/foundation/string';
+import { buildSnapshotMetadata, createBackups } from '@aztec-labs/node-lib/actions';
+import type { ChainConfig } from '@aztec-labs/stdlib/config';
+import { type FileStore, createFileStore } from '@aztec-labs/stdlib/file-store';
+import type { WorldStateSynchronizer } from '@aztec-labs/stdlib/interfaces/server';
+import type { DataStoreConfig } from '@aztec-labs/stdlib/kv-store';
+import { type UploadSnapshotMetadata, getBasePath, uploadSnapshotData } from '@aztec-labs/stdlib/snapshots';
+import { WORLD_STATE_DB_VERSION } from '@aztec-labs/world-state';
+import { mkdtemp } from 'fs/promises';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+
+import { type EpochProvingJobData, serializeEpochProvingJobData } from '../job/epoch-proving-job-data.js';
+
+type UploadEpochProofConfig = Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> & Pick<DataStoreConfig, 'dataDirectory'>;
+
+/** Whether uploaded data to the file store should be of public access. */
+const PUBLIC_UPLOADS = true;
+
+/**
+ * Uploads a snapshot of world state and archiver (requires pausing them) along with the proving job data,
+ * so we can download and re-run the job later under the same conditions.
+ * @param location The location to upload the data to (used to create the `FileStore`).
+ */
+export async function uploadEpochProofFailure(
+  location: string,
+  jobId: string,
+  jobData: EpochProvingJobData,
+  archiver: Archiver,
+  worldState: WorldStateSynchronizer,
+  config: UploadEpochProofConfig,
+  log: Logger,
+) {
+  const epochNumber = jobData.epochNumber;
+  log.warn(`Uploading epoch proof failure for ${epochNumber} to ${location}`, { epochNumber, jobId, location });
+
+  const backupDir = await mkdtemp(join(config.dataDirectory ?? tmpdir(), 'epoch-proof-data-'));
+  const store = await createFileStore(location);
+  if (!store) {
+    throw new Error(`Failed to create file store for epoch proof failure upload for location ${location}.`);
+  }
+
+  try {
+    const versions = { archiver: ARCHIVER_DB_VERSION, worldState: WORLD_STATE_DB_VERSION };
+    const uploadMetadata = await buildSnapshotMetadata(archiver, config);
+    const paths = await createBackups(backupDir, archiver, worldState, log);
+
+    const basePath = `${getBasePath(uploadMetadata)}/${epochNumber}-${isoDate()}-${jobId}`;
+    const pathFor = (key: string) => `${basePath}/${key}.db`;
+    const [metadata, dataUrl, metadataUrl] = await Promise.all([
+      uploadSnapshotData(paths, versions, uploadMetadata, store, { pathFor, private: !PUBLIC_UPLOADS }),
+      uploadJobData(jobData, store, basePath),
+      uploadSnapshotMetadata(uploadMetadata, store, basePath),
+    ] as const);
+
+    const baseUrl = dirname(metadataUrl);
+    log.warn(`Uploaded epoch ${epochNumber} proof failure data to ${baseUrl}`, {
+      epochNumber,
+      location,
+      basePath,
+      metadataUrl,
+      dataUrl,
+      metadata,
+      jobId,
+    });
+    return baseUrl;
+  } finally {
+    log.info(`Cleaning up backup dir ${backupDir}`);
+    await tryRmDir(backupDir, log);
+  }
+}
+
+async function uploadJobData(jobData: EpochProvingJobData, store: FileStore, basePath: string) {
+  const data = serializeEpochProvingJobData(jobData);
+  const path = `${basePath}/data.bin`;
+  return await store.save(path, data, { compress: true, public: PUBLIC_UPLOADS });
+}
+
+async function uploadSnapshotMetadata(metadata: UploadSnapshotMetadata, store: FileStore, basePath: string) {
+  const data = Buffer.from(jsonStringify(metadata), 'utf-8');
+  const path = `${basePath}/metadata.json`;
+  return await store.save(path, data, { compress: false, public: PUBLIC_UPLOADS });
+}

package/src/bin/run-failed-epoch.ts

@@ -0,0 +1,78 @@
+/* eslint-disable no-console */
+import { getL1ContractsConfigEnvVars } from '@aztec-labs/ethereum/config';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { jsonParseWithSchema, jsonStringify } from '@aztec-labs/foundation/json-rpc';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { downloadEpochProvingJob, getProverNodeConfigFromEnv, rerunEpochProvingJob } from '@aztec-labs/prover-node';
+import { type UploadSnapshotMetadata, UploadSnapshotMetadataSchema } from '@aztec-labs/stdlib/snapshots';
+import { existsSync, mkdirSync } from 'fs';
+import { readFile, writeFile } from 'fs/promises';
+import { basename, join } from 'path';
+
+const logger = createLogger('prover-node:run-failed-epoch');
+
+function printUsage() {
+  console.error('Usage: run-failed-epoch <proof-uri> [out-dir=./data]');
+}
+
+async function rerunFailedEpoch(provingJobUrl: string, baseLocalDir: string) {
+  const localDir = join(baseLocalDir, basename(provingJobUrl));
+  const jobPath = join(localDir, 'data.bin');
+  const dataDir = join(localDir, 'state');
+
+  const env = getProverNodeConfigFromEnv();
+  const l1Config = getL1ContractsConfigEnvVars();
+  const config = {
+    ...env,
+    ...l1Config,
+    dataDirectory: dataDir,
+    dataStoreMapSizeKb: env.dataStoreMapSizeKb ?? 1024 * 1024,
+    proverId: env.proverId ?? EthAddress.random(),
+  };
+
+  let metadata: UploadSnapshotMetadata;
+  const metadataPath = join(localDir, 'metadata.json');
+  if (existsSync(metadataPath)) {
+    logger.info(`Using downloaded data`);
+    metadata = jsonParseWithSchema(await readFile(metadataPath, 'utf-8'), UploadSnapshotMetadataSchema);
+  } else {
+    logger.info(`Downloading epoch proving job data and state from ${provingJobUrl} to ${localDir}`);
+    metadata = await downloadEpochProvingJob(provingJobUrl!, logger, {
+      jobDataDownloadPath: jobPath,
+      dataDirectory: dataDir,
+    });
+    await writeFile(metadataPath, jsonStringify(metadata, true));
+    logger.info(`Download to ${localDir} complete`);
+  }
+
+  logger.info(`Rerunning proving job from ${jobPath} with state from ${dataDir}`, metadata);
+  const result = await rerunEpochProvingJob(jobPath, logger, {
+    ...config,
+    rollupAddress: metadata.rollupAddress,
+    rollupVersion: metadata.rollupVersion,
+  });
+
+  console.error(`Epoch proving job complete with result ${result}`);
+}
+
+async function main() {
+  if (process.argv[2] === '--help') {
+    printUsage();
+    return;
+  }
+
+  const uri = process.argv[2];
+  const outDir = process.argv[3] || './data';
+  if (!uri) {
+    printUsage();
+    throw new Error('Missing URL to epoch proving job');
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  await rerunFailedEpoch(uri, outDir);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/src/checkpoint-store.ts

@@ -0,0 +1,212 @@
+import type { BlockNumber, CheckpointNumber, EpochNumber, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import type { L2BlockSource } from '@aztec-labs/stdlib/block';
+import type { Checkpoint } from '@aztec-labs/stdlib/checkpoint';
+import { type L1RollupConstants, getEpochAtSlot, getSlotRangeForEpoch } from '@aztec-labs/stdlib/epoch-helpers';
+
+import {
+  CheckpointProver,
+  type CheckpointProverArgs,
+  type CheckpointProverDeps,
+  type CheckpointProverTestHooks,
+} from './job/checkpoint-prover.js';
+
+/** Register-time data needed to construct a `CheckpointProver` (everything except the checkpoint + epoch). */
+export type RegisterCheckpointData = Omit<CheckpointProverArgs, 'checkpoint' | 'epochNumber'>;
+
+/** Factory used by the store to construct new provers. Tests can inject a stub. */
+export type CheckpointProverFactory = (args: CheckpointProverArgs, deps: CheckpointProverDeps) => CheckpointProver;
+
+/**
+ * Prover-node-wide registry of `CheckpointProver` instances, content-addressed by
+ * `(checkpoint number, slot, checkpoint archive root)`.
+ *
+ * The store survives every epoch / session boundary. A prover lives from its first
+ * `addOrUpdate` call until either:
+ *  - its checkpoint is pruned by an L1 reorg (`cancelAndRemoveAboveBlock`), or
+ *  - its epoch's proof-submission window has closed (`reapExpired`), so the proof could no
+ *    longer be accepted on L1 even if produced.
+ *
+ * A prover's sub-tree work forks world-state per block and does not survive a prune of a base
+ * block, so there is nothing to preserve across a reorg: a pruned prover is cancelled and
+ * dropped, and a re-add (even of identical content) constructs a fresh prover.
+ */
+export class CheckpointStore {
+  private readonly provers = new Map<string, CheckpointProver>();
+  /**
+   * Teardowns of provers already removed from `provers` (by prune or reap), awaited on `stop()`.
+   * Keyed by a monotonic id rather than the prover's content id: a prune-then-re-add can leave two
+   * teardowns for the same content id in flight at once, which a content-id key would clobber.
+   */
+  private readonly pendingTeardowns = new Map<number, Promise<void>>();
+  private nextTeardownId = 0;
+  /** Test-only hooks injected into every prover this store constructs. */
+  private testHooks: CheckpointProverTestHooks = {};
+  private readonly log: Logger;
+
+  constructor(
+    private readonly l2BlockSource: Pick<L2BlockSource, 'getL1Constants'>,
+    private readonly proverDeps: Omit<CheckpointProverDeps, 'log'>,
+    bindings?: LoggerBindings,
+    private readonly proverFactoryFn: CheckpointProverFactory = (args, deps) => new CheckpointProver(args, deps),
+  ) {
+    this.log = createLogger('prover-node:checkpoint-store', bindings);
+  }
+
+  public start(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async stop(): Promise<void> {
+    // Cancel every live prover, then await both their teardown and any still in flight for provers
+    // already removed by a prune or reap.
+    const provers = Array.from(this.provers.values());
+    this.provers.clear();
+    for (const prover of provers) {
+      prover.cancel();
+    }
+    await Promise.allSettled([...provers.map(p => p.whenDone()), ...this.pendingTeardowns.values()]);
+  }
+
+  /**
+   * Tracks the teardown of a prover just removed from the store so `stop()` can await it. The entry
+   * removes itself once teardown settles, so the map stays bounded by the number in flight.
+   */
+  private trackTeardown(prover: CheckpointProver): void {
+    const id = this.nextTeardownId++;
+    const done = prover.whenDone();
+    this.pendingTeardowns.set(id, done);
+    void done.finally(() => this.pendingTeardowns.delete(id));
+  }
+
+  /**
+   * Registers a checkpoint with the store. If a prover already exists for the
+   * `(number, slot, archive root)` content key it is reused (an at-least-once re-registration of
+   * still-canonical content); otherwise a new prover is constructed.
+   */
+  public async addOrUpdate(checkpoint: Checkpoint, data: RegisterCheckpointData): Promise<CheckpointProver> {
+    const l1Constants = await this.l2BlockSource.getL1Constants();
+    const epochNumber = getEpochAtSlot(checkpoint.header.slotNumber, l1Constants);
+    const id = CheckpointProver.idFor(checkpoint);
+
+    const existing = this.provers.get(id);
+    if (existing) {
+      return existing;
+    }
+
+    // At most one canonical checkpoint per slot. A different checkpoint at the same slot means the
+    // caller forgot to prune the old chain before adding the replacement — surface it rather than
+    // silently creating a parallel canonical chain. A pruned checkpoint has already been removed,
+    // so every prover still in the store is canonical.
+    for (const prover of this.provers.values()) {
+      if (prover.slotNumber === checkpoint.header.slotNumber) {
+        throw new Error(
+          `Cannot add checkpoint ${checkpoint.number} (archive ${checkpoint.archive.root}) at slot ${checkpoint.header.slotNumber}: ` +
+            `a different checkpoint already occupies this slot. Prune it first.`,
+        );
+      }
+    }
+
+    const prover = this.proverFactoryFn(
+      { ...data, checkpoint, epochNumber },
+      { ...this.proverDeps, checkpointProveOverride: this.testHooks.checkpointProveOverride, log: this.log },
+    );
+    this.provers.set(id, prover);
+    return prover;
+  }
+
+  /**
+   * Installs test-only hooks applied to every prover constructed from now on. Used by the e2e harness to
+   * force a checkpoint sub-tree failure without monkey-patching the prover factory.
+   */
+  public setTestHooks(hooks: CheckpointProverTestHooks): void {
+    this.testHooks = hooks;
+  }
+
+  /**
+   * Cancels and removes every prover that holds a block above the prune target. A checkpoint is orphaned by a prune to
+   * block `targetBlockNumber` iff its last block sits above the target — including a checkpoint whose range straddles
+   * the target (partially orphaned), which block-range marking catches without boundary ambiguity. Keying off the
+   * surviving block number (rather than a checkpoint number) is correct even when the source has already
+   * re-checkpointed past the divergence: the prune event reports the highest surviving block, which by construction
+   * survives on the source, whereas the source's current checkpointed tip can sit above the prune target.
+   *
+   * The prover's in-flight sub-tree work forks world-state per block and faults once its base block is pruned, so it
+   * cannot be reused; it is cancelled (aborting the fork reads) and dropped. A subsequent re-add constructs a fresh
+   * prover. Returns the removed provers.
+   */
+  public cancelAndRemoveAboveBlock(targetBlockNumber: BlockNumber): CheckpointProver[] {
+    const affected: CheckpointProver[] = [];
+    for (const [id, prover] of Array.from(this.provers.entries())) {
+      const lastBlockNumber = prover.checkpoint.blocks.at(-1)!.number;
+      if (lastBlockNumber > targetBlockNumber) {
+        prover.cancel();
+        this.trackTeardown(prover);
+        this.provers.delete(id);
+        affected.push(prover);
+      }
+    }
+    return affected;
+  }
+
+  /**
+   * Drops provers whose epoch is at or below the supplied expired epoch. Once an epoch's
+   * proof-submission window has closed, its proof can no longer be accepted on L1, so the
+   * prover is no longer needed.
+   */
+  public reapExpired(expiredEpoch: EpochNumber): void {
+    const reaped: { id: string; checkpointNumber: CheckpointNumber; epochNumber: EpochNumber }[] = [];
+    for (const [id, prover] of Array.from(this.provers.entries())) {
+      if (prover.epochNumber <= expiredEpoch) {
+        reaped.push({ id, checkpointNumber: prover.checkpoint.number, epochNumber: prover.epochNumber });
+        prover.cancel({ routine: true });
+        this.trackTeardown(prover);
+        this.provers.delete(id);
+      }
+    }
+    if (reaped.length > 0) {
+      this.log.info(`Reaped ${reaped.length} expired CheckpointProver(s) for expiredEpoch ${expiredEpoch}`, {
+        expiredEpoch,
+        reapedCount: reaped.length,
+        reaped,
+      });
+    }
+  }
+
+  /** Returns the prover with the supplied id, or undefined. */
+  public get(id: string): CheckpointProver | undefined {
+    return this.provers.get(id);
+  }
+
+  /** Returns the prover for the supplied checkpoint (by its content-addressed id), or undefined. */
+  public getByCheckpoint(checkpoint: Checkpoint): CheckpointProver | undefined {
+    return this.provers.get(CheckpointProver.idFor(checkpoint));
+  }
+
+  /** Every prover currently in the store, in insertion order. */
+  public listAll(): CheckpointProver[] {
+    return Array.from(this.provers.values());
+  }
+
+  /** Provers in the store, sorted by checkpoint number. */
+  public list(): CheckpointProver[] {
+    return Array.from(this.provers.values()).sort((a, b) => a.checkpoint.number - b.checkpoint.number);
+  }
+
+  /**
+   * Provers whose slot is in the supplied epoch's slot range, sorted by checkpoint number.
+   */
+  public async listForEpoch(epoch: EpochNumber): Promise<CheckpointProver[]> {
+    const l1Constants = await this.l2BlockSource.getL1Constants();
+    const [fromSlot, toSlot] = getSlotRangeForEpoch(epoch, l1Constants);
+    return this.listInSlotRange(fromSlot, toSlot);
+  }
+
+  /** Provers whose slot falls within `[fromSlot, toSlot]`, sorted by checkpoint number. */
+  public listInSlotRange(fromSlot: SlotNumber, toSlot: SlotNumber): CheckpointProver[] {
+    return this.list().filter(p => p.slotNumber >= fromSlot && p.slotNumber <= toSlot);
+  }
+}
+
+/** Sub-set of `L1RollupConstants` actually consumed by the store's slot helpers. */
+export type CheckpointStoreL1Constants = Pick<L1RollupConstants, 'epochDuration'>;