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

package/dest/prover-node.js

@@ -0,0 +1,1056 @@
+function applyDecs2203RFactory() {
+    function createAddInitializerMethod(initializers, decoratorFinishedRef) {
+        return function addInitializer(initializer) {
+            assertNotFinished(decoratorFinishedRef, "addInitializer");
+            assertCallable(initializer, "An initializer");
+            initializers.push(initializer);
+        };
+    }
+    function memberDec(dec, name, desc, initializers, kind, isStatic, isPrivate, metadata, value) {
+        var kindStr;
+        switch(kind){
+            case 1:
+                kindStr = "accessor";
+                break;
+            case 2:
+                kindStr = "method";
+                break;
+            case 3:
+                kindStr = "getter";
+                break;
+            case 4:
+                kindStr = "setter";
+                break;
+            default:
+                kindStr = "field";
+        }
+        var ctx = {
+            kind: kindStr,
+            name: isPrivate ? "#" + name : name,
+            static: isStatic,
+            private: isPrivate,
+            metadata: metadata
+        };
+        var decoratorFinishedRef = {
+            v: false
+        };
+        ctx.addInitializer = createAddInitializerMethod(initializers, decoratorFinishedRef);
+        var get, set;
+        if (kind === 0) {
+            if (isPrivate) {
+                get = desc.get;
+                set = desc.set;
+            } else {
+                get = function() {
+                    return this[name];
+                };
+                set = function(v) {
+                    this[name] = v;
+                };
+            }
+        } else if (kind === 2) {
+            get = function() {
+                return desc.value;
+            };
+        } else {
+            if (kind === 1 || kind === 3) {
+                get = function() {
+                    return desc.get.call(this);
+                };
+            }
+            if (kind === 1 || kind === 4) {
+                set = function(v) {
+                    desc.set.call(this, v);
+                };
+            }
+        }
+        ctx.access = get && set ? {
+            get: get,
+            set: set
+        } : get ? {
+            get: get
+        } : {
+            set: set
+        };
+        try {
+            return dec(value, ctx);
+        } finally{
+            decoratorFinishedRef.v = true;
+        }
+    }
+    function assertNotFinished(decoratorFinishedRef, fnName) {
+        if (decoratorFinishedRef.v) {
+            throw new Error("attempted to call " + fnName + " after decoration was finished");
+        }
+    }
+    function assertCallable(fn, hint) {
+        if (typeof fn !== "function") {
+            throw new TypeError(hint + " must be a function");
+        }
+    }
+    function assertValidReturnValue(kind, value) {
+        var type = typeof value;
+        if (kind === 1) {
+            if (type !== "object" || value === null) {
+                throw new TypeError("accessor decorators must return an object with get, set, or init properties or void 0");
+            }
+            if (value.get !== undefined) {
+                assertCallable(value.get, "accessor.get");
+            }
+            if (value.set !== undefined) {
+                assertCallable(value.set, "accessor.set");
+            }
+            if (value.init !== undefined) {
+                assertCallable(value.init, "accessor.init");
+            }
+        } else if (type !== "function") {
+            var hint;
+            if (kind === 0) {
+                hint = "field";
+            } else if (kind === 10) {
+                hint = "class";
+            } else {
+                hint = "method";
+            }
+            throw new TypeError(hint + " decorators must return a function or void 0");
+        }
+    }
+    function applyMemberDec(ret, base, decInfo, name, kind, isStatic, isPrivate, initializers, metadata) {
+        var decs = decInfo[0];
+        var desc, init, value;
+        if (isPrivate) {
+            if (kind === 0 || kind === 1) {
+                desc = {
+                    get: decInfo[3],
+                    set: decInfo[4]
+                };
+            } else if (kind === 3) {
+                desc = {
+                    get: decInfo[3]
+                };
+            } else if (kind === 4) {
+                desc = {
+                    set: decInfo[3]
+                };
+            } else {
+                desc = {
+                    value: decInfo[3]
+                };
+            }
+        } else if (kind !== 0) {
+            desc = Object.getOwnPropertyDescriptor(base, name);
+        }
+        if (kind === 1) {
+            value = {
+                get: desc.get,
+                set: desc.set
+            };
+        } else if (kind === 2) {
+            value = desc.value;
+        } else if (kind === 3) {
+            value = desc.get;
+        } else if (kind === 4) {
+            value = desc.set;
+        }
+        var newValue, get, set;
+        if (typeof decs === "function") {
+            newValue = memberDec(decs, name, desc, initializers, kind, isStatic, isPrivate, metadata, value);
+            if (newValue !== void 0) {
+                assertValidReturnValue(kind, newValue);
+                if (kind === 0) {
+                    init = newValue;
+                } else if (kind === 1) {
+                    init = newValue.init;
+                    get = newValue.get || value.get;
+                    set = newValue.set || value.set;
+                    value = {
+                        get: get,
+                        set: set
+                    };
+                } else {
+                    value = newValue;
+                }
+            }
+        } else {
+            for(var i = decs.length - 1; i >= 0; i--){
+                var dec = decs[i];
+                newValue = memberDec(dec, name, desc, initializers, kind, isStatic, isPrivate, metadata, value);
+                if (newValue !== void 0) {
+                    assertValidReturnValue(kind, newValue);
+                    var newInit;
+                    if (kind === 0) {
+                        newInit = newValue;
+                    } else if (kind === 1) {
+                        newInit = newValue.init;
+                        get = newValue.get || value.get;
+                        set = newValue.set || value.set;
+                        value = {
+                            get: get,
+                            set: set
+                        };
+                    } else {
+                        value = newValue;
+                    }
+                    if (newInit !== void 0) {
+                        if (init === void 0) {
+                            init = newInit;
+                        } else if (typeof init === "function") {
+                            init = [
+                                init,
+                                newInit
+                            ];
+                        } else {
+                            init.push(newInit);
+                        }
+                    }
+                }
+            }
+        }
+        if (kind === 0 || kind === 1) {
+            if (init === void 0) {
+                init = function(instance, init) {
+                    return init;
+                };
+            } else if (typeof init !== "function") {
+                var ownInitializers = init;
+                init = function(instance, init) {
+                    var value = init;
+                    for(var i = 0; i < ownInitializers.length; i++){
+                        value = ownInitializers[i].call(instance, value);
+                    }
+                    return value;
+                };
+            } else {
+                var originalInitializer = init;
+                init = function(instance, init) {
+                    return originalInitializer.call(instance, init);
+                };
+            }
+            ret.push(init);
+        }
+        if (kind !== 0) {
+            if (kind === 1) {
+                desc.get = value.get;
+                desc.set = value.set;
+            } else if (kind === 2) {
+                desc.value = value;
+            } else if (kind === 3) {
+                desc.get = value;
+            } else if (kind === 4) {
+                desc.set = value;
+            }
+            if (isPrivate) {
+                if (kind === 1) {
+                    ret.push(function(instance, args) {
+                        return value.get.call(instance, args);
+                    });
+                    ret.push(function(instance, args) {
+                        return value.set.call(instance, args);
+                    });
+                } else if (kind === 2) {
+                    ret.push(value);
+                } else {
+                    ret.push(function(instance, args) {
+                        return value.call(instance, args);
+                    });
+                }
+            } else {
+                Object.defineProperty(base, name, desc);
+            }
+        }
+    }
+    function applyMemberDecs(Class, decInfos, metadata) {
+        var ret = [];
+        var protoInitializers;
+        var staticInitializers;
+        var existingProtoNonFields = new Map();
+        var existingStaticNonFields = new Map();
+        for(var i = 0; i < decInfos.length; i++){
+            var decInfo = decInfos[i];
+            if (!Array.isArray(decInfo)) continue;
+            var kind = decInfo[1];
+            var name = decInfo[2];
+            var isPrivate = decInfo.length > 3;
+            var isStatic = kind >= 5;
+            var base;
+            var initializers;
+            if (isStatic) {
+                base = Class;
+                kind = kind - 5;
+                staticInitializers = staticInitializers || [];
+                initializers = staticInitializers;
+            } else {
+                base = Class.prototype;
+                protoInitializers = protoInitializers || [];
+                initializers = protoInitializers;
+            }
+            if (kind !== 0 && !isPrivate) {
+                var existingNonFields = isStatic ? existingStaticNonFields : existingProtoNonFields;
+                var existingKind = existingNonFields.get(name) || 0;
+                if (existingKind === true || existingKind === 3 && kind !== 4 || existingKind === 4 && kind !== 3) {
+                    throw new Error("Attempted to decorate a public method/accessor that has the same name as a previously decorated public method/accessor. This is not currently supported by the decorators plugin. Property name was: " + name);
+                } else if (!existingKind && kind > 2) {
+                    existingNonFields.set(name, kind);
+                } else {
+                    existingNonFields.set(name, true);
+                }
+            }
+            applyMemberDec(ret, base, decInfo, name, kind, isStatic, isPrivate, initializers, metadata);
+        }
+        pushInitializers(ret, protoInitializers);
+        pushInitializers(ret, staticInitializers);
+        return ret;
+    }
+    function pushInitializers(ret, initializers) {
+        if (initializers) {
+            ret.push(function(instance) {
+                for(var i = 0; i < initializers.length; i++){
+                    initializers[i].call(instance);
+                }
+                return instance;
+            });
+        }
+    }
+    function applyClassDecs(targetClass, classDecs, metadata) {
+        if (classDecs.length > 0) {
+            var initializers = [];
+            var newClass = targetClass;
+            var name = targetClass.name;
+            for(var i = classDecs.length - 1; i >= 0; i--){
+                var decoratorFinishedRef = {
+                    v: false
+                };
+                try {
+                    var nextNewClass = classDecs[i](newClass, {
+                        kind: "class",
+                        name: name,
+                        addInitializer: createAddInitializerMethod(initializers, decoratorFinishedRef),
+                        metadata
+                    });
+                } finally{
+                    decoratorFinishedRef.v = true;
+                }
+                if (nextNewClass !== undefined) {
+                    assertValidReturnValue(10, nextNewClass);
+                    newClass = nextNewClass;
+                }
+            }
+            return [
+                defineMetadata(newClass, metadata),
+                function() {
+                    for(var i = 0; i < initializers.length; i++){
+                        initializers[i].call(newClass);
+                    }
+                }
+            ];
+        }
+    }
+    function defineMetadata(Class, metadata) {
+        return Object.defineProperty(Class, Symbol.metadata || Symbol.for("Symbol.metadata"), {
+            configurable: true,
+            enumerable: true,
+            value: metadata
+        });
+    }
+    return function applyDecs2203R(targetClass, memberDecs, classDecs, parentClass) {
+        if (parentClass !== void 0) {
+            var parentMetadata = parentClass[Symbol.metadata || Symbol.for("Symbol.metadata")];
+        }
+        var metadata = Object.create(parentMetadata === void 0 ? null : parentMetadata);
+        var e = applyMemberDecs(targetClass, memberDecs, metadata);
+        if (!classDecs.length) defineMetadata(targetClass, metadata);
+        return {
+            e: e,
+            get c () {
+                return applyClassDecs(targetClass, classDecs, metadata);
+            }
+        };
+    };
+}
+function _apply_decs_2203_r(targetClass, memberDecs, classDecs, parentClass) {
+    return (_apply_decs_2203_r = applyDecs2203RFactory())(targetClass, memberDecs, classDecs, parentClass);
+}
+var _initProto;
+import { BlockNumber, CheckpointNumber, EpochNumber } from '@aztec-labs/foundation/branded-types';
+import { assertRequired, compact, pick } from '@aztec-labs/foundation/collection';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { memoize } from '@aztec-labs/foundation/decorators';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { RunningPromise } from '@aztec-labs/foundation/running-promise';
+import { DateProvider, executeTimeout } from '@aztec-labs/foundation/timer';
+import { getLastSiblingPath } from '@aztec-labs/prover-client/helpers';
+import { ChonkCache } from '@aztec-labs/prover-client/orchestrator';
+import { PublicProcessorFactory } from '@aztec-labs/simulator/server';
+import { EventDrivenL2BlockStream, L2TipsMemoryStore } from '@aztec-labs/stdlib/block';
+import { getEpochAtSlot, getProofSubmissionDeadlineEpoch } from '@aztec-labs/stdlib/epoch-helpers';
+import { EpochProvingJobTerminalState, tryStop } from '@aztec-labs/stdlib/interfaces/server';
+import { MerkleTreeId } from '@aztec-labs/stdlib/trees';
+import { getTelemetryClient } from '@aztec-labs/telemetry-client';
+import { uploadEpochProofFailure } from './actions/upload-epoch-proof-failure.js';
+import { CheckpointStore } from './checkpoint-store.js';
+import { ProverNodeJobMetrics, ProverNodeRewardsMetrics } from './metrics.js';
+import { ProofPublishingService } from './proof-publishing-service.js';
+import { SessionManager } from './session-manager.js';
+/**
+ * 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;
+    l2BlockSource;
+    l1ToL2MessageSource;
+    contractDataSource;
+    worldState;
+    p2pClient;
+    rollupContract;
+    l1Metrics;
+    avmSimulator;
+    telemetryClient;
+    delayer;
+    dateProvider;
+    static{
+        ({ e: [_initProto] } = _apply_decs_2203_r(this, [
+            [
+                memoize,
+                2,
+                "getL1Constants"
+            ]
+        ], []));
+    }
+    log;
+    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;
+    /**
+   * Highest checkpoint number whose proving-side handling has completed (or that was legitimately skipped).
+   * The catch-up loop walks from here to each `chain-checkpointed` tip event. Seeded at start() from the last
+   * checkpoint of the last fully-proven epoch (or 0), so a restart reprocesses the partially-proven epoch rather
+   * than trusting a checkpointed tip that may sit ahead of unproven checkpoints. Clamped down on a prune.
+   */ lastProcessedCheckpoint;
+    /** Periodic tick that runs the epoch-expiry sweep during idle periods when no block-stream events arrive. */ expiryTicker;
+    tracer;
+    publishingService;
+    constructor(prover, publisherFactory, l2BlockSource, l1ToL2MessageSource, contractDataSource, worldState, p2pClient, rollupContract, l1Metrics, avmSimulator, config = {}, telemetryClient = getTelemetryClient(), delayer, dateProvider = new DateProvider()){
+        this.prover = prover;
+        this.publisherFactory = publisherFactory;
+        this.l2BlockSource = l2BlockSource;
+        this.l1ToL2MessageSource = l1ToL2MessageSource;
+        this.contractDataSource = contractDataSource;
+        this.worldState = worldState;
+        this.p2pClient = p2pClient;
+        this.rollupContract = rollupContract;
+        this.l1Metrics = l1Metrics;
+        this.avmSimulator = avmSimulator;
+        this.telemetryClient = telemetryClient;
+        this.delayer = delayer;
+        this.dateProvider = dateProvider;
+        this.log = (_initProto(this), createLogger('prover-node'));
+        this.lastProcessedCheckpoint = CheckpointNumber.ZERO;
+        this.config = {
+            proverNodePollingIntervalMs: 1_000,
+            proverNodeMaxPendingJobs: 100,
+            proverNodeMaxParallelBlocksPerEpoch: 0,
+            txGatheringIntervalMs: 1_000,
+            txGatheringBatchSize: 10,
+            txGatheringMaxParallelRequestsPerNode: 100,
+            txGatheringTimeoutMs: 120_000,
+            proverNodeFailedEpochStore: undefined,
+            proverNodeEpochProvingDelayMs: undefined,
+            ...compact(config)
+        };
+        this.validateConfig();
+        const meter = telemetryClient.getMeter('ProverNode');
+        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.avmSimulator, 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,
+            // A checkpoint prover that fails (a sub-tree fault or a prune-induced fork fault) uploads a
+            // post-mortem for its own checkpoint, independently of any session. Fire-and-forget.
+            onFailed: (prover)=>void this.tryUploadCheckpointFailure(prover)
+        }, this.log.getBindings());
+    }
+    getProverId() {
+        return this.prover.getProverId();
+    }
+    getP2P() {
+        return this.p2pClient;
+    }
+    /** 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 the underlying prover instance. */ getProver() {
+        return this.prover;
+    }
+    // ---------------- L2BlockStream handler ----------------
+    async handleBlockStreamEvent(event) {
+        switch(event.type){
+            case 'chain-checkpointed':
+                await this.processCheckpointJump(event.checkpoint.number);
+                break;
+            case 'chain-pruned':
+                await this.handlePruneEvent(event.block);
+                break;
+            case 'chain-proven':
+                this.publishingService?.onChainProven(BlockNumber(event.block.number));
+                break;
+            // The proposed tip drives only the tips store's walk-back history (recorded below); the prover-node
+            // tracks checkpoints, not proposed blocks. `blocks-added` is never emitted in tips-only mode, and
+            // `chain-finalized` carries nothing the prover-node acts on.
+            case 'chain-proposed':
+            case 'chain-finalized':
+            case 'blocks-added':
+                break;
+            default:
+                {
+                    const _ = event;
+                    break;
+                }
+        }
+        // Advance the local tips store only after the proving-side handling (registration / prune) 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
+        await this.tipsStore.handleBlockStreamEvent(event);
+    }
+    /**
+   * Walks every checkpoint between the local cursor and the newly-reported checkpointed tip, registering
+   * each one that belongs to an epoch that can still be proven. The block stream now delivers a single thin
+   * `chain-checkpointed` tip event per pass rather than one fat event per checkpoint, so this drives the
+   * catch-up itself: light metadata first (`getCheckpointsData`) to decide relevance per epoch, then a heavy
+   * `getCheckpoints` fetch only for checkpoints in provable epochs.
+   *
+   * The cursor advances one checkpoint at a time and only after that checkpoint's proving-side handling has
+   * fully succeeded, preserving the A-1041 at-least-once semantics: a mid-jump failure leaves the cursor
+   * behind so the next pass retries from the first checkpoint that did not complete.
+   */ async processCheckpointJump(targetCheckpoint) {
+        if (targetCheckpoint <= this.lastProcessedCheckpoint) {
+            return;
+        }
+        const l1Constants = await this.getL1Constants();
+        // Cap the catch-up at the `(proofSubmissionEpochs + 1) * epochDuration` most recent checkpoints.
+        // When the cursor is much further behind (e.g. resyncing after a long time offline), fetching the whole gap could
+        // load thousands of checkpoints we cannot act on: anything older than the last two epochs is already past
+        // its proof-submission window, so we skip it and jump the cursor forward to the start of the capped range.
+        const maxCheckpoints = (l1Constants.proofSubmissionEpochs + 1) * l1Constants.epochDuration;
+        let from = CheckpointNumber(this.lastProcessedCheckpoint + 1);
+        if (Number(targetCheckpoint - from) + 1 > maxCheckpoints) {
+            const cappedFrom = CheckpointNumber(targetCheckpoint - maxCheckpoints + 1);
+            this.log.warn(`Skipping unprovable checkpoints during catch-up; the prover node is far behind`, {
+                from,
+                cappedFrom,
+                targetCheckpoint,
+                maxCheckpoints
+            });
+            // Advance the cursor past the skipped checkpoints so they are never retried.
+            this.lastProcessedCheckpoint = CheckpointNumber(cappedFrom - 1);
+            from = cappedFrom;
+        }
+        const limit = Number(targetCheckpoint - from) + 1;
+        const metadatas = await this.l2BlockSource.getCheckpointsData({
+            from,
+            limit
+        });
+        // Per-epoch relevance is cached so a multi-checkpoint epoch resolves it once. Skipping is whole-epoch
+        // only: the SessionManager requires an epoch's checkpoints fully covered before it opens a session, so we
+        // never drop an individual checkpoint inside an epoch we will prove.
+        const epochSkippable = new Map();
+        for (const metadata of metadatas){
+            const epochNumber = getEpochAtSlot(metadata.header.slotNumber, l1Constants);
+            let skippable = epochSkippable.get(epochNumber);
+            if (skippable === undefined) {
+                skippable = await this.isEpochFullyProven(epochNumber, l1Constants) || await this.isEpochPastProofSubmissionWindow(epochNumber, l1Constants);
+                epochSkippable.set(epochNumber, skippable);
+            }
+            if (skippable) {
+                this.log.debug(`Skipping checkpoint ${metadata.checkpointNumber} for unprovable epoch ${epochNumber}`);
+            } else {
+                await this.registerCheckpoint(metadata.checkpointNumber, epochNumber);
+            }
+            // Advance only after the checkpoint's handling succeeded (or it was legitimately skipped). registerCheckpoint
+            // throws on failure, which leaves the cursor here for the next pass to retry (A-1041).
+            this.lastProcessedCheckpoint = metadata.checkpointNumber;
+        }
+    }
+    /** Heavy-fetch a single checkpoint, register it with the store, and notify the session manager. */ async registerCheckpoint(checkpointNumber, epochNumber) {
+        const published = await this.l2BlockSource.getCheckpoint({
+            number: checkpointNumber
+        });
+        if (!published) {
+            throw new Error(`Checkpoint ${checkpointNumber} not found in block source during catch-up`);
+        }
+        const checkpoint = published.checkpoint;
+        this.log.info(`New checkpoint ${checkpoint.number} for epoch ${epochNumber}`, {
+            checkpointNumber: checkpoint.number,
+            epochNumber,
+            slotNumber: checkpoint.header.slotNumber
+        });
+        const registerData = await this.collectRegisterData(checkpoint, published.attestations);
+        await this.checkpointStore.addOrUpdate(checkpoint, registerData);
+        await this.sessionManager?.onCheckpointAdded(epochNumber);
+        // Tips-only mode delivers no blocks, so record one witness per checkpointed block: a reorg into the checkpoint's
+        // range then prunes at the true divergence instead of the nearest sparse tip anchor.
+        await this.tipsStore.recordBlockHashes(await Promise.all(checkpoint.blocks.map(async (block)=>({
+                number: block.number,
+                hash: (await block.header.hash()).toString()
+            }))));
+    }
+    /**
+   * 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 lastBlock = checkpoint.blocks.at(-1);
+        // Streaming Inbox: the checkpoint's consumed messages are those between the parent
+        // checkpoint's consumed position and this checkpoint's last block, as a compact leaf-count range. The prover
+        // slices them per block.
+        const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2MessagesBetweenLeafCounts(BigInt(previousBlockHeader.state.l1ToL2MessageTree.nextAvailableLeafIndex), BigInt(lastBlock.header.state.l1ToL2MessageTree.nextAvailableLeafIndex));
+        const previousInboxRollingHash = await this.gatherPreviousInboxRollingHash(checkpoint.number);
+        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,
+            previousInboxRollingHash,
+            previousArchiveSiblingPath
+        };
+    }
+    /**
+   * Sources the inbox rolling hash chain-start for a checkpoint: the previous checkpoint's `inboxRollingHash`, or zero
+   * for the genesis checkpoint. The prover threads this into the base parity circuits so the rebuilt checkpoint header
+   * matches the proposer's.
+   */ async gatherPreviousInboxRollingHash(checkpointNumber) {
+        if (checkpointNumber <= 1) {
+            return Fr.ZERO;
+        }
+        const previous = await this.l2BlockSource.getCheckpoint({
+            number: CheckpointNumber(checkpointNumber - 1)
+        });
+        if (!previous) {
+            throw new Error(`Previous checkpoint ${checkpointNumber - 1} not found when sourcing inbox rolling hash`);
+        }
+        return previous.checkpoint.header.inboxRollingHash;
+    }
+    /**
+   * Marks every prover orphaned by the prune as pruned, clamps the catch-up cursor below the prune target's
+   * checkpoint, and notifies the session manager. Keyed off the prune target block (the highest surviving block)
+   * rather than the source's checkpointed tip, which can sit above the target after a re-checkpoint and would leave
+   * orphaned provers canonical. Throws (rather than warning) if the cursor floor cannot be resolved, so the pass
+   * fails and the prune is retried next iteration.
+   */ async handlePruneEvent(prunedToBlock) {
+        this.log.warn(`Chain pruned to block ${prunedToBlock.number}`, {
+            prunedToBlock
+        });
+        // Resolve the cursor floor BEFORE removing provers: cancelAndRemoveAboveBlock returns only the provers it removed,
+        // so a throw after removing would leave a retry pass with nothing to act on. Resolving first means a throw leaves
+        // everything untouched and the next pass retries the whole handler (the tips cursor only advances on success).
+        let cursorFloor;
+        if (prunedToBlock.number === 0) {
+            cursorFloor = CheckpointNumber.ZERO;
+        } else {
+            const targetData = await this.l2BlockSource.getBlockData({
+                number: prunedToBlock.number
+            });
+            if (targetData === undefined) {
+                throw new Error(`No block data found for prune target block ${prunedToBlock.number}; cannot clamp checkpoint cursor`);
+            }
+            // Clamp to `cpAtTarget - 1`: a mid-checkpoint target leaves that checkpoint partially orphaned and it must be
+            // reprocessed. Over-clamping merely re-registers a checkpoint (at-least-once by design — A-1041); under-clamping
+            // would permanently skip a rebuilt same-number checkpoint.
+            cursorFloor = CheckpointNumber(Math.max(0, Number(targetData.checkpointNumber) - 1));
+        }
+        const affected = this.checkpointStore.cancelAndRemoveAboveBlock(prunedToBlock.number);
+        if (this.lastProcessedCheckpoint > cursorFloor) {
+            this.lastProcessedCheckpoint = cursorFloor;
+        }
+        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);
+    }
+    /**
+   * 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 is at or below it.
+   */ async expireEpoch(epoch) {
+        try {
+            const blocks = await this.l2BlockSource.getBlocks({
+                epoch,
+                onlyCheckpointed: true
+            });
+            if (blocks.length > 0) {
+                this.chonkCache.releaseForBlocks(blocks);
+            }
+        } catch (err) {
+            this.log.warn(`Could not release chonk-cache entries for expired epoch ${epoch}`, err);
+        }
+        this.checkpointStore.reapExpired(epoch);
+    }
+    // ---------------- public API ----------------
+    /**
+   * 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.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 { lastFullyProvenEpoch } = await this.resolveLastFullyProvenEpoch();
+        this.lastExpiredEpoch = lastFullyProvenEpoch;
+        this.lastProcessedCheckpoint = await this.computeStartingCheckpoint(lastFullyProvenEpoch);
+        this.blockStream = new EventDrivenL2BlockStream(this.l2BlockSource, this.tipsStore, this, this.log, {
+            pollIntervalMS: this.config.proverNodePollingIntervalMs,
+            tipsOnly: true
+        });
+        this.blockStream.start();
+        // The periodic ticker is the sole driver of the expiry sweep: it fires every poll interval whether
+        // or not block-stream events arrive, and RunningPromise never overlaps its own runs, so the sweep's
+        // `lastExpiredEpoch` high-water mark advances — and each epoch's post-mortem uploads — exactly once.
+        this.expiryTicker = new RunningPromise(()=>this.checkEpochExpiry(), this.log, this.config.proverNodePollingIntervalMs);
+        this.expiryTicker.start();
+        await this.rewardsMetrics.start();
+        this.l1Metrics.start();
+        this.log.info(`Started Prover Node with prover id ${this.prover.getProverId().toString()}`, this.config);
+    }
+    async stop() {
+        this.log.info('Stopping ProverNode');
+        this.jobMetrics.stopObservingState();
+        await this.blockStream?.stop();
+        await this.expiryTicker?.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.rewardsMetrics.stop();
+        this.l1Metrics.stop();
+        await this.telemetryClient.stop();
+        this.log.info('Stopped ProverNode');
+    }
+    /**
+   * Constructs the session manager. Extracted so subclasses (test harness) can swap the
+   * implementation. Wired to upload a post-mortem when a full session ends in its own genuine failure
+   * (`EpochSession.hasFailed()` — top-tree/submit failed with every prover healthy, so definitively not
+   * a prune). A `stopped` session (a prover under it failed) is not uploaded; it recovers on re-add.
+   */ 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.tryUploadEpochFailure(session.getId(), session.getCheckpoints());
+            },
+            bindings: this.log.getBindings()
+        });
+    }
+    /**
+   * 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);
+    }
+    /**
+   * Installs checkpoint-prover test hooks (e.g. forcing a sub-tree failure) applied to every
+   * CheckpointProver constructed after this call. For the e2e harness only.
+   */ setCheckpointHooks(hooks) {
+        this.checkpointStore.setTestHooks(hooks);
+    }
+    /**
+   * Uploads a post-mortem snapshot for an epoch whose full session failed to prove, built from that
+   * session's checkpoint provers. Fired from the session manager's `onSessionFailed` callback (a
+   * genuine, race-free failure). Exposed as a method so tests can spy on it. No-ops if no failed-epoch
+   * store is configured or the checkpoint set is empty.
+   */ async tryUploadEpochFailure(id, checkpoints) {
+        if (!this.config.proverNodeFailedEpochStore || checkpoints.length === 0) {
+            return undefined;
+        }
+        const data = await SessionManager.buildProvingData(checkpoints);
+        return await uploadEpochProofFailure(this.config.proverNodeFailedEpochStore, // The session's own id; `uploadEpochProofFailure` already prefixes the path with the epoch number.
+        id, data, this.l2BlockSource, this.worldState, assertRequired(pick(this.config, 'l1ChainId', 'rollupVersion', 'dataDirectory')), this.log);
+    }
+    /**
+   * Uploads a post-mortem for a single failed checkpoint prover, built from just that checkpoint's
+   * proving data. Fired (fire-and-forget) from the store's `onFailed` callback for any non-cancel
+   * block-proof failure — a genuine sub-tree fault or a prune-induced fork fault alike. No-ops if no
+   * failed-epoch store is configured, or if the checkpoint is no longer canonical (a prune left nothing
+   * to diagnose). Swallows its own errors so a fire-and-forget caller can't leak.
+   */ async tryUploadCheckpointFailure(prover) {
+        if (!this.config.proverNodeFailedEpochStore) {
+            return undefined;
+        }
+        try {
+            // A prune-induced fork fault and a genuine sub-tree failure are indistinguishable at the moment the
+            // prover rejects (no control-plane cancel has landed yet). But the archiver is the authoritative
+            // committed chain: if this checkpoint was pruned out, its last block is no longer canonical there.
+            // Only upload for a checkpoint that still exists on-chain — a prune leaves nothing to diagnose, and
+            // the snapshot (full world-state + archiver) is expensive to produce and store.
+            if (!await this.isCheckpointCanonical(prover.checkpoint)) {
+                this.log.debug(`Skipping checkpoint-failure upload for ${prover.id}: no longer canonical (pruned)`, {
+                    checkpointNumber: prover.checkpoint.number
+                });
+                return undefined;
+            }
+            const data = await SessionManager.buildProvingData([
+                prover
+            ]);
+            return await uploadEpochProofFailure(this.config.proverNodeFailedEpochStore, // The prover's content-addressed id; the epoch number is already in the upload path.
+            prover.id, data, this.l2BlockSource, this.worldState, assertRequired(pick(this.config, 'l1ChainId', 'rollupVersion', 'dataDirectory')), this.log);
+        } catch (err) {
+            this.log.error(`Error uploading checkpoint failure for ${prover.id}`, err);
+            return undefined;
+        }
+    }
+    // ---------------- helpers ----------------
+    /**
+   * True if the checkpoint still exists on the canonical chain: the archiver holds a block at its last
+   * block's height whose archive root matches. A prune (fork fault) leaves the block missing or replaced,
+   * so this returns false. Protected for direct unit-test access.
+   */ async isCheckpointCanonical(checkpoint) {
+        const lastBlock = checkpoint.blocks.at(-1);
+        if (!lastBlock) {
+            return false;
+        }
+        const onChain = await this.l2BlockSource.getBlock({
+            number: lastBlock.number
+        });
+        return !!onChain && onChain.archive.root.equals(checkpoint.archive.root);
+    }
+    getL1Constants() {
+        return this.l2BlockSource.getL1Constants();
+    }
+    /**
+   * 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;
+        }
+        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);
+    }
+    /**
+   * Resolves the last fully-proven epoch from L1 proven state, used to seed the catch-up cursor (via
+   * `computeStartingCheckpoint`) and `lastExpiredEpoch`. 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 (so a restart reprocesses the partially-proven epoch rather than trusting a stale tip).
+   */ async resolveLastFullyProvenEpoch() {
+        const provenBlockNumber = await this.l2BlockSource.getBlockNumber({
+            tag: 'proven'
+        });
+        if (!provenBlockNumber || provenBlockNumber <= 0) {
+            return {
+                lastFullyProvenEpoch: undefined
+            };
+        }
+        const l1Constants = await this.getL1Constants();
+        const provenHeader = (await this.l2BlockSource.getBlockData({
+            number: BlockNumber(provenBlockNumber)
+        }))?.header;
+        if (!provenHeader) {
+            return {
+                lastFullyProvenEpoch: undefined
+            };
+        }
+        const provenEpoch = getEpochAtSlot(provenHeader.getSlot(), l1Constants);
+        if (await this.isProvenBlockLastOfItsEpoch(BlockNumber(provenBlockNumber), provenEpoch, l1Constants)) {
+            return {
+                lastFullyProvenEpoch: provenEpoch
+            };
+        }
+        const lastFullyProvenEpoch = provenEpoch > 0 ? EpochNumber(provenEpoch - 1) : undefined;
+        return {
+            lastFullyProvenEpoch
+        };
+    }
+    /**
+   * Resolves the catch-up cursor seed: the last checkpoint of the last fully-proven epoch, or 0 if none. Seeding
+   * from a checkpoint (rather than a checkpointed tip) guarantees a restart reprocesses every checkpoint of the
+   * partially-proven epoch, since the checkpointed tip can sit ahead of the last fully-proven checkpoint.
+   */ async computeStartingCheckpoint(lastFullyProvenEpoch) {
+        if (lastFullyProvenEpoch === undefined) {
+            return CheckpointNumber.ZERO;
+        }
+        const checkpoints = await this.l2BlockSource.getCheckpointsData({
+            epoch: lastFullyProvenEpoch
+        });
+        return checkpoints.at(-1)?.checkpointNumber ?? CheckpointNumber.ZERO;
+    }
+    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)) {
+            this.log.warn(`Invalid prover-node config (missing dataDirectory, l1ChainId, or rollupVersion)`, pick(this.config, 'proverNodeFailedEpochStore', 'dataDirectory', 'l1ChainId', 'rollupVersion'));
+            throw new Error('All of dataDirectory, l1ChainId, and rollupVersion are required if proverNodeFailedEpochStore is set.');
+        }
+    }
+}
+// Re-export so handlers can compare states externally.
+export { EpochProvingJobTerminalState };