@aztec/aztec-node 5.3.0-nightly.20260909 → 5.3.0-nightly.20260911

package/dest/aztec-node/next_block/index.d.ts

@@ -0,0 +1,4 @@
+export * from './next_block_fee_cache.js';
+export * from './next_block_planner.js';
+export * from './next_block_predictor.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9henRlYy1ub2RlL25leHRfYmxvY2svaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsMkJBQTJCLENBQUMifQ==

package/dest/aztec-node/next_block/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/aztec-node/next_block/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}

package/dest/aztec-node/next_block/index.js

@@ -0,0 +1,3 @@
+export * from './next_block_fee_cache.js';
+export * from './next_block_planner.js';
+export * from './next_block_predictor.js';

package/dest/aztec-node/next_block/next_block_fee_cache.d.ts

@@ -0,0 +1,110 @@
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import { type RollupContract } from '@aztec/ethereum/contracts';
+import { type Logger } from '@aztec/foundation/log';
+import { type DateProvider } from '@aztec/foundation/timer';
+import type { L2BlockSource, L2Frontier } from '@aztec/stdlib/block';
+import type { CoordinationSignatureContext } from '@aztec/stdlib/p2p';
+import type { CheckpointGlobalVariables, GlobalVariableBuilder } from '@aztec/stdlib/tx';
+import { type BoundaryFeeKey } from './next_block_planner.js';
+/** Default interval for the background refresh, well below L1's block time. */
+export declare const DEFAULT_REFRESH_INTERVAL_MS = 1000;
+/**
+ * A record older than this many refresh intervals is treated as missing: the refresh has been failing long
+ * enough that serving its value could underquote a fee that has since stepped. Ten intervals because one
+ * failed pass is a hiccup, and a ten-second-old boundary fee is almost always still right.
+ */
+export declare const MAX_AGE_INTERVALS = 10;
+/** Dependencies required to build a {@link NextBlockFeeCache}. */
+export interface NextBlockFeeCacheDeps {
+    blockSource: L2BlockSource;
+    globalVariableBuilder: GlobalVariableBuilder;
+    /**
+     * Rollup contract used to build the fee-relevant L1 state overrides when opening a new checkpoint.
+     * Only needed when a proposed parent checkpoint exists (pipelining) or the pending chain is invalid;
+     * may be omitted in environments that never reach those states (e.g. TXE). When omitted, those paths
+     * degrade to a pinned-tips plan (non-pipelined fees) instead.
+     */
+    rollupContract?: RollupContract;
+    epochCache: EpochCacheInterface;
+    signatureContext: CoordinationSignatureContext;
+    dateProvider: DateProvider;
+    log?: Logger;
+}
+/**
+ * Caches the checkpoint globals, and so the mana min fee, that a block opening a fresh checkpoint would carry.
+ * This is the only value on the RPC path that has to be read from L1.
+ *
+ * A background loop prices the upcoming boundary on every pass, so requests are normally answered from memory.
+ * Records are looked up by {@link BoundaryFeeKey}: the target slot, the checkpointed tip, the block the plan
+ * builds on, and the proposed parent's fee-relevant fields or the pending chain's validity. The L1 block a record
+ * was priced at is stored with it but is not part of the key: the rollup transactions that move the fee also move
+ * the frontier and hence the key, so a miss means the chain moved (a slot rollover, a checkpoint landing or being
+ * proposed, a validity flip), not merely that L1 produced a block. Governance updates such as the mana target are
+ * the exception; the loop re-prices a matching record whenever the L1 anchor moves, so those lag by at most one
+ * refresh interval.
+ *
+ * On a miss a request does not call L1 itself. It joins the single refresh already in flight, or starts the one
+ * the loop would have started, so a burst of requests during a transition costs one L1 round trip. Simulations
+ * wait for as long as the refresh takes and surface its failure; fee quotes cap their wait and fall back to the
+ * last record they can trust.
+ *
+ * Before {@link start} (or after {@link stop}) requests still price inline through the same refresh path, which
+ * is what tests and TXE-like environments rely on.
+ */
+export declare class NextBlockFeeCache {
+    private readonly blockSource;
+    private readonly globalVariableBuilder;
+    private readonly rollupContract;
+    private readonly epochCache;
+    private readonly signatureContext;
+    private readonly dateProvider;
+    private readonly log;
+    private current;
+    private previous;
+    private refreshIntervalMs;
+    private refreshLoop;
+    private inFlightRefresh;
+    constructor(deps: NextBlockFeeCacheDeps);
+    /**
+     * Starts the background refresh. The loop's first pass begins immediately and a request that arrives before it
+     * completes joins it rather than pricing on its own, so nothing waits on priming here: a node whose archiver or
+     * L1 client is not ready yet still starts, and the loop fills the cache once they are. A second call while
+     * running is a no-op, so it cannot orphan a loop that {@link stop} could then never reach.
+     */
+    start(pollingIntervalMs?: number): void;
+    stop(): Promise<void>;
+    /**
+     * The checkpoint globals for a boundary keyed by `key`, or undefined when they could not be produced in time.
+     *
+     * A matching record under the staleness cutoff is served straight away. Otherwise the caller joins the single
+     * shared refresh: a simulation waits for it and surfaces its failure, while a quote passes `maxWaitMs` and
+     * falls back to whatever the cache already holds rather than turning an L1 outage into a multi-second RPC.
+     */
+    getBoundaryGlobals(key: BoundaryFeeKey, frontier: L2Frontier, opts?: {
+        maxWaitMs?: number;
+    }): Promise<CheckpointGlobalVariables | undefined>;
+    /**
+     * Runs one refresh pass, or joins the one already running. Single-flight is what keeps a burst of requests
+     * during a transition down to a single L1 round trip, shared with the background loop.
+     * @param frontier - Snapshot to plan from; read fresh from the archiver when omitted, as the loop does.
+     */
+    refresh(frontier?: L2Frontier): Promise<void>;
+    private runRefresh;
+    /** The freshest record matching `key`, or undefined when none is recent enough to trust. */
+    private findRecord;
+    /** Awaits `promise` for at most `maxWaitMs`, swallowing both a timeout and the promise's own failure. */
+    private waitFor;
+    /**
+     * Builds the chain-state overrides plan passed to `buildCheckpointGlobalVariables`, mirroring the sequencer
+     * (which always pins tips to neutralize prunes). When pipelining, the plan carries the proposed parent's
+     * archive, temp-checkpoint-log cell, and locally-derived fee header; when the pending chain is invalid, it
+     * pins the tips to the last valid checkpoint instead.
+     *
+     * Both of those need a rollup contract for the L1 fee reads. Environments that omit it (e.g. TXE, which never
+     * has a proposed checkpoint and whose pending chain is always valid) fall back to pinning both pending and
+     * proven tips to the checkpointed tip, which neutralizes prunes in fee computation at the cost of
+     * non-pipelined fees.
+     */
+    private buildOverridesPlan;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV4dF9ibG9ja19mZWVfY2FjaGUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9henRlYy1ub2RlL25leHRfYmxvY2svbmV4dF9ibG9ja19mZWVfY2FjaGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUM5RCxPQUFPLEVBQ0wsS0FBSyxjQUFjLEVBR3BCLE1BQU0sMkJBQTJCLENBQUM7QUFHbkMsT0FBTyxFQUFFLEtBQUssTUFBTSxFQUFnQixNQUFNLHVCQUF1QixDQUFDO0FBRWxFLE9BQU8sRUFBRSxLQUFLLFlBQVksRUFBa0IsTUFBTSx5QkFBeUIsQ0FBQztBQUU1RSxPQUFPLEtBQUssRUFBZSxhQUFhLEVBQUUsVUFBVSxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFFbEYsT0FBTyxLQUFLLEVBQUUsNEJBQTRCLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUN0RSxPQUFPLEtBQUssRUFBRSx5QkFBeUIsRUFBRSxxQkFBcUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRXpGLE9BQU8sRUFDTCxLQUFLLGNBQWMsRUFNcEIsTUFBTSx5QkFBeUIsQ0FBQztBQUVqQywrRUFBK0U7QUFDL0UsZUFBTyxNQUFNLDJCQUEyQixPQUFPLENBQUM7QUFFaEQ7Ozs7R0FJRztBQUNILGVBQU8sTUFBTSxpQkFBaUIsS0FBSyxDQUFDO0FBYXBDLGtFQUFrRTtBQUNsRSxNQUFNLFdBQVcscUJBQXFCO0lBQ3BDLFdBQVcsRUFBRSxhQUFhLENBQUM7SUFDM0IscUJBQXFCLEVBQUUscUJBQXFCLENBQUM7SUFDN0M7Ozs7O09BS0c7SUFDSCxjQUFjLENBQUMsRUFBRSxjQUFjLENBQUM7SUFDaEMsVUFBVSxFQUFFLG1CQUFtQixDQUFDO0lBQ2hDLGdCQUFnQixFQUFFLDRCQUE0QixDQUFDO0lBQy9DLFlBQVksRUFBRSxZQUFZLENBQUM7SUFDM0IsR0FBRyxDQUFDLEVBQUUsTUFBTSxDQUFDO0NBQ2Q7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FvQkc7QUFDSCxxQkFBYSxpQkFBaUI7SUFDNUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxXQUFXLENBQWdCO0lBQzVDLE9BQU8sQ0FBQyxRQUFRLENBQUMscUJBQXFCLENBQXdCO0lBQzlELE9BQU8sQ0FBQyxRQUFRLENBQUMsY0FBYyxDQUE2QjtJQUM1RCxPQUFPLENBQUMsUUFBUSxDQUFDLFVBQVUsQ0FBc0I7SUFDakQsT0FBTyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsQ0FBK0I7SUFDaEUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQWU7SUFDNUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQVM7SUFFN0IsT0FBTyxDQUFDLE9BQU8sQ0FBZ0M7SUFDL0MsT0FBTyxDQUFDLFFBQVEsQ0FBZ0M7SUFDaEQsT0FBTyxDQUFDLGlCQUFpQixDQUErQjtJQUN4RCxPQUFPLENBQUMsV0FBVyxDQUE2QjtJQUNoRCxPQUFPLENBQUMsZUFBZSxDQUE0QjtJQUVuRCxZQUFZLElBQUksRUFBRSxxQkFBcUIsRUFRdEM7SUFFRDs7Ozs7T0FLRztJQUNJLEtBQUssQ0FBQyxpQkFBaUIsU0FBOEIsR0FBRyxJQUFJLENBTWxFO0lBRVksSUFBSSxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FNakM7SUFFRDs7Ozs7O09BTUc7SUFDVSxrQkFBa0IsQ0FDN0IsR0FBRyxFQUFFLGNBQWMsRUFDbkIsUUFBUSxFQUFFLFVBQVUsRUFDcEIsSUFBSSxDQUFDLEVBQUU7UUFBRSxTQUFTLENBQUMsRUFBRSxNQUFNLENBQUE7S0FBRSxHQUM1QixPQUFPLENBQUMseUJBQXlCLEdBQUcsU0FBUyxDQUFDLENBY2hEO0lBRUQ7Ozs7T0FJRztJQUNJLE9BQU8sQ0FBQyxRQUFRLENBQUMsRUFBRSxVQUFVLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVluRDtZQUVhLFVBQVU7SUF1Q3hCLDRGQUE0RjtJQUM1RixPQUFPLENBQUMsVUFBVTtJQVFsQix5R0FBeUc7SUFDekcsT0FBTyxDQUFDLE9BQU87SUFNZjs7Ozs7Ozs7OztPQVVHO0lBQ0gsT0FBTyxDQUFDLGtCQUFrQjtDQThCM0IifQ==

package/dest/aztec-node/next_block/next_block_fee_cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next_block_fee_cache.d.ts","sourceRoot":"","sources":["../../../src/aztec-node/next_block/next_block_fee_cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAElE,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,yBAAyB,CAAC;AAE5E,OAAO,KAAK,EAAe,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAElF,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEzF,OAAO,EACL,KAAK,cAAc,EAMpB,MAAM,yBAAyB,CAAC;AAEjC,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAapC,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,aAAa,CAAC;IAC3B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,UAAU,EAAE,mBAAmB,CAAC;IAChC,gBAAgB,EAAE,4BAA4B,CAAC;IAC/C,YAAY,EAAE,YAAY,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,eAAe,CAA4B;IAEnD,YAAY,IAAI,EAAE,qBAAqB,EAQtC;IAED;;;;;OAKG;IACI,KAAK,CAAC,iBAAiB,SAA8B,GAAG,IAAI,CAMlE;IAEY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAMjC;IAED;;;;;;OAMG;IACU,kBAAkB,CAC7B,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,UAAU,EACpB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAchD;IAED;;;;OAIG;IACI,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAYnD;YAEa,UAAU;IAuCxB,4FAA4F;IAC5F,OAAO,CAAC,UAAU;IAQlB,yGAAyG;IACzG,OAAO,CAAC,OAAO;IAMf;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;CA8B3B"}

package/dest/aztec-node/next_block/next_block_fee_cache.js

@@ -0,0 +1,201 @@
+import { SimulationOverridesBuilder } from '@aztec/ethereum/contracts';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/promise';
+import { executeTimeout } from '@aztec/foundation/timer';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { buildCheckpointSimulationOverridesPlan } from '@aztec/stdlib/checkpoint';
+import { boundaryFeeKeyEquals, computeBoundaryFeeKey, getClockSlot, planNextBlock } from './next_block_planner.js';
+/** Default interval for the background refresh, well below L1's block time. */ export const DEFAULT_REFRESH_INTERVAL_MS = 1000;
+/**
+ * A record older than this many refresh intervals is treated as missing: the refresh has been failing long
+ * enough that serving its value could underquote a fee that has since stepped. Ten intervals because one
+ * failed pass is a hiccup, and a ten-second-old boundary fee is almost always still right.
+ */ export const MAX_AGE_INTERVALS = 10;
+/** Refresh passes an uncapped reader will wait through before giving up on its boundary. */ const MAX_REFRESH_ATTEMPTS = 2;
+/**
+ * Caches the checkpoint globals, and so the mana min fee, that a block opening a fresh checkpoint would carry.
+ * This is the only value on the RPC path that has to be read from L1.
+ *
+ * A background loop prices the upcoming boundary on every pass, so requests are normally answered from memory.
+ * Records are looked up by {@link BoundaryFeeKey}: the target slot, the checkpointed tip, the block the plan
+ * builds on, and the proposed parent's fee-relevant fields or the pending chain's validity. The L1 block a record
+ * was priced at is stored with it but is not part of the key: the rollup transactions that move the fee also move
+ * the frontier and hence the key, so a miss means the chain moved (a slot rollover, a checkpoint landing or being
+ * proposed, a validity flip), not merely that L1 produced a block. Governance updates such as the mana target are
+ * the exception; the loop re-prices a matching record whenever the L1 anchor moves, so those lag by at most one
+ * refresh interval.
+ *
+ * On a miss a request does not call L1 itself. It joins the single refresh already in flight, or starts the one
+ * the loop would have started, so a burst of requests during a transition costs one L1 round trip. Simulations
+ * wait for as long as the refresh takes and surface its failure; fee quotes cap their wait and fall back to the
+ * last record they can trust.
+ *
+ * Before {@link start} (or after {@link stop}) requests still price inline through the same refresh path, which
+ * is what tests and TXE-like environments rely on.
+ */ export class NextBlockFeeCache {
+    blockSource;
+    globalVariableBuilder;
+    rollupContract;
+    epochCache;
+    signatureContext;
+    dateProvider;
+    log;
+    current;
+    previous;
+    refreshIntervalMs = DEFAULT_REFRESH_INTERVAL_MS;
+    refreshLoop;
+    inFlightRefresh;
+    constructor(deps){
+        this.blockSource = deps.blockSource;
+        this.globalVariableBuilder = deps.globalVariableBuilder;
+        this.rollupContract = deps.rollupContract;
+        this.epochCache = deps.epochCache;
+        this.signatureContext = deps.signatureContext;
+        this.dateProvider = deps.dateProvider;
+        this.log = deps.log ?? createLogger('node:next-block-fee-cache');
+    }
+    /**
+   * Starts the background refresh. The loop's first pass begins immediately and a request that arrives before it
+   * completes joins it rather than pricing on its own, so nothing waits on priming here: a node whose archiver or
+   * L1 client is not ready yet still starts, and the loop fills the cache once they are. A second call while
+   * running is a no-op, so it cannot orphan a loop that {@link stop} could then never reach.
+   */ start(pollingIntervalMs = DEFAULT_REFRESH_INTERVAL_MS) {
+        if (this.refreshLoop) {
+            return;
+        }
+        this.refreshIntervalMs = pollingIntervalMs;
+        this.refreshLoop = new RunningPromise(()=>this.refresh(), this.log, pollingIntervalMs).start();
+    }
+    async stop() {
+        const loop = this.refreshLoop;
+        this.refreshLoop = undefined;
+        await loop?.stop();
+        // A refresh started by a request rather than by the loop may still be running; let it drain.
+        await this.inFlightRefresh?.catch(()=>{});
+    }
+    /**
+   * The checkpoint globals for a boundary keyed by `key`, or undefined when they could not be produced in time.
+   *
+   * A matching record under the staleness cutoff is served straight away. Otherwise the caller joins the single
+   * shared refresh: a simulation waits for it and surfaces its failure, while a quote passes `maxWaitMs` and
+   * falls back to whatever the cache already holds rather than turning an L1 outage into a multi-second RPC.
+   */ async getBoundaryGlobals(key, frontier, opts) {
+        const maxWaitMs = opts?.maxWaitMs;
+        // An uncapped reader gets more than one attempt because the refresh it joins may be one that started from an
+        // older frontier and therefore priced a different boundary; the next pass is its own. Still never concurrent.
+        const attempts = maxWaitMs === undefined ? MAX_REFRESH_ATTEMPTS : 1;
+        for(let attempt = 0; attempt < attempts; attempt++){
+            const hit = this.findRecord(key);
+            if (hit) {
+                return hit.globals;
+            }
+            const refresh = this.refresh(frontier);
+            await (maxWaitMs === undefined ? refresh : this.waitFor(refresh, maxWaitMs));
+        }
+        return this.findRecord(key)?.globals;
+    }
+    /**
+   * Runs one refresh pass, or joins the one already running. Single-flight is what keeps a burst of requests
+   * during a transition down to a single L1 round trip, shared with the background loop.
+   * @param frontier - Snapshot to plan from; read fresh from the archiver when omitted, as the loop does.
+   */ refresh(frontier) {
+        if (this.inFlightRefresh) {
+            return this.inFlightRefresh;
+        }
+        const refresh = this.runRefresh(frontier).finally(()=>{
+            this.inFlightRefresh = undefined;
+        });
+        // Every caller awaits the returned promise and reports its failure, but the stored copy may only be awaited by
+        // stop() after it has settled. Mark it handled now so a failure can never surface as an unhandled rejection.
+        refresh.catch(()=>{});
+        this.inFlightRefresh = refresh;
+        return refresh;
+    }
+    async runRefresh(frontier) {
+        const snapshot = frontier ?? await this.blockSource.getL2Frontier();
+        const plan = planNextBlock(snapshot, getClockSlot(this.epochCache));
+        const key = computeBoundaryFeeKey(plan, snapshot.pendingChainValidationStatus);
+        if (!key || !plan.newCheckpoint) {
+            // Mid-checkpoint: the fee is frozen in the in-progress checkpoint's header, so there is nothing to price.
+            return;
+        }
+        const current = this.current;
+        const sameKey = current !== undefined && boundaryFeeKeyEquals(current.key, key);
+        if (sameKey && l1SyncPointEquals(current.l1SyncPoint, snapshot.l1SyncPoint)) {
+            // This pass confirmed against a fresh snapshot that none of the fee's inputs moved, so the record is as
+            // good as one just priced. Re-stamping it is what makes the staleness cutoff mean "how long we have been
+            // unable to confirm", rather than expiring a value that is still exactly right.
+            this.current = {
+                ...current,
+                refreshedAtMs: this.dateProvider.now()
+            };
+            return;
+        }
+        const overrides = await this.buildOverridesPlan(snapshot, plan.newCheckpoint);
+        // Pinned to the L1 block the frontier was read at, so the fee describes the same L1 state the plan derives
+        // from. Undefined before the archiver's first sync pass, where the read falls back to L1's head.
+        const globals = await this.globalVariableBuilder.buildCheckpointGlobalVariables(EthAddress.ZERO, AztecAddress.ZERO, plan.newCheckpoint.targetSlot, overrides, {
+            blockNumber: snapshot.l1SyncPoint?.blockNumber
+        });
+        const record = {
+            key,
+            l1SyncPoint: snapshot.l1SyncPoint,
+            globals,
+            refreshedAtMs: this.dateProvider.now()
+        };
+        if (!sameKey) {
+            // Keep the boundary we just left addressable: a request that planned from the previous frontier is still
+            // served while the new one settles.
+            this.previous = current;
+        }
+        this.current = record;
+    }
+    /** The freshest record matching `key`, or undefined when none is recent enough to trust. */ findRecord(key) {
+        const maxAgeMs = MAX_AGE_INTERVALS * this.refreshIntervalMs;
+        const now = this.dateProvider.now();
+        return [
+            this.current,
+            this.previous
+        ].find((record)=>record !== undefined && boundaryFeeKeyEquals(record.key, key) && now - record.refreshedAtMs < maxAgeMs);
+    }
+    /** Awaits `promise` for at most `maxWaitMs`, swallowing both a timeout and the promise's own failure. */ waitFor(promise, maxWaitMs) {
+        return executeTimeout(()=>promise, maxWaitMs).catch((err)=>this.log.debug(`Refreshing the next-block boundary fee failed or timed out`, err));
+    }
+    /**
+   * Builds the chain-state overrides plan passed to `buildCheckpointGlobalVariables`, mirroring the sequencer
+   * (which always pins tips to neutralize prunes). When pipelining, the plan carries the proposed parent's
+   * archive, temp-checkpoint-log cell, and locally-derived fee header; when the pending chain is invalid, it
+   * pins the tips to the last valid checkpoint instead.
+   *
+   * Both of those need a rollup contract for the L1 fee reads. Environments that omit it (e.g. TXE, which never
+   * has a proposed checkpoint and whose pending chain is always valid) fall back to pinning both pending and
+   * proven tips to the checkpointed tip, which neutralizes prunes in fee computation at the cost of
+   * non-pipelined fees.
+   */ buildOverridesPlan(frontier, newCheckpoint) {
+        const { targetCheckpoint, proposedCheckpointData, checkpointedCheckpointNumber } = newCheckpoint;
+        const rollup = this.rollupContract;
+        if (!rollup) {
+            return Promise.resolve(new SimulationOverridesBuilder().withChainTips({
+                pending: checkpointedCheckpointNumber,
+                proven: checkpointedCheckpointNumber
+            }).build());
+        }
+        // The helper treats pipelining and invalidation as mutually exclusive; a proposed parent takes precedence.
+        const validationStatus = frontier.pendingChainValidationStatus;
+        const invalidateToPendingCheckpointNumber = !proposedCheckpointData && !validationStatus.valid ? CheckpointNumber(validationStatus.checkpoint.checkpointNumber - 1) : undefined;
+        return buildCheckpointSimulationOverridesPlan({
+            checkpointNumber: targetCheckpoint,
+            proposedCheckpointData,
+            invalidateToPendingCheckpointNumber,
+            checkpointedCheckpointNumber,
+            rollup,
+            signatureContext: this.signatureContext,
+            log: this.log
+        });
+    }
+}
+function l1SyncPointEquals(a, b) {
+    return a === undefined || b === undefined ? a === b : a.blockHash.equals(b.blockHash);
+}

package/dest/aztec-node/next_block/next_block_planner.d.ts

@@ -0,0 +1,78 @@
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { type L2Frontier, type ValidateCheckpointResult } from '@aztec/stdlib/block';
+import type { ProposedCheckpointData } from '@aztec/stdlib/checkpoint';
+/** Slot, target checkpoint, and parent data for a next block that opens a fresh checkpoint. */
+export type NewCheckpointPlan = {
+    /** Slot the next block will land in. */
+    targetSlot: SlotNumber;
+    /** Checkpoint whose L1-to-L2 messages the simulation fork needs. */
+    targetCheckpoint: CheckpointNumber;
+    /** The proposed (not yet L1-confirmed) parent checkpoint, when pipelining. */
+    proposedCheckpointData: ProposedCheckpointData | undefined;
+    /** Checkpointed tip at the time the plan's snapshot was taken. */
+    checkpointedCheckpointNumber: CheckpointNumber;
+};
+/**
+ * How the next block sits on the chain, derived from a single atomic archiver snapshot. Everything here comes
+ * from archiver reads only; turning it into globals is what may hit L1. `newCheckpoint` is set only when the
+ * next block opens a fresh checkpoint rather than continuing the in-progress one.
+ */
+export type NextBlockPlan = {
+    latestBlockNumber: BlockNumber;
+    /** Hash of the latest proposed block, so the world-state fork can be checked against the plan's chain. */
+    latestBlockHash: string;
+    newCheckpoint?: NewCheckpointPlan;
+};
+/** Identity of the parent the boundary fee is computed on top of. */
+export type BoundaryFeeParent = {
+    kind: 'proposed';
+    headerHash: string;
+    archiveRoot: string;
+    checkpointOutHash: string;
+    totalManaUsed: bigint;
+    feeAssetPriceModifier: bigint;
+} | {
+    kind: 'checkpointed';
+    pendingChainValid: boolean;
+    firstInvalidCheckpoint?: CheckpointNumber;
+};
+/**
+ * Every input the min fee of a checkpoint-opening block derives from, so two equal keys prove a cached fee is
+ * still what a fresh build would produce: the target slot, the checkpointed tip, the block the plan sits on,
+ * and either the proposed parent's fee-relevant fields or the pending-chain validity that selects the
+ * invalidation override.
+ *
+ * The L1 block the fee was read at is deliberately not part of the key. The min fee for a fixed slot and parent
+ * depends only on rollup storage, and the rollup transactions that move it (checkpoints landing, invalidations,
+ * prunes) all move the frontier and therefore this key, so a new L1 block on its own is a hit. The exception is a
+ * governance parameter update such as the mana target, which changes the fee without touching the frontier;
+ * the cache re-prices a matching record whenever the L1 anchor moves, so that lags by at most one refresh.
+ */
+export type BoundaryFeeKey = {
+    targetSlot: SlotNumber;
+    checkpointedCheckpointNumber: CheckpointNumber;
+    latestBlockHash: string;
+    parent: BoundaryFeeParent;
+};
+/**
+ * The slot this node's clock says the next block would be built in, the first of the three terms
+ * {@link planNextBlock} maximizes over. Pure arithmetic over the epoch cache's in-memory view.
+ */
+export declare function getClockSlot(epochCache: EpochCacheInterface): SlotNumber;
+/**
+ * Works out how the next block sits on the chain from one atomic frontier snapshot: whether it continues the
+ * in-progress checkpoint or opens a fresh one, which slot it lands in, and which checkpoint's L1-to-L2
+ * messages a fork would need. Pure: the caller supplies both the snapshot and the clock slot, so the fee a
+ * wallet is quoted and the fee a simulation charges can never derive from different decisions.
+ */
+export declare function planNextBlock(frontier: L2Frontier, clockSlot: SlotNumber): NextBlockPlan;
+/**
+ * Keys the fee of a plan that opens a new checkpoint. Undefined mid-checkpoint, where the fee is copied from
+ * the in-progress checkpoint's header and nothing needs pricing.
+ * @param pendingChainValidationStatus - From the same frontier snapshot the plan was built from.
+ */
+export declare function computeBoundaryFeeKey(plan: NextBlockPlan, pendingChainValidationStatus: ValidateCheckpointResult): BoundaryFeeKey | undefined;
+/** Whether two boundary fee keys describe the same fee. */
+export declare function boundaryFeeKeyEquals(a: BoundaryFeeKey, b: BoundaryFeeKey): boolean;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV4dF9ibG9ja19wbGFubmVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvYXp0ZWMtbm9kZS9uZXh0X2Jsb2NrL25leHRfYmxvY2tfcGxhbm5lci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEtBQUssRUFBRSxtQkFBbUIsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQzlELE9BQU8sRUFBRSxXQUFXLEVBQUUsZ0JBQWdCLEVBQUUsVUFBVSxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFFNUYsT0FBTyxFQUFFLEtBQUssVUFBVSxFQUFFLEtBQUssd0JBQXdCLEVBQTBCLE1BQU0scUJBQXFCLENBQUM7QUFDN0csT0FBTyxLQUFLLEVBQUUsc0JBQXNCLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQUV2RSwrRkFBK0Y7QUFDL0YsTUFBTSxNQUFNLGlCQUFpQixHQUFHO0lBQzlCLHdDQUF3QztJQUN4QyxVQUFVLEVBQUUsVUFBVSxDQUFDO0lBQ3ZCLG9FQUFvRTtJQUNwRSxnQkFBZ0IsRUFBRSxnQkFBZ0IsQ0FBQztJQUNuQyw4RUFBOEU7SUFDOUUsc0JBQXNCLEVBQUUsc0JBQXNCLEdBQUcsU0FBUyxDQUFDO0lBQzNELGtFQUFrRTtJQUNsRSw0QkFBNEIsRUFBRSxnQkFBZ0IsQ0FBQztDQUNoRCxDQUFDO0FBRUY7Ozs7R0FJRztBQUNILE1BQU0sTUFBTSxhQUFhLEdBQUc7SUFDMUIsaUJBQWlCLEVBQUUsV0FBVyxDQUFDO0lBQy9CLDBHQUEwRztJQUMxRyxlQUFlLEVBQUUsTUFBTSxDQUFDO0lBQ3hCLGFBQWEsQ0FBQyxFQUFFLGlCQUFpQixDQUFDO0NBQ25DLENBQUM7QUFFRixxRUFBcUU7QUFDckUsTUFBTSxNQUFNLGlCQUFpQixHQUN6QjtJQUNFLElBQUksRUFBRSxVQUFVLENBQUM7SUFDakIsVUFBVSxFQUFFLE1BQU0sQ0FBQztJQUNuQixXQUFXLEVBQUUsTUFBTSxDQUFDO0lBQ3BCLGlCQUFpQixFQUFFLE1BQU0sQ0FBQztJQUMxQixhQUFhLEVBQUUsTUFBTSxDQUFDO0lBQ3RCLHFCQUFxQixFQUFFLE1BQU0sQ0FBQztDQUMvQixHQUNEO0lBQUUsSUFBSSxFQUFFLGNBQWMsQ0FBQztJQUFDLGlCQUFpQixFQUFFLE9BQU8sQ0FBQztJQUFDLHNCQUFzQixDQUFDLEVBQUUsZ0JBQWdCLENBQUE7Q0FBRSxDQUFDO0FBRXBHOzs7Ozs7Ozs7OztHQVdHO0FBQ0gsTUFBTSxNQUFNLGNBQWMsR0FBRztJQUMzQixVQUFVLEVBQUUsVUFBVSxDQUFDO0lBQ3ZCLDRCQUE0QixFQUFFLGdCQUFnQixDQUFDO0lBQy9DLGVBQWUsRUFBRSxNQUFNLENBQUM7SUFDeEIsTUFBTSxFQUFFLGlCQUFpQixDQUFDO0NBQzNCLENBQUM7QUE2QkY7OztHQUdHO0FBQ0gsd0JBQWdCLFlBQVksQ0FBQyxVQUFVLEVBQUUsbUJBQW1CLEdBQUcsVUFBVSxDQUV4RTtBQUVEOzs7OztHQUtHO0FBQ0gsd0JBQWdCLGFBQWEsQ0FBQyxRQUFRLEVBQUUsVUFBVSxFQUFFLFNBQVMsRUFBRSxVQUFVLEdBQUcsYUFBYSxDQWtDeEY7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQWdCLHFCQUFxQixDQUNuQyxJQUFJLEVBQUUsYUFBYSxFQUNuQiw0QkFBNEIsRUFBRSx3QkFBd0IsR0FDckQsY0FBYyxHQUFHLFNBQVMsQ0FzQjVCO0FBRUQsMkRBQTJEO0FBQzNELHdCQUFnQixvQkFBb0IsQ0FBQyxDQUFDLEVBQUUsY0FBYyxFQUFFLENBQUMsRUFBRSxjQUFjLEdBQUcsT0FBTyxDQU9sRiJ9

package/dest/aztec-node/next_block/next_block_planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next_block_planner.d.ts","sourceRoot":"","sources":["../../../src/aztec-node/next_block/next_block_planner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE5F,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,wBAAwB,EAA0B,MAAM,qBAAqB,CAAC;AAC7G,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,+FAA+F;AAC/F,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wCAAwC;IACxC,UAAU,EAAE,UAAU,CAAC;IACvB,oEAAoE;IACpE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,8EAA8E;IAC9E,sBAAsB,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC3D,kEAAkE;IAClE,4BAA4B,EAAE,gBAAgB,CAAC;CAChD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,iBAAiB,EAAE,WAAW,CAAC;IAC/B,0GAA0G;IAC1G,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;CAC/B,GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAC;IAAC,sBAAsB,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAEpG;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,4BAA4B,EAAE,gBAAgB,CAAC;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AA6BF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,mBAAmB,GAAG,UAAU,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,aAAa,CAkCxF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,aAAa,EACnB,4BAA4B,EAAE,wBAAwB,GACrD,cAAc,GAAG,SAAS,CAsB5B;AAED,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAOlF"}

package/dest/aztec-node/next_block/next_block_planner.js

@@ -0,0 +1,109 @@
+import { PROPOSER_PIPELINING_SLOT_OFFSET } from '@aztec/epoch-cache';
+import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { compactArray } from '@aztec/foundation/collection';
+import { getCheckpointedTipSlot } from '@aztec/stdlib/block';
+/**
+ * Slot the next block will land in, the largest of three terms:
+ *
+ * - The sequencer's exact formula, `getEpochAndSlotInNextL1Slot().slot + PROPOSER_PIPELINING_SLOT_OFFSET`.
+ * - `proposedCheckpointSlot + 1`, an RPC-side approximation of the next build: when a proposed checkpoint
+ *   is gossiped before its L1 slot starts, the next build (once its wall clock arrives) will target
+ *   `parentSlot + 1`. The sequencer never advances its own target past wall clock — it just declines to
+ *   build — so this is a prediction of inclusion globals, not literal sequencer behavior. The parent slot
+ *   comes from the proposed checkpoint header so the slot and the overrides plan cannot derive from
+ *   different snapshots.
+ * - `checkpointedTipSlot + 1`, a floor: the next block can never land in a slot already taken by a
+ *   checkpointed checkpoint. The slot comes from the frontier's checkpointed checkpoint header, so it
+ *   describes the same instant as the tips and the proposed checkpoint. This only binds when this node's
+ *   clock is behind the chain, in which case the first term would otherwise price the next block in a slot
+ *   L1 has already moved past — and the L1 gas oracle can step between the two, so wallet quotes and
+ *   simulations would disagree on the fee.
+ */ function computeTargetSlot(clockSlot, proposedCheckpointData, checkpointedTipSlot) {
+    const slotAfterProposedCheckpoint = proposedCheckpointData ? proposedCheckpointData.header.slotNumber + 1 : undefined;
+    const slotAfterCheckpointedTip = checkpointedTipSlot !== undefined ? checkpointedTipSlot + 1 : undefined;
+    return SlotNumber(Math.max(...compactArray([
+        clockSlot,
+        slotAfterProposedCheckpoint,
+        slotAfterCheckpointedTip
+    ])));
+}
+/**
+ * The slot this node's clock says the next block would be built in, the first of the three terms
+ * {@link planNextBlock} maximizes over. Pure arithmetic over the epoch cache's in-memory view.
+ */ export function getClockSlot(epochCache) {
+    return SlotNumber(epochCache.getEpochAndSlotInNextL1Slot().slot + PROPOSER_PIPELINING_SLOT_OFFSET);
+}
+/**
+ * Works out how the next block sits on the chain from one atomic frontier snapshot: whether it continues the
+ * in-progress checkpoint or opens a fresh one, which slot it lands in, and which checkpoint's L1-to-L2
+ * messages a fork would need. Pure: the caller supplies both the snapshot and the clock slot, so the fee a
+ * wallet is quoted and the fee a simulation charges can never derive from different decisions.
+ */ export function planNextBlock(frontier, clockSlot) {
+    const { tips, proposedCheckpoint: proposedCheckpointData } = frontier;
+    const latestBlockNumber = tips.proposed.number;
+    const latestBlockHash = tips.proposed.hash;
+    // Terminating block of the proposed-checkpoint frontier: the leading proposed (not-yet-L1-confirmed)
+    // checkpoint's last block is `startBlock + blockCount - 1`; with no proposed checkpoint the frontier
+    // coincides with the checkpointed tip.
+    const proposedCheckpointLastBlock = proposedCheckpointData ? BlockNumber.add(proposedCheckpointData.startBlock, proposedCheckpointData.blockCount - 1) : tips.checkpointed.block.number;
+    // The next block continues the in-progress checkpoint when the latest proposed block is ahead of the
+    // proposed-checkpoint terminating block; it opens a new checkpoint when they coincide.
+    if (proposedCheckpointLastBlock !== latestBlockNumber) {
+        return {
+            latestBlockNumber,
+            latestBlockHash
+        };
+    }
+    const checkpointedCheckpointNumber = tips.checkpointed.checkpoint.number;
+    // The new checkpoint sits on top of the proposed one when pipelining, otherwise on the checkpointed tip.
+    const parentCheckpointNumber = proposedCheckpointData?.checkpointNumber ?? checkpointedCheckpointNumber;
+    // Undefined before the first checkpoint lands: no slot is taken yet, so there is no floor.
+    const checkpointedTipSlot = frontier.checkpointedCheckpoint ? getCheckpointedTipSlot(frontier) : undefined;
+    return {
+        latestBlockNumber,
+        latestBlockHash,
+        newCheckpoint: {
+            targetSlot: computeTargetSlot(clockSlot, proposedCheckpointData, checkpointedTipSlot),
+            targetCheckpoint: CheckpointNumber(parentCheckpointNumber + 1),
+            proposedCheckpointData,
+            checkpointedCheckpointNumber
+        }
+    };
+}
+/**
+ * Keys the fee of a plan that opens a new checkpoint. Undefined mid-checkpoint, where the fee is copied from
+ * the in-progress checkpoint's header and nothing needs pricing.
+ * @param pendingChainValidationStatus - From the same frontier snapshot the plan was built from.
+ */ export function computeBoundaryFeeKey(plan, pendingChainValidationStatus) {
+    if (!plan.newCheckpoint) {
+        return undefined;
+    }
+    const { targetSlot, proposedCheckpointData, checkpointedCheckpointNumber } = plan.newCheckpoint;
+    const parent = proposedCheckpointData ? {
+        kind: 'proposed',
+        headerHash: proposedCheckpointData.header.hash().toString(),
+        archiveRoot: proposedCheckpointData.archive.root.toString(),
+        checkpointOutHash: proposedCheckpointData.checkpointOutHash.toString(),
+        totalManaUsed: proposedCheckpointData.totalManaUsed,
+        feeAssetPriceModifier: proposedCheckpointData.feeAssetPriceModifier
+    } : {
+        kind: 'checkpointed',
+        pendingChainValid: pendingChainValidationStatus.valid,
+        firstInvalidCheckpoint: pendingChainValidationStatus.valid ? undefined : pendingChainValidationStatus.checkpoint.checkpointNumber
+    };
+    return {
+        targetSlot,
+        checkpointedCheckpointNumber,
+        latestBlockHash: plan.latestBlockHash,
+        parent
+    };
+}
+/** Whether two boundary fee keys describe the same fee. */ export function boundaryFeeKeyEquals(a, b) {
+    return a.targetSlot === b.targetSlot && a.checkpointedCheckpointNumber === b.checkpointedCheckpointNumber && a.latestBlockHash === b.latestBlockHash && boundaryFeeParentEquals(a.parent, b.parent);
+}
+function boundaryFeeParentEquals(a, b) {
+    if (a.kind === 'proposed') {
+        return b.kind === 'proposed' && a.headerHash === b.headerHash && a.archiveRoot === b.archiveRoot && a.checkpointOutHash === b.checkpointOutHash && a.totalManaUsed === b.totalManaUsed && a.feeAssetPriceModifier === b.feeAssetPriceModifier;
+    }
+    return b.kind === 'checkpointed' && a.pendingChainValid === b.pendingChainValid && a.firstInvalidCheckpoint === b.firstInvalidCheckpoint;
+}

package/dest/aztec-node/next_block/next_block_predictor.d.ts

@@ -0,0 +1,91 @@
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import { type Logger } from '@aztec/foundation/log';
+import type { L1SyncPoint, L2BlockSource, L2Frontier } from '@aztec/stdlib/block';
+import type { GasFees } from '@aztec/stdlib/gas';
+import { GlobalVariables } from '@aztec/stdlib/tx';
+import { NextBlockFeeCache, type NextBlockFeeCacheDeps } from './next_block_fee_cache.js';
+import { type NextBlockPlan } from './next_block_planner.js';
+/**
+ * How long a fee quote waits for a boundary refresh before answering with what it already has. Long enough for
+ * a slow but alive L1 RPC; short enough that an L1 outage does not turn every quote into a multi-second RPC.
+ */
+export declare const QUOTE_MAX_WAIT_MS = 5000;
+/** The next block as this node predicts it: how it sits on the chain, plus the globals it would carry. */
+export type NextBlockPrediction = {
+    plan: NextBlockPlan;
+    /** Snapshot the plan was derived from, so callers can pin their own reads to the same instant. */
+    frontier: L2Frontier;
+    globals: GlobalVariables;
+};
+/** Dependencies required to build a {@link NextBlockPredictor}. */
+export interface NextBlockPredictorDeps {
+    blockSource: L2BlockSource;
+    feeCache: NextBlockFeeCache;
+    epochCache: EpochCacheInterface;
+    log?: Logger;
+}
+/**
+ * Answers "what would the next block look like" for everything on the RPC side: the public simulation forks and
+ * executes against this prediction, and the fee quote reports the fee it carries.
+ *
+ * The plan is re-derived from a fresh archiver snapshot on every call — it is a handful of in-memory reads, and
+ * a stale plan would fork the wrong block, target the wrong checkpoint's L1-to-L2 messages, or miss that an
+ * in-progress checkpoint froze a different fee. Only the L1-derived part, the checkpoint globals of a block that
+ * opens a fresh checkpoint, is cached (see {@link NextBlockFeeCache}).
+ *
+ * Deliberately not used by the sequencer: its slot policy is stricter (it declines to build rather than
+ * predicting inclusion) and a stale fee would make L1 reject its checkpoint.
+ */
+export declare class NextBlockPredictor {
+    private readonly blockSource;
+    private readonly feeCache;
+    private readonly epochCache;
+    private readonly log;
+    constructor(deps: NextBlockPredictorDeps);
+    /**
+     * Builds a predictor together with the fee cache it reads from. It takes the cache's dependencies rather than
+     * {@link NextBlockPredictorDeps} because the cache is constructed here; everything the predictor itself needs is
+     * a subset of them.
+     */
+    static create(deps: NextBlockFeeCacheDeps): NextBlockPredictor;
+    start(pollingIntervalMs?: number): void;
+    stop(): Promise<void>;
+    /**
+     * Plans the next block and builds the globals it would carry, in one of two ways, mirroring how the sequencer
+     * builds the next block:
+     *
+     * - **Continuing an in-progress checkpoint**: every block in a checkpoint shares the same
+     *   `CheckpointGlobalVariables`, so the latest proposed block's globals are copied verbatim — including the
+     *   proposer's real coinbase and fee recipient — with only the block number bumped. No L1 involved.
+     * - **Opening a new checkpoint**: the globals are priced for the slot the next block will land in, under the
+     *   same overrides plan the sequencer applies, so the simulated mana min fee matches what the sequencer will
+     *   write into the block header. Coinbase and fee recipient stay zero: the future proposer's payout addresses
+     *   are unknowable.
+     *
+     * Waits without a bound for a boundary fee it does not have cached, and surfaces the L1 failure if that read
+     * fails, as a simulation did before this cache existed.
+     */
+    predict(): Promise<NextBlockPrediction>;
+    /**
+     * The mana min fee the next block will charge, for wallets to pad and pay. Mid-checkpoint this is the fee the
+     * in-progress checkpoint froze into its first block, which no forward-looking L1 projection can see. At a
+     * boundary it is the cached L1 price, waited on for at most {@link QUOTE_MAX_WAIT_MS}; undefined when the node
+     * has nothing usable, in which case the caller falls back to the fee provider's projections alone.
+     *
+     * Returns the L1 block the answer describes so the caller can tag its own fee reads with the same anchor.
+     */
+    quoteMinFees(): Promise<{
+        fees: GasFees;
+        l1SyncPoint: L1SyncPoint | undefined;
+    } | undefined>;
+    private planFromFrontier;
+    /**
+     * The header comes from the same snapshot as the tips, so it cannot describe a different block than the
+     * proposed tip. A missing header at a non-genesis proposed tip is an invariant violation and throws rather
+     * than falling through to the new-checkpoint path: a fork at the proposed tip already contains the ongoing
+     * checkpoint's L1-to-L2 messages, so a caller inserting the next checkpoint's messages would append them a
+     * second time.
+     */
+    private copyGlobalsFromLatestBlock;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmV4dF9ibG9ja19wcmVkaWN0b3IuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9henRlYy1ub2RlL25leHRfYmxvY2svbmV4dF9ibG9ja19wcmVkaWN0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUU5RCxPQUFPLEVBQUUsS0FBSyxNQUFNLEVBQWdCLE1BQU0sdUJBQXVCLENBQUM7QUFDbEUsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLGFBQWEsRUFBRSxVQUFVLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNsRixPQUFPLEtBQUssRUFBRSxPQUFPLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUNqRCxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFbkQsT0FBTyxFQUFFLGlCQUFpQixFQUFFLEtBQUsscUJBQXFCLEVBQUUsTUFBTSwyQkFBMkIsQ0FBQztBQUMxRixPQUFPLEVBQUUsS0FBSyxhQUFhLEVBQXNELE1BQU0seUJBQXlCLENBQUM7QUFFakg7OztHQUdHO0FBQ0gsZUFBTyxNQUFNLGlCQUFpQixPQUFPLENBQUM7QUFFdEMsMEdBQTBHO0FBQzFHLE1BQU0sTUFBTSxtQkFBbUIsR0FBRztJQUNoQyxJQUFJLEVBQUUsYUFBYSxDQUFDO0lBQ3BCLGtHQUFrRztJQUNsRyxRQUFRLEVBQUUsVUFBVSxDQUFDO0lBQ3JCLE9BQU8sRUFBRSxlQUFlLENBQUM7Q0FDMUIsQ0FBQztBQUVGLG1FQUFtRTtBQUNuRSxNQUFNLFdBQVcsc0JBQXNCO0lBQ3JDLFdBQVcsRUFBRSxhQUFhLENBQUM7SUFDM0IsUUFBUSxFQUFFLGlCQUFpQixDQUFDO0lBQzVCLFVBQVUsRUFBRSxtQkFBbUIsQ0FBQztJQUNoQyxHQUFHLENBQUMsRUFBRSxNQUFNLENBQUM7Q0FDZDtBQUVEOzs7Ozs7Ozs7OztHQVdHO0FBQ0gscUJBQWEsa0JBQWtCO0lBQzdCLE9BQU8sQ0FBQyxRQUFRLENBQUMsV0FBVyxDQUFnQjtJQUM1QyxPQUFPLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBb0I7SUFDN0MsT0FBTyxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQXNCO0lBQ2pELE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBRTdCLFlBQVksSUFBSSxFQUFFLHNCQUFzQixFQUt2QztJQUVEOzs7O09BSUc7SUFDSCxPQUFjLE1BQU0sQ0FBQyxJQUFJLEVBQUUscUJBQXFCLEdBQUcsa0JBQWtCLENBUXBFO0lBRU0sS0FBSyxDQUFDLGlCQUFpQixDQUFDLEVBQUUsTUFBTSxHQUFHLElBQUksQ0FFN0M7SUFFTSxJQUFJLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUUzQjtJQUVEOzs7Ozs7Ozs7Ozs7OztPQWNHO0lBQ1UsT0FBTyxJQUFJLE9BQU8sQ0FBQyxtQkFBbUIsQ0FBQyxDQVluRDtJQUVEOzs7Ozs7O09BT0c7SUFDVSxZQUFZLElBQUksT0FBTyxDQUFDO1FBQUUsSUFBSSxFQUFFLE9BQU8sQ0FBQztRQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsU0FBUyxDQUFBO0tBQUUsR0FBRyxTQUFTLENBQUMsQ0FleEc7WUFHYSxnQkFBZ0I7SUFPOUI7Ozs7OztPQU1HO0lBQ0gsT0FBTyxDQUFDLDBCQUEwQjtDQVFuQyJ9

package/dest/aztec-node/next_block/next_block_predictor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next_block_predictor.d.ts","sourceRoot":"","sources":["../../../src/aztec-node/next_block/next_block_predictor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EAAE,KAAK,aAAa,EAAsD,MAAM,yBAAyB,CAAC;AAEjH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,0GAA0G;AAC1G,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;CAC1B,CAAC;AAEF,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,aAAa,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,mBAAmB,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAAY,IAAI,EAAE,sBAAsB,EAKvC;IAED;;;;OAIG;IACH,OAAc,MAAM,CAAC,IAAI,EAAE,qBAAqB,GAAG,kBAAkB,CAQpE;IAEM,KAAK,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAE7C;IAEM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAED;;;;;;;;;;;;;;OAcG;IACU,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAYnD;IAED;;;;;;;OAOG;IACU,YAAY,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC,CAexG;YAGa,gBAAgB;IAO9B;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;CAQnC"}