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

package/dest/orchestrator/chonk-cache.d.ts

@@ -0,0 +1,39 @@
+import type { NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH } from '@aztec/constants';
+import { type LoggerBindings } 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 declare class ChonkCache {
+    private readonly cache;
+    private readonly pending;
+    private readonly log;
+    private stopped;
+    constructor(bindings?: LoggerBindings);
+    /** Returns the cached promise for `txHash`, or `undefined` if none is registered. */
+    get(txHash: string): Promise<ChonkVerifierProofResult> | undefined;
+    /**
+     * 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.
+     */
+    getOrCompute(txHash: string, factory: (signal: AbortSignal) => Promise<ChonkVerifierProofResult>): Promise<ChonkVerifierProofResult>;
+    /** Drops cache entries for every tx in the supplied blocks. */
+    releaseForBlocks(blocks: L2Block[]): void;
+    /** Aborts every in-flight chonk-verifier job and clears the cache. */
+    stop(): void;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2hvbmstY2FjaGUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9vcmNoZXN0cmF0b3IvY2hvbmstY2FjaGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUseUNBQXlDLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUNsRixPQUFPLEVBQWUsS0FBSyxjQUFjLEVBQWdCLE1BQU0sdUJBQXVCLENBQUM7QUFDdkYsT0FBTyxLQUFLLEVBQUUsT0FBTyxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDbkQsT0FBTyxLQUFLLEVBQUUsNkJBQTZCLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUNyRixPQUFPLEtBQUssRUFBRSwrQkFBK0IsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRTVFLDJEQUEyRDtBQUMzRCxNQUFNLE1BQU0sd0JBQXdCLEdBQUcsNkJBQTZCLENBQ2xFLCtCQUErQixFQUMvQixPQUFPLHlDQUF5QyxDQUNqRCxDQUFDO0FBRUY7Ozs7Ozs7O0dBUUc7QUFDSCxxQkFBYSxVQUFVO0lBQ3JCLE9BQU8sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUF3RDtJQUM5RSxPQUFPLENBQUMsUUFBUSxDQUFDLE9BQU8sQ0FBc0M7SUFDOUQsT0FBTyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQVM7SUFDN0IsT0FBTyxDQUFDLE9BQU8sQ0FBUztJQUV4QixZQUFZLFFBQVEsQ0FBQyxFQUFFLGNBQWMsRUFFcEM7SUFFRCxxRkFBcUY7SUFDOUUsR0FBRyxDQUFDLE1BQU0sRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLHdCQUF3QixDQUFDLEdBQUcsU0FBUyxDQUV4RTtJQUVEOzs7Ozs7O09BT0c7SUFDSSxZQUFZLENBQ2pCLE1BQU0sRUFBRSxNQUFNLEVBQ2QsT0FBTyxFQUFFLENBQUMsTUFBTSxFQUFFLFdBQVcsS0FBSyxPQUFPLENBQUMsd0JBQXdCLENBQUMsR0FDbEUsT0FBTyxDQUFDLHdCQUF3QixDQUFDLENBbUJuQztJQUVELCtEQUErRDtJQUN4RCxnQkFBZ0IsQ0FBQyxNQUFNLEVBQUUsT0FBTyxFQUFFLEdBQUcsSUFBSSxDQWUvQztJQUVELHNFQUFzRTtJQUMvRCxJQUFJLElBQUksSUFBSSxDQVVsQjtDQUNGIn0=

package/dest/orchestrator/chonk-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chonk-cache.d.ts","sourceRoot":"","sources":["../../src/orchestrator/chonk-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAe,KAAK,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AACvF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,sBAAsB,CAAC;AAE5E,2DAA2D;AAC3D,MAAM,MAAM,wBAAwB,GAAG,6BAA6B,CAClE,+BAA+B,EAC/B,OAAO,yCAAyC,CACjD,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwD;IAC9E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,QAAQ,CAAC,EAAE,cAAc,EAEpC;IAED,qFAAqF;IAC9E,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,GAAG,SAAS,CAExE;IAED;;;;;;;OAOG;IACI,YAAY,CACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,wBAAwB,CAAC,GAClE,OAAO,CAAC,wBAAwB,CAAC,CAmBnC;IAED,+DAA+D;IACxD,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAe/C;IAED,sEAAsE;IAC/D,IAAI,IAAI,IAAI,CAUlB;CACF"}

package/dest/orchestrator/chonk-cache.js

@@ -0,0 +1,80 @@
+import { createLogger } from '@aztec/foundation/log';
+/**
+ * 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 {
+    cache = new Map();
+    pending = new Map();
+    log;
+    stopped = false;
+    constructor(bindings){
+        this.log = createLogger('prover-client:chonk-cache', bindings);
+    }
+    /** Returns the cached promise for `txHash`, or `undefined` if none is registered. */ get(txHash) {
+        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.
+   */ getOrCompute(txHash, factory) {
+        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. */ releaseForBlocks(blocks) {
+        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. */ stop() {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        for (const controller of this.pending.values()){
+            controller.abort();
+        }
+        this.pending.clear();
+        this.cache.clear();
+    }
+}

package/dest/orchestrator/index.d.ts

@@ -1,2 +1,4 @@
-export { ProvingOrchestrator } from './orchestrator.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9vcmNoZXN0cmF0b3IvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sbUJBQW1CLENBQUMifQ==
+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';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9vcmNoZXN0cmF0b3IvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLDZCQUE2QixFQUFFLEtBQUssYUFBYSxFQUFFLE1BQU0sdUNBQXVDLENBQUM7QUFDMUcsT0FBTyxFQUFFLFVBQVUsRUFBRSxLQUFLLHdCQUF3QixFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDN0UsT0FBTyxFQUNMLG1CQUFtQixFQUNuQixxQkFBcUIsRUFDckIsS0FBSyxxQkFBcUIsRUFDMUIsS0FBSyxhQUFhLEdBQ25CLE1BQU0sNEJBQTRCLENBQUMifQ==

package/dest/orchestrator/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestrator/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestrator/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,KAAK,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAE,KAAK,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,4BAA4B,CAAC"}

package/dest/orchestrator/index.js

@@ -1 +1,3 @@
-export { ProvingOrchestrator } from './orchestrator.js';
+export { CheckpointSubTreeOrchestrator } from './checkpoint-sub-tree-orchestrator.js';
+export { ChonkCache } from './chonk-cache.js';
+export { TopTreeOrchestrator, TopTreeCancelledError } from './top-tree-orchestrator.js';

package/dest/orchestrator/proving-scheduler.d.ts

@@ -0,0 +1,81 @@
+import { type Logger, type LoggerBindings } from '@aztec/foundation/log';
+import { SerialQueue } from '@aztec/foundation/queue';
+/**
+ * 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 declare abstract class ProvingScheduler {
+    private readonly deferredJobQueue;
+    protected pendingProvingJobs: AbortController[];
+    protected logger: Logger;
+    constructor(deferredJobQueue: SerialQueue, loggerName?: string, bindings?: LoggerBindings);
+    /** Number of broker jobs currently in flight. */
+    getNumPendingProvingJobs(): number;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    stop(): Promise<void>;
+    /**
+     * 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): void;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJvdmluZy1zY2hlZHVsZXIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9vcmNoZXN0cmF0b3IvcHJvdmluZy1zY2hlZHVsZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLEtBQUssTUFBTSxFQUFFLEtBQUssY0FBYyxFQUFnQixNQUFNLHVCQUF1QixDQUFDO0FBQ3ZGLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUd0RDs7OztHQUlHO0FBQ0gsTUFBTSxXQUFXLGdCQUFnQjtJQUMvQixnRkFBZ0Y7SUFDaEYsV0FBVyxJQUFJLE9BQU8sQ0FBQztJQUN2QixxREFBcUQ7SUFDckQsTUFBTSxDQUFDLE1BQU0sRUFBRSxNQUFNLEdBQUcsSUFBSSxDQUFDO0NBQzlCO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0F5Qkc7QUFDSCw4QkFBc0IsZ0JBQWdCO0lBS2xDLE9BQU8sQ0FBQyxRQUFRLENBQUMsZ0JBQWdCO0lBSm5DLFNBQVMsQ0FBQyxrQkFBa0IsRUFBRSxlQUFlLEVBQUUsQ0FBTTtJQUNyRCxTQUFTLENBQUMsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUV6QixZQUNtQixnQkFBZ0IsRUFBRSxXQUFXLEVBQzlDLFVBQVUsU0FBb0MsRUFDOUMsUUFBUSxDQUFDLEVBQUUsY0FBYyxFQUcxQjtJQUVELGlEQUFpRDtJQUMxQyx3QkFBd0IsSUFBSSxNQUFNLENBRXhDO0lBRUQ7Ozs7Ozs7T0FPRztJQUNILFNBQVMsQ0FBQyxtQkFBbUIsQ0FBQyxTQUFTLEVBQUUsT0FBTyxHQUFHLElBQUksQ0FNdEQ7SUFFRDs7OztPQUlHO0lBQ0gsU0FBUyxDQUFDLFFBQVEsQ0FBQyxjQUFjLElBQUksSUFBSSxDQUFDO0lBRTFDOzs7T0FHRztJQUNJLElBQUksSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBRzNCO0lBRUQ7Ozs7Ozs7Ozs7O09BV0c7SUFDSCxTQUFTLENBQUMsZUFBZSxDQUFDLENBQUMsU0FBUyxnQkFBZ0IsRUFBRSxDQUFDLEVBQ3JELEtBQUssRUFBRSxDQUFDLEVBQ1IsT0FBTyxFQUFFLENBQUMsTUFBTSxFQUFFLFdBQVcsS0FBSyxPQUFPLENBQUMsQ0FBQyxDQUFDLEVBQzVDLFFBQVEsRUFBRSxDQUFDLE1BQU0sRUFBRSxDQUFDLEtBQUssSUFBSSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsRUFDN0MsV0FBVyxHQUFFLE1BQU0sT0FBcUIsR0FDdkMsSUFBSSxDQWlETjtDQUNGIn0=

package/dest/orchestrator/proving-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proving-scheduler.d.ts","sourceRoot":"","sources":["../../src/orchestrator/proving-scheduler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGtD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,WAAW,IAAI,OAAO,CAAC;IACvB,qDAAqD;IACrD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,gBAAgB;IAKlC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAJnC,SAAS,CAAC,kBAAkB,EAAE,eAAe,EAAE,CAAM;IACrD,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IAEzB,YACmB,gBAAgB,EAAE,WAAW,EAC9C,UAAU,SAAoC,EAC9C,QAAQ,CAAC,EAAE,cAAc,EAG1B;IAED,iDAAiD;IAC1C,wBAAwB,IAAI,MAAM,CAExC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAMtD;IAED;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,IAAI,IAAI,CAAC;IAE1C;;;OAGG;IACI,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,EACrD,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5C,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC7C,WAAW,GAAE,MAAM,OAAqB,GACvC,IAAI,CAiDN;CACF"}

package/dest/orchestrator/proving-scheduler.js

@@ -0,0 +1,120 @@
+import { AbortError } from '@aztec/foundation/error';
+import { createLogger } from '@aztec/foundation/log';
+import { sleep } from '@aztec/foundation/sleep';
+/**
+ * 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 class ProvingScheduler {
+    deferredJobQueue;
+    pendingProvingJobs;
+    logger;
+    constructor(deferredJobQueue, loggerName = 'prover-client:proving-scheduler', bindings){
+        this.deferredJobQueue = deferredJobQueue;
+        this.pendingProvingJobs = [];
+        this.logger = createLogger(loggerName, bindings);
+    }
+    /** Number of broker jobs currently in flight. */ getNumPendingProvingJobs() {
+        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).
+   */ resetSchedulerState(abortJobs) {
+        if (abortJobs) {
+            for (const controller of this.pendingProvingJobs){
+                controller.abort();
+            }
+        }
+    }
+    /**
+   * 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.
+   */ stop() {
+        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.
+   */ deferredProving(state, request, callback, isCancelled = ()=>false) {
+        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/dest/orchestrator/top-tree-orchestrator.d.ts

@@ -0,0 +1,88 @@
+import { type FinalBlobBatchingChallenges } from '@aztec/blob-lib';
+import type { BatchedBlob } from '@aztec/blob-lib/types';
+import { type ARCHIVE_HEIGHT, type 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 { SerialQueue } from '@aztec/foundation/queue';
+import type { Tuple } from '@aztec/foundation/serialize';
+import type { EthAddress } from '@aztec/stdlib/block';
+import type { PublicInputsAndRecursiveProof, ServerCircuitProver } from '@aztec/stdlib/interfaces/server';
+import type { Proof } from '@aztec/stdlib/proofs';
+import { type BlockRollupPublicInputs, type RootRollupPublicInputs } from '@aztec/stdlib/rollup';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+import { type TelemetryClient } from '@aztec/telemetry-client';
+import { ProvingScheduler } from './proving-scheduler.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 declare class TopTreeCancelledError extends Error {
+    constructor(reason?: string);
+}
+/**
+ * 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 declare class TopTreeOrchestrator extends ProvingScheduler {
+    protected readonly prover: ServerCircuitProver;
+    private readonly proverId;
+    private state;
+    private cancelled;
+    constructor(prover: ServerCircuitProver, proverId: EthAddress, deferredJobQueue: SerialQueue, _telemetryClient?: TelemetryClient, bindings?: LoggerBindings);
+    getProverId(): EthAddress;
+    /**
+     * 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.
+     */
+    prove(epochNumber: EpochNumber, totalNumCheckpoints: number, finalBlobBatchingChallenges: FinalBlobBatchingChallenges, checkpointData: CheckpointTopTreeData[]): Promise<TopTreeResult>;
+    /**
+     * 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.
+     */
+    cancel({ abortJobs }: {
+        abortJobs: boolean;
+    }): void;
+    /** Standard shutdown — preserve the broker queue (`abortJobs: false`). */
+    protected cancelInternal(): void;
+    private enqueueCheckpointRoot;
+    private buildCheckpointRootInputs;
+    private enqueueCheckpointMergeRollup;
+    private enqueueEpochPadding;
+    private enqueueRootRollup;
+    private checkAndEnqueueNextCheckpointMergeRollup;
+    private checkAndEnqueueRootRollup;
+    private computeOutHashHints;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidG9wLXRyZWUtb3JjaGVzdHJhdG9yLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvb3JjaGVzdHJhdG9yL3RvcC10cmVlLW9yY2hlc3RyYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQTBCLEtBQUssMkJBQTJCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUMzRixPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN6RCxPQUFPLEVBQ0wsS0FBSyxjQUFjLEVBR25CLEtBQUsseUNBQXlDLEVBRS9DLE1BQU0sa0JBQWtCLENBQUM7QUFDMUIsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFHbkUsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ3BELE9BQU8sS0FBSyxFQUFFLGNBQWMsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRTVELE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQzNELE9BQU8sS0FBSyxFQUFFLEtBQUssRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRXpELE9BQU8sS0FBSyxFQUFFLFVBQVUsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxFQUFFLDZCQUE2QixFQUFFLG1CQUFtQixFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFFMUcsT0FBTyxLQUFLLEVBQUUsS0FBSyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDbEQsT0FBTyxFQUNMLEtBQUssdUJBQXVCLEVBSTVCLEtBQUssc0JBQXNCLEVBQzVCLE1BQU0sc0JBQXNCLENBQUM7QUFFOUIsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDcEQsT0FBTyxFQUFFLEtBQUssZUFBZSxFQUFzQixNQUFNLHlCQUF5QixDQUFDO0FBR25GLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRzFELGlEQUFpRDtBQUNqRCxNQUFNLE1BQU0scUJBQXFCLEdBQUc7SUFDbEM7Ozs7T0FJRztJQUNILFdBQVcsRUFBRSxPQUFPLENBQ2xCLDZCQUE2QixDQUFDLHVCQUF1QixFQUFFLE9BQU8seUNBQXlDLENBQUMsRUFBRSxDQUMzRyxDQUFDO0lBQ0YsbUZBQW1GO0lBQ25GLGtCQUFrQixFQUFFLEVBQUUsRUFBRSxFQUFFLEVBQUUsQ0FBQztJQUM3Qiw4RkFBOEY7SUFDOUYsVUFBVSxFQUFFLEVBQUUsRUFBRSxDQUFDO0lBQ2pCLG9HQUFvRztJQUNwRyxtQkFBbUIsRUFBRSxXQUFXLENBQUM7SUFDakMsbUZBQW1GO0lBQ25GLDBCQUEwQixFQUFFLEtBQUssQ0FBQyxFQUFFLEVBQUUsT0FBTyxjQUFjLENBQUMsQ0FBQztDQUM5RCxDQUFDO0FBRUYsc0NBQXNDO0FBQ3RDLE1BQU0sTUFBTSxhQUFhLEdBQUc7SUFDMUIsWUFBWSxFQUFFLHNCQUFzQixDQUFDO0lBQ3JDLEtBQUssRUFBRSxLQUFLLENBQUM7SUFDYixpQkFBaUIsRUFBRSxXQUFXLENBQUM7Q0FDaEMsQ0FBQztBQUVGOzs7R0FHRztBQUNILHFCQUFhLHFCQUFzQixTQUFRLEtBQUs7SUFDOUMsWUFBWSxNQUFNLFNBQStCLEVBR2hEO0NBQ0Y7QUFPRDs7Ozs7Ozs7R0FRRztBQUNILHFCQUFhLG1CQUFvQixTQUFRLGdCQUFnQjtJQUtyRCxTQUFTLENBQUMsUUFBUSxDQUFDLE1BQU0sRUFBRSxtQkFBbUI7SUFDOUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxRQUFRO0lBTDNCLE9BQU8sQ0FBQyxLQUFLLENBQWtDO0lBQy9DLE9BQU8sQ0FBQyxTQUFTLENBQVM7SUFFMUIsWUFDcUIsTUFBTSxFQUFFLG1CQUFtQixFQUM3QixRQUFRLEVBQUUsVUFBVSxFQUNyQyxnQkFBZ0IsRUFBRSxXQUFXLEVBQzdCLGdCQUFnQixHQUFFLGVBQXNDLEVBQ3hELFFBQVEsQ0FBQyxFQUFFLGNBQWMsRUFHMUI7SUFFTSxXQUFXLElBQUksVUFBVSxDQUUvQjtJQUVEOzs7O09BSUc7SUFDVSxLQUFLLENBQ2hCLFdBQVcsRUFBRSxXQUFXLEVBQ3hCLG1CQUFtQixFQUFFLE1BQU0sRUFDM0IsMkJBQTJCLEVBQUUsMkJBQTJCLEVBQ3hELGNBQWMsRUFBRSxxQkFBcUIsRUFBRSxHQUN0QyxPQUFPLENBQUMsYUFBYSxDQUFDLENBaUZ4QjtJQUVEOzs7OztPQUtHO0lBQ0ksTUFBTSxDQUFDLEVBQUUsU0FBUyxFQUFFLEVBQUU7UUFBRSxTQUFTLEVBQUUsT0FBTyxDQUFBO0tBQUUsUUFJbEQ7SUFFRCw0RUFBMEU7SUFDMUUsVUFBbUIsY0FBYyxJQUFJLElBQUksQ0FFeEM7SUFJRCxPQUFPLENBQUMscUJBQXFCO1lBMkNmLHlCQUF5QjtJQStCdkMsT0FBTyxDQUFDLDRCQUE0QjtJQWVwQyxPQUFPLENBQUMsbUJBQW1CO0lBZTNCLE9BQU8sQ0FBQyxpQkFBaUI7SUFnQnpCLE9BQU8sQ0FBQyx3Q0FBd0M7SUFZaEQsT0FBTyxDQUFDLHlCQUF5QjtZQU9uQixtQkFBbUI7Q0F5QmxDIn0=

package/dest/orchestrator/top-tree-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"top-tree-orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator/top-tree-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,yCAAyC,EAE/C,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAGnE,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE1G,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,KAAK,uBAAuB,EAI5B,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,eAAe,EAAsB,MAAM,yBAAyB,CAAC;AAGnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,iDAAiD;AACjD,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAClB,6BAA6B,CAAC,uBAAuB,EAAE,OAAO,yCAAyC,CAAC,EAAE,CAC3G,CAAC;IACF,mFAAmF;IACnF,kBAAkB,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;IAC7B,8FAA8F;IAC9F,UAAU,EAAE,EAAE,EAAE,CAAC;IACjB,oGAAoG;IACpG,mBAAmB,EAAE,WAAW,CAAC;IACjC,mFAAmF;IACnF,0BAA0B,EAAE,KAAK,CAAC,EAAE,EAAE,OAAO,cAAc,CAAC,CAAC;CAC9D,CAAC;AAEF,sCAAsC;AACtC,MAAM,MAAM,aAAa,GAAG;IAC1B,YAAY,EAAE,sBAAsB,CAAC;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,iBAAiB,EAAE,WAAW,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,MAAM,SAA+B,EAGhD;CACF;AAOD;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;IAKrD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,SAAS,CAAS;IAE1B,YACqB,MAAM,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,UAAU,EACrC,gBAAgB,EAAE,WAAW,EAC7B,gBAAgB,GAAE,eAAsC,EACxD,QAAQ,CAAC,EAAE,cAAc,EAG1B;IAEM,WAAW,IAAI,UAAU,CAE/B;IAED;;;;OAIG;IACU,KAAK,CAChB,WAAW,EAAE,WAAW,EACxB,mBAAmB,EAAE,MAAM,EAC3B,2BAA2B,EAAE,2BAA2B,EACxD,cAAc,EAAE,qBAAqB,EAAE,GACtC,OAAO,CAAC,aAAa,CAAC,CAiFxB;IAED;;;;;OAKG;IACI,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,QAIlD;IAED,4EAA0E;IAC1E,UAAmB,cAAc,IAAI,IAAI,CAExC;IAID,OAAO,CAAC,qBAAqB;YA2Cf,yBAAyB;IA+BvC,OAAO,CAAC,4BAA4B;IAepC,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,wCAAwC;IAYhD,OAAO,CAAC,yBAAyB;YAOnB,mBAAmB;CAyBlC"}