@aztec/prover-node 0.0.1-commit.a072138 → 0.0.1-commit.a5db02d

package/dest/job/{epoch-proving-job.js → epoch-session.js}

@@ -371,371 +371,352 @@ function _apply_decs_2203_r(targetClass, memberDecs, classDecs, parentClass) {
     return (_apply_decs_2203_r = applyDecs2203RFactory())(targetClass, memberDecs, classDecs, parentClass);
 }
 var _dec, _initProto;
-import { NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
-import { asyncPool } from '@aztec/foundation/async-pool';
 import { BlockNumber } from '@aztec/foundation/branded-types';
-import { padArrayEnd } from '@aztec/foundation/collection';
-import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
-import { RunningPromise, promiseWithResolvers } from '@aztec/foundation/promise';
+import { sleep } from '@aztec/foundation/sleep';
 import { Timer } from '@aztec/foundation/timer';
-import { getVKTreeRoot } from '@aztec/noir-protocol-circuits-types/vk-tree';
-import { protocolContractsHash } from '@aztec/protocol-contracts';
-import { buildFinalBlobChallenges } from '@aztec/prover-client/helpers';
-import { PublicSimulatorConfig } from '@aztec/stdlib/avm';
+import { TopTreeCancelledError } from '@aztec/prover-client/orchestrator';
 import { EpochProvingJobTerminalState } from '@aztec/stdlib/interfaces/server';
-import { CheckpointConstantData } from '@aztec/stdlib/rollup';
-import { MerkleTreeId } from '@aztec/stdlib/trees';
 import { Attributes, trackSpan } from '@aztec/telemetry-client';
 import * as crypto from 'node:crypto';
-import { validateEpochProvingJobData } from './epoch-proving-job-data.js';
-_dec = trackSpan('EpochProvingJob.run', function() {
+import { TopTreeJob } from './top-tree-job.js';
+/** Stable string key for use in maps. */ export function specKey(spec) {
+    return `${spec.kind}:${spec.epochNumber}:${spec.fromSlot}-${spec.toSlot}`;
+}
+_dec = trackSpan('EpochSession.start', function() {
     return {
-        [Attributes.EPOCH_NUMBER]: this.data.epochNumber
+        [Attributes.EPOCH_NUMBER]: this.spec.epochNumber
     };
 });
 /**
- * Job that grabs a range of blocks from the unfinalized chain from L1, gets their txs given their hashes,
- * re-executes their public calls, generates a rollup proof, and submits it to L1. This job will update the
- * world state as part of public call execution via the public processor.
- */ export class EpochProvingJob {
-    data;
-    dbProvider;
-    prover;
-    publicProcessorFactory;
-    publisher;
-    l2BlockSource;
-    metrics;
-    deadline;
-    config;
+ * One attempt at proving and publishing a contiguous slot range. The `SessionSpec` and
+ * the prover set are both frozen at construction time; the session does not adapt to
+ * reorgs or extensions of canonical content. Instead, `SessionManager` owns the
+ * reconciliation loop and replaces invalidated sessions wholesale (cancel + construct
+ * a fresh session with the new prover set).
+ *
+ * Each session does three things in sequence:
+ *
+ *   1. Run a `TopTreeJob` over its frozen prover subset to produce the epoch proof.
+ *   2. Hand the proof to the shared `ProofPublishingService` as a `PublishCandidate`.
+ *   3. Translate the service's outcome into a terminal session state.
+ *
+ * Everything to do with submission — predecessor gating, same-epoch dedup, deadline
+ * enforcement, and the L1 transaction itself — is the publishing service's concern.
+ * The session is just the producer of one candidate and the observer of its outcome.
+ *
+ * Lifecycle (happy path):
+ *
+ *   initialized → awaiting-checkpoints → awaiting-root → publishing-proof → completed
+ *
+ * Terminal states map the publishing outcome: `published` → `completed`, `superseded` →
+ * `superseded`, `failed` → `failed`, `expired` → `timed-out`, `withdrawn` → `cancelled`.
+ * Additionally, the session-level deadline fires `cancel('deadline')` and transitions
+ * to `timed-out` for the pre-submit window (top-tree proving) — the publishing service
+ * handles the post-submit window via the candidate's `deadline`.
+ *
+ * `cancel()` is idempotent. It marks the session terminal, calls
+ * `publishingService.withdraw(uuid)` to drop any queued candidate (an in-flight publish
+ * runs to natural completion; the session has already settled), and tears down the
+ * top-tree job if proving is still in progress.
+ */ export class EpochSession {
+    spec;
+    deps;
     static{
         ({ e: [_initProto] } = _apply_decs_2203_r(this, [
             [
                 _dec,
                 2,
-                "run"
+                "start"
             ]
         ], []));
     }
-    state;
-    log;
+    tracer;
     uuid;
-    runPromise;
-    epochCheckPromise;
+    log;
+    state;
     deadlineTimeoutHandler;
-    tracer;
-    constructor(data, dbProvider, prover, publicProcessorFactory, publisher, l2BlockSource, metrics, deadline, config, bindings){
-        this.data = data;
-        this.dbProvider = dbProvider;
-        this.prover = prover;
-        this.publicProcessorFactory = publicProcessorFactory;
-        this.publisher = publisher;
-        this.l2BlockSource = l2BlockSource;
-        this.metrics = metrics;
-        this.deadline = deadline;
-        this.config = config;
+    topTreeJob;
+    /** Cancelled top-tree jobs whose teardown is still in flight. Awaited at session stop. */ pendingTopTreeCleanups;
+    completionPromise;
+    resolveCompletion;
+    /** Stable reference; never mutated after construction. */ checkpoints;
+    constructor(spec, checkpoints, deps){
+        this.spec = spec;
+        this.deps = deps;
         this.state = (_initProto(this), 'initialized');
-        validateEpochProvingJobData(data);
+        this.pendingTopTreeCleanups = [];
+        if (checkpoints.length === 0) {
+            throw new Error(`Cannot construct EpochSession for ${specKey(spec)}: empty checkpoint set`);
+        }
+        this.checkpoints = [
+            ...checkpoints
+        ];
         this.uuid = crypto.randomUUID();
-        this.log = createLogger('prover-node:epoch-proving-job', {
-            ...bindings,
-            instanceId: `epoch-${data.epochNumber}`
+        this.log = createLogger('prover-node:epoch-session', {
+            ...deps.bindings,
+            instanceId: `session-${spec.kind}-${spec.epochNumber}-${spec.fromSlot}-${spec.toSlot}`
+        });
+        this.tracer = deps.metrics.tracer;
+        this.completionPromise = new Promise((resolve)=>{
+            this.resolveCompletion = resolve;
+        });
+        this.scheduleDeadlineStop();
+        this.log.info(`Created EpochSession ${this.uuid}`, {
+            uuid: this.uuid,
+            ...spec,
+            checkpointCount: this.checkpoints.length,
+            checkpointIds: this.checkpoints.map((c)=>c.id)
         });
-        this.tracer = metrics.tracer;
     }
     getId() {
         return this.uuid;
     }
+    getSpec() {
+        return this.spec;
+    }
     getState() {
         return this.state;
     }
     getEpochNumber() {
-        return this.data.epochNumber;
+        return this.spec.epochNumber;
+    }
+    getKind() {
+        return this.spec.kind;
     }
     getDeadline() {
-        return this.deadline;
+        return this.deps.deadline;
     }
-    getProvingData() {
-        return this.data;
+    getCheckpoints() {
+        return this.checkpoints;
     }
-    get epochNumber() {
-        return this.data.epochNumber;
+    /** Resolves when the session reaches a terminal state. */ whenDone() {
+        return this.completionPromise;
     }
-    get checkpoints() {
-        return this.data.checkpoints;
+    /** True if the session is in a terminal state. */ isTerminal() {
+        return EpochProvingJobTerminalState.includes(this.state);
     }
-    get txs() {
-        return this.data.txs;
+    /** First block this session proves. */ getStartBlockNumber() {
+        return BlockNumber(this.checkpoints[0].checkpoint.blocks[0].number);
     }
-    get attestations() {
-        return this.data.attestations;
+    /** Last block this session proves. */ getEndBlockNumber() {
+        const lastCheckpoint = this.checkpoints[this.checkpoints.length - 1];
+        return BlockNumber(lastCheckpoint.checkpoint.blocks[lastCheckpoint.checkpoint.blocks.length - 1].number);
     }
     /**
-   * Proves the given epoch and submits the proof to L1.
-   */ async run() {
-        this.scheduleDeadlineStop();
-        if (!this.config.skipEpochCheck) {
-            await this.scheduleEpochCheck();
-        }
-        const attestations = this.attestations.map((attestation)=>attestation.toViem());
-        const epochNumber = this.epochNumber;
-        const epochSizeCheckpoints = this.checkpoints.length;
-        const epochSizeBlocks = this.checkpoints.reduce((accum, checkpoint)=>accum + checkpoint.blocks.length, 0);
-        const epochSizeTxs = this.checkpoints.reduce((accum, checkpoint)=>accum + checkpoint.blocks.reduce((accumC, block)=>accumC + block.body.txEffects.length, 0), 0);
-        const fromCheckpoint = this.checkpoints[0].number;
-        const toCheckpoint = this.checkpoints.at(-1).number;
-        const fromBlock = this.checkpoints[0].blocks[0].number;
-        const toBlock = this.checkpoints.at(-1).blocks.at(-1).number;
-        this.log.info(`Starting epoch ${epochNumber} proving job with checkpoints ${fromCheckpoint} to ${toCheckpoint}`, {
-            fromBlock,
-            toBlock,
-            epochSizeTxs,
-            epochNumber,
-            uuid: this.uuid
-        });
-        this.progressState('processing');
-        const timer = new Timer();
-        const { promise, resolve } = promiseWithResolvers();
-        this.runPromise = promise;
+   * Kicks off proving + submission. Fires and forgets — callers should await `whenDone()`.
+   * Returns a promise that resolves to the final state for callers that want to wait inline.
+   */ async start() {
         try {
-            const blobFieldsPerCheckpoint = this.checkpoints.map((checkpoint)=>checkpoint.toBlobFields());
-            const finalBlobBatchingChallenges = await buildFinalBlobChallenges(blobFieldsPerCheckpoint);
-            this.prover.startNewEpoch(epochNumber, epochSizeCheckpoints, finalBlobBatchingChallenges);
-            await this.prover.startChonkVerifierCircuits(Array.from(this.txs.values()));
-            // Everything in the epoch should have the same chainId and version.
-            const { chainId, version } = this.checkpoints[0].blocks[0].header.globalVariables;
-            const previousBlockHeaders = this.gatherPreviousBlockHeaders();
-            await asyncPool(this.config.parallelBlockLimit ?? 32, this.checkpoints, async (checkpoint)=>{
-                this.checkState();
-                const checkpointIndex = checkpoint.number - fromCheckpoint;
-                const checkpointConstants = CheckpointConstantData.from({
-                    chainId,
-                    version,
-                    vkTreeRoot: getVKTreeRoot(),
-                    protocolContractsHash: protocolContractsHash,
-                    proverId: this.prover.getProverId().toField(),
-                    slotNumber: checkpoint.header.slotNumber,
-                    coinbase: checkpoint.header.coinbase,
-                    feeRecipient: checkpoint.header.feeRecipient,
-                    gasFees: checkpoint.header.gasFees
-                });
-                const previousHeader = previousBlockHeaders[checkpointIndex];
-                const l1ToL2Messages = this.getL1ToL2Messages(checkpoint);
-                this.log.verbose(`Starting processing checkpoint ${checkpoint.number}`, {
-                    number: checkpoint.number,
-                    checkpointHash: checkpoint.hash().toString(),
-                    lastArchive: checkpoint.header.lastArchiveRoot,
-                    previousHeader: previousHeader.hash(),
-                    uuid: this.uuid
-                });
-                await this.prover.startNewCheckpoint(checkpointIndex, checkpointConstants, l1ToL2Messages, checkpoint.blocks.length, previousHeader);
-                for (const block of checkpoint.blocks){
-                    const globalVariables = block.header.globalVariables;
-                    const txs = this.getTxs(block);
-                    this.log.verbose(`Starting processing block ${block.number}`, {
-                        number: block.number,
-                        blockHash: (await block.hash()).toString(),
-                        lastArchive: block.header.lastArchive.root,
-                        noteHashTreeRoot: block.header.state.partial.noteHashTree.root,
-                        nullifierTreeRoot: block.header.state.partial.nullifierTree.root,
-                        publicDataTreeRoot: block.header.state.partial.publicDataTree.root,
-                        ...globalVariables,
-                        numTxs: txs.length
-                    });
-                    // Start block proving
-                    await this.prover.startNewBlock(block.number, globalVariables.timestamp, txs.length);
-                    // Process public fns
-                    const db = await this.createFork(BlockNumber(block.number - 1), l1ToL2Messages);
-                    const config = PublicSimulatorConfig.from({
-                        proverId: this.prover.getProverId().toField(),
-                        skipFeeEnforcement: false,
-                        collectDebugLogs: false,
-                        collectHints: true,
-                        collectPublicInputs: true,
-                        collectStatistics: false
-                    });
-                    const publicProcessor = this.publicProcessorFactory.create(db, globalVariables, config);
-                    const processed = await this.processTxs(publicProcessor, txs);
-                    await this.prover.addTxs(processed);
-                    await db.close();
-                    this.log.verbose(`Processed all ${txs.length} txs for block ${block.number}`, {
-                        blockNumber: block.number,
-                        blockHash: (await block.hash()).toString(),
-                        uuid: this.uuid
-                    });
-                    // Mark block as completed to pad it
-                    const expectedBlockHeader = block.header;
-                    await this.prover.setBlockCompleted(block.number, expectedBlockHeader);
-                }
-            });
-            const executionTime = timer.ms();
-            this.progressState('awaiting-prover');
-            const { publicInputs, proof, batchedBlobInputs } = await this.prover.finalizeEpoch();
-            this.log.info(`Finalized proof for epoch ${epochNumber}`, {
-                epochNumber,
-                uuid: this.uuid,
-                duration: timer.ms()
-            });
-            this.progressState('publishing-proof');
-            if (this.config.skipSubmitProof) {
-                this.log.info(`Proof publishing is disabled. Dropping valid proof for epoch ${epochNumber} (checkpoints ${fromCheckpoint} to ${toCheckpoint})`);
-                this.state = 'completed';
-                this.metrics.recordProvingJob(executionTime, timer.ms(), epochSizeCheckpoints, epochSizeBlocks, epochSizeTxs);
-                return;
-            }
-            const success = await this.publisher.submitEpochProof({
-                fromCheckpoint,
-                toCheckpoint,
-                epochNumber,
-                publicInputs,
-                proof,
-                batchedBlobInputs,
-                attestations
-            });
-            if (!success) {
-                throw new Error('Failed to submit epoch proof to L1');
-            }
-            this.log.info(`Submitted proof for epoch ${epochNumber} (checkpoints ${fromCheckpoint} to ${toCheckpoint})`, {
-                epochNumber,
-                uuid: this.uuid
-            });
-            this.state = 'completed';
-            this.metrics.recordProvingJob(executionTime, timer.ms(), epochSizeCheckpoints, epochSizeBlocks, epochSizeTxs);
+            await this.run();
         } catch (err) {
-            if (err && err.name === 'HaltExecutionError') {
-                this.log.warn(`Halted execution of epoch ${epochNumber} prover job`, {
-                    uuid: this.uuid,
-                    epochNumber,
-                    details: err.message
-                });
-                return;
-            }
-            this.log.error(`Error running epoch ${epochNumber} prover job`, err, {
+            this.log.error(`Error in EpochSession ${this.uuid}`, err, {
                 uuid: this.uuid,
-                epochNumber
+                ...this.spec
             });
-            if (this.state === 'processing' || this.state === 'awaiting-prover' || this.state === 'publishing-proof') {
+            if (!this.isTerminal()) {
                 this.state = 'failed';
             }
         } finally{
             clearTimeout(this.deadlineTimeoutHandler);
-            await this.epochCheckPromise?.stop();
-            await this.prover.stop();
-            resolve();
+            await this.teardownTopTreeIfNeeded();
+            this.resolveCompletion(this.state);
         }
+        return this.state;
     }
     /**
-   * Create a new db fork for tx processing, inserting all L1 to L2.
-   * REFACTOR: The prover already spawns a db fork of its own for each block, so we may be able to do away with just one fork.
-   */ async createFork(blockNumber, l1ToL2Messages) {
-        const db = await this.dbProvider.fork(blockNumber);
-        const l1ToL2MessagesPadded = padArrayEnd(l1ToL2Messages, Fr.ZERO, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP, 'Too many L1 to L2 messages');
-        this.log.verbose(`Creating fork at ${blockNumber} with ${l1ToL2Messages.length} L1 to L2 messages`, {
-            blockNumber,
-            l1ToL2Messages: l1ToL2Messages.map((m)=>m.toString())
+   * Cancels the session. Idempotent. Withdraws any submitted candidate from the
+   * publishing service so the in-flight publisher (if any) is interrupted.
+   */ async cancel(reason = 'cancelled', { abortJobs = true } = {}) {
+        if (this.isTerminal()) {
+            return;
+        }
+        this.log.info(`Cancelling EpochSession ${this.uuid}: ${reason}`, {
+            uuid: this.uuid,
+            ...this.spec,
+            previousState: this.state,
+            reason
         });
-        await db.appendLeaves(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, l1ToL2MessagesPadded);
-        return db;
-    }
-    progressState(state) {
-        this.checkState();
-        this.state = state;
-    }
-    checkState() {
-        if (this.state === 'timed-out' || this.state === 'stopped' || this.state === 'failed' || this.state === 'reorg') {
-            throw new HaltExecutionError(this.state);
+        this.state = 'cancelled';
+        try {
+            this.deps.publishingService.withdraw(this.uuid);
+        } catch (err) {
+            this.log.error(`Error withdrawing candidate from publishing service`, err);
         }
-    }
-    async stop(state = 'stopped') {
-        this.state = state;
-        this.prover.cancel();
-        if (this.runPromise) {
-            await this.runPromise;
+        if (this.topTreeJob && !this.topTreeJob.isCancelled()) {
+            const job = this.topTreeJob;
+            this.topTreeJob = undefined;
+            // On a clean shutdown we leave the in-flight broker jobs alone so a restart can reuse them;
+            // other cancellations (reorg, supersede, deadline) abort them since their inputs are stale.
+            job.cancel(abortJobs);
+            this.pendingTopTreeCleanups.push(job);
         }
+        await this.teardownTopTreeIfNeeded();
+        this.resolveCompletion(this.state);
     }
-    scheduleDeadlineStop() {
-        const deadline = this.deadline;
-        if (deadline) {
-            const timeout = deadline.getTime() - Date.now();
-            if (timeout <= 0) {
-                throw new Error('Cannot start job with deadline in the past');
+    async run() {
+        const timer = new Timer();
+        if (this.deps.config.finalizationDelayMs && this.deps.config.finalizationDelayMs > 0) {
+            this.log.warn(`Waiting ${this.deps.config.finalizationDelayMs}ms before starting top-tree proving`, {
+                uuid: this.uuid,
+                ...this.spec
+            });
+            await sleep(this.deps.config.finalizationDelayMs);
+            if (this.isTerminal()) {
+                return;
             }
-            this.deadlineTimeoutHandler = setTimeout(()=>{
-                if (EpochProvingJobTerminalState.includes(this.state)) {
-                    return;
-                }
-                this.log.warn('Stopping job due to deadline hit', {
+        }
+        // Stage 1 — top-tree proving.
+        const topTreeJob = new TopTreeJob(this.spec.epochNumber, this.checkpoints, {
+            proverFactory: this.deps.proverFactory,
+            metrics: this.deps.metrics,
+            log: this.log,
+            hooks: this.toTopTreeHooks()
+        });
+        this.topTreeJob = topTreeJob;
+        const { fromCheckpoint, toCheckpoint, count } = topTreeJob.getRange();
+        this.state = 'awaiting-checkpoints';
+        let proof;
+        try {
+            proof = await topTreeJob.start();
+        } catch (err) {
+            if (err instanceof TopTreeCancelledError) {
+                // Session cancel kicked off the underlying teardown; nothing more to do here.
+                this.log.info(`Top-tree cancelled for EpochSession ${this.uuid}`, {
                     uuid: this.uuid,
-                    epochNumber: this.epochNumber
+                    ...this.spec
                 });
-                this.stop('timed-out').catch((err)=>{
-                    this.log.error('Error stopping job', err, {
-                        uuid: this.uuid,
-                        epochNumber: this.epochNumber
-                    });
-                });
-            }, timeout);
+                return;
+            }
+            throw err;
         }
-    }
-    /**
-   * Kicks off a running promise that queries the archiver for the set of L2 blocks of the current epoch.
-   * If those change, stops the proving job with a `rerun` state, so the node re-enqueues it.
-   */ async scheduleEpochCheck() {
-        const l2BlockSource = this.l2BlockSource;
-        if (!l2BlockSource) {
-            this.log.warn(`No L2 block source available, skipping epoch check`);
+        this.topTreeJob = undefined;
+        this.log.info(`Top-tree proof ready for EpochSession ${this.uuid}`, {
+            uuid: this.uuid,
+            ...this.spec,
+            fromCheckpoint,
+            toCheckpoint,
+            durationMs: timer.ms()
+        });
+        // Stage 2 — hand the proof to the publishing service and wait for its verdict.
+        await this.submitProof(proof, fromCheckpoint, toCheckpoint, count, timer);
+    }
+    async submitProof(proof, fromCheckpoint, toCheckpoint, checkpointCount, timer) {
+        // Attestations come from the highest-numbered registered checkpoint — that's the one
+        // whose attestations the L1 contract checks for the proven range.
+        const lastCheckpoint = this.checkpoints[this.checkpoints.length - 1];
+        const attestations = lastCheckpoint.attestations.map((a)=>a.toViem());
+        const epochSizeBlocks = this.checkpoints.reduce((acc, c)=>acc + c.checkpoint.blocks.length, 0);
+        const epochSizeTxs = this.checkpoints.reduce((acc, c)=>acc + c.checkpoint.blocks.reduce((bAcc, block)=>bAcc + block.body.txEffects.length, 0), 0);
+        // Reflect the publish phase. Guard against a terminal state set concurrently by cancel() — the
+        // post-submit isTerminal() check below relies on cancel still winning.
+        if (!this.isTerminal()) {
+            this.state = 'publishing-proof';
+        }
+        const outcome = await this.deps.publishingService.submit({
+            id: this.uuid,
+            epoch: this.spec.epochNumber,
+            kind: this.spec.kind,
+            startBlock: this.getStartBlockNumber(),
+            endBlock: this.getEndBlockNumber(),
+            deadline: this.deps.deadline,
+            fromCheckpoint,
+            toCheckpoint,
+            publicInputs: proof.publicInputs,
+            proof: proof.proof,
+            batchedBlobInputs: proof.batchedBlobInputs,
+            attestations,
+            headers: this.checkpoints.map((c)=>c.checkpoint.header)
+        });
+        if (this.isTerminal()) {
+            // cancel() already set the terminal state — don't clobber it.
             return;
         }
-        const intervalMs = Math.ceil((await l2BlockSource.getL1Constants()).ethereumSlotDuration / 2) * 1000;
-        this.epochCheckPromise = new RunningPromise(async ()=>{
-            const blockHeaders = await l2BlockSource.getCheckpointedBlockHeadersForEpoch(this.epochNumber);
-            const blockHashes = await Promise.all(blockHeaders.map((header)=>header.hash()));
-            const thisBlocks = this.checkpoints.flatMap((checkpoint)=>checkpoint.blocks);
-            const thisBlockHashes = await Promise.all(thisBlocks.map((block)=>block.hash()));
-            if (blockHeaders.length !== thisBlocks.length || !blockHashes.every((block, i)=>block.equals(thisBlockHashes[i]))) {
-                this.log.warn('Epoch blocks changed underfoot', {
+        switch(outcome){
+            case 'published':
+                this.log.info(`Submitted proof for epoch ${this.spec.epochNumber} (checkpoints ${fromCheckpoint}..${toCheckpoint})`, {
                     uuid: this.uuid,
-                    epochNumber: this.epochNumber,
-                    oldBlockHashes: thisBlockHashes,
-                    newBlockHashes: blockHashes
+                    ...this.spec
                 });
-                void this.stop('reorg');
-            }
-        }, this.log, intervalMs).start();
-        this.log.verbose(`Scheduled epoch check for epoch ${this.epochNumber} every ${intervalMs}ms`);
-    }
-    /* Returns the last block header in the previous checkpoint for all checkpoints in the epoch */ gatherPreviousBlockHeaders() {
-        const lastBlocks = this.checkpoints.map((checkpoint)=>checkpoint.blocks.at(-1));
-        return [
-            this.data.previousBlockHeader,
-            ...lastBlocks.map((block)=>block.header).slice(0, -1)
-        ];
+                this.state = 'completed';
+                this.deps.metrics.recordProvingJob(timer.ms(), checkpointCount, epochSizeBlocks, epochSizeTxs);
+                return;
+            case 'superseded':
+                this.log.info(`EpochSession ${this.uuid} superseded by a longer candidate`, {
+                    uuid: this.uuid,
+                    ...this.spec
+                });
+                this.state = 'superseded';
+                return;
+            case 'withdrawn':
+                // cancel() ran but the terminal-state check above missed it. Defensive: treat as cancelled.
+                this.state = 'cancelled';
+                return;
+            case 'expired':
+                this.log.warn(`EpochSession ${this.uuid} expired before publishing`, {
+                    uuid: this.uuid,
+                    ...this.spec
+                });
+                this.state = 'timed-out';
+                return;
+            case 'failed':
+                throw new Error('Failed to submit epoch proof to L1');
+        }
     }
-    getTxs(block) {
-        return block.body.txEffects.map((txEffect)=>this.txs.get(txEffect.txHash.toString()));
+    async teardownTopTreeIfNeeded() {
+        if (this.topTreeJob) {
+            const job = this.topTreeJob;
+            this.topTreeJob = undefined;
+            job.cancel();
+            this.pendingTopTreeCleanups.push(job);
+        }
+        if (this.pendingTopTreeCleanups.length > 0) {
+            await Promise.allSettled(this.pendingTopTreeCleanups.map((j)=>j.whenDone()));
+            this.pendingTopTreeCleanups.length = 0;
+        }
     }
-    getL1ToL2Messages(checkpoint) {
-        return this.data.l1ToL2Messages[checkpoint.number];
+    scheduleDeadlineStop() {
+        const deadline = this.deps.deadline;
+        if (!deadline) {
+            return;
+        }
+        const timeout = Math.max(deadline.getTime() - this.deps.dateProvider.now(), 0);
+        this.deadlineTimeoutHandler = setTimeout(()=>{
+            void this.handleDeadline();
+        }, timeout);
     }
-    async processTxs(publicProcessor, txs) {
-        const { deadline } = this;
-        const [processedTxs, failedTxs] = await publicProcessor.process(txs, {
-            deadline
-        });
-        if (failedTxs.length) {
-            const failedTxHashes = await Promise.all(failedTxs.map(({ tx })=>tx.getTxHash()));
-            throw new Error(`Txs failed processing: ${failedTxs.map(({ error }, index)=>`${failedTxHashes[index]} (${error})`).join(', ')}`);
+    /**
+   * Returns a promise that resolves once cancellation has propagated and the state has
+   * been flipped from 'cancelled' to 'timed-out'. Protected so unit tests can drive the
+   * deadline path without waiting on the real `setTimeout` to fire.
+   */ async handleDeadline() {
+        if (this.isTerminal()) {
+            return;
         }
-        if (processedTxs.length !== txs.length) {
-            throw new Error(`Failed to process all txs: processed ${processedTxs.length} out of ${txs.length}`);
+        this.log.warn(`EpochSession ${this.uuid} hit deadline`, {
+            uuid: this.uuid,
+            ...this.spec
+        });
+        await this.cancel('deadline');
+        // After cancel, override state if it was the canonical timeout case so observers see 'timed-out'.
+        if (this.state === 'cancelled') {
+            this.state = 'timed-out';
         }
-        return processedTxs;
     }
-}
-class HaltExecutionError extends Error {
-    state;
-    constructor(state){
-        super(`Halted execution due to state ${state}`), this.state = state;
-        this.name = 'HaltExecutionError';
+    toTopTreeHooks() {
+        const hooks = this.deps.hooks;
+        return {
+            // `beforeProve` fires once the sub-tree (checkpoint block) proofs are ready and the root prove is
+            // about to start — the boundary between `awaiting-checkpoints` and proving the top tree. Don't
+            // clobber a terminal state set concurrently by cancel().
+            beforeProve: async ()=>{
+                if (!this.isTerminal()) {
+                    this.state = 'awaiting-root';
+                }
+                await hooks?.beforeTopTreeProve?.();
+            },
+            afterProve: hooks?.afterTopTreeProve,
+            proveOverride: hooks?.topTreeProveOverride
+        };
     }
 }