@aztec-labs/prover-client 6.0.0-nightly.20260829

package/dest/orchestrator/checkpoint-sub-tree-orchestrator.js

@@ -0,0 +1,1047 @@
+function applyDecs2203RFactory() {
+    function createAddInitializerMethod(initializers, decoratorFinishedRef) {
+        return function addInitializer(initializer) {
+            assertNotFinished(decoratorFinishedRef, "addInitializer");
+            assertCallable(initializer, "An initializer");
+            initializers.push(initializer);
+        };
+    }
+    function memberDec(dec, name, desc, initializers, kind, isStatic, isPrivate, metadata, value) {
+        var kindStr;
+        switch(kind){
+            case 1:
+                kindStr = "accessor";
+                break;
+            case 2:
+                kindStr = "method";
+                break;
+            case 3:
+                kindStr = "getter";
+                break;
+            case 4:
+                kindStr = "setter";
+                break;
+            default:
+                kindStr = "field";
+        }
+        var ctx = {
+            kind: kindStr,
+            name: isPrivate ? "#" + name : name,
+            static: isStatic,
+            private: isPrivate,
+            metadata: metadata
+        };
+        var decoratorFinishedRef = {
+            v: false
+        };
+        ctx.addInitializer = createAddInitializerMethod(initializers, decoratorFinishedRef);
+        var get, set;
+        if (kind === 0) {
+            if (isPrivate) {
+                get = desc.get;
+                set = desc.set;
+            } else {
+                get = function() {
+                    return this[name];
+                };
+                set = function(v) {
+                    this[name] = v;
+                };
+            }
+        } else if (kind === 2) {
+            get = function() {
+                return desc.value;
+            };
+        } else {
+            if (kind === 1 || kind === 3) {
+                get = function() {
+                    return desc.get.call(this);
+                };
+            }
+            if (kind === 1 || kind === 4) {
+                set = function(v) {
+                    desc.set.call(this, v);
+                };
+            }
+        }
+        ctx.access = get && set ? {
+            get: get,
+            set: set
+        } : get ? {
+            get: get
+        } : {
+            set: set
+        };
+        try {
+            return dec(value, ctx);
+        } finally{
+            decoratorFinishedRef.v = true;
+        }
+    }
+    function assertNotFinished(decoratorFinishedRef, fnName) {
+        if (decoratorFinishedRef.v) {
+            throw new Error("attempted to call " + fnName + " after decoration was finished");
+        }
+    }
+    function assertCallable(fn, hint) {
+        if (typeof fn !== "function") {
+            throw new TypeError(hint + " must be a function");
+        }
+    }
+    function assertValidReturnValue(kind, value) {
+        var type = typeof value;
+        if (kind === 1) {
+            if (type !== "object" || value === null) {
+                throw new TypeError("accessor decorators must return an object with get, set, or init properties or void 0");
+            }
+            if (value.get !== undefined) {
+                assertCallable(value.get, "accessor.get");
+            }
+            if (value.set !== undefined) {
+                assertCallable(value.set, "accessor.set");
+            }
+            if (value.init !== undefined) {
+                assertCallable(value.init, "accessor.init");
+            }
+        } else if (type !== "function") {
+            var hint;
+            if (kind === 0) {
+                hint = "field";
+            } else if (kind === 10) {
+                hint = "class";
+            } else {
+                hint = "method";
+            }
+            throw new TypeError(hint + " decorators must return a function or void 0");
+        }
+    }
+    function applyMemberDec(ret, base, decInfo, name, kind, isStatic, isPrivate, initializers, metadata) {
+        var decs = decInfo[0];
+        var desc, init, value;
+        if (isPrivate) {
+            if (kind === 0 || kind === 1) {
+                desc = {
+                    get: decInfo[3],
+                    set: decInfo[4]
+                };
+            } else if (kind === 3) {
+                desc = {
+                    get: decInfo[3]
+                };
+            } else if (kind === 4) {
+                desc = {
+                    set: decInfo[3]
+                };
+            } else {
+                desc = {
+                    value: decInfo[3]
+                };
+            }
+        } else if (kind !== 0) {
+            desc = Object.getOwnPropertyDescriptor(base, name);
+        }
+        if (kind === 1) {
+            value = {
+                get: desc.get,
+                set: desc.set
+            };
+        } else if (kind === 2) {
+            value = desc.value;
+        } else if (kind === 3) {
+            value = desc.get;
+        } else if (kind === 4) {
+            value = desc.set;
+        }
+        var newValue, get, set;
+        if (typeof decs === "function") {
+            newValue = memberDec(decs, name, desc, initializers, kind, isStatic, isPrivate, metadata, value);
+            if (newValue !== void 0) {
+                assertValidReturnValue(kind, newValue);
+                if (kind === 0) {
+                    init = newValue;
+                } else if (kind === 1) {
+                    init = newValue.init;
+                    get = newValue.get || value.get;
+                    set = newValue.set || value.set;
+                    value = {
+                        get: get,
+                        set: set
+                    };
+                } else {
+                    value = newValue;
+                }
+            }
+        } else {
+            for(var i = decs.length - 1; i >= 0; i--){
+                var dec = decs[i];
+                newValue = memberDec(dec, name, desc, initializers, kind, isStatic, isPrivate, metadata, value);
+                if (newValue !== void 0) {
+                    assertValidReturnValue(kind, newValue);
+                    var newInit;
+                    if (kind === 0) {
+                        newInit = newValue;
+                    } else if (kind === 1) {
+                        newInit = newValue.init;
+                        get = newValue.get || value.get;
+                        set = newValue.set || value.set;
+                        value = {
+                            get: get,
+                            set: set
+                        };
+                    } else {
+                        value = newValue;
+                    }
+                    if (newInit !== void 0) {
+                        if (init === void 0) {
+                            init = newInit;
+                        } else if (typeof init === "function") {
+                            init = [
+                                init,
+                                newInit
+                            ];
+                        } else {
+                            init.push(newInit);
+                        }
+                    }
+                }
+            }
+        }
+        if (kind === 0 || kind === 1) {
+            if (init === void 0) {
+                init = function(instance, init) {
+                    return init;
+                };
+            } else if (typeof init !== "function") {
+                var ownInitializers = init;
+                init = function(instance, init) {
+                    var value = init;
+                    for(var i = 0; i < ownInitializers.length; i++){
+                        value = ownInitializers[i].call(instance, value);
+                    }
+                    return value;
+                };
+            } else {
+                var originalInitializer = init;
+                init = function(instance, init) {
+                    return originalInitializer.call(instance, init);
+                };
+            }
+            ret.push(init);
+        }
+        if (kind !== 0) {
+            if (kind === 1) {
+                desc.get = value.get;
+                desc.set = value.set;
+            } else if (kind === 2) {
+                desc.value = value;
+            } else if (kind === 3) {
+                desc.get = value;
+            } else if (kind === 4) {
+                desc.set = value;
+            }
+            if (isPrivate) {
+                if (kind === 1) {
+                    ret.push(function(instance, args) {
+                        return value.get.call(instance, args);
+                    });
+                    ret.push(function(instance, args) {
+                        return value.set.call(instance, args);
+                    });
+                } else if (kind === 2) {
+                    ret.push(value);
+                } else {
+                    ret.push(function(instance, args) {
+                        return value.call(instance, args);
+                    });
+                }
+            } else {
+                Object.defineProperty(base, name, desc);
+            }
+        }
+    }
+    function applyMemberDecs(Class, decInfos, metadata) {
+        var ret = [];
+        var protoInitializers;
+        var staticInitializers;
+        var existingProtoNonFields = new Map();
+        var existingStaticNonFields = new Map();
+        for(var i = 0; i < decInfos.length; i++){
+            var decInfo = decInfos[i];
+            if (!Array.isArray(decInfo)) continue;
+            var kind = decInfo[1];
+            var name = decInfo[2];
+            var isPrivate = decInfo.length > 3;
+            var isStatic = kind >= 5;
+            var base;
+            var initializers;
+            if (isStatic) {
+                base = Class;
+                kind = kind - 5;
+                staticInitializers = staticInitializers || [];
+                initializers = staticInitializers;
+            } else {
+                base = Class.prototype;
+                protoInitializers = protoInitializers || [];
+                initializers = protoInitializers;
+            }
+            if (kind !== 0 && !isPrivate) {
+                var existingNonFields = isStatic ? existingStaticNonFields : existingProtoNonFields;
+                var existingKind = existingNonFields.get(name) || 0;
+                if (existingKind === true || existingKind === 3 && kind !== 4 || existingKind === 4 && kind !== 3) {
+                    throw new Error("Attempted to decorate a public method/accessor that has the same name as a previously decorated public method/accessor. This is not currently supported by the decorators plugin. Property name was: " + name);
+                } else if (!existingKind && kind > 2) {
+                    existingNonFields.set(name, kind);
+                } else {
+                    existingNonFields.set(name, true);
+                }
+            }
+            applyMemberDec(ret, base, decInfo, name, kind, isStatic, isPrivate, initializers, metadata);
+        }
+        pushInitializers(ret, protoInitializers);
+        pushInitializers(ret, staticInitializers);
+        return ret;
+    }
+    function pushInitializers(ret, initializers) {
+        if (initializers) {
+            ret.push(function(instance) {
+                for(var i = 0; i < initializers.length; i++){
+                    initializers[i].call(instance);
+                }
+                return instance;
+            });
+        }
+    }
+    function applyClassDecs(targetClass, classDecs, metadata) {
+        if (classDecs.length > 0) {
+            var initializers = [];
+            var newClass = targetClass;
+            var name = targetClass.name;
+            for(var i = classDecs.length - 1; i >= 0; i--){
+                var decoratorFinishedRef = {
+                    v: false
+                };
+                try {
+                    var nextNewClass = classDecs[i](newClass, {
+                        kind: "class",
+                        name: name,
+                        addInitializer: createAddInitializerMethod(initializers, decoratorFinishedRef),
+                        metadata
+                    });
+                } finally{
+                    decoratorFinishedRef.v = true;
+                }
+                if (nextNewClass !== undefined) {
+                    assertValidReturnValue(10, nextNewClass);
+                    newClass = nextNewClass;
+                }
+            }
+            return [
+                defineMetadata(newClass, metadata),
+                function() {
+                    for(var i = 0; i < initializers.length; i++){
+                        initializers[i].call(newClass);
+                    }
+                }
+            ];
+        }
+    }
+    function defineMetadata(Class, metadata) {
+        return Object.defineProperty(Class, Symbol.metadata || Symbol.for("Symbol.metadata"), {
+            configurable: true,
+            enumerable: true,
+            value: metadata
+        });
+    }
+    return function applyDecs2203R(targetClass, memberDecs, classDecs, parentClass) {
+        if (parentClass !== void 0) {
+            var parentMetadata = parentClass[Symbol.metadata || Symbol.for("Symbol.metadata")];
+        }
+        var metadata = Object.create(parentMetadata === void 0 ? null : parentMetadata);
+        var e = applyMemberDecs(targetClass, memberDecs, metadata);
+        if (!classDecs.length) defineMetadata(targetClass, metadata);
+        return {
+            e: e,
+            get c () {
+                return applyClassDecs(targetClass, classDecs, metadata);
+            }
+        };
+    };
+}
+function _apply_decs_2203_r(targetClass, memberDecs, classDecs, parentClass) {
+    return (_apply_decs_2203_r = applyDecs2203RFactory())(targetClass, memberDecs, classDecs, parentClass);
+}
+var _dec, _dec1, _dec2, _dec3, _initProto;
+import { L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec-labs/constants';
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { AbortError } from '@aztec-labs/foundation/error';
+import { promiseWithResolvers } from '@aztec-labs/foundation/promise';
+import { assertLength } from '@aztec-labs/foundation/serialize';
+import { appendL1ToL2MessagesToTree } from '@aztec-labs/stdlib/messaging';
+import { PrivateTxBaseRollupPrivateInputs } from '@aztec-labs/stdlib/rollup';
+import { MerkleTreeId } from '@aztec-labs/stdlib/trees';
+import { Attributes, getTelemetryClient, trackSpan, wrapCallbackInSpan } from '@aztec-labs/telemetry-client';
+import { inspect } from 'util';
+import { buildHeaderFromCircuitOutputs, getFrontierSiblingPath, getLastSiblingPath, getPublicChonkVerifierPrivateInputsFromTx, getRootTreeSiblingPath, getTreeSnapshot, insertSideEffectsAndBuildBaseRollupHints, validatePartialState, validateTx } from './block-building-helpers.js';
+import { CheckpointProvingState } from './checkpoint-proving-state.js';
+import { ProvingOrchestratorMetrics } from './orchestrator_metrics.js';
+import { ProvingScheduler } from './proving-scheduler.js';
+import { TxProvingState } from './tx-proving-state.js';
+_dec = trackSpan('CheckpointSubTreeOrchestrator.startNewBlock', (blockNumber)=>({
+        [Attributes.BLOCK_NUMBER]: blockNumber
+    })), _dec1 = trackSpan('CheckpointSubTreeOrchestrator.addTxs', (txs)=>({
+        [Attributes.BLOCK_TXS_COUNT]: txs.length
+    })), _dec2 = trackSpan('CheckpointSubTreeOrchestrator.setBlockCompleted', (blockNumber)=>({
+        [Attributes.BLOCK_NUMBER]: blockNumber
+    })), _dec3 = trackSpan('CheckpointSubTreeOrchestrator.prepareBaseRollupInputs', (tx)=>({
+        [Attributes.TX_HASH]: tx.hash.toString()
+    }));
+/**
+ * Orchestrates block-level proving for a single checkpoint, stopping at the boundary
+ * where checkpoint root rollup would otherwise begin. Used by the per-checkpoint
+ * `CheckpointProver` in production; the top-tree orchestrator then composes the
+ * sub-tree's block proofs into the epoch proof.
+ *
+ * Wiring: a single-checkpoint mini-proving session is owned by the constructor. The
+ * canonical way to obtain a fully-started sub-tree is the `start` static factory,
+ * which also drives the single internal `startCheckpoint` call. The sub-tree never
+ * escalates past the checkpoint root boundary; `getSubTreeResult()` resolves once
+ * every block-level proof in the checkpoint's tree is ready.
+ */ export class CheckpointSubTreeOrchestrator extends ProvingScheduler {
+    dbProvider;
+    prover;
+    proverId;
+    chonkCache;
+    epochNumber;
+    cancelJobsOnStop;
+    static{
+        ({ e: [_initProto] } = _apply_decs_2203_r(this, [
+            [
+                _dec,
+                2,
+                "startNewBlock"
+            ],
+            [
+                _dec1,
+                2,
+                "addTxs"
+            ],
+            [
+                _dec2,
+                2,
+                "setBlockCompleted"
+            ],
+            [
+                _dec3,
+                2,
+                "prepareBaseRollupInputs"
+            ]
+        ], []));
+    }
+    /** The single checkpoint proving state this sub-tree owns. Allocated in the `start` factory. */ provingState;
+    subTreeResult;
+    metrics;
+    dbs;
+    constructor(dbProvider, prover, proverId, /**
+     * Shared chonk-verifier proof cache. Every chonk-verifier proof started by this
+     * sub-tree lives on the cache 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.
+     */ chonkCache, /** The epoch this sub-tree proves into. */ epochNumber, cancelJobsOnStop = false, deferredJobQueue, telemetryClient = getTelemetryClient(), bindings){
+        super(deferredJobQueue, 'prover-client:checkpoint-sub-tree-orchestrator', bindings), this.dbProvider = dbProvider, this.prover = prover, this.proverId = proverId, this.chonkCache = chonkCache, this.epochNumber = epochNumber, this.cancelJobsOnStop = cancelJobsOnStop, this.provingState = (_initProto(this), undefined), this.dbs = new Map(), this.cancelled = false;
+        this.metrics = new ProvingOrchestratorMetrics(telemetryClient, 'CheckpointSubTreeOrchestrator');
+        this.subTreeResult = promiseWithResolvers();
+        // 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(()=>{});
+    }
+    /** Tracks whether `cancel()` has been called; flows into the checkpoint state's isAlive hook. */ cancelled;
+    get tracer() {
+        return this.metrics.tracer;
+    }
+    getProverId() {
+        return this.proverId;
+    }
+    getNumActiveForks() {
+        return this.dbs.size;
+    }
+    /** Returns a promise that resolves when block-level proving completes for the checkpoint. */ getSubTreeResult() {
+        return this.subTreeResult.promise;
+    }
+    /**
+   * Returns the archive sibling path captured at the internal checkpoint start.
+   * 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.
+   */ getPreviousArchiveSiblingPath() {
+        if (!this.provingState) {
+            throw new Error('Checkpoint not started; call CheckpointSubTreeOrchestrator.start first.');
+        }
+        return this.provingState.getLastArchiveSiblingPath();
+    }
+    /**
+   * Constructs and starts a sub-tree for a single checkpoint. The returned sub-tree
+   * has had its single internal checkpoint state allocated; callers proceed directly
+   * to per-block `startNewBlock` / `addTxs` / `setBlockCompleted`.
+   *
+   * If the internal start rejects, the partially-constructed sub-tree is stopped
+   * before the error propagates, so no broker resources leak.
+   */ static async start(dbProvider, prover, proverId, chonkCache, epochNumber, cancelJobsOnStop, deferredJobQueue, checkpointConstants, l1ToL2Messages, startInboxRollingHash, totalNumBlocks, headerOfLastBlockInPreviousCheckpoint, telemetryClient = getTelemetryClient(), bindings) {
+        const subTree = new CheckpointSubTreeOrchestrator(dbProvider, prover, proverId, chonkCache, epochNumber, cancelJobsOnStop, deferredJobQueue, telemetryClient, bindings);
+        try {
+            await subTree.startCheckpoint(checkpointConstants, l1ToL2Messages, startInboxRollingHash, totalNumBlocks, headerOfLastBlockInPreviousCheckpoint);
+            return subTree;
+        } catch (err) {
+            await subTree.stop().catch(()=>{});
+            throw err;
+        }
+    }
+    /**
+   * Kickstart chonk-verifier circuits via the shared `ChonkCache`. The cache 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.
+   */ startChonkVerifierCircuits(txs) {
+        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.chonkCache.getOrCompute(txHash, (signal)=>this.prover.getPublicChonkVerifierProof(inputs, signal, this.epochNumber));
+        }
+        return Promise.resolve();
+    }
+    // ---------------- per-block driving (called by the per-checkpoint CheckpointProver) ----------------
+    /**
+   * Starts off a new block.
+   * @param blockNumber - The block number
+   * @param timestamp - The timestamp of the block. Required for empty blocks to construct private inputs.
+   * @param totalNumTxs - The total number of txs in the block.
+   */ async startNewBlock(blockNumber, timestamp, totalNumTxs, l1ToL2Messages) {
+        if (!this.provingState) {
+            throw new Error('Empty proving state. The checkpoint sub-tree has not been started.');
+        }
+        if (!this.provingState.isAcceptingBlocks()) {
+            throw new Error(`Checkpoint not accepting further blocks.`);
+        }
+        const constants = this.provingState.constants;
+        this.logger.info(`Starting block ${blockNumber} for slot ${constants.slotNumber}.`);
+        // Fork the db only when it's not already set. The db for the first block is set in startCheckpoint.
+        if (!this.dbs.has(blockNumber)) {
+            // Fork world state at the end of the immediately previous block.
+            const db = await this.dbProvider.fork(BlockNumber(blockNumber - 1));
+            this.dbs.set(blockNumber, db);
+        }
+        const db = this.getDbForBlock(blockNumber);
+        // Get archive snapshot and sibling path before any txs in this block lands.
+        const lastArchiveTreeSnapshot = await getTreeSnapshot(MerkleTreeId.ARCHIVE, db);
+        const lastArchiveSiblingPath = await getRootTreeSiblingPath(MerkleTreeId.ARCHIVE, db);
+        // The previous block's full state reference, captured before this block's message bundle is appended. Feeds the
+        // msgs-only block root, whose zero-tx block carries no tx constants to pin the previous state.
+        const previousState = await db.getStateReference();
+        // Streaming Inbox: insert this block's own real message slice at compact indices, capturing
+        // the start snapshot + full-height frontier before the append and the block's own post-bundle end snapshot after.
+        const startL1ToL2Snapshot = await getTreeSnapshot(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, db);
+        const l1ToL2FrontierHint = assertLength(await getFrontierSiblingPath(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, db), L1_TO_L2_MSG_TREE_HEIGHT);
+        await appendL1ToL2MessagesToTree(db, l1ToL2Messages);
+        const endL1ToL2Snapshot = await getTreeSnapshot(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, db);
+        const blockProvingState = await this.provingState.startNewBlock(blockNumber, timestamp, totalNumTxs, lastArchiveTreeSnapshot, lastArchiveSiblingPath, previousState, startL1ToL2Snapshot, endL1ToL2Snapshot, l1ToL2FrontierHint, l1ToL2Messages);
+        // Because `addTxs` won't be called for a block without txs, and that's where the sponge blob state is computed,
+        // set its end sponge blob here. This becomes the start sponge blob for the next block.
+        if (totalNumTxs === 0) {
+            const endState = await db.getStateReference();
+            blockProvingState.setEndState(endState);
+            const endSpongeBlob = blockProvingState.getStartSpongeBlob().clone();
+            const blockEndBlobFields = blockProvingState.getBlockEndBlobFields();
+            await endSpongeBlob.absorb(blockEndBlobFields);
+            blockProvingState.setEndSpongeBlob(endSpongeBlob);
+            // A block with no txs has no base or merge proof whose completion would enqueue its block root,
+            // and parity now gates the checkpoint root rather than the first block root, so no other callback
+            // fires it. Enqueue it here. This drives the empty-tx first block root, or the msgs-only block root
+            // for a non-first zero-tx block carrying a message bundle.
+            this.checkAndEnqueueBlockRootRollup(blockProvingState);
+        }
+    }
+    /**
+   * The interface to add simulated transactions to the scheduler. Called at most once per block.
+   * @param txs - The transactions to be proven
+   */ async addTxs(txs) {
+        if (!this.provingState) {
+            throw new Error(`Empty proving state. The checkpoint sub-tree has not been started.`);
+        }
+        if (!txs.length) {
+            // Empty block: setBlockCompleted handles this without addTxs being called. Bail to
+            // avoid the throw below (we cannot find the blockNumber without any txs).
+            this.logger.verbose(`Provided no txs to addTxs.`);
+            return;
+        }
+        const blockNumber = BlockNumber(txs[0].globalVariables.blockNumber);
+        const provingState = this.provingState.getBlockProvingStateByBlockNumber(blockNumber);
+        if (!provingState) {
+            throw new Error(`Proving state for block ${blockNumber} not found. Call startNewBlock first.`);
+        }
+        if (provingState.totalNumTxs !== txs.length) {
+            throw new Error(`Block ${blockNumber} should be filled with ${provingState.totalNumTxs} txs. Received ${txs.length} txs.`);
+        }
+        if (!provingState.isAcceptingTxs()) {
+            throw new Error(`Block ${blockNumber} has been initialized with transactions.`);
+        }
+        this.logger.info(`Adding ${txs.length} transactions to block ${blockNumber}`);
+        const db = this.getDbForBlock(blockNumber);
+        const lastArchive = provingState.lastArchiveTreeSnapshot;
+        const newL1ToL2MessageTreeSnapshot = provingState.newL1ToL2MessageTreeSnapshot;
+        const spongeBlobState = provingState.getStartSpongeBlob().clone();
+        for (const tx of txs){
+            try {
+                if (!provingState.verifyState()) {
+                    throw new Error(`Invalid proving state when adding a tx`);
+                }
+                validateTx(tx);
+                this.logger.debug(`Received transaction: ${tx.hash}`);
+                const startSpongeBlob = spongeBlobState.clone();
+                const [hints, treeSnapshots] = await this.prepareBaseRollupInputs(tx, lastArchive, newL1ToL2MessageTreeSnapshot, startSpongeBlob, db);
+                if (!provingState.verifyState()) {
+                    throw new Error(`Unable to add transaction, preparing base inputs failed`);
+                }
+                await spongeBlobState.absorb(tx.txEffect.toBlobFields());
+                const txProvingState = new TxProvingState(tx, hints, treeSnapshots, this.proverId.toField());
+                const txIndex = provingState.addNewTx(txProvingState);
+                if (txProvingState.requireAvmProof) {
+                    this.getOrEnqueueChonkVerifier(provingState, txIndex);
+                    this.logger.debug(`Enqueueing public VM for tx ${txIndex}`);
+                    this.enqueueVM(provingState, txIndex);
+                } else {
+                    this.logger.debug(`Enqueueing base rollup for private-only tx ${txIndex}`);
+                    this.enqueueBaseRollup(provingState, txIndex);
+                }
+            } catch (err) {
+                throw new Error(`Error adding transaction ${tx.hash.toString()} to block ${blockNumber}: ${err.message}`, {
+                    cause: err
+                });
+            }
+        }
+        const endState = await db.getStateReference();
+        provingState.setEndState(endState);
+        const blockEndBlobFields = provingState.getBlockEndBlobFields();
+        await spongeBlobState.absorb(blockEndBlobFields);
+        provingState.setEndSpongeBlob(spongeBlobState);
+    }
+    /**
+   * Marks the block as completed.
+   * Computes the block header and updates the archive tree.
+   */ async setBlockCompleted(blockNumber, expectedHeader) {
+        const provingState = this.provingState?.getBlockProvingStateByBlockNumber(blockNumber);
+        if (!provingState) {
+            throw new Error(`Block proving state for ${blockNumber} not found`);
+        }
+        // Abort with specific error for the block if there's one.
+        const error = provingState.getError();
+        if (error) {
+            throw new Error(`Block proving failed: ${error}`);
+        }
+        // Abort if the proving state is not valid due to errors occurred elsewhere.
+        if (!provingState.verifyState()) {
+            throw new Error(`Invalid proving state when completing block ${blockNumber}.`);
+        }
+        if (provingState.isAcceptingTxs()) {
+            throw new Error(`Block ${blockNumber} is still accepting txs. Call setBlockCompleted after all txs have been added.`);
+        }
+        // Given we've applied every change from this block, now assemble the block header:
+        this.logger.verbose(`Block ${blockNumber} completed. Assembling header.`);
+        const header = await provingState.buildBlockHeader();
+        if (expectedHeader && !header.equals(expectedHeader)) {
+            this.logger.error(`Block header mismatch: header=${header} expectedHeader=${expectedHeader}`);
+            throw new Error('Block header mismatch');
+        }
+        // Get db for this block and remove from map — no other code should use it after this point.
+        const db = this.getDbForBlock(provingState.blockNumber);
+        this.dbs.delete(provingState.blockNumber);
+        // Update the archive tree, capture the snapshot, and close the fork deterministically.
+        try {
+            this.logger.verbose(`Updating archive tree with block ${provingState.blockNumber} header ${(await header.hash()).toString()}`);
+            await db.updateArchive(header);
+            provingState.setBuiltArchive(await getTreeSnapshot(MerkleTreeId.ARCHIVE, db));
+        } finally{
+            await db.close();
+        }
+        await this.verifyBuiltBlockAgainstSyncedState(provingState);
+        return header;
+    }
+    // ---------------- lifecycle ----------------
+    /**
+   * Cancels any further proving. If `cancelJobsOnStop` was set, aborts all pending broker jobs
+   * (used on reorg). Otherwise jobs remain in the broker queue and can be reused on restart.
+   */ cancel() {
+        this.cancelled = true;
+        this.resetSchedulerState(this.cancelJobsOnStop);
+        // Reject the proving state (and hence subTreeResult) so anyone awaiting the sub-tree result
+        // is released rather than hanging — matching TopTreeOrchestrator.cancel().
+        this.provingState?.cancel();
+        for (const [blockNumber, db] of this.dbs.entries()){
+            void db.close().catch((err)=>this.logger.error(`Error closing db for block ${blockNumber}`, err));
+        }
+        this.dbs.clear();
+    }
+    cancelInternal() {
+        this.cancel();
+    }
+    // ---------------- private: per-checkpoint init ----------------
+    /**
+   * Internal driver for the single-checkpoint init. Allocates the world-state fork,
+   * inserts L1-to-L2 messages, and creates the per-checkpoint proving state with this
+   * sub-tree as its parent. Only called once, from the `start` factory.
+   */ async startCheckpoint(constants, l1ToL2Messages, startInboxRollingHash, totalNumBlocks, headerOfLastBlockInPreviousCheckpoint) {
+        if (this.provingState) {
+            throw new Error('Checkpoint sub-tree already started.');
+        }
+        // Fork world state at the end of the immediately previous block.
+        const lastBlockNumber = headerOfLastBlockInPreviousCheckpoint.globalVariables.blockNumber;
+        const db = await this.dbProvider.fork(lastBlockNumber);
+        const firstBlockNumber = BlockNumber(lastBlockNumber + 1);
+        this.dbs.set(firstBlockNumber, db);
+        // Get archive sibling path before any block in this checkpoint lands.
+        const lastArchiveSiblingPath = await getLastSiblingPath(MerkleTreeId.ARCHIVE, db);
+        // Streaming Inbox: messages are inserted per block in `startNewBlock`, not the whole
+        // checkpoint up front. The message sponge is likewise threaded per block (each block's start sponge is the
+        // previous block's end), so the last block's end sponge matches the checkpoint's single InboxParity proof.
+        this.provingState = new CheckpointProvingState(/* index */ 0, constants, totalNumBlocks, headerOfLastBlockInPreviousCheckpoint, lastArchiveSiblingPath, l1ToL2Messages, startInboxRollingHash, Number(this.epochNumber), /* isAlive */ ()=>!this.cancelled, /* onReject */ (reason)=>this.subTreeResult.reject(new Error(reason)));
+        // Parity now gates the checkpoint root (not the first block root); prove the single sized InboxParity per
+        // checkpoint up front.
+        this.enqueueInboxParityCircuit(this.provingState);
+    }
+    // ---------------- private: per-block proof orchestration ----------------
+    // Updates the merkle trees for a transaction. The first enqueued job for a transaction.
+    async prepareBaseRollupInputs(tx, lastArchive, newL1ToL2MessageTreeSnapshot, startSpongeBlob, db) {
+        // These hints deliberately carry no recursive proof or verification key — see
+        // BaseRollupHintsWithoutProofAndVK. The tx's proof + VK are attached later in
+        // TxProvingState.getBaseRollupTypeAndInputs from the proven chonk-verifier / kernel / AVM
+        // proofs, which are required there and so cannot be silently omitted.
+        const start = performance.now();
+        const hints = await insertSideEffectsAndBuildBaseRollupHints(tx, lastArchive, newL1ToL2MessageTreeSnapshot, startSpongeBlob, this.proverId.toField(), db);
+        this.metrics.recordBaseRollupInputs(performance.now() - start);
+        const promises = [
+            MerkleTreeId.NOTE_HASH_TREE,
+            MerkleTreeId.NULLIFIER_TREE,
+            MerkleTreeId.PUBLIC_DATA_TREE
+        ].map(async (id)=>{
+            return {
+                key: id,
+                value: await getTreeSnapshot(id, db)
+            };
+        });
+        const treeSnapshots = new Map((await Promise.all(promises)).map((obj)=>[
+                obj.key,
+                obj.value
+            ]));
+        return [
+            hints,
+            treeSnapshots
+        ];
+    }
+    // Executes the base rollup circuit and stores the output as intermediate state for the parent merge/root circuit.
+    // Executes the next level of merge if all inputs are available.
+    enqueueBaseRollup(provingState, txIndex) {
+        if (!provingState.verifyState()) {
+            this.logger.debug('Not running base rollup, state invalid');
+            return;
+        }
+        if (!provingState.tryStartProvingBase(txIndex)) {
+            this.logger.debug(`Base rollup for tx ${txIndex} already started.`);
+            return;
+        }
+        const txProvingState = provingState.getTxProvingState(txIndex);
+        const { processedTx } = txProvingState;
+        const { rollupType, inputs } = txProvingState.getBaseRollupTypeAndInputs();
+        this.logger.debug(`Enqueuing deferred proving base rollup for ${processedTx.hash.toString()}`);
+        this.deferredProving(provingState, this.wrapCircuitCall(inputs instanceof PrivateTxBaseRollupPrivateInputs ? 'getPrivateTxBaseRollupProof' : 'getPublicTxBaseRollupProof', (signal)=>{
+            if (inputs instanceof PrivateTxBaseRollupPrivateInputs) {
+                return this.prover.getPrivateTxBaseRollupProof(inputs, signal, provingState.epochNumber);
+            } else {
+                return this.prover.getPublicTxBaseRollupProof(inputs, signal, provingState.epochNumber);
+            }
+        }, {
+            [Attributes.TX_HASH]: processedTx.hash.toString(),
+            [Attributes.PROTOCOL_CIRCUIT_NAME]: rollupType
+        }), (result)=>{
+            this.logger.debug(`Completed proof for ${rollupType} for tx ${processedTx.hash.toString()}`);
+            validatePartialState(result.inputs.endTreeSnapshots, txProvingState.treeSnapshots);
+            const leafLocation = provingState.setBaseRollupProof(txIndex, result);
+            if (provingState.totalNumTxs === 1) {
+                this.checkAndEnqueueBlockRootRollup(provingState);
+            } else {
+                this.checkAndEnqueueNextMergeRollup(provingState, leafLocation);
+            }
+        });
+    }
+    /**
+   * 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.
+   */ getOrEnqueueChonkVerifier(provingState, txIndex) {
+        if (!provingState.verifyState()) {
+            return;
+        }
+        const txProvingState = provingState.getTxProvingState(txIndex);
+        const txHash = txProvingState.processedTx.hash.toString();
+        const handleResult = (result)=>{
+            if (!provingState.verifyState()) {
+                return;
+            }
+            txProvingState.setPublicChonkVerifierProof(result);
+            this.checkAndEnqueueBaseRollup(provingState, txIndex);
+        };
+        const promise = this.chonkCache.getOrCompute(txHash, (signal)=>this.prover.getPublicChonkVerifierProof(txProvingState.getPublicChonkVerifierPrivateInputs(), signal, this.epochNumber));
+        void promise.then(handleResult).catch((err)=>{
+            // The cache self-cleans on rejection, so a replacement sub-tree for this tx will see the
+            // miss and re-enqueue. But if this proving state is still active, the failure must abort
+            // it: otherwise the base rollup for this tx is never enqueued and the checkpoint (and
+            // epoch) orchestrators hang forever waiting for a proof that will never arrive.
+            if (err instanceof AbortError || !provingState.verifyState()) {
+                return;
+            }
+            this.logger.error(`Chonk verifier proof failed for tx ${txHash}`, err);
+            provingState.reject(`Chonk verifier proof failed for tx ${txHash}: ${err}`);
+        });
+    }
+    // Executes the merge rollup circuit. Enqueues the next level of merge if all inputs are available.
+    enqueueMergeRollup(provingState, location) {
+        if (!provingState.verifyState()) {
+            this.logger.debug('Not running merge rollup. State no longer valid.');
+            return;
+        }
+        if (!provingState.tryStartProvingMerge(location)) {
+            this.logger.debug('Merge rollup already started.');
+            return;
+        }
+        const inputs = provingState.getMergeRollupInputs(location);
+        this.deferredProving(provingState, this.wrapCircuitCall('getTxMergeRollupProof', (signal)=>this.prover.getTxMergeRollupProof(inputs, signal, provingState.epochNumber), {
+            [Attributes.PROTOCOL_CIRCUIT_NAME]: 'rollup-tx-merge'
+        }), (result)=>{
+            provingState.setMergeRollupProof(location, result);
+            this.checkAndEnqueueNextMergeRollup(provingState, location);
+        });
+    }
+    // Executes the block root rollup circuit.
+    enqueueBlockRootRollup(provingState) {
+        if (!provingState.verifyState()) {
+            this.logger.debug('Not running block root rollup, state no longer valid');
+            return;
+        }
+        if (!provingState.tryStartProvingBlockRoot()) {
+            this.logger.debug('Block root rollup already started.');
+            return;
+        }
+        // Kept whole (not destructured) so the switch on the `rollupType` discriminant narrows `inputs` per case.
+        const rollup = provingState.getBlockRootRollupTypeAndInputs();
+        const rollupType = rollup.rollupType;
+        this.logger.debug(`Enqueuing ${rollupType} for block ${provingState.blockNumber}.`);
+        this.deferredProving(provingState, this.wrapCircuitCall('getBlockRootRollupProof', (signal)=>{
+            switch(rollup.rollupType){
+                case 'rollup-block-root-no-txs':
+                    return this.prover.getBlockRootNoTxsRollupProof(rollup.inputs, signal, provingState.epochNumber);
+                case 'rollup-block-root-single-tx':
+                    return this.prover.getBlockRootSingleTxRollupProof(rollup.inputs, signal, provingState.epochNumber);
+                case 'rollup-block-root':
+                    return this.prover.getBlockRootRollupProof(rollup.inputs, signal, provingState.epochNumber);
+            }
+        }, {
+            [Attributes.PROTOCOL_CIRCUIT_NAME]: rollupType
+        }), async (result)=>{
+            this.logger.debug(`Completed ${rollupType} proof for block ${provingState.blockNumber}`, {
+                blockNumber: provingState.blockNumber,
+                checkpointIndex: provingState.parentCheckpoint.index,
+                ...result.inputs.toInspect()
+            });
+            const leafLocation = provingState.setBlockRootRollupProof(result);
+            const checkpointProvingState = provingState.parentCheckpoint;
+            // Verification is called from both here and setBlockCompleted. Whichever runs last
+            // will be the first to see all three pieces (header, proof output, archive) and run the checks.
+            await this.verifyBuiltBlockAgainstSyncedState(provingState);
+            if (checkpointProvingState.totalNumBlocks === 1) {
+                this.checkAndEnqueueSubTreeResolution(checkpointProvingState);
+            } else {
+                this.checkAndEnqueueNextBlockMergeRollup(checkpointProvingState, leafLocation);
+            }
+        });
+    }
+    // Runs the checkpoint's single InboxParity circuit and stores the output. The proof feeds the checkpoint root (in
+    // the top tree), so completing it may resolve the sub-tree rather than a block root.
+    enqueueInboxParityCircuit(checkpointProvingState) {
+        if (!checkpointProvingState.verifyState()) {
+            this.logger.debug('Not running inbox parity. State no longer valid.');
+            return;
+        }
+        if (!checkpointProvingState.tryStartProvingInboxParity()) {
+            this.logger.debug('Inbox parity already started.');
+            return;
+        }
+        const inputs = checkpointProvingState.getInboxParityInputs();
+        const circuitName = `inbox-parity-${inputs.size}`;
+        this.deferredProving(checkpointProvingState, this.wrapCircuitCall('getInboxParityProof', (signal)=>this.prover.getInboxParityProof(inputs, signal, checkpointProvingState.epochNumber), {
+            [Attributes.PROTOCOL_CIRCUIT_NAME]: circuitName
+        }), (result)=>{
+            checkpointProvingState.setInboxParityProof(result);
+            this.checkAndEnqueueSubTreeResolution(checkpointProvingState);
+        });
+    }
+    // Executes the block merge rollup circuit.
+    enqueueBlockMergeRollup(provingState, location) {
+        if (!provingState.verifyState()) {
+            this.logger.debug('Not running block merge rollup. State no longer valid.');
+            return;
+        }
+        if (!provingState.tryStartProvingBlockMerge(location)) {
+            this.logger.debug('Block merge rollup already started.');
+            return;
+        }
+        const inputs = provingState.getBlockMergeRollupInputs(location);
+        this.deferredProving(provingState, this.wrapCircuitCall('getBlockMergeRollupProof', (signal)=>this.prover.getBlockMergeRollupProof(inputs, signal, provingState.epochNumber), {
+            [Attributes.PROTOCOL_CIRCUIT_NAME]: 'rollup-block-merge'
+        }), (result)=>{
+            this.logger.debug(`Completed block merge rollup proof for checkpoint ${provingState.index}`, {
+                checkpointIndex: provingState.index,
+                mergeLocation: location,
+                ...result.inputs.toInspect()
+            });
+            provingState.setBlockMergeRollupProof(location, result);
+            this.checkAndEnqueueNextBlockMergeRollup(provingState, location);
+        });
+    }
+    checkAndEnqueueNextMergeRollup(provingState, currentLocation) {
+        if (!provingState.isReadyForMergeRollup(currentLocation)) {
+            return;
+        }
+        const parentLocation = provingState.getParentLocation(currentLocation);
+        if (parentLocation.level === 0) {
+            this.checkAndEnqueueBlockRootRollup(provingState);
+        } else {
+            this.enqueueMergeRollup(provingState, parentLocation);
+        }
+    }
+    checkAndEnqueueBlockRootRollup(provingState) {
+        if (!provingState.isReadyForBlockRootRollup()) {
+            this.logger.debug('Not ready for block root rollup');
+            return;
+        }
+        this.enqueueBlockRootRollup(provingState);
+    }
+    checkAndEnqueueNextBlockMergeRollup(provingState, currentLocation) {
+        if (!provingState.isReadyForBlockMerge(currentLocation)) {
+            return;
+        }
+        const parentLocation = provingState.getParentLocation(currentLocation);
+        if (parentLocation.level === 0) {
+            this.checkAndEnqueueSubTreeResolution(provingState);
+        } else {
+            this.enqueueBlockMergeRollup(provingState, parentLocation);
+        }
+    }
+    /**
+   * Sub-tree analogue of the orchestrator's `checkAndEnqueueCheckpointRootRollup`:
+   * resolves the sub-tree promise with the block-level proof outputs once they're all ready,
+   * instead of escalating to the checkpoint root rollup.
+   */ checkAndEnqueueSubTreeResolution(provingState) {
+        const proofs = provingState.getSubTreeOutputProofs();
+        const nonEmpty = proofs.filter((p)=>!!p);
+        if (proofs.length !== nonEmpty.length) {
+            // Block merge tree not fully resolved yet — retried as more block proofs land.
+            return;
+        }
+        // The InboxParity proof gates the sub-tree result too (it feeds the checkpoint root in the top tree).
+        const inboxParityProof = provingState.getInboxParityProof();
+        if (!inboxParityProof) {
+            // Parity not proven yet — retried when the inbox parity proof lands.
+            return;
+        }
+        this.subTreeResult.resolve({
+            blockProofOutputs: nonEmpty,
+            inboxParityProof,
+            previousArchiveSiblingPath: provingState.getLastArchiveSiblingPath()
+        });
+    }
+    /**
+   * Executes the VM circuit for a public function. Enqueues the base rollup once the
+   * tx's chonk-verifier + VM proofs are both ready.
+   */ enqueueVM(provingState, txIndex) {
+        if (!provingState.verifyState()) {
+            this.logger.debug(`Not running VM circuit as state is no longer valid`);
+            return;
+        }
+        const txProvingState = provingState.getTxProvingState(txIndex);
+        this.deferredProving(provingState, this.wrapCircuitCall('getAvmProof', async (signal)=>{
+            const inputs = txProvingState.getAvmInputs();
+            return await this.prover.getAvmProof(inputs, signal, provingState.epochNumber);
+        }, {
+            [Attributes.TX_HASH]: txProvingState.processedTx.hash.toString()
+        }), (proof)=>{
+            this.logger.debug(`Proven VM for tx index: ${txIndex}`);
+            txProvingState.setAvmProof(proof);
+            this.checkAndEnqueueBaseRollup(provingState, txIndex);
+        });
+    }
+    checkAndEnqueueBaseRollup(provingState, txIndex) {
+        const txProvingState = provingState.getTxProvingState(txIndex);
+        if (!txProvingState.ready()) {
+            return;
+        }
+        // All upstream proofs (chonk verifier and, if required, vm) are ready — proceed to the base rollup.
+        this.logger.debug(`Public functions completed for tx ${txIndex} enqueueing base rollup`);
+        this.enqueueBaseRollup(provingState, txIndex);
+    }
+    // Flagged as protected so unit tests can override.
+    async verifyBuiltBlockAgainstSyncedState(provingState) {
+        const builtBlockHeader = provingState.getBuiltBlockHeader();
+        if (!builtBlockHeader) {
+            this.logger.debug('Block header not built yet, skipping header check.');
+            return;
+        }
+        const output = provingState.getBlockRootRollupOutput();
+        if (!output) {
+            this.logger.debug('Block root rollup proof not built yet, skipping header check.');
+            return;
+        }
+        const newArchive = provingState.getBuiltArchive();
+        if (!newArchive) {
+            this.logger.debug('Archive snapshot not yet captured, skipping header check.');
+            return;
+        }
+        const header = await buildHeaderFromCircuitOutputs(output);
+        if (!(await header.hash()).equals(await builtBlockHeader.hash())) {
+            this.logger.error(`Block header mismatch.\nCircuit: ${inspect(header)}\nComputed: ${inspect(builtBlockHeader)}`);
+            provingState.reject(`Block header hash mismatch.`);
+            return;
+        }
+        const blockNumber = provingState.blockNumber;
+        const syncedArchive = await getTreeSnapshot(MerkleTreeId.ARCHIVE, this.dbProvider.getSnapshot(blockNumber));
+        if (!syncedArchive.equals(newArchive)) {
+            this.logger.error(`Archive tree mismatch for block ${blockNumber}: world state synced to ${inspect(syncedArchive)} but built ${inspect(newArchive)}`);
+            provingState.reject(`Archive tree mismatch.`);
+            return;
+        }
+        const circuitArchive = output.newArchive;
+        if (!newArchive.equals(circuitArchive)) {
+            this.logger.error(`New archive mismatch.\nCircuit: ${output.newArchive}\nComputed: ${newArchive}`);
+            provingState.reject(`New archive mismatch.`);
+            return;
+        }
+    }
+    getDbForBlock(blockNumber) {
+        const db = this.dbs.get(blockNumber);
+        if (!db) {
+            throw new Error(`World state fork for block ${blockNumber} not found.`);
+        }
+        return db;
+    }
+    /**
+   * Wraps a circuit call with a tracer span and circuit attributes. Replaces the
+   * `ProvingScheduler.wrapCircuitCall` indirection that used to live on the abstract base.
+   */ wrapCircuitCall(circuitName, fn, attributes = {}) {
+        return wrapCallbackInSpan(this.tracer, `CheckpointSubTreeOrchestrator.prover.${circuitName}`, {
+            [Attributes.PROTOCOL_CIRCUIT_NAME]: circuitName,
+            ...attributes
+        }, fn);
+    }
+}