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

package/dest/job/epoch-session.js

@@ -0,0 +1,709 @@
+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 _dec, _initProto;
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { createLogger } from '@aztec/foundation/log';
+import { sleep } from '@aztec/foundation/sleep';
+import { Timer } from '@aztec/foundation/timer';
+import { TopTreeCancelledError } from '@aztec/prover-client/orchestrator';
+import { EpochProvingJobTerminalState } from '@aztec/stdlib/interfaces/server';
+import { Attributes, trackSpan } from '@aztec/telemetry-client';
+import * as crypto from 'node:crypto';
+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.spec.epochNumber
+    };
+});
+/**
+ * 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 → 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,
+                "start"
+            ]
+        ], []));
+    }
+    tracer;
+    uuid;
+    log;
+    state;
+    deadlineTimeoutHandler;
+    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');
+        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-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)
+        });
+    }
+    getId() {
+        return this.uuid;
+    }
+    getSpec() {
+        return this.spec;
+    }
+    getState() {
+        return this.state;
+    }
+    getEpochNumber() {
+        return this.spec.epochNumber;
+    }
+    getKind() {
+        return this.spec.kind;
+    }
+    getDeadline() {
+        return this.deps.deadline;
+    }
+    getCheckpoints() {
+        return this.checkpoints;
+    }
+    /** Resolves when the session reaches a terminal state. */ whenDone() {
+        return this.completionPromise;
+    }
+    /** True if the session is in a terminal state. */ isTerminal() {
+        return EpochProvingJobTerminalState.includes(this.state);
+    }
+    /** First block this session proves. */ getStartBlockNumber() {
+        return BlockNumber(this.checkpoints[0].checkpoint.blocks[0].number);
+    }
+    /** 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);
+    }
+    /**
+   * 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 {
+            await this.run();
+        } catch (err) {
+            this.log.error(`Error in EpochSession ${this.uuid}`, err, {
+                uuid: this.uuid,
+                ...this.spec
+            });
+            if (!this.isTerminal()) {
+                this.state = 'failed';
+            }
+        } finally{
+            clearTimeout(this.deadlineTimeoutHandler);
+            await this.teardownTopTreeIfNeeded();
+            this.resolveCompletion(this.state);
+        }
+        return this.state;
+    }
+    /**
+   * 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') {
+        if (this.isTerminal()) {
+            return;
+        }
+        this.log.info(`Cancelling EpochSession ${this.uuid}: ${reason}`, {
+            uuid: this.uuid,
+            ...this.spec,
+            previousState: this.state,
+            reason
+        });
+        this.state = 'cancelled';
+        try {
+            this.deps.publishingService.withdraw(this.uuid);
+        } catch (err) {
+            this.log.error(`Error withdrawing candidate from publishing service`, err);
+        }
+        if (this.topTreeJob && !this.topTreeJob.isCancelled()) {
+            const job = this.topTreeJob;
+            this.topTreeJob = undefined;
+            job.cancel();
+            this.pendingTopTreeCleanups.push(job);
+        }
+        await this.teardownTopTreeIfNeeded();
+        this.resolveCompletion(this.state);
+    }
+    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;
+            }
+        }
+        // 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,
+                    ...this.spec
+                });
+                return;
+            }
+            throw err;
+        }
+        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);
+        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
+        });
+        if (this.isTerminal()) {
+            // cancel() already set the terminal state — don't clobber it.
+            return;
+        }
+        switch(outcome){
+            case 'published':
+                this.log.info(`Submitted proof for epoch ${this.spec.epochNumber} (checkpoints ${fromCheckpoint}..${toCheckpoint})`, {
+                    uuid: this.uuid,
+                    ...this.spec
+                });
+                this.state = 'completed';
+                this.deps.metrics.recordProvingJob(timer.ms(), 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');
+        }
+    }
+    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;
+        }
+    }
+    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);
+    }
+    /**
+   * 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;
+        }
+        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';
+        }
+    }
+    toTopTreeHooks() {
+        const hooks = this.deps.hooks;
+        if (!hooks?.beforeTopTreeProve && !hooks?.afterTopTreeProve && !hooks?.topTreeProveOverride) {
+            return undefined;
+        }
+        return {
+            beforeProve: hooks.beforeTopTreeProve,
+            afterProve: hooks.afterTopTreeProve,
+            proveOverride: hooks.topTreeProveOverride
+        };
+    }
+}