@aztec/prover-client 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

package/src/orchestrator/checkpoint-proving-state.ts

@@ -1,18 +1,26 @@
-import { BatchedBlobAccumulator, type FinalBlobBatchingChallenges, SpongeBlob } from '@aztec/blob-lib';
+import {
+  BatchedBlobAccumulator,
+  type FinalBlobBatchingChallenges,
+  SpongeBlob,
+  encodeCheckpointBlobDataFromBlocks,
+} from '@aztec/blob-lib';
 import {
   type ARCHIVE_HEIGHT,
-  BLOBS_PER_BLOCK,
+  BLOBS_PER_CHECKPOINT,
   FIELDS_PER_BLOB,
   type L1_TO_L2_MSG_SUBTREE_ROOT_SIBLING_PATH_LENGTH,
   type NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH,
   NUM_MSGS_PER_BASE_PARITY,
+  OUT_HASH_TREE_HEIGHT,
 } from '@aztec/constants';
+import { BlockNumber } from '@aztec/foundation/branded-types';
 import { padArrayEnd } from '@aztec/foundation/collection';
-import { BLS12Point, Fr } from '@aztec/foundation/fields';
+import { BLS12Point } from '@aztec/foundation/curves/bls12';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import type { Tuple } from '@aztec/foundation/serialize';
 import { type TreeNodeLocation, UnbalancedTreeStore } from '@aztec/foundation/trees';
-import { getCheckpointBlobFields } from '@aztec/stdlib/checkpoint';
 import type { PublicInputsAndRecursiveProof } from '@aztec/stdlib/interfaces/server';
