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

package/dest/index.js

@@ -1,4 +1,5 @@
 export * from './aztec-node/config.js';
+export { NextBlockPredictor } from './aztec-node/next_block/index.js';
 export * from './aztec-node/register_node_rpc_handlers.js';
 export * from './aztec-node/server.js';
 export * from './factory.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/aztec-node",
-  "version": "5.3.0-nightly.20260909",
+  "version": "5.3.0-nightly.20260910",
   "main": "dest/index.js",
   "type": "module",
   "exports": {
@@ -65,33 +65,33 @@
     ]
   },
   "dependencies": {
-    "@aztec/archiver": "5.3.0-nightly.20260909",
-    "@aztec/bb-prover": "5.3.0-nightly.20260909",
-    "@aztec/bb.js": "5.3.0-nightly.20260909",
-    "@aztec/blob-client": "5.3.0-nightly.20260909",
-    "@aztec/blob-lib": "5.3.0-nightly.20260909",
-    "@aztec/constants": "5.3.0-nightly.20260909",
-    "@aztec/epoch-cache": "5.3.0-nightly.20260909",
-    "@aztec/ethereum": "5.3.0-nightly.20260909",
-    "@aztec/foundation": "5.3.0-nightly.20260909",
-    "@aztec/kv-store": "5.3.0-nightly.20260909",
-    "@aztec/l1-artifacts": "5.3.0-nightly.20260909",
-    "@aztec/node-keystore": "5.3.0-nightly.20260909",
-    "@aztec/node-lib": "5.3.0-nightly.20260909",
-    "@aztec/noir-protocol-circuits-types": "5.3.0-nightly.20260909",
-    "@aztec/p2p": "5.3.0-nightly.20260909",
-    "@aztec/protocol-contracts": "5.3.0-nightly.20260909",
-    "@aztec/prover-client": "5.3.0-nightly.20260909",
-    "@aztec/prover-node": "5.3.0-nightly.20260909",
-    "@aztec/sequencer-client": "5.3.0-nightly.20260909",
-    "@aztec/simulator": "5.3.0-nightly.20260909",
-    "@aztec/slasher": "5.3.0-nightly.20260909",
-    "@aztec/standard-contracts": "5.3.0-nightly.20260909",
-    "@aztec/stdlib": "5.3.0-nightly.20260909",
-    "@aztec/telemetry-client": "5.3.0-nightly.20260909",
-    "@aztec/validator-client": "5.3.0-nightly.20260909",
-    "@aztec/validator-ha-signer": "5.3.0-nightly.20260909",
-    "@aztec/world-state": "5.3.0-nightly.20260909",
+    "@aztec/archiver": "5.3.0-nightly.20260910",
+    "@aztec/bb-prover": "5.3.0-nightly.20260910",
+    "@aztec/bb.js": "5.3.0-nightly.20260910",
+    "@aztec/blob-client": "5.3.0-nightly.20260910",
+    "@aztec/blob-lib": "5.3.0-nightly.20260910",
+    "@aztec/constants": "5.3.0-nightly.20260910",
+    "@aztec/epoch-cache": "5.3.0-nightly.20260910",
+    "@aztec/ethereum": "5.3.0-nightly.20260910",
+    "@aztec/foundation": "5.3.0-nightly.20260910",
+    "@aztec/kv-store": "5.3.0-nightly.20260910",
+    "@aztec/l1-artifacts": "5.3.0-nightly.20260910",
+    "@aztec/node-keystore": "5.3.0-nightly.20260910",
+    "@aztec/node-lib": "5.3.0-nightly.20260910",
+    "@aztec/noir-protocol-circuits-types": "5.3.0-nightly.20260910",
+    "@aztec/p2p": "5.3.0-nightly.20260910",
+    "@aztec/protocol-contracts": "5.3.0-nightly.20260910",
+    "@aztec/prover-client": "5.3.0-nightly.20260910",
+    "@aztec/prover-node": "5.3.0-nightly.20260910",
+    "@aztec/sequencer-client": "5.3.0-nightly.20260910",
+    "@aztec/simulator": "5.3.0-nightly.20260910",
+    "@aztec/slasher": "5.3.0-nightly.20260910",
+    "@aztec/standard-contracts": "5.3.0-nightly.20260910",
+    "@aztec/stdlib": "5.3.0-nightly.20260910",
+    "@aztec/telemetry-client": "5.3.0-nightly.20260910",
+    "@aztec/validator-client": "5.3.0-nightly.20260910",
+    "@aztec/validator-ha-signer": "5.3.0-nightly.20260910",
+    "@aztec/world-state": "5.3.0-nightly.20260910",
     "koa": "^2.16.1",
     "koa-router": "^13.1.1",
     "tslib": "^2.4.0",

package/src/aztec-node/next_block/index.ts

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

package/src/aztec-node/next_block/next_block_fee_cache.ts

@@ -0,0 +1,279 @@
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import {
+  type RollupContract,
+  SimulationOverridesBuilder,
+  type SimulationOverridesPlan,
+} from '@aztec/ethereum/contracts';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/promise';
+import { type DateProvider, executeTimeout } from '@aztec/foundation/timer';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { L1SyncPoint, L2BlockSource, L2Frontier } from '@aztec/stdlib/block';
+import { buildCheckpointSimulationOverridesPlan } from '@aztec/stdlib/checkpoint';
+import type { CoordinationSignatureContext } from '@aztec/stdlib/p2p';
+import type { CheckpointGlobalVariables, GlobalVariableBuilder } from '@aztec/stdlib/tx';
+
+import {
+  type BoundaryFeeKey,
+  type NewCheckpointPlan,
+  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;
+
+/** A priced checkpoint boundary, with the L1 block it was priced at kept as metadata. */
+type BoundaryFeeRecord = {
+  key: BoundaryFeeKey;
+  l1SyncPoint: L1SyncPoint | undefined;
+  globals: CheckpointGlobalVariables;
+  refreshedAtMs: number;
+};
+
+/** 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 class NextBlockFeeCache {
+  private readonly blockSource: L2BlockSource;
+  private readonly globalVariableBuilder: GlobalVariableBuilder;
+  private readonly rollupContract: RollupContract | undefined;
+  private readonly epochCache: EpochCacheInterface;
+  private readonly signatureContext: CoordinationSignatureContext;
+  private readonly dateProvider: DateProvider;
+  private readonly log: Logger;
+
+  private current: BoundaryFeeRecord | undefined;
+  private previous: BoundaryFeeRecord | undefined;
+  private refreshIntervalMs = DEFAULT_REFRESH_INTERVAL_MS;
+  private refreshLoop: RunningPromise | undefined;
+  private inFlightRefresh: Promise<void> | undefined;
+
+  constructor(deps: NextBlockFeeCacheDeps) {
+    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.
+   */
+  public start(pollingIntervalMs = DEFAULT_REFRESH_INTERVAL_MS): void {
+    if (this.refreshLoop) {
+      return;
+    }
+    this.refreshIntervalMs = pollingIntervalMs;
+    this.refreshLoop = new RunningPromise(() => this.refresh(), this.log, pollingIntervalMs).start();
+  }
+
+  public async stop(): Promise<void> {
+    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.
+   */
+  public async getBoundaryGlobals(
+    key: BoundaryFeeKey,
+    frontier: L2Frontier,
+    opts?: { maxWaitMs?: number },
+  ): Promise<CheckpointGlobalVariables | undefined> {
+    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.
+   */
+  public refresh(frontier?: L2Frontier): Promise<void> {
+    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;
+  }
+
+  private async runRefresh(frontier?: L2Frontier): Promise<void> {
+    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. */
+  private findRecord(key: BoundaryFeeKey): BoundaryFeeRecord | undefined {
+    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. */
+  private waitFor(promise: Promise<void>, maxWaitMs: number): Promise<void> {
+    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.
+   */
+  private buildOverridesPlan(
+    frontier: L2Frontier,
+    newCheckpoint: NewCheckpointPlan,
+  ): Promise<SimulationOverridesPlan | undefined> {
+    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: L1SyncPoint | undefined, b: L1SyncPoint | undefined): boolean {
+  return a === undefined || b === undefined ? a === b : a.blockHash.equals(b.blockHash);
+}

package/src/aztec-node/next_block/next_block_planner.ts

@@ -0,0 +1,198 @@
+import { PROPOSER_PIPELINING_SLOT_OFFSET } from '@aztec/epoch-cache';
+import type { EpochCacheInterface } from '@aztec/epoch-cache';
+import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { compactArray } from '@aztec/foundation/collection';
+import { type L2Frontier, type ValidateCheckpointResult, getCheckpointedTipSlot } 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;
+};
+
+/**
+ * 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: SlotNumber,
+  proposedCheckpointData: ProposedCheckpointData | undefined,
+  checkpointedTipSlot: SlotNumber | undefined,
+): SlotNumber {
+  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: EpochCacheInterface): SlotNumber {
+  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: L2Frontier, clockSlot: SlotNumber): NextBlockPlan {
+  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: NextBlockPlan,
+  pendingChainValidationStatus: ValidateCheckpointResult,
+): BoundaryFeeKey | undefined {
+  if (!plan.newCheckpoint) {
+    return undefined;
+  }
+  const { targetSlot, proposedCheckpointData, checkpointedCheckpointNumber } = plan.newCheckpoint;
+  const parent: BoundaryFeeParent = 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: BoundaryFeeKey, b: BoundaryFeeKey): boolean {
+  return (
+    a.targetSlot === b.targetSlot &&
+    a.checkpointedCheckpointNumber === b.checkpointedCheckpointNumber &&
+    a.latestBlockHash === b.latestBlockHash &&
+    boundaryFeeParentEquals(a.parent, b.parent)
+  );
+}
+
+function boundaryFeeParentEquals(a: BoundaryFeeParent, b: BoundaryFeeParent): boolean {
+  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
+  );
+}