refactor(fast-inbox): name the checkpoint sub-tree proof bundle for what it holds (A-1427)

The top tree's per-checkpoint `blockProofs` promise stopped holding just block proofs when
parity moved to the checkpoint root: it now carries the block-rollup proof outputs plus the
checkpoint's InboxParity proof. Rename it to `subTreeProofs`, typed by a single exported
`CheckpointSubTreeProofs` in prover-client (dropping the duplicate alias in prover-node), and
rename the block-proof-array parameters in the orchestrator so `blockProofOutputs` means the
same thing everywhere. `CheckpointProver.whenBlockProofsReady` follows suit.

Author: spalladino

yarn-project/prover-client/src/orchestrator/checkpoint-sub-tree-orchestrator.ts

@@ -90,6 +90,12 @@ export type SubTreeResult = {
   previousArchiveSiblingPath: Tuple<Fr, typeof ARCHIVE_HEIGHT>;
 };
 
+/**
+ * The proofs a checkpoint's sub-tree hands to the top tree: the per-block rollup proofs plus the checkpoint's single
+ * variable-size InboxParity proof (parity moved from the first block root to the checkpoint root in AZIP-22 Fast Inbox).
+ */
+export type CheckpointSubTreeProofs = Pick<SubTreeResult, 'blockProofOutputs' | 'inboxParityProof'>;
+
 type TreeSnapshots = Map<MerkleTreeId, AppendOnlyTreeSnapshot>;
 
 /**

yarn-project/prover-client/src/orchestrator/index.ts

@@ -1,4 +1,8 @@
-export { CheckpointSubTreeOrchestrator, type SubTreeResult } from './checkpoint-sub-tree-orchestrator.js';
+export {
+  CheckpointSubTreeOrchestrator,
+  type CheckpointSubTreeProofs,
+  type SubTreeResult,
+} from './checkpoint-sub-tree-orchestrator.js';
 export { ChonkCache, type ChonkVerifierProofResult } from './chonk-cache.js';
 export {
   TopTreeOrchestrator,

yarn-project/prover-client/src/orchestrator/top-tree-orchestrator.test.ts

@@ -85,7 +85,7 @@ describe('prover/orchestrator/top-tree', () => {
     await subTree.stop();
 
     const topTreeData: CheckpointTopTreeData = {
-      blockProofs: Promise.resolve({
+      subTreeProofs: Promise.resolve({
         blockProofOutputs: result.blockProofOutputs,
         inboxParityProof: result.inboxParityProof,
       }),
@@ -170,9 +170,9 @@ describe('prover/orchestrator/top-tree', () => {
     const b = await driveSubTree(1, 1);
     const challenges = await context.getFinalBlobChallenges();
 
-    // Replace ckpt1's blockProofs with a deferred promise that resolves later.
-    const deferred = promiseWithResolvers<typeof b.topTreeData.blockProofs extends Promise<infer T> ? T : never>();
-    const ckpt1 = { ...b.topTreeData, blockProofs: deferred.promise } as CheckpointTopTreeData;
+    // Replace ckpt1's subTreeProofs with a deferred promise that resolves later.
+    const deferred = promiseWithResolvers<typeof b.topTreeData.subTreeProofs extends Promise<infer T> ? T : never>();
+    const ckpt1 = { ...b.topTreeData, subTreeProofs: deferred.promise } as CheckpointTopTreeData;
 
     const topTree = new TopTreeOrchestrator(context.prover, EthAddress.ZERO, makeTestDeferredJobQueue());
     try {
@@ -184,7 +184,7 @@ describe('prover/orchestrator/top-tree', () => {
       await new Promise(resolve => setTimeout(resolve, 50));
 
       // Now resolve ckpt1 — the orchestrator should pick it up and continue.
-      deferred.resolve((await b.topTreeData.blockProofs) as any);
+      deferred.resolve((await b.topTreeData.subTreeProofs) as any);
 
       const result = await provePromise;
       expect(result.proof).toBeDefined();
@@ -197,9 +197,9 @@ describe('prover/orchestrator/top-tree', () => {
     const { topTreeData } = await driveSubTree(1, 1);
     const challenges = await context.getFinalBlobChallenges();
 
-    // Block ckpt0's blockProofs forever so prove() can't finish.
-    const stuck = new Promise<typeof topTreeData.blockProofs extends Promise<infer T> ? T : never>(() => {});
-    const stuckData = { ...topTreeData, blockProofs: stuck } as CheckpointTopTreeData;
+    // Block ckpt0's subTreeProofs forever so prove() can't finish.
+    const stuck = new Promise<typeof topTreeData.subTreeProofs extends Promise<infer T> ? T : never>(() => {});
+    const stuckData = { ...topTreeData, subTreeProofs: stuck } as CheckpointTopTreeData;
 
     const topTree = new TopTreeOrchestrator(context.prover, EthAddress.ZERO, makeTestDeferredJobQueue());
     const provePromise = topTree.prove(EpochNumber(1), 1, challenges, [stuckData]);
@@ -258,7 +258,7 @@ describe('prover/orchestrator/top-tree', () => {
     // A malformed block proof makes toProofData (inside buildCheckpointRootInputs) throw.
     const badData = {
       ...topTreeData,
-      blockProofs: Promise.resolve({ blockProofOutputs: [{} as any], inboxParityProof: {} as any }),
+      subTreeProofs: Promise.resolve({ blockProofOutputs: [{} as any], inboxParityProof: {} as any }),
     } as CheckpointTopTreeData;
 
     const topTree = new TopTreeOrchestrator(context.prover, EthAddress.ZERO, makeTestDeferredJobQueue());
@@ -288,23 +288,23 @@ describe('prover/orchestrator/top-tree', () => {
     const { topTreeData } = await driveSubTree(1, 1);
     const challenges = await context.getFinalBlobChallenges();
 
-    const deferred = promiseWithResolvers<typeof topTreeData.blockProofs extends Promise<infer T> ? T : never>();
-    // Observe exactly when prove() attaches its blockProofs handler, so we can sequence the
+    const deferred = promiseWithResolvers<typeof topTreeData.subTreeProofs extends Promise<infer T> ? T : never>();
+    // Observe exactly when prove() attaches its subTreeProofs handler, so we can sequence the
     // genuine rejection and the cancel deterministically rather than racing a fixed timeout.
     let handlerAttached = false;
-    const observableBlockProofs = {
+    const observableSubTreeProofs = {
       then: (onF: any, onR: any) => {
         handlerAttached = true;
         return deferred.promise.then(onF, onR);
       },
     };
-    const failingData = { ...topTreeData, blockProofs: observableBlockProofs as any } as CheckpointTopTreeData;
+    const failingData = { ...topTreeData, subTreeProofs: observableSubTreeProofs as any } as CheckpointTopTreeData;
 
     const topTree = new TopTreeOrchestrator(context.prover, EthAddress.ZERO, makeTestDeferredJobQueue());
     const provePromise = topTree.prove(EpochNumber(1), 1, challenges, [failingData]);
 
-    // Wait until prove() has finished its pre-loop setup and registered the blockProofs handler.
-    await retryUntil(() => handlerAttached, 'prove() attaches blockProofs handler', 5, 0.005);
+    // Wait until prove() has finished its pre-loop setup and registered the subTreeProofs handler.
+    await retryUntil(() => handlerAttached, 'prove() attaches subTreeProofs handler', 5, 0.005);
 
     // Register a cancel reaction on the rejection, after prove()'s own handler (registered
     // first, so it runs first). On rejection the ordering is: prove's handler rejects the

yarn-project/prover-client/src/orchestrator/top-tree-orchestrator.ts

@@ -33,24 +33,19 @@ import type { BlockHeader } from '@aztec/stdlib/tx';
 import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
 
 import { buildBlobHints, toProofData } from './block-building-helpers.js';
+import type { CheckpointSubTreeProofs } from './checkpoint-sub-tree-orchestrator.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 and the parity root proof 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. `blockProofOutputs`
-   * resolves to 1 entry for a single-block checkpoint, 2 for multi-block. The parity root proof feeds the checkpoint
-   * root rollup (parity moved there from the first block root in AZIP-22 Fast Inbox).
+   * The checkpoint sub-tree's proofs. Passed as a Promise so the top tree can start (compute hints, pipeline merges)
+   * while sub-trees are still proving. `blockProofOutputs` resolves to 1 entry for a single-block checkpoint, 2 for
+   * multi-block; `inboxParityProof` feeds the checkpoint root rollup (parity moved there from the first block root in
+   * AZIP-22 Fast Inbox).
    */
