@aztec/prover-node 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5a9928

package/dest/job/checkpoint-prover.js

@@ -0,0 +1,405 @@
+import { NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP } from '@aztec/constants';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+import { Timer } from '@aztec/foundation/timer';
+import { getVKTreeRoot } from '@aztec/noir-protocol-circuits-types/vk-tree';
+import { protocolContractsHash } from '@aztec/protocol-contracts';
+import { PublicSimulatorConfig } from '@aztec/stdlib/avm';
+import { CheckpointConstantData } from '@aztec/stdlib/rollup';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+/**
+ * Self-contained per-checkpoint prover, content-addressed by
+ * `(checkpoint number, slot number, checkpoint archive root)`.
+ *
+ * The store creates a CheckpointProver once per content-key. Keying on the checkpoint's
+ * own archive root (its post-state) means two checkpoints are "the same" iff they
+ * produce the same archive — so a reorg branch, or a replacement built on the same
+ * predecessor but with different content, keys to a distinct prover.
+ *
+ * The prover eagerly starts its own tx gather and sub-tree work in the constructor, so
+ * callers only need to call `whenBlockProofsReady()` to obtain the resulting block-rollup
+ * proofs.
+ *
+ * A CheckpointProver does not survive a prune: its sub-tree work forks world-state per
+ * block, and an L1 prune of a base block faults those reads. The store therefore cancels and
+ * discards a prover when its checkpoint is pruned, and a re-add (even of identical content)
+ * constructs a fresh prover.
+ *
+ * `cancel()` is idempotent. It aborts the gather + sub-tree, rejects the block-proof
+ * promise, and exposes a `whenDone()` that resolves once teardown has unwound.
+ */ export class CheckpointProver {
+    deps;
+    id;
+    checkpoint;
+    epochNumber;
+    slotNumber;
+    attestations;
+    previousBlockHeader;
+    l1ToL2Messages;
+    previousArchiveSiblingPath;
+    /** Resolved by the sub-tree on success, rejected on cancel/failure. */ blockProofs;
+    // Three independent lifecycle facts — deliberately not collapsed into one status enum, because several
+    // combinations are legal and relied on: a prover can be `completed` and then `cancelled` (routine
+    // teardown of an already-proven checkpoint), or `completed` and then `failed` (block proving was
+    // enqueued, but the sub-tree subsequently faulted). Only `failed` + `cancelled` is excluded — a cancel
+    // is not a failure (enforced in `failBlockProofs`).
+    /** Block-level proving was fully *enqueued* (a progress marker; the sub-tree may still be proving). */ completed;
+    /** Block proofs rejected for a genuine (non-cancel) reason — a sub-tree or prune-induced fork fault. */ failed;
+    /** The prover was torn down (prune / reap / shutdown). */ cancelled;
+    subTree;
+    abortController;
+    /** Tracks the eager gather+execute task so `cancel()` and `whenDone()` can await its unwind. */ runPromise;
+    /** Tracks the cancel-driven teardown so `whenDone()` can await it. */ cancelPromise;
+    /** Tracks the success-driven sub-tree teardown (once block proofs are captured) so `whenDone()` can await it. */ teardownPromise;
+    constructor(args, deps){
+        this.deps = deps;
+        this.blockProofs = promiseWithResolvers();
+        this.completed = false;
+        this.failed = false;
+        this.cancelled = false;
+        this.abortController = new AbortController();
+        this.checkpoint = args.checkpoint;
+        this.epochNumber = args.epochNumber;
+        this.slotNumber = args.checkpoint.header.slotNumber;
+        this.attestations = args.attestations;
+        this.previousBlockHeader = args.previousBlockHeader;
+        this.l1ToL2Messages = args.l1ToL2Messages;
+        this.previousArchiveSiblingPath = args.previousArchiveSiblingPath;
+        this.id = CheckpointProver.idFor(args.checkpoint);
+        // Mark blockProofs as observed so a cancel that lands before any consumer awaits
+        // does not surface as an unhandled rejection.
+        this.blockProofs.promise.catch(()=>{});
+        deps.log.info(`Created CheckpointProver ${this.id}`, {
+            checkpointNumber: this.checkpoint.number,
+            epochNumber: this.epochNumber,
+            slotNumber: this.slotNumber,
+            blockCount: this.checkpoint.blocks.length,
+            l1ToL2MessageCount: this.l1ToL2Messages.length,
+            archiveRoot: this.checkpoint.archive.root.toString()
+        });
+        // Kick off the eager gather + sub-tree pipeline.
+        this.runPromise = this.gatherAndExecute();
+    }
+    /**
+   * Stable content-addressed identifier: `${checkpoint number}:${slot}:${archive root}`.
+   * The archive root is the checkpoint's post-state, so it distinguishes any two
+   * checkpoints that differ in history or content while collapsing identical re-adds.
+   */ static idFor(checkpoint) {
+        return `${checkpoint.number}:${checkpoint.header.slotNumber}:${checkpoint.archive.root.toString()}`;
+    }
+    isCancelled() {
+        return this.cancelled;
+    }
+    /**
+   * True once this prover's block proofs have rejected for a genuine (non-cancel) reason — a sub-tree
+   * proving fault or a prune-induced world-state fork fault. A failed prover cannot produce its block
+   * proofs, so the reconciler must not build (or rebuild) an EpochSession over it; it is cleared only by
+   * a prune/re-add replacing it with a fresh prover, or by expiry reaping it.
+   */ isFailed() {
+        return this.failed;
+    }
+    /** AbortSignal that fires on cancel — for callers that want to wire their own tasks. */ getAbortSignal() {
+        return this.abortController.signal;
+    }
+    /** Promise that resolves with the block-rollup proofs for this checkpoint (or rejects on cancel/failure). */ whenBlockProofsReady() {
+        return this.blockProofs.promise;
+    }
+    /** Resolves when all in-flight work for this prover has fully unwound. */ async whenDone() {
+        await this.runPromise.catch(()=>{});
+        // `runPromise` resolves once block-level proving is *enqueued*, but the sub-tree's proofs (and the
+        // success-driven teardown they trigger) land later, on the `getSubTreeResult()` callback. Awaiting
+        // `blockProofs` here bridges that gap: on success the callback resolves `blockProofs` and then
+        // synchronously sets `teardownPromise` before this await resumes, so the teardown is observable
+        // below; on failure/cancel `blockProofs` rejects and teardown is driven by the `finally`/cancel
+        // paths already awaited via `runPromise`/`cancelPromise`.
+        await this.blockProofs.promise.catch(()=>{});
+        if (this.cancelPromise) {
+            await this.cancelPromise;
+        }
+        if (this.teardownPromise) {
+            await this.teardownPromise;
+        }
+    }
+    async gatherAndExecute() {
+        try {
+            const txs = await this.gatherTxs();
+            if (this.cancelled) {
+                return;
+            }
+            await this.executeCheckpoint(txs);
+        } catch (err) {
+            if (this.cancelled) {
+                this.deps.log.debug(`CheckpointProver ${this.id} cancelled during gather/execute`, {
+                    checkpointNumber: this.checkpoint.number
+                });
+                return;
+            }
+            this.deps.log.error(`Error in CheckpointProver ${this.id}`, err, {
+                checkpointNumber: this.checkpoint.number
+            });
+            this.failBlockProofs(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    /**
+   * Rejects the block-proof promise and, unless this is a cancellation, records the prover as failed so
+   * the reconciler won't build an EpochSession over it. First rejection wins, so a later duplicate reject
+   * (e.g. the executeCheckpoint `finally`) is a harmless no-op.
+   */ failBlockProofs(err) {
+        if (!this.cancelled && !this.failed) {
+            this.failed = true;
+            // Notify the owner so it can upload a post-mortem for this checkpoint. Fire-and-forget: the
+            // callback must not block the prover's teardown, and a throw in it must not mask the rejection.
+            try {
+                this.deps.onFailed?.(this);
+            } catch (err) {
+                this.deps.log.error(`Error in CheckpointProver onFailed callback for ${this.id}`, err);
+            }
+        }
+        this.blockProofs.reject(err);
+    }
+    /** Fetches every tx in this checkpoint from the tx pool (by hash, via the block tx effects). */ async fetchTxs() {
+        const deadline = new Date(this.deps.dateProvider.now() + this.deps.txGatheringTimeoutMs);
+        const txsByBlock = await Promise.all(this.checkpoint.blocks.map((block)=>this.deps.txProvider.getTxsForBlock(block, {
+                deadline
+            })));
+        const txs = txsByBlock.flatMap(({ txs })=>txs);
+        const missingTxs = txsByBlock.flatMap(({ missingTxs })=>missingTxs);
+        return {
+            txs: new Map(txs.map((tx)=>[
+                    tx.getTxHash().toString(),
+                    tx
+                ])),
+            missingTxs
+        };
+    }
+    async gatherTxs() {
+        const { txs, missingTxs } = await this.fetchTxs();
+        if (missingTxs.length > 0) {
+            throw new Error(`Txs not found for checkpoint ${this.checkpoint.number}: ${missingTxs.map((hash)=>hash.toString()).join(', ')}`);
+        }
+        return txs;
+    }
+    /**
+   * Re-fetches this checkpoint's txs from the tx pool for a post-mortem failure upload.
+   *
+   * The prover does not cache txs on the heap — they are consumed during proving and dropped — so the
+   * durable pool (which keeps a mined tx until L1 finality, with A-1274's retention margin covering a
+   * lagging prover) is the source of truth, read back by hash here. Best-effort: any tx the pool can
+   * no longer supply is logged and omitted rather than failing the upload, since a partial post-mortem
+   * snapshot is still useful for diagnosis.
+   */ async getTxsForUpload() {
+        const { txs, missingTxs } = await this.fetchTxs();
+        if (missingTxs.length > 0) {
+            this.deps.log.warn(`Missing ${missingTxs.length} tx(s) re-fetching checkpoint ${this.checkpoint.number} for failure upload`, {
+                checkpointNumber: this.checkpoint.number,
+                missingTxCount: missingTxs.length
+            });
+        }
+        return txs;
+    }
+    async executeCheckpoint(txs) {
+        const signal = this.abortController.signal;
+        const checkpointTimer = new Timer();
+        let subTreeStarted = false;
+        try {
+            // Test hook: force a sub-tree failure to exercise the checkpoint failure/upload path.
+            if (this.deps.checkpointProveOverride) {
+                await this.deps.checkpointProveOverride();
+            }
+            // The gathered txs are consumed locally below (public processing + sub-tree) and then dropped.
+            // They are deliberately not retained on the instance: the tx pool is the durable source and
+            // `getTxsForUpload` re-fetches them by hash if a post-mortem upload needs them.
+            const { chainId, version } = this.checkpoint.blocks[0].header.globalVariables;
+            const checkpointConstants = CheckpointConstantData.from({
+                chainId,
+                version,
+                vkTreeRoot: getVKTreeRoot(),
+                protocolContractsHash: protocolContractsHash,
+                proverId: this.deps.proverId.toField(),
+                slotNumber: this.checkpoint.header.slotNumber,
+                coinbase: this.checkpoint.header.coinbase,
+                feeRecipient: this.checkpoint.header.feeRecipient,
+                gasFees: this.checkpoint.header.gasFees
+            });
+            this.deps.log.info(`Starting processing checkpoint ${this.checkpoint.number}`, {
+                checkpointNumber: this.checkpoint.number,
+                checkpointHash: this.checkpoint.hash().toString(),
+                blockCount: this.checkpoint.blocks.length
+            });
+            this.subTree = await this.deps.proverFactory.createCheckpointSubTreeOrchestrator(this.deps.chonkCache, this.epochNumber, checkpointConstants, this.l1ToL2Messages, this.checkpoint.blocks.length, this.previousBlockHeader);
+            subTreeStarted = true;
+            // Bridge the sub-tree's result onto blockProofs.
+            void this.subTree.getSubTreeResult().then((result)=>{
+                this.deps.log.info(`Sub-tree block proofs ready for checkpoint ${this.checkpoint.number}`, {
+                    checkpointNumber: this.checkpoint.number,
+                    blockProofCount: result.blockProofOutputs.length
+                });
+                // Spans processing + proving (from executeCheckpoint start, after tx gathering) to proofs ready.
+                this.deps.metrics.recordCheckpointProving(checkpointTimer.ms());
+                this.blockProofs.resolve(result.blockProofOutputs);
+                // Release the sub-tree orchestrator now that its output is captured. The block-proof outputs
+                // survive via the resolved promise; everything else the sub-tree held — per-tx AVM inputs, and
+                // the base/merge/parity proof trees — is dead once proving completes, yet the prover is retained
+                // for the whole proof-submission window. Dropping it here is what stops that retention from
+                // accumulating across every proven checkpoint. Post-completion consumers (the top-tree job, a
+                // rebuilt EpochSession, failure upload) read only `whenBlockProofsReady()` and this prover's own
+                // fields (`checkpoint`, `txs`, headers, sibling paths), never the sub-tree.
+                this.teardownPromise = this.teardownSubTree();
+            }, (err)=>this.failBlockProofs(err instanceof Error ? err : new Error(String(err))));
+            if (signal.aborted) {
+                return;
+            }
+            const allTxs = this.checkpoint.blocks.flatMap((block)=>block.body.txEffects.map((txEffect)=>txs.get(txEffect.txHash.toString())));
+            const publicTxs = allTxs.filter((tx)=>tx?.data.forPublic);
+            if (publicTxs.length > 0) {
+                await this.subTree.startChonkVerifierCircuits(publicTxs);
+                if (signal.aborted) {
+                    return;
+                }
+            }
+            for(let blockIndex = 0; blockIndex < this.checkpoint.blocks.length; blockIndex++){
+                const blockTimer = new Timer();
+                const block = this.checkpoint.blocks[blockIndex];
+                const globalVariables = block.header.globalVariables;
+                const blockTxs = this.getTxsForBlock(block, txs);
+                await this.subTree.startNewBlock(block.number, globalVariables.timestamp, blockTxs.length);
+                if (signal.aborted) {
+                    return;
+                }
+                const db = await this.createFork(BlockNumber(block.number - 1), blockIndex === 0 ? this.l1ToL2Messages : undefined);
+                try {
+                    if (signal.aborted) {
+                        return;
+                    }
+                    const config = PublicSimulatorConfig.from({
+                        proverId: this.deps.proverId.toField(),
+                        skipFeeEnforcement: false,
+                        collectDebugLogs: false,
+                        collectHints: true,
+                        collectPublicInputs: true,
+                        collectStatistics: false
+                    });
+                    const publicProcessor = this.deps.publicProcessorFactory.create(db, globalVariables, config);
+                    const processed = await this.processTxs(publicProcessor, blockTxs);
+                    if (signal.aborted) {
+                        return;
+                    }
+                    await this.subTree.addTxs(processed);
+                } finally{
+                    await db.close();
+                }
+                if (signal.aborted) {
+                    return;
+                }
+                await this.subTree.setBlockCompleted(block.number, block.header);
+                this.deps.metrics.recordBlockProcessing(blockTimer.ms());
+                if (signal.aborted) {
+                    return;
+                }
+            }
+            this.completed = true;
+            const numTxs = this.checkpoint.blocks.reduce((acc, block)=>acc + block.body.txEffects.length, 0);
+            this.deps.metrics.recordCheckpointProcessing(checkpointTimer.ms(), this.checkpoint.blocks.length, numTxs);
+            this.deps.log.info(`Finished enqueueing block-level proving for checkpoint ${this.checkpoint.number} in ${checkpointTimer.ms()}ms`, {
+                checkpointNumber: this.checkpoint.number,
+                blockCount: this.checkpoint.blocks.length,
+                durationMs: checkpointTimer.ms()
+            });
+        } finally{
+            if (!this.completed) {
+                if (subTreeStarted) {
+                    await this.teardownSubTree();
+                }
+                this.failBlockProofs(new Error(`Checkpoint ${this.id} did not complete block processing`));
+            }
+        }
+    }
+    /**
+   * Mark cancelled. Idempotent. Aborts in-flight work, rejects the block-proof promise,
+   * and kicks off a background teardown of the sub-tree. The teardown promise is exposed
+   * via `whenDone()`.
+   *
+   * `routine` distinguishes a post-finalize teardown (sub-tree already proven, fires
+   * once at prover exit) from a real abort (reorg, prune, deadline). Behaviour is
+   * identical either way; the flag only adjusts log verbosity.
+   */ cancel({ routine = false } = {}) {
+        if (this.cancelled) {
+            return;
+        }
+        this.cancelled = true;
+        // A teardown of a completed prover is routine regardless of the caller's flag —
+        // we logged the work as done already, so don't relabel it as a mid-flight cancel.
+        if (routine || this.completed) {
+            this.deps.log.verbose(`Tearing down CheckpointProver ${this.id}`, {
+                checkpointNumber: this.checkpoint.number,
+                wasCompleted: this.completed
+            });
+        } else {
+            this.deps.log.info(`Cancelling in-flight CheckpointProver ${this.id}`, {
+                checkpointNumber: this.checkpoint.number,
+                wasCompleted: this.completed
+            });
+        }
+        this.abortController.abort();
+        this.blockProofs.reject(new Error(`Checkpoint ${this.id} cancelled`));
+        this.cancelPromise = this.runCancel().catch(()=>{});
+    }
+    async runCancel() {
+        if (this.subTree) {
+            try {
+                this.subTree.cancel();
+            } catch (err) {
+                this.deps.log.error('Error cancelling sub-tree', err);
+            }
+        }
+        await this.runPromise.catch(()=>{});
+        if (this.subTree) {
+            await this.teardownSubTree();
+        }
+    }
+    async teardownSubTree() {
+        const { subTree } = this;
+        this.subTree = undefined;
+        if (subTree) {
+            this.deps.log.debug(`Tearing down sub-tree for checkpoint ${this.checkpoint.number}`, {
+                checkpointNumber: this.checkpoint.number
+            });
+            try {
+                await subTree.stop();
+            } catch (err) {
+                this.deps.log.error('Error stopping sub-tree', err);
+            }
+        }
+    }
+    getTxsForBlock(block, txs) {
+        return block.body.txEffects.map((txEffect)=>txs.get(txEffect.txHash.toString()));
+    }
+    async processTxs(publicProcessor, txs) {
+        // Pass the abort signal so a prune-driven cancel stops the current block's public execution
+        // immediately, rather than running it to completion before the next `signal.aborted` check.
+        // On abort `process` returns a partial result, the length check below throws, and
+        // `gatherAndExecute` swallows it via its `cancelled` guard.
+        const [processedTxs, failedTxs] = await publicProcessor.process(txs, {
+            deadline: this.deps.deadline,
+            signal: this.abortController.signal
+        });
+        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(', ')}`);
+        }
+        if (processedTxs.length !== txs.length) {
+            throw new Error(`Failed to process all txs: processed ${processedTxs.length} out of ${txs.length}`);
+        }
+        return processedTxs;
+    }
+    async createFork(blockNumber, l1ToL2Messages) {
+        const db = await this.deps.dbProvider.fork(blockNumber);
+        if (l1ToL2Messages !== undefined) {
+            const l1ToL2MessagesPadded = padArrayEnd(l1ToL2Messages, Fr.ZERO, NUMBER_OF_L1_L2_MESSAGES_PER_ROLLUP, 'Too many L1 to L2 messages');
+            await db.appendLeaves(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, l1ToL2MessagesPadded);
+        }
+        return db;
+    }
+}

package/dest/job/epoch-session.d.ts

@@ -0,0 +1,160 @@
+import { BlockNumber, type EpochNumber, type SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type LoggerBindings } from '@aztec/foundation/log';
+import { type DateProvider } from '@aztec/foundation/timer';
+import type { EpochProverFactory } from '@aztec/prover-client';
+import { type EpochProvingJobState } from '@aztec/stdlib/interfaces/server';
+import { type Traceable, type Tracer } from '@aztec/telemetry-client';
+import type { ProverNodeJobMetrics } from '../metrics.js';
+import type { ProofPublishingService } from '../proof-publishing-service.js';
+import { CheckpointProver } from './checkpoint-prover.js';
+import { type TopTreeProof } from './top-tree-job.js';
+export type { EpochProvingJobState };
+/** Full vs partial — the only behavioural difference is at the L1 submission step. */
+export type SessionKind = 'full' | 'partial';
+/**
+ * Identifies what a session proves: a contiguous slot range within an epoch. The
+ * concrete prover set the session holds is the *implementation* of the spec — frozen
+ * at construction time, derived from the canonical content for `[fromSlot, toSlot]`.
+ *
+ * Reconciliation in `ProverNode` is uniform across kinds: whenever the canonical
+ * content for the slot range changes, the session is cancelled and replaced with a
+ * fresh session that **preserves the slot range** but adopts the new checkpoints.
+ *
+ * Kind affects only the publishing decision (see `EpochSession`).
+ */
+export interface SessionSpec {
+    kind: SessionKind;
+    epochNumber: EpochNumber;
+    fromSlot: SlotNumber;
+    toSlot: SlotNumber;
+}
+/** Stable string key for use in maps. */
+export declare function specKey(spec: SessionSpec): string;
+/** Hooks tests use to interpose around the top-tree prove without monkey-patching. */
+export type EpochSessionHooks = {
+    beforeTopTreeProve?: () => Promise<void> | void;
+    afterTopTreeProve?: () => Promise<void> | void;
+    topTreeProveOverride?: (defaultProve: () => Promise<TopTreeProof>) => Promise<TopTreeProof>;
+};
+export type EpochSessionOptions = {
+    /**
+     * If set, the session sleeps this many ms after `start()` (before the TopTreeJob is
+     * constructed). Lets late-arriving events (e.g. a prune) be processed before
+     * top-tree proving begins.
+     */
+    finalizationDelayMs?: number;
+};
+/** Dependencies an `EpochSession` needs at construction. */
+export type EpochSessionDeps = {
+    proverFactory: EpochProverFactory;
+    proverId: EthAddress;
+    publishingService: Pick<ProofPublishingService, 'submit' | 'withdraw'>;
+    metrics: ProverNodeJobMetrics;
+    dateProvider: DateProvider;
+    /** Optional proving deadline. The session enters `timed-out` if exceeded. */
+    deadline: Date | undefined;
+    config: EpochSessionOptions;
+    bindings?: LoggerBindings;
+    hooks?: EpochSessionHooks;
+};
+/**
+ * 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`, `expired` → `timed-out`, `withdrawn` → `cancelled`. A fault ends the attempt in one
+ * of two terminal states depending on its cause: `stopped` if a checkpoint prover under it failed
+ * (possibly a prune — the reconciler will rebuild over a fresh prover on re-add), or `failed` if the
+ * session's own top-tree/submit work failed while every prover was healthy (a genuine, non-prune
+ * failure the reconciler retains and uploads — see `hasFailed()`).
+ * 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 declare class EpochSession implements Traceable {
+    private readonly spec;
+    private readonly deps;
+    readonly tracer: Tracer;
+    private readonly uuid;
+    private readonly log;
+    private state;
+    private deadlineTimeoutHandler;
+    private topTreeJob;
+    /** Cancelled top-tree jobs whose teardown is still in flight. Awaited at session stop. */
+    private readonly pendingTopTreeCleanups;
+    private readonly completionPromise;
+    private resolveCompletion;
+    /** Stable reference; never mutated after construction. */
+    private readonly checkpoints;
+    constructor(spec: SessionSpec, checkpoints: readonly CheckpointProver[], deps: EpochSessionDeps);
+    getId(): string;
+    getSpec(): SessionSpec;
+    getState(): EpochProvingJobState;
+    getEpochNumber(): EpochNumber;
+    getKind(): SessionKind;
+    getDeadline(): Date | undefined;
+    getCheckpoints(): readonly CheckpointProver[];
+    /** Resolves when the session reaches a terminal state. */
+    whenDone(): Promise<EpochProvingJobState>;
+    /** True if the session is in a terminal state. */
+    isTerminal(): boolean;
+    /**
+     * True if the session ended in its own genuine failure — top-tree proving or L1 submission failed
+     * while every checkpoint prover succeeded. Because healthy provers rule out a prune-induced fault,
+     * this is a race-free "the epoch could not be proven" signal: the reconciler retains such a (full)
+     * session rather than re-proving it, and uploads a post-mortem. A `stopped` session (a checkpoint
+     * prover failed under it) is NOT a session failure in this sense.
+     */
+    hasFailed(): boolean;
+    /** First block this session proves. */
+    getStartBlockNumber(): BlockNumber;
+    /** Last block this session proves. */
+    getEndBlockNumber(): BlockNumber;
+    /**
+     * 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.
+     */
+    start(): Promise<EpochProvingJobState>;
+    /**
+     * Cancels the session. Idempotent. Withdraws any submitted candidate from the
+     * publishing service so the in-flight publisher (if any) is interrupted.
+     */
+    cancel(reason?: string, { abortJobs }?: {
+        abortJobs?: boolean;
+    }): Promise<void>;
+    private run;
+    private submitProof;
+    private teardownTopTreeIfNeeded;
+    private scheduleDeadlineStop;
+    /**
+     * 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.
+     */
+    protected handleDeadline(): Promise<void>;
+    private toTopTreeHooks;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXBvY2gtc2Vzc2lvbi5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2pvYi9lcG9jaC1zZXNzaW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxXQUFXLEVBQXlCLEtBQUssV0FBVyxFQUFFLEtBQUssVUFBVSxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFDeEgsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDaEUsT0FBTyxFQUFlLEtBQUssY0FBYyxFQUFnQixNQUFNLHVCQUF1QixDQUFDO0FBRXZGLE9BQU8sRUFBRSxLQUFLLFlBQVksRUFBUyxNQUFNLHlCQUF5QixDQUFDO0FBQ25FLE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFL0QsT0FBTyxFQUFFLEtBQUssb0JBQW9CLEVBQWdDLE1BQU0saUNBQWlDLENBQUM7QUFDMUcsT0FBTyxFQUFjLEtBQUssU0FBUyxFQUFFLEtBQUssTUFBTSxFQUFhLE1BQU0seUJBQXlCLENBQUM7QUFJN0YsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDMUQsT0FBTyxLQUFLLEVBQUUsc0JBQXNCLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUM3RSxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUMxRCxPQUFPLEVBQW9DLEtBQUssWUFBWSxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFFeEYsWUFBWSxFQUFFLG9CQUFvQixFQUFFLENBQUM7QUFFckMsd0ZBQXNGO0FBQ3RGLE1BQU0sTUFBTSxXQUFXLEdBQUcsTUFBTSxHQUFHLFNBQVMsQ0FBQztBQUU3Qzs7Ozs7Ozs7OztHQVVHO0FBQ0gsTUFBTSxXQUFXLFdBQVc7SUFDMUIsSUFBSSxFQUFFLFdBQVcsQ0FBQztJQUNsQixXQUFXLEVBQUUsV0FBVyxDQUFDO0lBQ3pCLFFBQVEsRUFBRSxV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

package/dest/job/epoch-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch-session.d.ts","sourceRoot":"","sources":["../../src/job/epoch-session.ts"],"names":[],"mappings":"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"}