+import { computeCheckpointOutHash } from '@aztec/stdlib/messaging';
 import { ParityBasePrivateInputs } from '@aztec/stdlib/parity';
 import {
   BlockMergeRollupPrivateInputs,
@@ -32,6 +40,11 @@ import { accumulateBlobs, buildBlobHints, toProofData } from './block-building-h
 import { BlockProvingState, type ProofState } from './block-proving-state.js';
 import type { EpochProvingState } from './epoch-proving-state.js';
 
+type OutHashHint = {
+  treeSnapshot: AppendOnlyTreeSnapshot;
+  siblingPath: Tuple<Fr, typeof OUT_HASH_TREE_HEIGHT>;
+};
+
 export class CheckpointProvingState {
   private blockProofs: UnbalancedTreeStore<
     ProofState<BlockRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
@@ -40,17 +53,21 @@ export class CheckpointProvingState {
     | ProofState<CheckpointRollupPublicInputs, typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH>
     | undefined;
   private blocks: (BlockProvingState | undefined)[] = [];
+  private previousOutHashHint: OutHashHint | undefined;
+  private outHash: Fr | undefined;
+  // The snapshot and sibling path after the checkpoint's out hash is inserted.
+  // Stored here to be retrieved for the next checkpoint when it's added.
+  private newOutHashHint: OutHashHint | undefined;
   private startBlobAccumulator: BatchedBlobAccumulator | undefined;
   private endBlobAccumulator: BatchedBlobAccumulator | undefined;
   private blobFields: Fr[] | undefined;
   private error: string | undefined;
-  public readonly firstBlockNumber: number;
+  public readonly firstBlockNumber: BlockNumber;
 
   constructor(
     public readonly index: number,
     public readonly constants: CheckpointConstantData,
     public readonly totalNumBlocks: number,
-    private readonly totalNumBlobFields: number,
     private readonly finalBlobBatchingChallenges: FinalBlobBatchingChallenges,
     private readonly headerOfLastBlockInPreviousCheckpoint: BlockHeader,
     private readonly lastArchiveSiblingPath: Tuple<Fr, typeof ARCHIVE_HEIGHT>,
@@ -68,24 +85,24 @@ export class CheckpointProvingState {
       typeof L1_TO_L2_MSG_SUBTREE_ROOT_SIBLING_PATH_LENGTH
     >,
     public parentEpoch: EpochProvingState,
-    private onBlobAccumulatorSet: (checkpoint: CheckpointProvingState) => void,
+    private onBlobAccumulatorSet: (checkpoint: CheckpointProvingState) => Promise<void>,
   ) {
     this.blockProofs = new UnbalancedTreeStore(totalNumBlocks);
-    this.firstBlockNumber = headerOfLastBlockInPreviousCheckpoint.globalVariables.blockNumber + 1;
+    this.firstBlockNumber = BlockNumber(headerOfLastBlockInPreviousCheckpoint.globalVariables.blockNumber + 1);
   }
 
   public get epochNumber(): number {
     return this.parentEpoch.epochNumber;
   }
 
-  public async startNewBlock(
-    blockNumber: number,
+  public startNewBlock(
+    blockNumber: BlockNumber,
     timestamp: UInt64,
     totalNumTxs: number,
     lastArchiveTreeSnapshot: AppendOnlyTreeSnapshot,
     lastArchiveSiblingPath: Tuple<Fr, typeof ARCHIVE_HEIGHT>,
-  ): Promise<BlockProvingState> {
-    const index = blockNumber - this.firstBlockNumber;
+  ): BlockProvingState {
+    const index = Number(blockNumber) - Number(this.firstBlockNumber);
     if (index >= this.totalNumBlocks) {
       throw new Error(`Unable to start a new block at index ${index}. Expected at most ${this.totalNumBlocks} blocks.`);
     }
@@ -98,8 +115,7 @@ export class CheckpointProvingState {
     const lastL1ToL2MessageSubtreeRootSiblingPath =
       index === 0 ? this.lastL1ToL2MessageSubtreeRootSiblingPath : this.newL1ToL2MessageSubtreeRootSiblingPath;
 
-    const startSpongeBlob =
-      index === 0 ? await SpongeBlob.init(this.totalNumBlobFields) : this.blocks[index - 1]?.getEndSpongeBlob();
+    const startSpongeBlob = index === 0 ? SpongeBlob.init() : this.blocks[index - 1]?.getEndSpongeBlob();
     if (!startSpongeBlob) {
       throw new Error(
         'Cannot start a new block before the trees have progressed from the tx effects in the previous block.',
@@ -188,19 +204,48 @@ export class CheckpointProvingState {
       Fr.ZERO,
       NUM_MSGS_PER_BASE_PARITY,
     );
-    return new ParityBasePrivateInputs(messages, this.constants.vkTreeRoot);
+    return new ParityBasePrivateInputs(messages, this.constants.vkTreeRoot, this.constants.proverId);
+  }
+
+  public setOutHashHint(hint: OutHashHint) {
+    this.previousOutHashHint = hint;
+  }
+
+  public getOutHashHint() {
+    return this.previousOutHashHint;
+  }
+
+  public accumulateBlockOutHashes() {
+    if (this.isAcceptingBlocks() || this.blocks.some(b => !b?.hasEndState())) {
+      return;
+    }
+
+    if (!this.outHash) {
+      const messagesPerBlock = this.blocks.map(b => b!.getTxEffects().map(tx => tx.l2ToL1Msgs));
+      this.outHash = computeCheckpointOutHash(messagesPerBlock);
+    }
+
+    return this.outHash;
+  }
+
+  public setOutHashHintForNextCheckpoint(hint: OutHashHint) {
+    this.newOutHashHint = hint;
+  }
+
+  public getOutHashHintForNextCheckpoint() {
+    return this.newOutHashHint;
   }
 
   public async accumulateBlobs(startBlobAccumulator: BatchedBlobAccumulator) {
-    if (this.isAcceptingBlocks() || this.blocks.some(b => b!.isAcceptingTxs())) {
+    if (this.isAcceptingBlocks() || this.blocks.some(b => !b?.hasEndState())) {
       return;
     }
 
-    this.blobFields = getCheckpointBlobFields(this.blocks.map(b => b!.getTxEffects()));
-    this.endBlobAccumulator = await accumulateBlobs(this.blobFields, startBlobAccumulator);
+    this.blobFields = encodeCheckpointBlobDataFromBlocks(this.blocks.map(b => b!.getBlockBlobData()));
+    this.endBlobAccumulator = await accumulateBlobs(this.blobFields!, startBlobAccumulator);
     this.startBlobAccumulator = startBlobAccumulator;
 
-    this.onBlobAccumulatorSet(this);
+    await this.onBlobAccumulatorSet(this);
 
     return this.endBlobAccumulator;
   }
@@ -226,12 +271,15 @@ export class CheckpointProvingState {
     return this.totalNumBlocks === 1 ? 'rollup-checkpoint-root-single-block' : 'rollup-checkpoint-root';
   }
 
-  public getCheckpointRootRollupInputs() {
+  public async getCheckpointRootRollupInputs() {
     const proofs = this.#getChildProofsForRoot();
     const nonEmptyProofs = proofs.filter(p => !!p);
     if (proofs.length !== nonEmptyProofs.length) {
       throw new Error('At least one child is not ready for the checkpoint root rollup.');
     }
+    if (!this.previousOutHashHint) {
+      throw new Error('Out hash hint is not set.');
+    }
     if (!this.startBlobAccumulator) {
       throw new Error('Start blob accumulator is not set.');
     }
@@ -239,15 +287,17 @@ export class CheckpointProvingState {
     // `blobFields` must've been set if `startBlobAccumulator` is set (in `accumulateBlobs`).
     const blobFields = this.blobFields!;
 
-    const { blobCommitments, blobsHash } = buildBlobHints(blobFields);
+    const { blobCommitments, blobsHash } = await buildBlobHints(blobFields);
 
     const hints = CheckpointRootRollupHints.from({
       previousBlockHeader: this.headerOfLastBlockInPreviousCheckpoint,
       previousArchiveSiblingPath: this.lastArchiveSiblingPath,
+      previousOutHash: this.previousOutHashHint.treeSnapshot,
+      newOutHashSiblingPath: this.previousOutHashHint.siblingPath,
       startBlobAccumulator: this.startBlobAccumulator.toBlobAccumulator(),
       finalBlobChallenges: this.finalBlobBatchingChallenges,
-      blobFields: padArrayEnd(blobFields, Fr.ZERO, FIELDS_PER_BLOB * BLOBS_PER_BLOCK),
-      blobCommitments: padArrayEnd(blobCommitments, BLS12Point.ZERO, BLOBS_PER_BLOCK),
+      blobFields: padArrayEnd(blobFields, Fr.ZERO, FIELDS_PER_BLOB * BLOBS_PER_CHECKPOINT),
+      blobCommitments: padArrayEnd(blobCommitments, BLS12Point.ZERO, BLOBS_PER_CHECKPOINT),
       blobsHash,
     });
 
@@ -258,8 +308,8 @@ export class CheckpointProvingState {
       : new CheckpointRootRollupPrivateInputs([left, right], hints);
   }
 
-  public getBlockProvingStateByBlockNumber(blockNumber: number) {
-    const index = blockNumber - this.firstBlockNumber;
+  public getBlockProvingStateByBlockNumber(blockNumber: BlockNumber) {
+    const index = Number(blockNumber) - Number(this.firstBlockNumber);
     return this.blocks[index];
   }
 
@@ -269,7 +319,7 @@ export class CheckpointProvingState {
 
   public isReadyForCheckpointRoot() {
     const allChildProofsReady = this.#getChildProofsForRoot().every(p => !!p);
-    return allChildProofsReady && !!this.startBlobAccumulator;
+    return allChildProofsReady && !!this.previousOutHashHint && !!this.startBlobAccumulator;
   }
 
   public verifyState() {
@@ -296,4 +346,17 @@ export class CheckpointProvingState {
       ? [this.blockProofs.getNode(rootLocation)?.provingOutput] // If there's only 1 block, its proof will be stored at the root.
       : this.blockProofs.getChildren(rootLocation).map(c => c?.provingOutput);
   }
+
+  /**
+   * Returns the block-level proof outputs that feed into the checkpoint root rollup.
+   * Used by `CheckpointSubTreeOrchestrator` to surface its sub-tree result.
+   */
+  public getSubTreeOutputProofs() {
+    return this.#getChildProofsForRoot();
+  }
+
+  /** Sibling path of the archive tree captured before any block in this checkpoint landed. */
+  public getLastArchiveSiblingPath() {
+    return this.lastArchiveSiblingPath;
+  }
 }

package/src/orchestrator/checkpoint-sub-tree-orchestrator.ts

@@ -0,0 +1,271 @@
+import { FinalBlobBatchingChallenges } from '@aztec/blob-lib';
+import type { ARCHIVE_HEIGHT, NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH } from '@aztec/constants';
+import type { EpochNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { LoggerBindings } from '@aztec/foundation/log';
+import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
+import type { Tuple } from '@aztec/foundation/serialize';
+import type { EthAddress } from '@aztec/stdlib/block';
+import type {
+  ForkMerkleTreeOperations,
+  PublicInputsAndRecursiveProof,
+  ReadonlyWorldStateAccess,
+  ServerCircuitProver,
+} from '@aztec/stdlib/interfaces/server';
+import type {
+  BlockRollupPublicInputs,
+  CheckpointConstantData,
+  PublicChonkVerifierPublicInputs,
+} from '@aztec/stdlib/rollup';
+import type { BlockHeader, Tx } from '@aztec/stdlib/tx';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import { getPublicChonkVerifierPrivateInputsFromTx } from './block-building-helpers.js';
+import type { BlockProvingState } from './block-proving-state.js';
+import type { CheckpointProvingState } from './checkpoint-proving-state.js';
+import type { EpochProvingContext } from './epoch-proving-context.js';
+import { ProvingOrchestrator } from './orchestrator.js';
+
+/**
+ * Result of proving a single checkpoint's block-level sub-tree.
+ *
+ * Contains the final block-rollup proof outputs that feed the checkpoint root rollup,
+ * plus the archive sibling path captured before any block in the checkpoint landed
+ * (the top-tree needs this to assemble the checkpoint root rollup hints).
+ */
+export type SubTreeResult = {
+  blockProofOutputs: PublicInputsAndRecursiveProof<
+    BlockRollupPublicInputs,
+    typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+  >[];
+  previousArchiveSiblingPath: Tuple<Fr, typeof ARCHIVE_HEIGHT>;
+};
+
+/**
+ * Orchestrates block-level proving for a single checkpoint, stopping at the boundary
+ * where checkpoint root rollup would otherwise begin.
+ *
+ * Reuses every circuit driver in `ProvingOrchestrator` (chonk verifier, base, merge,
+ * block-root, parity, block-merge) but overrides the gating method that escalates to
+ * checkpoint root rollup. Instead of escalating, the orchestrator resolves
+ * `getSubTreeResult()` once every block-level proof in the checkpoint's tree is ready.
+ *
+ * Wiring: a single-checkpoint epoch is created in the constructor (epoch number sourced
+ * from the supplied `EpochProvingContext`). The canonical way to obtain a fully-started
+ * sub-tree is the `start` static factory, which also drives the single internal
+ * `startNewCheckpoint(0, ...)` call. The sub-tree never calls `finalizeEpochStructure`;
+ * the override of `checkAndEnqueueCheckpointRootRollup` resolves `getSubTreeResult` once
+ * block-level proving completes.
+ */
+export class CheckpointSubTreeOrchestrator extends ProvingOrchestrator {
+  private readonly subTreeResult: PromiseWithResolvers<SubTreeResult>;
+
+  constructor(
+    dbProvider: ReadonlyWorldStateAccess & ForkMerkleTreeOperations,
+    prover: ServerCircuitProver,
+    proverId: EthAddress,
+    /**
+     * Per-epoch shared chonk-verifier proof cache. Every chonk-verifier proof started
+     * by this sub-tree lives on the context and survives the sub-tree's cancellation,
+     * so a tx whose original checkpoint is reorged out and re-appears in a replacement
+     * checkpoint reuses the cached proof. The context's `epochNumber` is the epoch
+     * this sub-tree proves into.
+     */
+    private readonly epochContext: EpochProvingContext,
+    cancelJobsOnStop: boolean = false,
+    enqueueConcurrency: number,
+    telemetryClient: TelemetryClient = getTelemetryClient(),
+    bindings?: LoggerBindings,
+  ) {
+    super(dbProvider, prover, proverId, cancelJobsOnStop, enqueueConcurrency, telemetryClient, bindings);
+
+    // Single-checkpoint mini-epoch by construction. The total/challenges supplied to
+    // `super.startNewEpoch` are never read, because the sub-tree overrides
+    // `checkAndEnqueueCheckpointRootRollup` to short-circuit before the parent's
+    // checkpoint-root / finalize machinery would consume them.
+    super.startNewEpoch(epochContext.epochNumber, 1, FinalBlobBatchingChallenges.empty());
+
+    this.subTreeResult = promiseWithResolvers<SubTreeResult>();
+    // Mark the rejection branch as observed so a `cancel()` or proving failure does not
+    // surface an unhandled rejection when no consumer awaits getSubTreeResult().
+    this.subTreeResult.promise.catch(() => {});
+
+    // If the parent's proving state ever rejects, surface the failure on the sub-tree promise.
+    void this.provingPromise!.then(result => {
+      if (result.status === 'failure') {
+        this.subTreeResult.reject(new Error(result.reason));
+      }
+    });
+  }
+
+  /**
+   * Constructs and starts a sub-tree for a single checkpoint. The returned sub-tree
+   * has had its single internal `startNewCheckpoint(0, ...)` driven; callers proceed
+   * directly to per-block `startNewBlock` / `addTxs` / `setBlockCompleted`.
+   *
+   * If the internal `startNewCheckpoint` rejects, the partially-constructed sub-tree
+   * is stopped before the error propagates, so no broker resources leak.
+   */
+  public static async start(
+    dbProvider: ReadonlyWorldStateAccess & ForkMerkleTreeOperations,
+    prover: ServerCircuitProver,
+    proverId: EthAddress,
+    epochContext: EpochProvingContext,
+    cancelJobsOnStop: boolean,
+    enqueueConcurrency: number,
+    checkpointConstants: CheckpointConstantData,
+    l1ToL2Messages: Fr[],
+    totalNumBlocks: number,
+    headerOfLastBlockInPreviousCheckpoint: BlockHeader,
+    telemetryClient: TelemetryClient = getTelemetryClient(),
+    bindings?: LoggerBindings,
+  ): Promise<CheckpointSubTreeOrchestrator> {
+    const subTree = new CheckpointSubTreeOrchestrator(
+      dbProvider,
+      prover,
+      proverId,
+      epochContext,
+      cancelJobsOnStop,
+      enqueueConcurrency,
+      telemetryClient,
+      bindings,
+    );
+    try {
+      await ProvingOrchestrator.prototype.startNewCheckpoint.call(
+        subTree,
+        0,
+        checkpointConstants,
+        l1ToL2Messages,
+        totalNumBlocks,
+        headerOfLastBlockInPreviousCheckpoint,
+      );
+      return subTree;
+    } catch (err) {
+      await subTree.stop().catch(() => {});
+      throw err;
+    }
+  }
+
+  /** Returns a promise that resolves when block-level proving completes for the checkpoint. */
+  public getSubTreeResult(): Promise<SubTreeResult> {
+    return this.subTreeResult.promise;
+  }
+
+  /**
+   * The epoch is started in the constructor.
+   */
+  public override startNewEpoch(
+    _epochNumber: EpochNumber,
+    _totalNumCheckpoints: number,
+    _finalBlobBatchingChallenges: FinalBlobBatchingChallenges,
+  ): void {
+    throw new Error('CheckpointSubTreeOrchestrator starts its epoch in the constructor; do not call startNewEpoch.');
+  }
+
+  /**
+   * The single internal checkpoint is started by the `start` factory
+   */
+  public override startNewCheckpoint(
+    _checkpointIndex: number,
+    _constants: CheckpointConstantData,
+    _l1ToL2Messages: Fr[],
+    _totalNumBlocks: number,
+    _headerOfLastBlockInPreviousCheckpoint: BlockHeader,
+  ): Promise<void> {
+    return Promise.reject(
+      new Error(
+        'CheckpointSubTreeOrchestrator drives its single checkpoint in `start`; do not call startNewCheckpoint.',
+      ),
+    );
+  }
+
+  /**
+   * Returns the archive sibling path captured at the internal `startNewCheckpoint`.
+   * Available synchronously once `start` has resolved, before block-level proving
+   * completes. The top-tree consumer uses this to assemble checkpoint root rollup hints
+   * up-front so checkpoint root proofs can pipeline against in-flight sub-tree proving.
+   */
+  public getPreviousArchiveSiblingPath(): Tuple<Fr, typeof ARCHIVE_HEIGHT> {
+    const checkpoint = this.provingState!.getCheckpointProvingState(0);
+    if (!checkpoint) {
+      throw new Error('Checkpoint not started; call CheckpointSubTreeOrchestrator.start first.');
+    }
+    return checkpoint.getLastArchiveSiblingPath();
+  }
+
+  /**
+   * Override the checkpoint-root boundary: instead of escalating to checkpoint root,
+   * resolve the sub-tree promise with the block-level proof outputs once they're all ready.
+   */
+  // eslint-disable-next-line require-await
+  protected override async checkAndEnqueueCheckpointRootRollup(provingState: CheckpointProvingState): Promise<void> {
+    const proofs = provingState.getSubTreeOutputProofs();
+    const nonEmpty = proofs.filter((p): p is NonNullable<typeof p> => !!p);
+    if (proofs.length !== nonEmpty.length) {
+      // Block merge tree not fully resolved yet — will be retried as more block proofs land.
+      return;
+    }
+
+    this.subTreeResult.resolve({
+      blockProofOutputs: nonEmpty,
+      previousArchiveSiblingPath: provingState.getLastArchiveSiblingPath(),
+    });
+  }
+
+  /**
+   * Kickstart chonk-verifier circuits via the shared `EpochProvingContext`. The context
+   * owns the broker job lifecycle, so the proof survives this sub-tree's `cancel()` —
+   * a tx that ends up in a replacement checkpoint after a reorg can pick the cached
+   * promise up and skip re-proving.
+   */
+  public override startChonkVerifierCircuits(txs: Tx[]): Promise<void> {
+    if (!this.provingState?.verifyState()) {
+      return Promise.reject(new Error('Sub-tree proving state is not active.'));
+    }
+    const publicTxs = txs.filter(tx => tx.data.forPublic);
+    for (const tx of publicTxs) {
+      const txHash = tx.getTxHash().toString();
+      const inputs = getPublicChonkVerifierPrivateInputsFromTx(tx, this.getProverId().toField());
+      // Fire and forget — getOrEnqueueChonkVerifier later picks up the cached promise
+      // when the tx is processed inside its block.
+      void this.epochContext.enqueue(txHash, inputs);
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Route the tx's chonk-verifier dependency through the per-epoch context: read the
+   * cached promise (or enqueue if missing), then `.then(handleResult)` to progress to
+   * the base rollup once the proof lands.
+   */
+  protected override getOrEnqueueChonkVerifier(provingState: BlockProvingState, txIndex: number) {
+    if (!provingState.verifyState()) {
+      return;
+    }
+
+    const txProvingState = provingState.getTxProvingState(txIndex);
+    const txHash = txProvingState.processedTx.hash.toString();
+
+    const handleResult = (
+      result: PublicInputsAndRecursiveProof<
+        PublicChonkVerifierPublicInputs,
+        typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+      >,
+    ) => {
+      if (!provingState.verifyState()) {
+        return;
+      }
+      txProvingState.setPublicChonkVerifierProof(result);
+      this.checkAndEnqueueBaseRollup(provingState, txIndex);
+    };
+
+    let promise = this.epochContext.getCached(txHash);
+    if (!promise) {
+      promise = this.epochContext.enqueue(txHash, txProvingState.getPublicChonkVerifierPrivateInputs());
+    }
+    void promise.then(handleResult).catch(() => {
+      // The context self-cleans on rejection; a future call (replacement sub-tree
+      // for this tx) will see the miss and re-enqueue. No action needed here.
+    });
+  }
+}

package/src/orchestrator/epoch-proving-context.ts

@@ -0,0 +1,101 @@
+import type { NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH } from '@aztec/constants';
+import type { EpochNumber } from '@aztec/foundation/branded-types';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
+import type { PublicInputsAndRecursiveProof, ServerCircuitProver } from '@aztec/stdlib/interfaces/server';
+import type { PublicChonkVerifierPrivateInputs, PublicChonkVerifierPublicInputs } from '@aztec/stdlib/rollup';
+
+/**
+ * Result of a chonk-verifier proof, cached per tx hash on `EpochProvingContext`.
+ */
+export type ChonkVerifierProofResult = PublicInputsAndRecursiveProof<
+  PublicChonkVerifierPublicInputs,
+  typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
+>;
+
+/**
+ * Per-epoch state shared across every `CheckpointSubTreeOrchestrator` constructed for
+ * the same epoch. Owns the chonk-verifier proof cache so a tx whose checkpoint is
+ * reorged out and re-appears in a replacement checkpoint does not have to re-prove
+ * its chonk circuit.
+ *
+ * The context's chonk-verifier broker jobs are deliberately submitted **outside** the
+ * sub-tree's deferred-proving queue. The sub-tree's `cancel()` therefore does not abort
+ * them — by design, because their result is tx-scoped, not sub-tree-scoped, and a
+ * replacement sub-tree should be able to consume the cached proof.
+ *
+ * Callers (`EpochProvingJob`, or unit tests) construct one context per epoch and pass
+ * it into every sub-tree they create. `stop()` aborts every in-flight chonk job.
+ */
+export class EpochProvingContext {
+  private readonly cache = new Map<string, Promise<ChonkVerifierProofResult>>();
+  /** Abort controllers for in-flight chonk jobs, keyed by tx hash. */
+  private readonly pending = new Map<string, AbortController>();
+  private readonly log: Logger;
+  private stopped = false;
+
+  constructor(
+    private readonly prover: ServerCircuitProver,
+    public readonly epochNumber: EpochNumber,
+    bindings?: LoggerBindings,
+  ) {
+    this.log = createLogger('prover-client:epoch-proving-context', bindings);
+  }
+
+  /**
+   * Returns the cached chonk-verifier proof promise for the given tx hash, or
+   * `undefined` if none has been enqueued yet. Non-mutating.
+   */
+  public getCached(txHash: string): Promise<ChonkVerifierProofResult> | undefined {
+    return this.cache.get(txHash);
+  }
+
+  /**
+   * Enqueues a chonk-verifier proof for the given tx hash, returning the promise (or
+   * the already-cached one if already enqueued). The promise resolves when the broker
+   * delivers the result; on rejection (including `stop()`), the cache entry is removed
+   * so a subsequent caller can re-enqueue.
+   */
+  public enqueue(txHash: string, inputs: PublicChonkVerifierPrivateInputs): Promise<ChonkVerifierProofResult> {
+    if (this.stopped) {
+      return Promise.reject(new Error('EpochProvingContext is stopped'));
+    }
+
+    const cached = this.cache.get(txHash);
+    if (cached) {
+      return cached;
+    }
+
+    const controller = new AbortController();
+    this.pending.set(txHash, controller);
+    this.log.debug(`Enqueueing chonk-verifier circuit`, { txHash, epochNumber: this.epochNumber });
+
+    const promise = this.prover
+      .getPublicChonkVerifierProof(inputs, controller.signal, this.epochNumber)
+      .finally(() => this.pending.delete(txHash));
+
+    // Self-clean on rejection so a future caller can re-enqueue. Mark the rejection
+    // path as observed to silence unhandled-rejection warnings when no consumer
+    // awaits the promise (e.g. when the only `.then` chain belonged to a cancelled
+    // sub-tree's tx-proving state).
+    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;
+  }
+
+  /**
+   * Aborts every in-flight chonk-verifier broker job and clears the cache. Called by
+   * the owning `EpochProvingJob` when the job stops.
+   */
+  public stop() {
+    this.stopped = true;
+    for (const controller of this.pending.values()) {
+      controller.abort();
+    }
+    this.pending.clear();
+    this.cache.clear();
+  }
+}