@aztec/prover-node 0.0.1-commit.3fd054f6 → 0.0.1-commit.431c48d

package/src/job/epoch-session.ts

@@ -0,0 +1,462 @@
+import { BlockNumber, type CheckpointNumber, type EpochNumber, type SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import { sleep } from '@aztec/foundation/sleep';
+import { type DateProvider, Timer } from '@aztec/foundation/timer';
+import type { EpochProverFactory } from '@aztec/prover-client';
+import { TopTreeCancelledError } from '@aztec/prover-client/orchestrator';
+import { type EpochProvingJobState, EpochProvingJobTerminalState } from '@aztec/stdlib/interfaces/server';
+import { Attributes, type Traceable, type Tracer, trackSpan } from '@aztec/telemetry-client';
+
+import * as crypto from 'node:crypto';
+
+import type { ProverNodeJobMetrics } from '../metrics.js';
+import type { ProofPublishingService } from '../proof-publishing-service.js';
+import { CheckpointProver } from './checkpoint-prover.js';
+import { TopTreeJob, type TopTreeJobHooks, 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 function specKey(spec: SessionSpec): string {
+  return `${spec.kind}:${spec.epochNumber}:${spec.fromSlot}-${spec.toSlot}`;
+}
+
+/** 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 class EpochSession implements Traceable {
+  public readonly tracer: Tracer;
+  private readonly uuid: string;
+  private readonly log: Logger;
+  private state: EpochProvingJobState = 'initialized';
+  private deadlineTimeoutHandler: NodeJS.Timeout | undefined;
+
+  private topTreeJob: TopTreeJob | undefined;
+  /** Cancelled top-tree jobs whose teardown is still in flight. Awaited at session stop. */
+  private readonly pendingTopTreeCleanups: TopTreeJob[] = [];
+
+  private readonly completionPromise: Promise<EpochProvingJobState>;
+  private resolveCompletion!: (state: EpochProvingJobState) => void;
+
+  /** Stable reference; never mutated after construction. */
+  private readonly checkpoints: readonly CheckpointProver[];
+
+  constructor(
+    private readonly spec: SessionSpec,
+    checkpoints: readonly CheckpointProver[],
+    private readonly deps: EpochSessionDeps,
+  ) {
+    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),
+    });
+  }
+
+  public getId(): string {
+    return this.uuid;
+  }
+
+  public getSpec(): SessionSpec {
+    return this.spec;
+  }
+
+  public getState(): EpochProvingJobState {
+    return this.state;
+  }
+
+  public getEpochNumber(): EpochNumber {
+    return this.spec.epochNumber;
+  }
+
+  public getKind(): SessionKind {
+    return this.spec.kind;
+  }
+
+  public getDeadline(): Date | undefined {
+    return this.deps.deadline;
+  }
+
+  public getCheckpoints(): readonly CheckpointProver[] {
+    return this.checkpoints;
+  }
+
+  /** Resolves when the session reaches a terminal state. */
+  public whenDone(): Promise<EpochProvingJobState> {
+    return this.completionPromise;
+  }
+
+  /** True if the session is in a terminal state. */
+  public isTerminal(): boolean {
+    return EpochProvingJobTerminalState.includes(this.state);
+  }
+
+  /**
+   * 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.
+   */
+  public hasFailed(): boolean {
+    return this.state === 'failed';
+  }
+
+  /** First block this session proves. */
+  public getStartBlockNumber(): BlockNumber {
+    return BlockNumber(this.checkpoints[0].checkpoint.blocks[0].number);
+  }
+
+  /** Last block this session proves. */
+  public getEndBlockNumber(): BlockNumber {
+    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.
+   */
+  @trackSpan('EpochSession.start', function () {
+    return { [Attributes.EPOCH_NUMBER]: this.spec.epochNumber };
+  })
+  public async start(): Promise<EpochProvingJobState> {
+    try {
+      await this.run();
+    } catch (err) {
+      this.log.error(`Error in EpochSession ${this.uuid}`, err, {
+        uuid: this.uuid,
+        ...this.spec,
+      });
+      // Distinguish the two ways an attempt can fault:
+      //  - a checkpoint prover in the set has failed OR was cancelled (a sub-tree fault, a prune-induced
+      //    fork fault, or a control-plane cancel that reached this catch before the reconcile marked the
+      //    session 'cancelled'): end in the non-declaring terminal 'stopped'. This is not the session's own
+      //    failure and may be a prune, so the reconciler does not upload it; a re-add installs a fresh prover.
+      //  - no prover failed or was cancelled, yet top-tree proving or L1 submission failed: this is the
+      //    session's own, genuine failure — and, because every prover is healthy and un-cancelled, it is
+      //    definitively NOT a prune. End in terminal 'failed' so the reconciler retains it (no pointless
+      //    re-prove) and uploads a race-free post-mortem.
+      if (!this.isTerminal()) {
+        this.state = this.checkpoints.some(c => c.isFailed() || c.isCancelled()) ? 'stopped' : '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.
+   */
+  public async cancel(reason = 'cancelled', { abortJobs = true }: { abortJobs?: boolean } = {}): Promise<void> {
+    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;
+      // On a clean shutdown we leave the in-flight broker jobs alone so a restart can reuse them;
+      // other cancellations (reorg, supersede, deadline) abort them since their inputs are stale.
+      job.cancel(abortJobs);
+      this.pendingTopTreeCleanups.push(job);
+    }
+    await this.teardownTopTreeIfNeeded();
+    this.resolveCompletion(this.state);
+  }
+
+  private async run(): Promise<void> {
+    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: TopTreeProof;
+    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);
+  }
+
+  private async submitProof(
+    proof: TopTreeProof,
+    fromCheckpoint: CheckpointNumber,
+    toCheckpoint: CheckpointNumber,
+    checkpointCount: number,
+    timer: Timer,
+  ): Promise<void> {
+    // Attestations come from the highest-numbered registered checkpoint — that's the one
+    // whose attestations the L1 contract checks for the proven range.
+    const lastCheckpoint = this.checkpoints[this.checkpoints.length - 1];
+    const attestations = lastCheckpoint.attestations.map(a => a.toViem());
+    const epochSizeBlocks = this.checkpoints.reduce((acc, c) => acc + c.checkpoint.blocks.length, 0);
+    const epochSizeTxs = this.checkpoints.reduce(
+      (acc, c) => acc + c.checkpoint.blocks.reduce((bAcc, block) => bAcc + block.body.txEffects.length, 0),
+      0,
+    );
+
+    // Reflect the publish phase. Guard against a terminal state set concurrently by cancel() — the
+    // post-submit isTerminal() check below relies on cancel still winning.
+    if (!this.isTerminal()) {
+      this.state = 'publishing-proof';
+    }
+
+    const outcome = await this.deps.publishingService.submit({
+      id: this.uuid,
+      epoch: this.spec.epochNumber,
+      kind: this.spec.kind,
+      startBlock: this.getStartBlockNumber(),
+      endBlock: this.getEndBlockNumber(),
+      deadline: this.deps.deadline,
+      fromCheckpoint,
+      toCheckpoint,
+      publicInputs: proof.publicInputs,
+      proof: proof.proof,
+      batchedBlobInputs: proof.batchedBlobInputs,
+      attestations,
+      headers: this.checkpoints.map(c => c.checkpoint.header),
+    });
+
+    if (this.isTerminal()) {
+      // cancel() already set the terminal state — don't clobber it.
+      return;
+    }
+
+    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(), 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');
+    }
+  }
+
+  private async teardownTopTreeIfNeeded(): Promise<void> {
+    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;
+    }
+  }
+
+  private scheduleDeadlineStop(): void {
+    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.
+   */
+  protected async handleDeadline(): Promise<void> {
+    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';
+    }
+  }
+
+  private toTopTreeHooks(): TopTreeJobHooks {
+    const hooks = this.deps.hooks;
+    return {
+      // `beforeProve` fires once the sub-tree (checkpoint block) proofs are ready and the root prove is
+      // about to start — the boundary between `awaiting-checkpoints` and proving the top tree. Don't
+      // clobber a terminal state set concurrently by cancel().
+      beforeProve: async () => {
+        if (!this.isTerminal()) {
+          this.state = 'awaiting-root';
+        }
+        await hooks?.beforeTopTreeProve?.();
+      },
+      afterProve: hooks?.afterTopTreeProve,
+      proveOverride: hooks?.topTreeProveOverride,
+    };
+  }
+}

