@aztec/prover-node 5.0.0-private.20260318 → 5.0.0-rc.1

package/dest/prover-node.js

@@ -370,28 +370,39 @@ function applyDecs2203RFactory() {
 function _apply_decs_2203_r(targetClass, memberDecs, classDecs, parentClass) {
     return (_apply_decs_2203_r = applyDecs2203RFactory())(targetClass, memberDecs, classDecs, parentClass);
 }
-var _dec, _dec1, _initProto;
-import { BlockNumber } from '@aztec/foundation/branded-types';
-import { assertRequired, compact, pick, sum } from '@aztec/foundation/collection';
+var _initProto;
+import { BlockNumber, EpochNumber } from '@aztec/foundation/branded-types';
+import { assertRequired, compact, pick } from '@aztec/foundation/collection';
 import { memoize } from '@aztec/foundation/decorators';
 import { createLogger } from '@aztec/foundation/log';
-import { DateProvider } from '@aztec/foundation/timer';
+import { DateProvider, executeTimeout } from '@aztec/foundation/timer';
+import { getLastSiblingPath } from '@aztec/prover-client/helpers';
+import { ChonkCache } from '@aztec/prover-client/orchestrator';
 import { PublicProcessorFactory } from '@aztec/simulator/server';
-import { getProofSubmissionDeadlineTimestamp } from '@aztec/stdlib/epoch-helpers';
+import { L2BlockStream, L2TipsMemoryStore } from '@aztec/stdlib/block';
+import { getEpochAtSlot, getProofSubmissionDeadlineEpoch } from '@aztec/stdlib/epoch-helpers';
 import { EpochProvingJobTerminalState, tryStop } from '@aztec/stdlib/interfaces/server';
-import { Attributes, getTelemetryClient, trackSpan } from '@aztec/telemetry-client';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+import { getTelemetryClient } from '@aztec/telemetry-client';
 import { uploadEpochProofFailure } from './actions/upload-epoch-proof-failure.js';
-import { EpochProvingJob } from './job/epoch-proving-job.js';
+import { CheckpointStore } from './checkpoint-store.js';
 import { ProverNodeJobMetrics, ProverNodeRewardsMetrics } from './metrics.js';
-_dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
-        [Attributes.EPOCH_NUMBER]: epochNumber
-    })), _dec1 = trackSpan('ProverNode.gatherEpochData', (epochNumber)=>({
-        [Attributes.EPOCH_NUMBER]: epochNumber
-    }));
+import { ProofPublishingService } from './proof-publishing-service.js';
+import { SessionManager } from './session-manager.js';
 /**
- * An Aztec Prover Node is a standalone process that monitors the unfinalized chain on L1 for unproven epochs,
- * fetches their txs from the p2p network or external nodes, re-executes their public functions, creates a rollup
- * proof for the epoch, and submits it to L1.
+ * Grace period for the proof-publishing service to settle during shutdown. The service waits for
+ * any in-flight L1 proof-submission tx to finish; that tx can take a long time to mine, so we cap
+ * the wait rather than letting `stop()` hang indefinitely.
+ */ const PUBLISHING_SERVICE_STOP_TIMEOUT_MS = 30_000;
+/**
+ * An Aztec Prover Node is a standalone process that monitors the chain for new checkpoints,
+ * starts proving them optimistically as they arrive, and submits epoch proofs to L1 once
+ * complete.
+ *
+ * The class is intentionally thin: it owns the long-lived collections (`CheckpointStore`,
+ * `ChonkCache`, `SessionManager`), the L2BlockStream, and a periodic ticker that nudges the
+ * manager to pick up newly-complete epochs. Every session lifecycle decision is delegated to
+ * the `SessionManager`. Each chain event is translated here into a single method call on it.
  */ export class ProverNode {
     prover;
     publisherFactory;
@@ -400,7 +411,6 @@ _dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
     contractDataSource;
     worldState;
     p2pClient;
-    epochsMonitor;
     rollupContract;
     l1Metrics;
     telemetryClient;
@@ -408,31 +418,31 @@ _dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
     dateProvider;
     static{
         ({ e: [_initProto] } = _apply_decs_2203_r(this, [
-            [
-                _dec,
-                2,
-                "createProvingJob"
-            ],
             [
                 memoize,
                 2,
                 "getL1Constants"
-            ],
-            [
-                _dec1,
-                2,
-                "gatherEpochData"
             ]
         ], []));
     }
     log;
-    jobs;
+    checkpointStore;
+    chonkCache;
+    sessionManager;
     config;
     jobMetrics;
     rewardsMetrics;
+    /** In-memory store for the L2BlockStream's local data provider. */ tipsStore;
+    /** Block stream for checkpoint and reorg detection. */ blockStream;
+    /**
+   * Highest epoch whose proof-submission window has passed. Monotonic high-water mark.
+   * Seeded from the last fully-proven epoch at start(); advanced on every block-stream
+   * event by comparing the archiver's latest synced L2 slot against each epoch's
+   * submission deadline. Protected so tests can verify the start() seeding.
+   */ lastExpiredEpoch;
     tracer;
-    publisher;
-    constructor(prover, publisherFactory, l2BlockSource, l1ToL2MessageSource, contractDataSource, worldState, p2pClient, epochsMonitor, rollupContract, l1Metrics, config = {}, telemetryClient = getTelemetryClient(), delayer, dateProvider = new DateProvider()){
+    publishingService;
+    constructor(prover, publisherFactory, l2BlockSource, l1ToL2MessageSource, contractDataSource, worldState, p2pClient, rollupContract, l1Metrics, config = {}, telemetryClient = getTelemetryClient(), delayer, dateProvider = new DateProvider()){
         this.prover = prover;
         this.publisherFactory = publisherFactory;
         this.l2BlockSource = l2BlockSource;
@@ -440,14 +450,12 @@ _dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
         this.contractDataSource = contractDataSource;
         this.worldState = worldState;
         this.p2pClient = p2pClient;
-        this.epochsMonitor = epochsMonitor;
         this.rollupContract = rollupContract;
         this.l1Metrics = l1Metrics;
         this.telemetryClient = telemetryClient;
         this.delayer = delayer;
         this.dateProvider = dateProvider;
         this.log = (_initProto(this), createLogger('prover-node'));
-        this.jobs = new Map();
         this.config = {
             proverNodePollingIntervalMs: 1_000,
             proverNodeMaxPendingJobs: 100,
@@ -465,6 +473,22 @@ _dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
         this.tracer = telemetryClient.getTracer('ProverNode');
         this.jobMetrics = new ProverNodeJobMetrics(meter, telemetryClient.getTracer('EpochProvingJob'));
         this.rewardsMetrics = new ProverNodeRewardsMetrics(meter, this.prover.getProverId(), rollupContract);
+        this.tipsStore = new L2TipsMemoryStore(this.l2BlockSource.getGenesisBlockHash());
+        this.chonkCache = new ChonkCache(this.log.getBindings());
+        this.checkpointStore = new CheckpointStore(this.l2BlockSource, {
+            proverFactory: this.prover,
+            chonkCache: this.chonkCache,
+            publicProcessorFactory: new PublicProcessorFactory(this.contractDataSource, this.dateProvider, this.telemetryClient, this.log.getBindings()),
+            dbProvider: this.worldState,
+            txProvider: this.p2pClient.getTxProvider(),
+            dateProvider: this.dateProvider,
+            proverId: this.prover.getProverId(),
+            metrics: this.jobMetrics,
+            txGatheringTimeoutMs: this.config.txGatheringTimeoutMs,
+            deadline: undefined
+        }, {
+            slotWatcherPollIntervalMs: this.config.proverNodePollingIntervalMs
+        }, this.log.getBindings());
     }
     getProverId() {
         return this.prover.getProverId();
@@ -472,233 +496,368 @@ _dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
     getP2P() {
         return this.p2pClient;
     }
-    /** Returns the shared tx delayer for prover L1 txs, if enabled. Test-only. */ getDelayer() {
+    /** Test-only: the shared L1 tx delayer, if enabled. */ getDelayer() {
         return this.delayer;
     }
+    /** Observability summary for the ProverNodeApi. */ getJobs() {
+        return Promise.resolve(this.sessionManager?.getJobs() ?? []);
+    }
+    /** Tests inspect this when validating reconcile behaviour. */ getCheckpointStore() {
+        return this.checkpointStore;
+    }
+    /** Tests inspect this to verify chonk-cache release semantics. */ getChonkCache() {
+        return this.chonkCache;
+    }
+    /** Tests inspect this when looking up live sessions. */ getSessionManager() {
+        if (!this.sessionManager) {
+            throw new Error('SessionManager not yet constructed — start() must be called first.');
+        }
+        return this.sessionManager;
+    }
+    /** Returns world state status. */ async getWorldStateSyncStatus() {
+        const { syncSummary } = await this.worldState.status();
+        return syncSummary;
+    }
+    /** Returns archiver status. */ getL2Tips() {
+        return this.l2BlockSource.getL2Tips();
+    }
+    /** Returns the underlying prover instance. */ getProver() {
+        return this.prover;
+    }
+    // ---------------- L2BlockStream handler ----------------
+    async handleBlockStreamEvent(event) {
+        switch(event.type){
+            case 'chain-checkpointed':
+                await this.handleCheckpointEvent(event.checkpoint);
+                break;
+            case 'chain-pruned':
+                await this.handlePruneEvent(event.checkpointed.checkpoint);
+                break;
+            case 'chain-proven':
+                this.publishingService?.onChainProven(BlockNumber(event.block.number));
+                break;
+            case 'chain-finalized':
+            case 'blocks-added':
+                break;
+        }
+        // Expiry is driven by the archiver's latest synced L2 slot
+        await this.checkEpochExpiry();
+        // Advance the local tips store only after the proving-side handling has succeeded. Any
+        // failure above propagates to the L2BlockStream (which logs and stops this poll pass) and
+        // skips this update, so the event is re-emitted on the next poll rather than skipped (A-1041).
+        await this.tipsStore.handleBlockStreamEvent(event);
+    }
+    /** Register a new checkpoint with the store and notify the session manager. */ async handleCheckpointEvent(publishedCheckpoint) {
+        const checkpoint = publishedCheckpoint.checkpoint;
+        const slotNumber = checkpoint.header.slotNumber;
+        const l1Constants = await this.getL1Constants();
+        const epochNumber = getEpochAtSlot(slotNumber, l1Constants);
+        if (await this.isEpochFullyProven(epochNumber, l1Constants)) {
+            this.log.debug(`Skipping checkpoint ${checkpoint.number} for already-proven epoch ${epochNumber}`);
+            return;
+        }
+        if (await this.isEpochPastProofSubmissionWindow(epochNumber, l1Constants)) {
+            this.log.debug(`Skipping checkpoint ${checkpoint.number} for epoch ${epochNumber} past its proof-submission window`);
+            return;
+        }
+        this.log.info(`New checkpoint ${checkpoint.number} for epoch ${epochNumber}`, {
+            checkpointNumber: checkpoint.number,
+            epochNumber,
+            slotNumber
+        });
+        const registerData = await this.collectRegisterData(checkpoint, publishedCheckpoint.attestations);
+        await this.checkpointStore.addOrUpdate(checkpoint, registerData);
+        await this.sessionManager?.onCheckpointAdded(epochNumber);
+    }
+    /**
+   * Gathers register-time data for a checkpoint: previous block header, L1-to-L2 messages,
+   * and the archive sibling path.
+   */ async collectRegisterData(checkpoint, attestations) {
+        const previousBlockNumber = BlockNumber(checkpoint.blocks[0].number - 1);
+        const previousBlockHeader = await this.gatherPreviousBlockHeader(previousBlockNumber);
+        const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2Messages(checkpoint.number);
+        const lastBlock = checkpoint.blocks.at(-1);
+        const lastBlockHash = await lastBlock.header.hash();
+        await this.worldState.syncImmediate(lastBlock.number, lastBlockHash);
+        const previousArchiveSiblingPath = await getLastSiblingPath(MerkleTreeId.ARCHIVE, this.worldState.getSnapshot(previousBlockNumber));
+        return {
+            attestations,
+            previousBlockHeader,
+            l1ToL2Messages,
+            previousArchiveSiblingPath
+        };
+    }
+    /** Mark every prover above the prune threshold as pruned and notify the session manager. */ async handlePruneEvent(prunedCheckpoint) {
+        this.log.warn(`Chain pruned to checkpoint ${prunedCheckpoint.number}`, {
+            prunedCheckpoint
+        });
+        const affected = this.checkpointStore.markPrunedAfter(prunedCheckpoint.number);
+        if (affected.length === 0) {
+            return;
+        }
+        const l1Constants = await this.getL1Constants();
+        const affectedEpochs = Array.from(new Set(affected.map((p)=>Number(getEpochAtSlot(p.slotNumber, l1Constants))))).map((n)=>EpochNumber(n));
+        // The session manager cancels every affected session, which in turn calls
+        // publishingService.withdraw(uuid) for each candidate; no separate notification to the
+        // publishing service is needed.
+        await this.sessionManager?.onPrune(affectedEpochs);
+    }
+    /**
+   * Returns true once the chain has advanced past the given epoch's proof-submission window.
+   * Used to ignore checkpoints whose epoch can no longer be proven in time — chiefly while the
+   * archiver replays old blocks after a restart. Compares the archiver's latest synced L2 slot
+   * against the epoch's submission-deadline epoch; conservatively returns false if the slot can't
+   * be read yet.
+   */ async isEpochPastProofSubmissionWindow(epochNumber, l1Constants) {
+        const latestSlot = await this.l2BlockSource.getSyncedL2SlotNumber();
+        if (latestSlot === undefined) {
+            return false;
+        }
+        const latestEpoch = getEpochAtSlot(latestSlot, l1Constants);
+        return latestEpoch >= getProofSubmissionDeadlineEpoch(epochNumber, l1Constants);
+    }
     /**
-   * Handles an epoch being completed by starting a proof for it if there are no active jobs for it.
-   * @param epochNumber - The epoch number that was just completed.
-   * @returns false if there is an error, true otherwise
-   */ async handleEpochReadyToProve(epochNumber) {
+   * Compares the archiver's latest synced L2 slot against `lastExpiredEpoch` and, for each
+   * newly-expired epoch, releases the chonk-cache entries for its blocks and reaps any
+   * CheckpointProvers in the store. An epoch E is expired once the chain reaches the start
+   * of epoch `E + proofSubmissionEpochs + 1`. Silently no-ops if nothing has expired since
+   * the last check or the archiver's slot can't be read.
+   */ async checkEpochExpiry() {
+        const latestSlot = await this.l2BlockSource.getSyncedL2SlotNumber();
+        if (latestSlot === undefined) {
+            return;
+        }
+        const l1Constants = await this.getL1Constants();
+        const latestEpoch = getEpochAtSlot(latestSlot, l1Constants);
+        const offset = l1Constants.proofSubmissionEpochs + 1;
+        if (latestEpoch < offset) {
+            return;
+        }
+        const newlyExpiredUpTo = EpochNumber(latestEpoch - offset);
+        const from = this.lastExpiredEpoch === undefined ? EpochNumber(0) : EpochNumber(this.lastExpiredEpoch + 1);
+        if (newlyExpiredUpTo < from) {
+            return;
+        }
+        for(let e = from; e <= newlyExpiredUpTo; e = EpochNumber(e + 1)){
+            await this.expireEpoch(e);
+        }
+        this.lastExpiredEpoch = newlyExpiredUpTo;
+    }
+    /**
+   * Releases chonk-cache entries for every block in the supplied epoch (best-effort) and
+   * reaps every CheckpointProver in the store whose epoch number matches.
+   */ async expireEpoch(epoch) {
         try {
-            this.log.debug(`Running jobs as ${epochNumber} is ready to prove`, {
-                jobs: Array.from(this.jobs.values()).map((job)=>`${job.getEpochNumber()}:${job.getId()}`)
+            const blocks = await this.l2BlockSource.getBlocks({
+                epoch,
+                onlyCheckpointed: true
             });
-            const activeJobs = await this.getActiveJobsForEpoch(epochNumber);
-            if (activeJobs.length > 0) {
-                this.log.warn(`Not starting proof for ${epochNumber} since there are active jobs for the epoch`, {
-                    activeJobs: activeJobs.map((job)=>job.uuid)
-                });
-                return true;
+            if (blocks.length > 0) {
+                this.chonkCache.releaseForBlocks(blocks);
             }
-            await this.startProof(epochNumber);
-            return true;
         } catch (err) {
-            if (err instanceof EmptyEpochError) {
-                this.log.info(`Not starting proof for ${epochNumber} since no blocks were found`);
-            } else {
-                this.log.error(`Error handling epoch completed`, err);
-            }
-            return false;
+            this.log.warn(`Could not release chonk-cache entries for expired epoch ${epoch}`, err);
         }
+        this.checkpointStore.reapExpired(epoch);
     }
+    // ---------------- public API ----------------
     /**
-   * Starts the prover node so it periodically checks for unproven epochs in the unfinalized chain from L1 and
-   * starts proving jobs for them.
-   */ async start() {
-        this.epochsMonitor.start(this);
+   * Schedules proving for the given epoch and returns the job id without waiting for completion.
+   */ async startProof(epochNumber) {
+        if (!this.sessionManager) {
+            throw new Error('ProverNode not started');
+        }
+        return await this.sessionManager.startProof(epochNumber);
+    }
+    // ---------------- Service lifecycle ----------------
+    async start() {
+        await this.checkpointStore.start();
         await this.publisherFactory.start();
-        this.publisher = await this.publisherFactory.create();
+        this.publishingService = new ProofPublishingService({
+            publisherFactory: this.publisherFactory,
+            l2BlockSource: this.l2BlockSource,
+            dateProvider: this.dateProvider,
+            config: {
+                skipSubmitProof: !!this.config.proverNodeDisableProofPublish
+            },
+            bindings: this.log.getBindings()
+        });
+        this.sessionManager = this.createSessionManager(this.publishingService);
+        // SessionManager owns its own periodic tick; start it here so it begins picking up
+        // epochs that become complete by time (no fresh checkpoint event) and advances once
+        // the previous epoch is proven on L1.
+        this.sessionManager.start();
+        // Now that the store + manager exist, arm the live-state observable gauges.
+        this.jobMetrics.observeState(this.checkpointStore, this.sessionManager);
+        const { startingBlock, lastFullyProvenEpoch } = await this.computeStartupState();
+        this.lastExpiredEpoch = lastFullyProvenEpoch;
+        this.blockStream = new L2BlockStream(this.l2BlockSource, this.tipsStore, this, this.log, {
+            pollIntervalMS: this.config.proverNodePollingIntervalMs,
+            startingBlock
+        });
+        this.blockStream.start();
         await this.rewardsMetrics.start();
         this.l1Metrics.start();
         this.log.info(`Started Prover Node with prover id ${this.prover.getProverId().toString()}`, this.config);
     }
-    /**
-   * Stops the prover node and all its dependencies.
-   * Resources not owned by this node (shared with the parent aztec-node) are skipped.
-   */ async stop() {
+    async stop() {
         this.log.info('Stopping ProverNode');
-        await this.epochsMonitor.stop();
+        this.jobMetrics.stopObservingState();
+        await this.blockStream?.stop();
+        if (this.sessionManager) {
+            await this.sessionManager.stop();
+        }
+        if (this.publishingService) {
+            // Bound the wait: the publishing service blocks until any in-flight L1 proof-submission tx
+            // settles, which can outlast a reasonable shutdown window. On timeout we log and move on —
+            // the tx may still mine, but shutdown must not hang on it.
+            const publishingService = this.publishingService;
+            await executeTimeout(()=>publishingService.stop(), PUBLISHING_SERVICE_STOP_TIMEOUT_MS, 'prover-node publishing-service stop').catch((err)=>this.log.warn(`Timed out stopping proof publishing service`, err));
+        }
+        await this.checkpointStore.stop();
+        this.chonkCache.stop();
         await this.prover.stop();
         await tryStop(this.publisherFactory);
-        this.publisher?.interrupt();
-        await Promise.all(Array.from(this.jobs.values()).map((job)=>job.stop()));
         this.rewardsMetrics.stop();
         this.l1Metrics.stop();
         await this.telemetryClient.stop();
         this.log.info('Stopped ProverNode');
     }
-    /** Returns world state status. */ async getWorldStateSyncStatus() {
-        const { syncSummary } = await this.worldState.status();
-        return syncSummary;
-    }
-    /** Returns archiver status. */ getL2Tips() {
-        return this.l2BlockSource.getL2Tips();
-    }
     /**
-   * Starts a proving process and returns immediately.
-   */ async startProof(epochNumber) {
-        const job = await this.createProvingJob(epochNumber, {
-            skipEpochCheck: true
+   * Constructs the session manager. Extracted so subclasses (test harness) can swap
+   * the implementation. Wired to `tryUploadSessionFailure` so failed sessions get
+   * their proving data uploaded.
+   */ createSessionManager(publishingService) {
+        return new SessionManager({
+            checkpointStore: this.checkpointStore,
+            l2BlockSource: this.l2BlockSource,
+            proverFactory: this.prover,
+            proverId: this.prover.getProverId(),
+            publishingService,
+            metrics: this.jobMetrics,
+            dateProvider: this.dateProvider,
+            config: {
+                maxPendingJobs: this.config.proverNodeMaxPendingJobs,
+                tickIntervalMs: this.config.proverNodePollingIntervalMs,
+                finalizationDelayMs: this.config.proverNodeEpochProvingDelayMs
+            },
+            onSessionFailed: async (session)=>{
+                await this.tryUploadSessionFailure(session);
+            },
+            bindings: this.log.getBindings()
         });
-        void this.runJob(job);
     }
-    async runJob(job) {
-        const epochNumber = job.getEpochNumber();
-        const ctx = {
-            id: job.getId(),
-            epochNumber,
-            state: undefined
-        };
-        try {
-            await job.run();
-            const state = job.getState();
-            ctx.state = state;
-            if (state === 'reorg') {
-                this.log.warn(`Running new job for epoch ${epochNumber} due to reorg`, ctx);
-                await this.createProvingJob(epochNumber);
-            } else if (state === 'failed') {
-                this.log.error(`Job for ${epochNumber} exited with state ${state}`, ctx);
-                await this.tryUploadEpochFailure(job);
-            } else {
-                this.log.verbose(`Job for ${epochNumber} exited with state ${state}`, ctx);
-            }
-        } catch (err) {
-            this.log.error(`Error proving epoch ${epochNumber}`, err, ctx);
-        } finally{
-            this.jobs.delete(job.getId());
+    /**
+   * Installs session hooks for the e2e harness to interpose around top-tree proving
+   * (gate, override, or observe it) without monkey-patching the orchestrator factory.
+   * Applies to every session constructed after this call.
+   */ setSessionHooks(hooks) {
+        if (!this.sessionManager) {
+            throw new Error('ProverNode not started; call start() before setting session hooks.');
         }
+        this.sessionManager.setSessionHooks(hooks);
     }
-    async tryUploadEpochFailure(job) {
-        if (this.config.proverNodeFailedEpochStore) {
-            return await uploadEpochProofFailure(this.config.proverNodeFailedEpochStore, job.getId(), job.getProvingData(), this.l2BlockSource, this.worldState, assertRequired(pick(this.config, 'l1ChainId', 'rollupVersion', 'dataDirectory')), this.log);
+    /** Uploads failure snapshots when sessions exit with `failed`. Exposed as a method so tests can spy on it. */ async tryUploadSessionFailure(session) {
+        if (!this.config.proverNodeFailedEpochStore) {
+            return undefined;
         }
+        const data = SessionManager.buildSessionProvingData(session);
+        return await uploadEpochProofFailure(this.config.proverNodeFailedEpochStore, session.getId(), data, this.l2BlockSource, this.worldState, assertRequired(pick(this.config, 'l1ChainId', 'rollupVersion', 'dataDirectory')), this.log);
     }
-    /**
-   * Returns the prover instance.
-   */ getProver() {
-        return this.prover;
-    }
-    /**
-   * Returns an array of jobs being processed.
-   */ getJobs() {
-        return Promise.resolve(Array.from(this.jobs.entries()).map(([uuid, job])=>({
-                uuid,
-                status: job.getState(),
-                epochNumber: job.getEpochNumber()
-            })));
-    }
-    async getActiveJobsForEpoch(epochNumber) {
-        const jobs = await this.getJobs();
-        return jobs.filter((job)=>job.epochNumber === epochNumber && !EpochProvingJobTerminalState.includes(job.status));
-    }
-    checkMaximumPendingJobs() {
-        const { proverNodeMaxPendingJobs: maxPendingJobs } = this.config;
-        if (maxPendingJobs > 0 && this.jobs.size >= maxPendingJobs) {
-            throw new Error(`Maximum pending proving jobs ${maxPendingJobs} reached. Cannot create new job.`);
-        }
-    }
-    async createProvingJob(epochNumber, opts = {}) {
-        this.checkMaximumPendingJobs();
-        this.publisher = await this.publisherFactory.create();
-        // Gather all data for this epoch
-        const epochData = await this.gatherEpochData(epochNumber);
-        const fromCheckpoint = epochData.checkpoints[0].number;
-        const toCheckpoint = epochData.checkpoints.at(-1).number;
-        const fromBlock = epochData.checkpoints[0].blocks[0].number;
-        const lastBlock = epochData.checkpoints.at(-1).blocks.at(-1);
-        const toBlock = lastBlock.number;
-        this.log.verbose(`Creating proving job for epoch ${epochNumber} for checkpoint range ${fromCheckpoint} to ${toCheckpoint} and block range ${fromBlock} to ${toBlock}`);
-        // Fast forward world state to right before the target block and get a fork
-        const lastBlockHash = await lastBlock.header.hash();
-        await this.worldState.syncImmediate(toBlock, lastBlockHash);
-        // Create a processor factory
-        const publicProcessorFactory = new PublicProcessorFactory(this.contractDataSource, this.dateProvider, this.telemetryClient, this.log.getBindings());
-        // Set deadline for this job to run. It will abort if it takes too long.
-        const deadlineTs = getProofSubmissionDeadlineTimestamp(epochNumber, await this.getL1Constants());
-        const deadline = new Date(Number(deadlineTs) * 1000);
-        const job = this.doCreateEpochProvingJob(epochData, deadline, publicProcessorFactory, this.publisher, opts);
-        this.jobs.set(job.getId(), job);
-        return job;
-    }
+    // ---------------- helpers ----------------
     getL1Constants() {
         return this.l2BlockSource.getL1Constants();
     }
-    async gatherEpochData(epochNumber) {
-        const checkpoints = await this.gatherCheckpoints(epochNumber);
-        const txArray = await this.gatherTxs(epochNumber, checkpoints);
-        const txs = new Map(txArray.map((tx)=>[
-                tx.getTxHash().toString(),
-                tx
-            ]));
-        const l1ToL2Messages = await this.gatherMessages(epochNumber, checkpoints);
-        const [firstBlock] = checkpoints[0].blocks;
-        const previousBlockHeader = await this.gatherPreviousBlockHeader(epochNumber, firstBlock.number - 1);
-        const [lastPublishedCheckpoint] = await this.l2BlockSource.getCheckpoints(checkpoints.at(-1).number, 1);
-        const attestations = lastPublishedCheckpoint?.attestations ?? [];
-        return {
-            checkpoints,
-            txs,
-            l1ToL2Messages,
-            epochNumber,
-            previousBlockHeader,
-            attestations
-        };
-    }
-    async gatherCheckpoints(epochNumber) {
-        const checkpoints = await this.l2BlockSource.getCheckpointsForEpoch(epochNumber);
-        if (checkpoints.length === 0) {
-            throw new EmptyEpochError(epochNumber);
-        }
-        return checkpoints;
-    }
-    async gatherTxs(epochNumber, checkpoints) {
-        const deadline = new Date(this.dateProvider.now() + this.config.txGatheringTimeoutMs);
-        const txProvider = this.p2pClient.getTxProvider();
-        const blocks = checkpoints.flatMap((checkpoint)=>checkpoint.blocks);
-        const txsByBlock = await Promise.all(blocks.map((block)=>txProvider.getTxsForBlock(block, {
-                deadline
-            })));
-        const txs = txsByBlock.map(({ txs })=>txs).flat();
-        const missingTxs = txsByBlock.map(({ missingTxs })=>missingTxs).flat();
-        if (missingTxs.length === 0) {
-            this.log.verbose(`Gathered all ${txs.length} txs for epoch ${epochNumber}`, {
-                epochNumber
-            });
-            return txs;
+    /**
+   * Returns true if every block in the given epoch is proven on L1. An epoch is only
+   * fully proven when its *last* block is proven. Protected for direct unit-test access.
+   */ async isEpochFullyProven(epochNumber, l1Constants) {
+        const provenBlockNumber = await this.l2BlockSource.getBlockNumber({
+            tag: 'proven'
+        });
+        if (!provenBlockNumber || provenBlockNumber <= 0) {
+            return false;
+        }
+        const provenHeader = (await this.l2BlockSource.getBlockData({
+            number: BlockNumber(provenBlockNumber)
+        }))?.header;
+        if (!provenHeader) {
+            return false;
         }
-        throw new Error(`Txs not found for epoch ${epochNumber}: ${missingTxs.map((hash)=>hash.toString()).join(', ')}`);
+        const provenEpoch = getEpochAtSlot(provenHeader.getSlot(), l1Constants);
+        if (epochNumber < provenEpoch) {
+            return true;
+        }
+        if (epochNumber > provenEpoch) {
+            return false;
+        }
+        return this.isProvenBlockLastOfItsEpoch(BlockNumber(provenBlockNumber), provenEpoch, l1Constants);
+    }
+    /** Protected for direct unit-test access. */ async isProvenBlockLastOfItsEpoch(provenBlockNumber, provenEpoch, l1Constants) {
+        const nextHeader = (await this.l2BlockSource.getBlockData({
+            number: BlockNumber(provenBlockNumber + 1)
+        }))?.header;
+        if (nextHeader) {
+            return getEpochAtSlot(nextHeader.getSlot(), l1Constants) > provenEpoch;
+        }
+        return this.l2BlockSource.isEpochComplete(provenEpoch);
     }
-    async gatherMessages(epochNumber, checkpoints) {
-        const messages = await Promise.all(checkpoints.map((c)=>this.l1ToL2MessageSource.getL1ToL2Messages(c.number)));
-        const messageCount = sum(messages.map((m)=>m.length));
-        this.log.verbose(`Gathered all ${messageCount} messages for epoch ${epochNumber}`, {
-            epochNumber
+    /**
+   * Resolves the L2BlockStream's starting block and the last fully-proven epoch in one
+   * pass. The starting block is the first block of the next unproven epoch (or the start
+   * of the partially-proven epoch if the proven tip falls mid-epoch). The fully-proven
+   * epoch is `provenEpoch` when the proven tip is the last block of its epoch, otherwise
+   * `provenEpoch - 1`, or `undefined` if no block is proven yet.
+   */ async computeStartupState() {
+        const provenBlockNumber = await this.l2BlockSource.getBlockNumber({
+            tag: 'proven'
         });
-        const messagesByCheckpoint = {};
-        for(let i = 0; i < checkpoints.length; i++){
-            messagesByCheckpoint[checkpoints[i].number] = messages[i];
-        }
-        return messagesByCheckpoint;
-    }
-    async gatherPreviousBlockHeader(epochNumber, previousBlockNumber) {
-        const header = await (previousBlockNumber === 0 ? this.worldState.getCommitted().getInitialHeader() : this.l2BlockSource.getBlockHeader(BlockNumber(previousBlockNumber)));
-        if (!header) {
-            throw new Error(`Previous block header ${previousBlockNumber} not found for proving epoch ${epochNumber}`);
-        }
-        this.log.verbose(`Gathered previous block header ${header.getBlockNumber()} for epoch ${epochNumber}`);
-        return header;
-    }
-    /** Extracted for testing purposes. */ doCreateEpochProvingJob(data, deadline, publicProcessorFactory, publisher, opts = {}) {
-        const { proverNodeMaxParallelBlocksPerEpoch: parallelBlockLimit, proverNodeDisableProofPublish } = this.config;
-        return new EpochProvingJob(data, this.worldState, this.prover.createEpochProver(), publicProcessorFactory, publisher, this.l2BlockSource, this.jobMetrics, deadline, {
-            parallelBlockLimit,
-            skipSubmitProof: proverNodeDisableProofPublish,
-            ...opts
-        }, this.log.getBindings());
+        if (!provenBlockNumber || provenBlockNumber <= 0) {
+            return {
+                startingBlock: BlockNumber(1),
+                lastFullyProvenEpoch: undefined
+            };
+        }
+        const l1Constants = await this.getL1Constants();
+        const provenHeader = (await this.l2BlockSource.getBlockData({
+            number: BlockNumber(provenBlockNumber)
+        }))?.header;
+        if (!provenHeader) {
+            return {
+                startingBlock: BlockNumber(provenBlockNumber + 1),
+                lastFullyProvenEpoch: undefined
+            };
+        }
+        const provenEpoch = getEpochAtSlot(provenHeader.getSlot(), l1Constants);
+        if (await this.isProvenBlockLastOfItsEpoch(BlockNumber(provenBlockNumber), provenEpoch, l1Constants)) {
+            return {
+                startingBlock: BlockNumber(provenBlockNumber + 1),
+                lastFullyProvenEpoch: provenEpoch
+            };
+        }
+        const epochCheckpoints = await this.l2BlockSource.getCheckpointsData({
+            epoch: provenEpoch
+        });
+        const firstBlockOfEpoch = epochCheckpoints.length > 0 ? epochCheckpoints[0].startBlock : BlockNumber(provenBlockNumber);
+        this.log.info(`Starting L2BlockStream at block ${firstBlockOfEpoch} (start of partially-proven epoch ${provenEpoch})`, {
+            provenBlockNumber,
+            provenEpoch,
+            firstBlockOfEpoch
+        });
+        const lastFullyProvenEpoch = provenEpoch > 0 ? EpochNumber(provenEpoch - 1) : undefined;
+        return {
+            startingBlock: firstBlockOfEpoch,
+            lastFullyProvenEpoch
+        };
     }
-    /** Extracted for testing purposes. */ async triggerMonitors() {
-        await this.epochsMonitor.work();
+    async gatherPreviousBlockHeader(previousBlockNumber) {
+        const data = await this.l2BlockSource.getBlockData({
+            number: BlockNumber(previousBlockNumber)
+        });
+        if (!data?.header) {
+            throw new Error(`Previous block header ${previousBlockNumber} not found`);
+        }
+        return data.header;
     }
     validateConfig() {
         if (this.config.proverNodeFailedEpochStore && (!this.config.dataDirectory || !this.config.l1ChainId || this.config.rollupVersion === undefined)) {
@@ -707,9 +866,5 @@ _dec = trackSpan('ProverNode.createProvingJob', (epochNumber)=>({
         }
     }
 }
-class EmptyEpochError extends Error {
-    constructor(epochNumber){
-        super(`No blocks found for epoch ${epochNumber}`);
-        this.name = 'EmptyEpochError';
-    }
-}
+// Re-export so handlers can compare states externally.
+export { EpochProvingJobTerminalState };