@aztec/prover-client 5.0.0-private.20260319 → 5.0.0-rc.2

package/src/orchestrator/chonk-cache.ts

@@ -0,0 +1,99 @@
+import type { NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH } from '@aztec/constants';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import type { L2Block } from '@aztec/stdlib/block';
+import type { PublicInputsAndRecursiveProof } from '@aztec/stdlib/interfaces/server';
+import type { PublicChonkVerifierPublicInputs } from '@aztec/stdlib/rollup';
+
+/** Result of a chonk-verifier proof, cached by tx hash. */
+export type ChonkVerifierProofResult = PublicInputsAndRecursiveProof<
+  PublicChonkVerifierPublicInputs,
+  typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+>;
+
+/**
+ * Shared cache of `getPublicChonkVerifierProof` results, keyed by tx hash.
+ *
+ * Owned by the prover-node and shared across every epoch / session: a tx remined into
+ * a different block (e.g. after a brief L1 reorg) reuses the already-computed chonk
+ * proof rather than redoing it. Entries are released via `releaseForBlocks` once the
+ * containing block is no longer interesting to the caller (e.g. its epoch's proof
+ * submission window has expired).
+ */
+export class ChonkCache {
+  private readonly cache = new Map<string, Promise<ChonkVerifierProofResult>>();
+  private readonly pending = new Map<string, AbortController>();
+  private readonly log: Logger;
+  private stopped = false;
+
+  constructor(bindings?: LoggerBindings) {
+    this.log = createLogger('prover-client:chonk-cache', bindings);
+  }
+
+  /** Returns the cached promise for `txHash`, or `undefined` if none is registered. */
+  public get(txHash: string): Promise<ChonkVerifierProofResult> | undefined {
+    return this.cache.get(txHash);
+  }
+
+  /**
+   * Atomic get-or-compute: returns the cached promise for `txHash`, or runs `factory`
+   * (passing an AbortSignal the cache controls) and caches its result. Concurrent
+   * callers for the same `txHash` share the same promise.
+   *
+   * Rejected promises are evicted so a future caller can retry. The factory's
+   * AbortSignal fires when the cache is stopped.
+   */
+  public getOrCompute(
+    txHash: string,
+    factory: (signal: AbortSignal) => Promise<ChonkVerifierProofResult>,
+  ): Promise<ChonkVerifierProofResult> {
+    if (this.stopped) {
+      return Promise.reject(new Error('ChonkCache is stopped'));
+    }
+    const existing = this.cache.get(txHash);
+    if (existing) {
+      return existing;
+    }
+    const controller = new AbortController();
+    this.pending.set(txHash, controller);
+    this.log.debug(`Enqueueing chonk-verifier circuit`, { txHash });
+    const promise = factory(controller.signal).finally(() => this.pending.delete(txHash));
+    // Silently observe the rejection branch and evict so a retry is possible.
+    promise.catch(err => {
+      this.cache.delete(txHash);
+      this.log.debug(`Chonk-verifier proof failed; evicted from cache`, { txHash, error: `${err}` });
+    });
+    this.cache.set(txHash, promise);
+    return promise;
+  }
+
+  /** Drops cache entries for every tx in the supplied blocks. */
+  public releaseForBlocks(blocks: L2Block[]): void {
+    let released = 0;
+    for (const block of blocks) {
+      for (const txEffect of block.body.txEffects) {
+        if (this.cache.delete(txEffect.txHash.toString())) {
+          released++;
+        }
+      }
+    }
+    if (released > 0) {
+      this.log.debug(`Released ${released} chonk-verifier cache entries`, {
+        blockCount: blocks.length,
+        releasedCount: released,
+      });
+    }
+  }
+
+  /** Aborts every in-flight chonk-verifier job and clears the cache. */
+  public stop(): void {
+    if (this.stopped) {
+      return;
+    }
+    this.stopped = true;
+    for (const controller of this.pending.values()) {
+      controller.abort();
+    }
+    this.pending.clear();
+    this.cache.clear();
+  }
+}