package/src/job/top-tree-job.ts

@@ -0,0 +1,227 @@
+import type { BatchedBlob } from '@aztec/blob-lib/types';
+import type { CheckpointNumber, EpochNumber } from '@aztec/foundation/branded-types';
+import type { Logger } from '@aztec/foundation/log';
+import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
+import { Timer } from '@aztec/foundation/timer';
+import type { EpochProverFactory } from '@aztec/prover-client';
+import { buildFinalBlobChallenges } from '@aztec/prover-client/helpers';
+import {
+  type CheckpointTopTreeData,
+  TopTreeCancelledError,
+  type TopTreeOrchestrator,
+} from '@aztec/prover-client/orchestrator';
+import type { Proof } from '@aztec/stdlib/proofs';
+import type { RootRollupPublicInputs } from '@aztec/stdlib/rollup';
+
+import type { ProverNodeJobMetrics } from '../metrics.js';
+import type { CheckpointProver } from './checkpoint-prover.js';
+
+/** Result of a successful top-tree run. */
+export type TopTreeProof = {
+  publicInputs: RootRollupPublicInputs;
+  proof: Proof;
+  batchedBlobInputs: BatchedBlob;
+};
+
+/**
+ * Hooks for tests to interpose around the underlying `topTree.prove(...)` call without
+ * monkey-patching the orchestrator.
+ */
+export type TopTreeJobHooks = {
+  /** Called immediately before the top tree's `prove` runs. */
+  beforeProve?: () => Promise<void> | void;
+  /** Called after `prove` returns successfully (not on failure / cancellation). */
+  afterProve?: () => Promise<void> | void;
+  /**
+   * If set, called instead of running the underlying prove. Receives a thunk that
+   * runs the real call. Lets tests substitute a synthetic proof or delay/throw without
+   * re-implementing the rest of the finalize flow.
+   */
+  proveOverride?: (defaultProve: () => Promise<TopTreeProof>) => Promise<TopTreeProof>;
+};
+
+/**
+ * Self-contained top-tree job. Constructed from a snapshot of `CheckpointProver`s; runs
+ * `topTree.prove(...)` against their pending `blockProofs` promises and exposes the
+ * final epoch proof via `result`.
+ *
+ */
+export class TopTreeJob {
+  /** Resolves with the final proof on success; rejects on cancellation or any prove error. */
+  readonly result: PromiseWithResolvers<TopTreeProof> = promiseWithResolvers();
+
+  /** Snapshot of checkpoint jobs the top tree is built from, in checkpoint-number order. */
+  readonly snapshot: readonly CheckpointProver[];
+
+  private readonly topTree: TopTreeOrchestrator;
+  private readonly fromCheckpoint: CheckpointNumber;
+  private readonly toCheckpoint: CheckpointNumber;
+  private cancelled = false;
+  /** Tracks the cancel-driven background teardown so `whenDone()` can await it. */
+  private cancelPromise?: Promise<void>;
+  private readonly executionTimer = new Timer();
+
+  constructor(
+    private readonly epochNumber: EpochNumber,
+    snapshot: readonly CheckpointProver[],
+    private readonly deps: {
+      proverFactory: EpochProverFactory;
+      metrics: ProverNodeJobMetrics;
+      log: Logger;
+      hooks?: TopTreeJobHooks;
+    },
+  ) {
+    if (snapshot.length === 0) {
+      throw new Error(`Cannot construct TopTreeJob for epoch ${epochNumber}: empty snapshot`);
+    }
+    for (let i = 1; i < snapshot.length; i++) {
+      const prev = snapshot[i - 1].checkpoint.number;
+      const curr = snapshot[i].checkpoint.number;
+      if (curr !== prev + 1) {
+        throw new Error(
+          `Cannot construct TopTreeJob for epoch ${epochNumber}: checkpoint numbers must be contiguous, got gap between ${prev} and ${curr}`,
+        );
+      }
+    }
+    this.snapshot = snapshot;
+    this.fromCheckpoint = snapshot[0].checkpoint.number;
+    this.toCheckpoint = snapshot[snapshot.length - 1].checkpoint.number;
+    this.topTree = deps.proverFactory.createTopTreeOrchestrator();
+    deps.log.info(
+      `Created TopTreeJob for epoch ${epochNumber} covering checkpoints ${this.fromCheckpoint}..${this.toCheckpoint}`,
+      {
+        epochNumber,
+        fromCheckpoint: this.fromCheckpoint,
+        toCheckpoint: this.toCheckpoint,
+        checkpointCount: snapshot.length,
+      },
+    );
+    // Mark the result's rejection branch as observed so a cancellation before any
+    // consumer awaits does not surface as unhandled.
+    this.result.promise.catch(() => {});
+  }
+
+  /** Range covered by this attempt — useful for logging and L1 submission. */
+  public getRange(): { fromCheckpoint: CheckpointNumber; toCheckpoint: CheckpointNumber; count: number } {
+    return { fromCheckpoint: this.fromCheckpoint, toCheckpoint: this.toCheckpoint, count: this.snapshot.length };
+  }
+
+  public isCancelled(): boolean {
+    return this.cancelled;
+  }
+
+  /** Wall-time since construction — used by the owning job for metrics. */
+  public elapsedMs(): number {
+    return this.executionTimer.ms();
+  }
+
+  /** Kicks off the prove. Returns the result promise (also available as `result.promise`). */
+  public start(): Promise<TopTreeProof> {
+    void this.run();
+    return this.result.promise;
+  }
+
+  /**
+   * Cancels the in-flight prove. Idempotent. Rejects the result promise with
+   * `TopTreeCancelledError`, then kicks off the underlying orchestrator's teardown
+   * in the background so callers don't block on it. The teardown promise is exposed
+   * via `whenDone()` — the parent collects the cancelled job and awaits all
+   * pending top-tree teardowns at the end of the epoch.
+   */
+  public cancel(abortJobs = true): void {
+    if (this.cancelled) {
+      return;
+    }
+    this.cancelled = true;
+    this.deps.log.info(
+      `Cancelling TopTreeJob for epoch ${this.epochNumber} (checkpoints ${this.fromCheckpoint}..${this.toCheckpoint})`,
+      {
+        epochNumber: this.epochNumber,
+        fromCheckpoint: this.fromCheckpoint,
+        toCheckpoint: this.toCheckpoint,
+        elapsedMs: this.executionTimer.ms(),
+      },
+    );
+    this.result.reject(new TopTreeCancelledError());
+    // Fire and forget: parent awaits the cancel-driven teardown via whenDone(); the
+    // chained .catch swallows rejections so the unawaited promise doesn't surface
+    // as an unhandled rejection.
+    this.cancelPromise = this.runCancel(abortJobs).catch(() => {});
+  }
+
+  /** Resolves once the cancel-driven teardown of the underlying orchestrator has unwound. */
+  public async whenDone(): Promise<void> {
+    if (this.cancelPromise) {
+      await this.cancelPromise;
+    }
+  }
+
+  private async runCancel(abortJobs: boolean): Promise<void> {
+    try {
+      this.topTree.cancel({ abortJobs });
+    } catch (err) {
+      this.deps.log.error('Error cancelling top tree', err);
+    }
+    try {
+      await this.topTree.stop();
+    } catch (err) {
+      this.deps.log.error('Error stopping top tree', err);
+    }
+  }
+
+  private async run() {
+    try {
+      const blobTimer = new Timer();
+      const blobFieldsPerCheckpoint = this.snapshot.map(j => j.checkpoint.toBlobFields());
+      const finalBlobBatchingChallenges = await buildFinalBlobChallenges(blobFieldsPerCheckpoint);
+      this.deps.metrics.recordBlobProcessing(blobTimer.ms());
+      this.deps.log.verbose(
+        `Built final blob batching challenges for epoch ${this.epochNumber} in ${blobTimer.ms()}ms`,
+        {
+          epochNumber: this.epochNumber,
+          checkpointCount: this.snapshot.length,
+          durationMs: blobTimer.ms(),
+        },
+      );
+
+      const checkpointData: CheckpointTopTreeData[] = this.snapshot.map(j => ({
+        blockProofs: j.whenBlockProofsReady(),
+        l2ToL1MsgsPerBlock: j.checkpoint.blocks.map(b => b.body.txEffects.map(tx => tx.l2ToL1Msgs)),
+        blobFields: j.checkpoint.toBlobFields(),
+        previousBlockHeader: j.previousBlockHeader,
+        previousArchiveSiblingPath: j.previousArchiveSiblingPath,
+      }));
+
+      const defaultProve = (): Promise<TopTreeProof> =>
+        this.topTree.prove(this.epochNumber, this.snapshot.length, finalBlobBatchingChallenges, checkpointData);
+
+      await this.deps.hooks?.beforeProve?.();
+      const proveTimer = new Timer();
+      this.deps.log.info(
+        `Starting top-tree prove for epoch ${this.epochNumber} (checkpoints ${this.fromCheckpoint}..${this.toCheckpoint})`,
+        {
+          epochNumber: this.epochNumber,
+          fromCheckpoint: this.fromCheckpoint,
+          toCheckpoint: this.toCheckpoint,
+          checkpointCount: this.snapshot.length,
+        },
+      );
+      const proof = await (this.deps.hooks?.proveOverride
+        ? this.deps.hooks.proveOverride(defaultProve)
+        : defaultProve());
+      await this.deps.hooks?.afterProve?.();
+      this.deps.log.info(`Top-tree prove succeeded for epoch ${this.epochNumber} in ${proveTimer.ms()}ms`, {
+        epochNumber: this.epochNumber,
+        fromCheckpoint: this.fromCheckpoint,
+        toCheckpoint: this.toCheckpoint,
+        durationMs: proveTimer.ms(),
+        totalElapsedMs: this.executionTimer.ms(),
+      });
+
+      this.result.resolve(proof);
+    } catch (err) {
+      // Cancel paths surface as TopTreeCancelledError; everything else propagates as-is.
+      this.result.reject(err);
+    }
+  }
+}