-  blockProofs: Promise<{
-    blockProofOutputs: PublicInputsAndRecursiveProof<
-      BlockRollupPublicInputs,
-      typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
-    >[];
-    inboxParityProof: PublicInputsAndRecursiveProof<ParityPublicInputs>;
-  }>;
+  subTreeProofs: Promise<CheckpointSubTreeProofs>;
   /** 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. */
@@ -90,7 +85,7 @@ type OutHashHint = {
  *
  * 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`
+ * and each checkpoint's root rollup fires the moment its sub-tree's `subTreeProofs`
  * promise resolves. Later checkpoints can still be block-level proving in parallel.
  */
 export class TopTreeOrchestrator extends ProvingScheduler {
@@ -172,7 +167,7 @@ export class TopTreeOrchestrator extends ProvingScheduler {
     for (let i = 0; i < checkpointData.length; i++) {
       const cd = checkpointData[i];
       const checkpointIndex = i;
-      void cd.blockProofs.then(
+      void cd.subTreeProofs.then(
         subTreeProofs => {
           if (this.cancelled || !this.state?.verifyState()) {
             return;
@@ -227,7 +222,7 @@ export class TopTreeOrchestrator extends ProvingScheduler {
   private enqueueCheckpointRoot(
     state: TopTreeProvingState,
     checkpointIndex: number,
-    blockProofs: PublicInputsAndRecursiveProof<
+    blockProofOutputs: PublicInputsAndRecursiveProof<
       BlockRollupPublicInputs,
       typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
     >[],
@@ -236,7 +231,13 @@ export class TopTreeOrchestrator extends ProvingScheduler {
     outHashHint: OutHashHint,
     startBlobAccumulator: BatchedBlobAccumulator,
   ) {
-    void this.buildCheckpointRootInputs(blockProofs, inboxParityProof, cd, outHashHint, startBlobAccumulator).then(
+    void this.buildCheckpointRootInputs(
+      blockProofOutputs,
+      inboxParityProof,
+      cd,
+      outHashHint,
+      startBlobAccumulator,
+    ).then(
       inputs => {
         this.deferredProving(
           state,
@@ -269,7 +270,7 @@ export class TopTreeOrchestrator extends ProvingScheduler {
   }
 
   private async buildCheckpointRootInputs(
-    blockProofs: PublicInputsAndRecursiveProof<
+    blockProofOutputs: PublicInputsAndRecursiveProof<
       BlockRollupPublicInputs,
       typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
     >[],
@@ -293,7 +294,7 @@ export class TopTreeOrchestrator extends ProvingScheduler {
     });
 
     const inboxParity = toProofData(inboxParityProof);
-    const proofDatas = blockProofs.map(p => toProofData(p));
+    const proofDatas = blockProofOutputs.map(p => toProofData(p));
     return proofDatas.length === 1
       ? new CheckpointRootSingleBlockRollupPrivateInputs(proofDatas[0], inboxParity, hints)
       : new CheckpointRootRollupPrivateInputs([proofDatas[0], proofDatas[1]], inboxParity, hints);

yarn-project/prover-client/src/test/bb_prover_full_rollup.test.ts

@@ -103,7 +103,7 @@ describe('prover/bb_prover/full-rollup', () => {
           }
 
           topTreeData.push({
-            blockProofs: subTree
+            subTreeProofs: subTree
               .getSubTreeResult()
               .then(r => ({ blockProofOutputs: r.blockProofOutputs, inboxParityProof: r.inboxParityProof })),
             l2ToL1MsgsPerBlock: blocks.map(b => b.txs.map(tx => tx.txEffect.l2ToL1Msgs)),

yarn-project/prover-client/src/test/regenerate_rollup_sample_inputs.test.ts

@@ -154,7 +154,7 @@ describeOrSkip('prover/regenerate-rollup-sample-inputs', () => {
           }
 
           topTreeData.push({
-            blockProofs: subTree
+            subTreeProofs: subTree
               .getSubTreeResult()
               .then(r => ({ blockProofOutputs: r.blockProofOutputs, inboxParityProof: r.inboxParityProof })),
             l2ToL1MsgsPerBlock: blocks.map(b => b.txs.map(tx => tx.txEffect.l2ToL1Msgs)),

yarn-project/prover-node/src/actions/rerun-epoch-proving-job.ts

@@ -95,9 +95,9 @@ export async function rerunCheckpointProvingJob(
 
   const prover = await buildCheckpointProver(ctx, 0, log);
   try {
-    const blockProofs = await prover.whenBlockProofsReady();
-    log.info(`Completed proving for checkpoint ${checkpointNumber} with ${blockProofs.length} block proof(s)`);
-    return blockProofs;
+    const { blockProofOutputs } = await prover.whenSubTreeProofsReady();
+    log.info(`Completed proving for checkpoint ${checkpointNumber} with ${blockProofOutputs.length} block proof(s)`);
+    return blockProofOutputs;
   } finally {
     prover.cancel({ routine: true });
     await prover.whenDone();

yarn-project/prover-node/src/job/checkpoint-prover.test.ts

@@ -134,13 +134,13 @@ describe('CheckpointProver', () => {
       await prover.whenDone();
     });
 
-    it('rejects whenBlockProofsReady() but does not mark the prover failed or fire onFailed', async () => {
+    it('rejects whenSubTreeProofsReady() but does not mark the prover failed or fire onFailed', async () => {
       // A cancel (reorg/prune/shutdown) is not a proving failure: isFailed() must stay false and the
       // onFailed callback must not fire (no post-mortem upload for a cancelled prover).
       const prover = makeProver();
-      const blockProofs = prover.whenBlockProofsReady();
+      const subTreeProofs = prover.whenSubTreeProofsReady();
       prover.cancel();
-      await expect(blockProofs).rejects.toThrow(/cancelled/);
+      await expect(subTreeProofs).rejects.toThrow(/cancelled/);
       expect(prover.isFailed()).toBe(false);
       expect(onFailed).not.toHaveBeenCalled();
       await prover.whenDone();
@@ -161,11 +161,11 @@ describe('CheckpointProver', () => {
 
     it('routine cancel still aborts and rejects block proofs (only log level differs)', async () => {
       const prover = makeProver();
-      const blockProofs = prover.whenBlockProofsReady();
+      const subTreeProofs = prover.whenSubTreeProofsReady();
       prover.cancel({ routine: true });
       expect(prover.isCancelled()).toBe(true);
       expect(prover.getAbortSignal().aborted).toBe(true);
-      await expect(blockProofs).rejects.toThrow(/cancelled/);
+      await expect(subTreeProofs).rejects.toThrow(/cancelled/);
       await prover.whenDone();
     });
   });
@@ -221,7 +221,7 @@ describe('CheckpointProver', () => {
   // ---------------- gather failure ----------------
 
   describe('gather failures', () => {
-    it('rejects whenBlockProofsReady when txProvider returns missing txs', async () => {
+    it('rejects whenSubTreeProofsReady when txProvider returns missing txs', async () => {
       const missingHash = checkpoint.blocks[0].body.txEffects[0]?.txHash;
       // Without a real missing hash the per-block payload would be empty and the prover
       // would happily proceed; only checkpoints with txs can exercise this branch.
@@ -232,7 +232,7 @@ describe('CheckpointProver', () => {
       txProvider.getTxsForBlock.mockResolvedValue({ txs: [], missingTxs: [missingHash] });
 
       const prover = makeProver();
-      await expect(prover.whenBlockProofsReady()).rejects.toThrow(/Txs not found/);
+      await expect(prover.whenSubTreeProofsReady()).rejects.toThrow(/Txs not found/);
       await prover.whenDone();
     });
 
@@ -245,19 +245,19 @@ describe('CheckpointProver', () => {
       txProvider.getTxsForBlock.mockReturnValue(gate.promise);
 
       const prover = makeProver();
-      const blockProofs = prover.whenBlockProofsReady();
+      const subTreeProofs = prover.whenSubTreeProofsReady();
       prover.cancel();
       gate.reject(new Error('gather aborted by test'));
-      await expect(blockProofs).rejects.toThrow(/cancelled/);
+      await expect(subTreeProofs).rejects.toThrow(/cancelled/);
       await expect(prover.whenDone()).resolves.toBeUndefined();
     });
 
-    it('lets a second whenBlockProofsReady caller observe the same rejection', async () => {
+    it('lets a second whenSubTreeProofsReady caller observe the same rejection', async () => {
       // Two callers awaiting the same promise both see the rejection — neither leaks an
       // unhandled rejection (the constructor pre-attaches a noop catch handler).
       const prover = makeProver();
-      const a = prover.whenBlockProofsReady();
-      const b = prover.whenBlockProofsReady();
+      const a = prover.whenSubTreeProofsReady();
+      const b = prover.whenSubTreeProofsReady();
       prover.cancel();
       await Promise.all([expect(a).rejects.toThrow(/cancelled/), expect(b).rejects.toThrow(/cancelled/)]);
       await prover.whenDone();
@@ -274,7 +274,7 @@ describe('CheckpointProver', () => {
 
       const prover = makeProver();
       failure.resolve({ txs: [], missingTxs: [missingHash] });
-      await expect(prover.whenBlockProofsReady()).rejects.toThrow(/Txs not found/);
+      await expect(prover.whenSubTreeProofsReady()).rejects.toThrow(/Txs not found/);
       // Subsequent cancel is a no-op; no throws.
       prover.cancel();
       expect(prover.isCancelled()).toBe(true);
@@ -285,10 +285,10 @@ describe('CheckpointProver', () => {
   // ---------------- data-plane reorg fork fault ----------------
 
   describe('data-plane reorg fault', () => {
-    it('rejects whenBlockProofsReady when a world-state fork faults mid-proof', async () => {
+    it('rejects whenSubTreeProofsReady when a world-state fork faults mid-proof', async () => {
       // Models the data-plane prune race: gather succeeds and the sub-tree starts, but the
       // world-state synchronizer has already unwound the base block, so forking it faults inside
-      // executeCheckpoint. The fault must reject whenBlockProofsReady() AND mark the prover failed, so
+      // executeCheckpoint. The fault must reject whenSubTreeProofsReady() AND mark the prover failed, so
       // the SessionManager won't build (or rebuild) an EpochSession over it until a re-add replaces it.
       txProvider.getTxsForBlock.mockReset();
       txProvider.getTxsForBlock.mockResolvedValue({ txs: [], missingTxs: [] });
@@ -310,9 +310,9 @@ describe('CheckpointProver', () => {
 
       const prover = makeProver();
 
-      // blockProofs rejects: the fork error aborts the block loop before completion, so the sub-tree
+      // subTreeProofs rejects: the fork error aborts the block loop before completion, so the sub-tree
       // never yields proofs. (The raw fork error is logged; the promise settles as not-completed.)
-      await expect(prover.whenBlockProofsReady()).rejects.toThrow(/did not complete block processing/);
+      await expect(prover.whenSubTreeProofsReady()).rejects.toThrow(/did not complete block processing/);
       expect(dbProvider.fork).toHaveBeenCalled();
       expect(prover.isFailed()).toBe(true);
       // The owner is notified exactly once, with this prover, so it can upload a checkpoint post-mortem.