@aztec/prover-client 0.0.1-commit.b33fc05d0 → 0.0.1-commit.b3d3157a

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

@@ -0,0 +1,314 @@
+import { BatchedBlobAccumulator, type FinalBlobBatchingChallenges } from '@aztec/blob-lib';
+import type { BatchedBlob } from '@aztec/blob-lib/types';
+import {
+  type ARCHIVE_HEIGHT,
+  BLOBS_PER_CHECKPOINT,
+  FIELDS_PER_BLOB,
+  type NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH,
+  OUT_HASH_TREE_HEIGHT,
+} from '@aztec/constants';
+import type { EpochNumber } from '@aztec/foundation/branded-types';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { BLS12Point } from '@aztec/foundation/curves/bls12';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { LoggerBindings } from '@aztec/foundation/log';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+import type { Tuple } from '@aztec/foundation/serialize';
+import { MerkleTreeCalculator, shaMerkleHash } from '@aztec/foundation/trees';
+import type { EthAddress } from '@aztec/stdlib/block';
+import type { PublicInputsAndRecursiveProof, ServerCircuitProver } from '@aztec/stdlib/interfaces/server';
+import { computeCheckpointOutHash } from '@aztec/stdlib/messaging';
+import type { Proof } from '@aztec/stdlib/proofs';
+import {
+  type BlockRollupPublicInputs,
+  CheckpointRootRollupHints,
+  CheckpointRootRollupPrivateInputs,
+  CheckpointRootSingleBlockRollupPrivateInputs,
+  type RootRollupPublicInputs,
+} from '@aztec/stdlib/rollup';
+import { AppendOnlyTreeSnapshot } from '@aztec/stdlib/trees';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import { buildBlobHints, toProofData } from './block-building-helpers.js';
+import { TopTreeProvingScheduler } from './top-tree-proving-scheduler.js';
+import { TopTreeProvingState } from './top-tree-proving-state.js';
+
+/** Per-checkpoint data fed into the top tree. */
+export type CheckpointTopTreeData = {
+  /**
+   * Block-rollup proof outputs from the checkpoint's sub-tree. Passed as a Promise so the
+   * top tree can start (compute hints, pipeline merges) while sub-trees are still proving.
+   * The promise resolves to 1 entry for a single-block checkpoint, 2 for multi-block.
+   */
+  blockProofs: Promise<
+    PublicInputsAndRecursiveProof<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>[]
+  >;
+  /** L2-to-L1 messages per block in the checkpoint, used to compute the out hash. */
+  l2ToL1MsgsPerBlock: Fr[][][];
+  /** Blob fields encoding the checkpoint's tx effects, used to compute the blob accumulator. */
+  blobFields: Fr[];
+  /** Header of the last block in the previous checkpoint (or the epoch's predecessor for index 0). */
+  previousBlockHeader: BlockHeader;
+  /** Sibling path of the archive tree before any block in this checkpoint landed. */
+  previousArchiveSiblingPath: Tuple<Fr, typeof ARCHIVE_HEIGHT>;
+};
+
+/** Result of proving the top tree. */
+export type TopTreeResult = {
+  publicInputs: RootRollupPublicInputs;
+  proof: Proof;
+  batchedBlobInputs: BatchedBlob;
+};
+
+/**
+ * Sentinel thrown by `cancel` so callers can distinguish reorg-driven cancellation from
+ * a genuine proving failure (and choose to rebuild + retry instead of failing the epoch).
+ */
+export class TopTreeCancelledError extends Error {
+  constructor(reason = 'Top-tree proving cancelled') {
+    super(reason);
+    this.name = 'TopTreeCancelledError';
+  }
+}
+
+type OutHashHint = {
+  treeSnapshot: AppendOnlyTreeSnapshot;
+  siblingPath: Tuple<Fr, typeof OUT_HASH_TREE_HEIGHT>;
+};
+
+/**
+ * Drives proving from checkpoint root rollups through the epoch root rollup. Owns no
+ * world-state forks or tx processing — every input is supplied by the caller.
+ *
+ * Pipelined start: `prove()` does not wait for block-level proving. It pre-computes the
+ * out-hash and blob-accumulator hint chains immediately from archiver-derivable data,
+ * and each checkpoint's root rollup fires the moment its sub-tree's `blockProofs`
+ * promise resolves. Later checkpoints can still be block-level proving in parallel.
+ */
+export class TopTreeOrchestrator extends TopTreeProvingScheduler {
+  private state: TopTreeProvingState | undefined;
+  private cancelled = false;
+
+  constructor(
+    prover: ServerCircuitProver,
+    private readonly proverId: EthAddress,
+    enqueueConcurrency: number,
+    _telemetryClient: TelemetryClient = getTelemetryClient(),
+    bindings?: LoggerBindings,
+  ) {
+    super(prover, enqueueConcurrency, 'prover-client:top-tree-orchestrator', bindings);
+  }
+
+  public getProverId(): EthAddress {
+    return this.proverId;
+  }
+
+  /**
+   * Proves the top tree from per-checkpoint data and pending block-proofs promises.
+   * Resolves with the final epoch proof, or rejects with `TopTreeCancelledError` if
+   * `cancel()` is invoked, or any other error if a circuit fails.
+   */
+  public async prove(
+    epochNumber: EpochNumber,
+    totalNumCheckpoints: number,
+    finalBlobBatchingChallenges: FinalBlobBatchingChallenges,
+    checkpointData: CheckpointTopTreeData[],
+  ): Promise<TopTreeResult> {
+    if (checkpointData.length !== totalNumCheckpoints) {
+      throw new Error(
+        `checkpointData length (${checkpointData.length}) does not match totalNumCheckpoints (${totalNumCheckpoints}).`,
+      );
+    }
+    if (this.state) {
+      throw new Error('TopTreeOrchestrator.prove called twice; construct a new orchestrator per epoch.');
+    }
+    // If cancel() was already called before prove() ran (e.g. a removeCheckpoint that
+    // landed while the caller was still preparing inputs), short-circuit the whole
+    // proving path. Without this, prove() would build its state, the per-checkpoint
+    // .then handlers would all bail on `this.cancelled`, and the completion promise
+    // would never resolve — prove() would hang forever.
+    if (this.cancelled) {
+      throw new TopTreeCancelledError();
+    }
+
+    const { promise: completionPromise, resolve, reject } = promiseWithResolvers<void>();
+    // The completion promise is awaited inside the try/catch below. Attach a no-op catch
+    // here as well so any spurious unhandled-rejection detection during cancellation
+    // (where reject() can fire synchronously before the await microtask installs a handler)
+    // is silenced.
+    completionPromise.catch(() => {});
+    const startBlobAccumulator = BatchedBlobAccumulator.newWithChallenges(finalBlobBatchingChallenges);
+
+    this.state = new TopTreeProvingState(
+      epochNumber,
+      totalNumCheckpoints,
+      finalBlobBatchingChallenges,
+      startBlobAccumulator,
+      resolve,
+      reason => reject(this.cancelled ? new TopTreeCancelledError(reason) : new Error(reason)),
+    );
+
+    // Compute the full out-hash hint chain and per-checkpoint start blob accumulators
+    // synchronously from archiver data. No proving required.
+    const outHashHints = await this.computeOutHashHints(checkpointData);
+    const checkpointStartBlobs: BatchedBlobAccumulator[] = [];
+    let runningBlobAccumulator = startBlobAccumulator;
+    for (const cd of checkpointData) {
+      checkpointStartBlobs.push(runningBlobAccumulator);
+      runningBlobAccumulator = await runningBlobAccumulator.accumulateFields(cd.blobFields);
+    }
+    this.state.setEndBlobAccumulator(runningBlobAccumulator);
+
+    // For each checkpoint, await its block proofs promise then enqueue the checkpoint root.
+    // Each await runs independently — checkpoints whose sub-trees finish first start their
+    // root proofs first, in parallel with later checkpoints' block-level proving.
+    for (let i = 0; i < checkpointData.length; i++) {
+      const cd = checkpointData[i];
+      const checkpointIndex = i;
+      void cd.blockProofs.then(
+        blockProofs => {
+          if (this.cancelled || !this.state?.verifyState()) {
+            return;
+          }
+          this.enqueueCheckpointRoot(
+            this.state,
+            checkpointIndex,
+            blockProofs,
+            cd,
+            outHashHints[i],
+            checkpointStartBlobs[i],
+          );
+        },
+        err => {
+          if (this.cancelled) {
+            return;
+          }
+          this.state?.reject(`Sub-tree for checkpoint ${i} failed: ${err}`);
+        },
+      );
+    }
+
+    try {
+      await completionPromise;
+      await this.state.finalizeBatchedBlob();
+      return this.state.getEpochProofResult();
+    } catch (err: any) {
+      if (this.cancelled) {
+        throw new TopTreeCancelledError();
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Cancels in-flight proving. If `abortJobs` is true, each pending broker job is aborted
+   * (used on reorg, when the surviving checkpoint set differs and the in-flight jobs'
+   * inputs are no longer valid). On shutdown the caller passes `false` so jobs remain in
+   * the broker queue for reuse on restart.
+   */
+  public cancel({ abortJobs }: { abortJobs: boolean }) {
+    this.cancelled = true;
+    this.resetSchedulerState(abortJobs);
+    this.state?.cancel();
+  }
+
+  /** Standard shutdown — preserve the broker queue (`abortJobs: false`). */
+  protected override cancelInternal(): void {
+    this.cancel({ abortJobs: false });
+  }
+
+  // --- internal: per-checkpoint enqueue path ---
+
+  protected override onRootRollupComplete(state: TopTreeProvingState) {
+    state.resolve();
+  }
+
+  private enqueueCheckpointRoot(
+    state: TopTreeProvingState,
+    checkpointIndex: number,
+    blockProofs: PublicInputsAndRecursiveProof<
+      BlockRollupPublicInputs,
+      typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+    >[],
+    cd: CheckpointTopTreeData,
+    outHashHint: OutHashHint,
+    startBlobAccumulator: BatchedBlobAccumulator,
+  ) {
+    void this.buildCheckpointRootInputs(blockProofs, cd, outHashHint, startBlobAccumulator).then(inputs => {
+      this.deferredProving(
+        state,
+        signal => {
+          if (inputs instanceof CheckpointRootSingleBlockRollupPrivateInputs) {
+            return this.prover.getCheckpointRootSingleBlockRollupProof(inputs, signal, state.epochNumber);
+          }
+          return this.prover.getCheckpointRootRollupProof(inputs, signal, state.epochNumber);
+        },
+        result => {
+          this.logger.debug(`Completed checkpoint root proof for checkpoint ${checkpointIndex}`);
+          const leafLocation = state.setCheckpointRootRollupProof(checkpointIndex, result);
+          if (state.totalNumCheckpoints === 1) {
+            this.enqueueEpochPadding(state);
+          } else {
+            this.checkAndEnqueueNextCheckpointMergeRollup(state, leafLocation);
+          }
+        },
+      );
+    });
+  }
+
+  private async buildCheckpointRootInputs(
+    blockProofs: PublicInputsAndRecursiveProof<
+      BlockRollupPublicInputs,
+      typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+    >[],
+    cd: CheckpointTopTreeData,
+    outHashHint: OutHashHint,
+    startBlobAccumulator: BatchedBlobAccumulator,
+  ) {
+    const { blobCommitments, blobsHash } = await buildBlobHints(cd.blobFields);
+
+    const hints = CheckpointRootRollupHints.from({
+      previousBlockHeader: cd.previousBlockHeader,
+      previousArchiveSiblingPath: cd.previousArchiveSiblingPath,
+      previousOutHash: outHashHint.treeSnapshot,
+      newOutHashSiblingPath: outHashHint.siblingPath,
+      startBlobAccumulator: startBlobAccumulator.toBlobAccumulator(),
+      finalBlobChallenges: this.state!.finalBlobBatchingChallenges,
+      blobFields: padArrayEnd(cd.blobFields, Fr.ZERO, FIELDS_PER_BLOB * BLOBS_PER_CHECKPOINT),
+      blobCommitments: padArrayEnd(blobCommitments, BLS12Point.ZERO, BLOBS_PER_CHECKPOINT),
+      blobsHash,
+    });
+
+    const proofDatas = blockProofs.map(p => toProofData(p));
+    return proofDatas.length === 1
+      ? new CheckpointRootSingleBlockRollupPrivateInputs(proofDatas[0], hints)
+      : new CheckpointRootRollupPrivateInputs([proofDatas[0], proofDatas[1]], hints);
+  }
+
+  private async computeOutHashHints(checkpointData: CheckpointTopTreeData[]): Promise<OutHashHint[]> {
+    const treeCalculator = await MerkleTreeCalculator.create(OUT_HASH_TREE_HEIGHT, undefined, (left, right) =>
+      Promise.resolve(shaMerkleHash(left, right)),
+    );
+
+    const computeHint = async (leaves: Fr[]): Promise<OutHashHint> => {
+      const tree = await treeCalculator.computeTree(leaves.map(l => l.toBuffer()));
+      const nextAvailableLeafIndex = leaves.length;
+      return {
+        treeSnapshot: new AppendOnlyTreeSnapshot(Fr.fromBuffer(tree.root), nextAvailableLeafIndex),
+        siblingPath: tree.getSiblingPath(nextAvailableLeafIndex).map(Fr.fromBuffer) as Tuple<
+          Fr,
+          typeof OUT_HASH_TREE_HEIGHT
+        >,
+      };
+    };
+
+    const hints: OutHashHint[] = [];
+    const outHashes: Fr[] = [];
+    for (const cd of checkpointData) {
+      hints.push(await computeHint(outHashes));
+      outHashes.push(computeCheckpointOutHash(cd.l2ToL1MsgsPerBlock));
+    }
+    return hints;
+  }
+}

package/src/orchestrator/top-tree-proving-scheduler.ts

@@ -0,0 +1,154 @@
+import type { NESTED_RECURSIVE_PROOF_LENGTH, NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH } from '@aztec/constants';
+import type { EpochNumber } from '@aztec/foundation/branded-types';
+import type { LoggerBindings } from '@aztec/foundation/log';
+import type { TreeNodeLocation } from '@aztec/foundation/trees';
+import type { PublicInputsAndRecursiveProof, ServerCircuitProver } from '@aztec/stdlib/interfaces/server';
+import type {
+  CheckpointMergeRollupPrivateInputs,
+  CheckpointPaddingRollupPrivateInputs,
+  CheckpointRollupPublicInputs,
+  RootRollupPrivateInputs,
+  RootRollupPublicInputs,
+} from '@aztec/stdlib/rollup';
+
+import { ProvingScheduler, type ProvingStateLike } from './proving-scheduler.js';
+
+type CheckpointRollupProof = PublicInputsAndRecursiveProof<
+  CheckpointRollupPublicInputs,
+  typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+>;
+
+type RootRollupProof = PublicInputsAndRecursiveProof<RootRollupPublicInputs, typeof NESTED_RECURSIVE_PROOF_LENGTH>;
+
+/**
+ * State interface required by the top-tree proving drivers (checkpoint-merge → padding →
+ * root-rollup). Both `EpochProvingState` and `TopTreeProvingState` satisfy it structurally;
+ * the per-checkpoint state in `EpochProvingState` (block/tx proving, world-state forks)
+ * is owned outside this surface.
+ */
+export interface TopTreeStateLike extends ProvingStateLike {
+  readonly epochNumber: EpochNumber;
+  readonly totalNumCheckpoints: number;
+
+  tryStartProvingCheckpointMerge(location: TreeNodeLocation): boolean;
+  setCheckpointMergeRollupProof(location: TreeNodeLocation, provingOutput: CheckpointRollupProof): void;
+  isReadyForCheckpointMerge(location: TreeNodeLocation): boolean;
+  getParentLocation(location: TreeNodeLocation): TreeNodeLocation;
+  getCheckpointMergeRollupInputs(location: TreeNodeLocation): CheckpointMergeRollupPrivateInputs;
+
+  tryStartProvingPaddingCheckpoint(): boolean;
+  setCheckpointPaddingProof(provingOutput: CheckpointRollupProof): void;
+  getPaddingCheckpointInputs(): CheckpointPaddingRollupPrivateInputs;
+
+  tryStartProvingRootRollup(): boolean;
+  setRootRollupProof(provingOutput: RootRollupProof): void;
+  isReadyForRootRollup(): boolean;
+  getRootRollupInputs(): RootRollupPrivateInputs;
+}
+
+/**
+ * Shared scheduling for the top-tree section of epoch proving — checkpoint-merge,
+ * padding (single-checkpoint case), and root rollup. Both `ProvingOrchestrator` and
+ * `TopTreeOrchestrator` extend this; their per-checkpoint-root drivers diverge (one
+ * drains state-derived inputs once block-merge is done, the other builds inputs from
+ * caller-supplied checkpoint data), but the rest of the tree is identical.
+ *
+ * Subclasses provide a `wrapCircuitCall` hook for telemetry (the orchestrator wraps
+ * each call in a span; the top-tree leaves it as identity), and an
+ * `onRootRollupComplete` hook to invoke the right shape of `state.resolve()` —
+ * `EpochProvingState.resolve` takes a `ProvingResult`, `TopTreeProvingState.resolve`
+ * is no-arg.
+ */
+export abstract class TopTreeProvingScheduler extends ProvingScheduler {
+  constructor(
+    protected readonly prover: ServerCircuitProver,
+    enqueueConcurrency: number,
+    loggerName?: string,
+    bindings?: LoggerBindings,
+  ) {
+    super(enqueueConcurrency, loggerName, bindings);
+  }
+
+  /**
+   * Wraps a circuit call for telemetry. Default is identity; the orchestrator overrides
+   * to wrap with `wrapCallbackInSpan`.
+   */
+  protected wrapCircuitCall<T>(
+    _circuitName: string,
+    fn: (signal: AbortSignal) => Promise<T>,
+  ): (signal: AbortSignal) => Promise<T> {
+    return fn;
+  }
+
+  /** Called once the root rollup proof has been set; subclasses call `state.resolve(...)` with the right shape. */
+  protected abstract onRootRollupComplete(state: TopTreeStateLike): void;
+
+  protected enqueueCheckpointMergeRollup(state: TopTreeStateLike, location: TreeNodeLocation) {
+    if (!state.verifyState() || !state.tryStartProvingCheckpointMerge(location)) {
+      return;
+    }
+    const inputs = state.getCheckpointMergeRollupInputs(location);
+    this.deferredProving(
+      state,
+      this.wrapCircuitCall('rollup-checkpoint-merge', signal =>
+        this.prover.getCheckpointMergeRollupProof(inputs, signal, state.epochNumber),
+      ),
+      result => {
+        state.setCheckpointMergeRollupProof(location, result);
+        this.checkAndEnqueueNextCheckpointMergeRollup(state, location);
+      },
+    );
+  }
+
+  protected enqueueEpochPadding(state: TopTreeStateLike) {
+    if (!state.verifyState() || !state.tryStartProvingPaddingCheckpoint()) {
+      return;
+    }
+    const inputs = state.getPaddingCheckpointInputs();
+    this.deferredProving(
+      state,
+      this.wrapCircuitCall('rollup-checkpoint-padding', signal =>
+        this.prover.getCheckpointPaddingRollupProof(inputs, signal, state.epochNumber),
+      ),
+      result => {
+        state.setCheckpointPaddingProof(result);
+        this.checkAndEnqueueRootRollup(state);
+      },
+    );
+  }
+
+  protected enqueueRootRollup(state: TopTreeStateLike) {
+    if (!state.verifyState() || !state.tryStartProvingRootRollup()) {
+      return;
+    }
+    const inputs = state.getRootRollupInputs();
+    this.deferredProving(
+      state,
+      this.wrapCircuitCall('rollup-root', signal => this.prover.getRootRollupProof(inputs, signal, state.epochNumber)),
+      result => {
+        this.logger.verbose(`Completed root rollup for epoch ${state.epochNumber}`);
+        state.setRootRollupProof(result);
+        this.onRootRollupComplete(state);
+      },
+    );
+  }
+
+  protected checkAndEnqueueNextCheckpointMergeRollup(state: TopTreeStateLike, currentLocation: TreeNodeLocation) {
+    if (!state.isReadyForCheckpointMerge(currentLocation)) {
+      return;
+    }
+    const parentLocation = state.getParentLocation(currentLocation);
+    if (parentLocation.level === 0) {
+      this.checkAndEnqueueRootRollup(state);
+    } else {
+      this.enqueueCheckpointMergeRollup(state, parentLocation);
+    }
+  }
+
+  protected checkAndEnqueueRootRollup(state: TopTreeStateLike) {
+    if (!state.isReadyForRootRollup()) {
+      return;
+    }
+    this.enqueueRootRollup(state);
+  }
+}

package/src/orchestrator/top-tree-proving-state.ts

@@ -0,0 +1,220 @@
+import type { BatchedBlob, BatchedBlobAccumulator, FinalBlobBatchingChallenges } from '@aztec/blob-lib';
+import type { NESTED_RECURSIVE_PROOF_LENGTH, NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH } from '@aztec/constants';
+import { EpochNumber } from '@aztec/foundation/branded-types';
+import { type TreeNodeLocation, UnbalancedTreeStore } from '@aztec/foundation/trees';
+import type { PublicInputsAndRecursiveProof } from '@aztec/stdlib/interfaces/server';
+import type { Proof } from '@aztec/stdlib/proofs';
+import {
+  CheckpointMergeRollupPrivateInputs,
+  CheckpointPaddingRollupPrivateInputs,
+  CheckpointRollupPublicInputs,
+  RootRollupPrivateInputs,
+  type RootRollupPublicInputs,
+} from '@aztec/stdlib/rollup';
+
+import { toProofData } from './block-building-helpers.js';
+import type { ProofState } from './block-proving-state.js';
+
+enum TOP_TREE_LIFECYCLE {
+  CREATED,
+  RESOLVED,
+  REJECTED,
+}
+
+/**
+ * Lean top-tree-only state. Owns the merge tree of checkpoint root proofs, the
+ * single-checkpoint padding proof slot, the final root rollup proof, and the blob
+ * accumulator endpoints needed to finalise the epoch's batched blob proof.
+ *
+ * Constructed with `totalNumCheckpoints` and `finalBlobBatchingChallenges` upfront —
+ * by the time the top tree starts, all checkpoints are known and the challenges are
+ * derivable from their blob fields.
+ */
+export class TopTreeProvingState {
+  private checkpointProofs: UnbalancedTreeStore<
+    ProofState<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+  >;
+  private checkpointPaddingProof:
+    | ProofState<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
+    | undefined;
+  private rootRollupProof: ProofState<RootRollupPublicInputs, typeof NESTED_RECURSIVE_PROOF_LENGTH> | undefined;
+  private endBlobAccumulator: BatchedBlobAccumulator | undefined;
+  private finalBatchedBlob: BatchedBlob | undefined;
+  private lifecycle = TOP_TREE_LIFECYCLE.CREATED;
+
+  constructor(
+    public readonly epochNumber: EpochNumber,
+    public readonly totalNumCheckpoints: number,
+    public readonly finalBlobBatchingChallenges: FinalBlobBatchingChallenges,
+    public readonly startBlobAccumulator: BatchedBlobAccumulator,
+    private readonly completionCallback: () => void,
+    private readonly rejectionCallback: (reason: string) => void,
+  ) {
+    if (totalNumCheckpoints < 1) {
+      throw new Error(`TopTreeProvingState requires at least one checkpoint; got ${totalNumCheckpoints}.`);
+    }
+    this.checkpointProofs = new UnbalancedTreeStore(totalNumCheckpoints);
+  }
+
+  // --- checkpoint root rollup ---
+
+  public setCheckpointRootRollupProof(
+    checkpointIndex: number,
+    provingOutput: PublicInputsAndRecursiveProof<
+      CheckpointRollupPublicInputs,
+      typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+    >,
+  ): TreeNodeLocation {
+    return this.checkpointProofs.setLeaf(checkpointIndex, { provingOutput });
+  }
+
+  // --- checkpoint merge rollup ---
+
+  public tryStartProvingCheckpointMerge(location: TreeNodeLocation) {
+    if (this.checkpointProofs.getNode(location)?.isProving) {
+      return false;
+    }
+    this.checkpointProofs.setNode(location, { isProving: true });
+    return true;
+  }
+
+  public setCheckpointMergeRollupProof(
+    location: TreeNodeLocation,
+    provingOutput: PublicInputsAndRecursiveProof<
+      CheckpointRollupPublicInputs,
+      typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+    >,
+  ) {
+    this.checkpointProofs.setNode(location, { provingOutput });
+  }
+
+  public isReadyForCheckpointMerge(location: TreeNodeLocation) {
+    return !!this.checkpointProofs.getSibling(location)?.provingOutput;
+  }
+
+  public getParentLocation(location: TreeNodeLocation) {
+    return this.checkpointProofs.getParentLocation(location);
+  }
+
+  public getCheckpointMergeRollupInputs(mergeLocation: TreeNodeLocation) {
+    const [left, right] = this.checkpointProofs.getChildren(mergeLocation).map(c => c?.provingOutput);
+    if (!left || !right) {
+      throw new Error('At least one child is not ready for the checkpoint merge rollup.');
+    }
+    return new CheckpointMergeRollupPrivateInputs([toProofData(left), toProofData(right)]);
+  }
+
+  // --- padding (single-checkpoint case) ---
+
+  public tryStartProvingPaddingCheckpoint() {
+    if (this.checkpointPaddingProof?.isProving) {
+      return false;
+    }
+    this.checkpointPaddingProof = { isProving: true };
+    return true;
+  }
+
+  public setCheckpointPaddingProof(
+    provingOutput: PublicInputsAndRecursiveProof<
+      CheckpointRollupPublicInputs,
+      typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+    >,
+  ) {
+    this.checkpointPaddingProof = { provingOutput };
+  }
+
+  public getPaddingCheckpointInputs() {
+    return new CheckpointPaddingRollupPrivateInputs();
+  }
+
+  // --- root rollup ---
+
+  public tryStartProvingRootRollup() {
+    if (this.rootRollupProof?.isProving) {
+      return false;
+    }
+    this.rootRollupProof = { isProving: true };
+    return true;
+  }
+
+  public setRootRollupProof(provingOutput: PublicInputsAndRecursiveProof<RootRollupPublicInputs>) {
+    this.rootRollupProof = { provingOutput };
+  }
+
+  public isReadyForRootRollup() {
+    const childProofs = this.#getChildProofsForRoot();
+    return childProofs.every(p => !!p);
+  }
+
+  public getRootRollupInputs() {
+    const [left, right] = this.#getChildProofsForRoot();
+    if (!left || !right) {
+      throw new Error('At least one child is not ready for the root rollup.');
+    }
+    return RootRollupPrivateInputs.from({
+      previousRollups: [toProofData(left), toProofData(right)],
+    });
+  }
+
+  // --- blob accumulator finalisation ---
+
+  /**
+   * Sets the end-of-epoch blob accumulator, computed by the top-tree orchestrator
+   * from the surviving checkpoints' blob fields. Required before `finalizeBatchedBlob`.
+   */
+  public setEndBlobAccumulator(accumulator: BatchedBlobAccumulator) {
+    this.endBlobAccumulator = accumulator;
+  }
+
+  public async finalizeBatchedBlob() {
+    if (!this.endBlobAccumulator) {
+      throw new Error('End blob accumulator not set; call setEndBlobAccumulator before finalize.');
+    }
+    this.finalBatchedBlob = await this.endBlobAccumulator.finalize(true /* verifyProof */);
+  }
+
+  public getEpochProofResult(): { proof: Proof; publicInputs: RootRollupPublicInputs; batchedBlobInputs: BatchedBlob } {
+    const provingOutput = this.rootRollupProof?.provingOutput;
+    if (!provingOutput || !this.finalBatchedBlob) {
+      throw new Error('Top-tree proof not ready; root rollup or batched blob missing.');
+    }
+    return {
+      proof: provingOutput.proof.binaryProof,
+      publicInputs: provingOutput.inputs,
+      batchedBlobInputs: this.finalBatchedBlob,
+    };
+  }
+
+  // --- lifecycle ---
+
+  public verifyState() {
+    return this.lifecycle === TOP_TREE_LIFECYCLE.CREATED;
+  }
+
+  public resolve() {
+    if (!this.verifyState()) {
+      return;
+    }
+    this.lifecycle = TOP_TREE_LIFECYCLE.RESOLVED;
+    this.completionCallback();
+  }
+
+  public reject(reason: string) {
+    if (!this.verifyState()) {
+      return;
+    }
+    this.lifecycle = TOP_TREE_LIFECYCLE.REJECTED;
+    this.rejectionCallback(reason);
+  }
+
+  public cancel() {
+    this.reject('Top-tree proving cancelled');
+  }
+
+  #getChildProofsForRoot() {
+    const rootLocation = { level: 0, index: 0 };
+    return this.totalNumCheckpoints === 1
+      ? [this.checkpointProofs.getNode(rootLocation)?.provingOutput, this.checkpointPaddingProof?.provingOutput]
+      : this.checkpointProofs.getChildren(rootLocation).map(c => c?.provingOutput);
+  }
+}