package/src/orchestrator/index.ts

@@ -1 +1,8 @@
-export { ProvingOrchestrator } from './orchestrator.js';
+export { CheckpointSubTreeOrchestrator, type SubTreeResult } from './checkpoint-sub-tree-orchestrator.js';
+export { ChonkCache, type ChonkVerifierProofResult } from './chonk-cache.js';
+export {
+  TopTreeOrchestrator,
+  TopTreeCancelledError,
+  type CheckpointTopTreeData,
+  type TopTreeResult,
+} from './top-tree-orchestrator.js';

package/src/orchestrator/proving-scheduler.ts

@@ -0,0 +1,160 @@
+import { AbortError } from '@aztec/foundation/error';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import { SerialQueue } from '@aztec/foundation/queue';
+import { sleep } from '@aztec/foundation/sleep';
+
+/**
+ * Minimal surface a deferred-proving state must expose. Both `CheckpointProvingState` /
+ * `BlockProvingState` (used by `CheckpointSubTreeOrchestrator`) and `TopTreeProvingState`
+ * (used by `TopTreeOrchestrator`) satisfy it.
+ */
+export interface ProvingStateLike {
+  /** Returns false once the state has been cancelled or otherwise invalidated. */
+  verifyState(): boolean;
+  /** Surfaces a proving error to the state's owner. */
+  reject(reason: string): void;
+}
+
+/**
+ * Common scheduling infrastructure shared by every orchestrator that drives broker
+ * proving jobs:
+ *
+ *   - A shared `SerialQueue` (`deferredJobQueue`) that serialises the *act of handing a
+ *     job to the broker*, one initiation per event-loop tick. Each queue task kicks off
+ *     `safeJob` (which submits to the broker) without awaiting it, then yields with
+ *     `sleep(0)`; the next task therefore runs on the following macrotask. This does NOT
+ *     cap how many broker jobs are concurrently in flight — the broker's own queue absorbs
+ *     that. What it bounds is the burst rate: a sub-tree that synchronously discovers
+ *     thousands of ready jobs can't flood the broker (and monopolise the event loop) in a
+ *     single tick. The queue is owned by the `ProverClient` and shared across every
+ *     orchestrator (every sub-tree and top-tree across every concurrent epoch session), so
+ *     this pacing is applied once globally rather than once-per-orchestrator.
+ *   - A list of `AbortController`s (`pendingProvingJobs`) so a `cancel()` can abort
+ *     in-flight broker jobs when needed.
+ *   - A `deferredProving<T>(state, request, callback, isCancelled?)` method that wraps
+ *     a broker request in the standard "submit, drop result if state invalidated, push
+ *     errors to state.reject" envelope.
+ *
+ * Subclasses own their own concrete proving state and define `cancelInternal()` for
+ * the rest of the cleanup work (closing world-state forks, marking sub-trees
+ * cancelled, etc.). Because the queue is shared, neither `cancel()` nor `stop()` touch
+ * it — they only abort this orchestrator's in-flight broker jobs. Queued-but-unrun jobs
+ * for a cancelled orchestrator no-op via the guards in `deferredProving`.
+ */
+export abstract class ProvingScheduler {
+  protected pendingProvingJobs: AbortController[] = [];
+  protected logger: Logger;
+
+  constructor(
+    private readonly deferredJobQueue: SerialQueue,
+    loggerName = 'prover-client:proving-scheduler',
+    bindings?: LoggerBindings,
+  ) {
+    this.logger = createLogger(loggerName, bindings);
+  }
+
+  /** Number of broker jobs currently in flight. */
+  public getNumPendingProvingJobs(): number {
+    return this.pendingProvingJobs.length;
+  }
+
+  /**
+   * Optionally aborts every in-flight broker job. Aborting is the right choice on
+   * reorg-driven cancel (where the in-flight inputs are no longer valid) and the
+   * wrong choice on shutdown (where leaving jobs in the broker queue lets a restart
+   * pick them up). The shared queue is not touched — queued-but-unrun jobs belonging
+   * to this orchestrator no-op once their controller is aborted (or once their state
+   * is marked invalid by the subclass).
+   */
+  protected resetSchedulerState(abortJobs: boolean): void {
+    if (abortJobs) {
+      for (const controller of this.pendingProvingJobs) {
+        controller.abort();
+      }
+    }
+  }
+
+  /**
+   * Subclass-defined cancellation. Implementations call `resetSchedulerState(...)`
+   * and then do their own cleanup (close world-state forks, propagate cancel into
+   * the proving state, etc.).
+   */
+  protected abstract cancelInternal(): void;
+
+  /**
+   * Standard stop: cancel this orchestrator's work. The shared queue is owned by the
+   * `ProverClient` and outlives every orchestrator, so it is not drained here.
+   */
+  public stop(): Promise<void> {
+    this.cancelInternal();
+    return Promise.resolve();
+  }
+
+  /**
+   * Submits a broker request. The returned-via-callback result is dropped if the
+   * state has become invalid (re-org, cancellation) by the time it lands. Errors
+   * are routed to `state.reject` unless they are abort-driven or the state is
+   * already invalid (in which case they're a stale echo of the cancel).
+   *
+   * @param state - Object exposing `verifyState()` and `reject()`.
+   * @param request - The broker call. Receives the controller's signal.
+   * @param callback - Runs on success, after `verifyState()` is checked.
+   * @param isCancelled - Optional extra cancellation predicate (e.g. a `cancelled`
+   *   flag the subclass maintains independently of the state). Defaults to never.
+   */
+  protected deferredProving<S extends ProvingStateLike, T>(
+    state: S,
+    request: (signal: AbortSignal) => Promise<T>,
+    callback: (result: T) => void | Promise<void>,
+    isCancelled: () => boolean = () => false,
+  ): void {
+    if (!state.verifyState()) {
+      this.logger.debug(`Not enqueuing job, state no longer valid`);
+      return;
+    }
+
+    const controller = new AbortController();
+    this.pendingProvingJobs.push(controller);
+
+    // We use a 'safeJob'. We don't want promise rejections in the proving pool — we
+    // want to capture the error here and reject the proving state while keeping the
+    // event loop free of rejections.
+    const safeJob = async () => {
+      try {
+        if (controller.signal.aborted) {
+          return;
+        }
+        const result = await request(controller.signal);
+        if (controller.signal.aborted || !state.verifyState() || isCancelled()) {
+          this.logger.debug(`State no longer valid, discarding result`);
+          return;
+        }
+        await callback(result);
+      } catch (err) {
+        if (err instanceof AbortError || isCancelled()) {
+          return;
+        }
+        if (!state.verifyState()) {
+          this.logger.debug(`State no longer valid, discarding error from proving job`, err);
+          return;
+        }
+        this.logger.error(`Error thrown when proving job`, err);
+        state.reject(`${err}`);
+      } finally {
+        const idx = this.pendingProvingJobs.indexOf(controller);
+        if (idx > -1) {
+          this.pendingProvingJobs.splice(idx, 1);
+        }
+      }
+    };
+
+    void this.deferredJobQueue.put(async () => {
+      // Kick off the broker submission without awaiting it — awaiting here would serialise all
+      // proving (one job at a time) and kill parallelism. The `sleep(0)` yields the event loop
+      // so the next queued job initiates on the following macrotask, pacing bursts rather than
+      // bounding in-flight broker concurrency (the broker's own queue handles that).
+      void safeJob();
+      await sleep(0);
+    });
+  }
+}

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

@@ -0,0 +1,384 @@
+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 { SerialQueue } from '@aztec/foundation/queue';
+import type { Tuple } from '@aztec/foundation/serialize';
+import { MerkleTreeCalculator, type TreeNodeLocation, 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 { ProvingScheduler } from './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 ProvingScheduler {
+  private state: TopTreeProvingState | undefined;
+  private cancelled = false;
+
+  constructor(
+    protected readonly prover: ServerCircuitProver,
+    private readonly proverId: EthAddress,
+    deferredJobQueue: SerialQueue,
+    _telemetryClient: TelemetryClient = getTelemetryClient(),
+    bindings?: LoggerBindings,
+  ) {
+    super(deferredJobQueue, '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 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}`);
+        },
+      );
+    }
+
+    // The error type is stamped atomically at rejection time by the rejectionCallback above
+    // (TopTreeCancelledError iff cancel() drove the rejection). Re-deriving it here from the
+    // live `cancelled` flag would mask a genuine failure that lost a race with a late cancel
+    // (A-1035), so let the original error propagate untouched.
+    await completionPromise;
+    await this.state.finalizeBatchedBlob();
+    return this.state.getEpochProofResult();
+  }
+
+  /**
+   * 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 ---
+
+  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);
+            }
+          },
+        );
+      },
+      // Without this, an input-building failure rejects a discarded promise, state.reject() is
+      // never called, and prove() hangs forever on its completion promise (A-1036).
+      err => {
+        if (this.cancelled) {
+          return;
+        }
+        state.reject(`Building checkpoint root inputs for checkpoint ${checkpointIndex} failed: ${err}`);
+      },
+    );
+  }
+
+  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);
+  }
+
+  // --- internal: top-tree proof orchestration (formerly TopTreeProvingScheduler) ---
+
+  private enqueueCheckpointMergeRollup(state: TopTreeProvingState, location: TreeNodeLocation) {
+    if (!state.verifyState() || !state.tryStartProvingCheckpointMerge(location)) {
+      return;
+    }
+    const inputs = state.getCheckpointMergeRollupInputs(location);
+    this.deferredProving(
+      state,
+      signal => this.prover.getCheckpointMergeRollupProof(inputs, signal, state.epochNumber),
+      result => {
+        state.setCheckpointMergeRollupProof(location, result);
+        this.checkAndEnqueueNextCheckpointMergeRollup(state, location);
+      },
+    );
+  }
+
+  private enqueueEpochPadding(state: TopTreeProvingState) {
+    if (!state.verifyState() || !state.tryStartProvingPaddingCheckpoint()) {
+      return;
+    }
+    const inputs = state.getPaddingCheckpointInputs();
+    this.deferredProving(
+      state,
+      signal => this.prover.getCheckpointPaddingRollupProof(inputs, signal, state.epochNumber),
+      result => {
+        state.setCheckpointPaddingProof(result);
+        this.checkAndEnqueueRootRollup(state);
+      },
+    );
+  }
+
+  private enqueueRootRollup(state: TopTreeProvingState) {
+    if (!state.verifyState() || !state.tryStartProvingRootRollup()) {
+      return;
+    }
+    const inputs = state.getRootRollupInputs();
+    this.deferredProving(
+      state,
+      signal => this.prover.getRootRollupProof(inputs, signal, state.epochNumber),
+      result => {
+        this.logger.verbose(`Completed root rollup for epoch ${state.epochNumber}`);
+        state.setRootRollupProof(result);
+        state.resolve();
+      },
+    );
+  }
+
+  private checkAndEnqueueNextCheckpointMergeRollup(state: TopTreeProvingState, currentLocation: TreeNodeLocation) {
+    if (!state.isReadyForCheckpointMerge(currentLocation)) {
+      return;
+    }
+    const parentLocation = state.getParentLocation(currentLocation);
+    if (parentLocation.level === 0) {
+      this.checkAndEnqueueRootRollup(state);
+    } else {
+      this.enqueueCheckpointMergeRollup(state, parentLocation);
+    }
+  }
+
+  private checkAndEnqueueRootRollup(state: TopTreeProvingState) {
+    if (!state.isReadyForRootRollup()) {
+      return;
+    }
+    this.enqueueRootRollup(state);
+  }
+
+  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;
+  }
+}