@aztec/sequencer-client 0.0.1-commit.04852196a → 0.0.1-commit.04d373f

package/src/client/sequencer-client.ts

@@ -12,22 +12,16 @@ import type { DateProvider } from '@aztec/foundation/timer';
 import type { KeystoreManager } from '@aztec/node-keystore';
 import type { P2P } from '@aztec/p2p';
 import type { SlasherClientInterface } from '@aztec/slasher';
-import type { L2BlockSink, L2BlockSource } from '@aztec/stdlib/block';
+import type { L2BlockSink, L2BlockSource, ProposedCheckpointSink } from '@aztec/stdlib/block';
 import type { ValidatorClientFullConfig, WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
-import { SlashFactoryContract } from '@aztec/stdlib/l1-contracts';
 import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
 import { L1Metrics, type TelemetryClient } from '@aztec/telemetry-client';
 import { FullNodeCheckpointsBuilder, NodeKeystoreAdapter, type ValidatorClient } from '@aztec/validator-client';
 
-import {
-  DefaultSequencerConfig,
-  type SequencerClientConfig,
-  getPublisherConfigFromSequencerConfig,
-} from '../config.js';
-import { GlobalVariableBuilder } from '../global_variable_builder/index.js';
+import { type SequencerClientConfig, getPublisherConfigFromSequencerConfig } from '../config.js';
+import type { GlobalVariableBuilder } from '../global_variable_builder/index.js';
 import { SequencerPublisherFactory } from '../publisher/sequencer-publisher-factory.js';
 import { Sequencer, type SequencerConfig } from '../sequencer/index.js';
-import { SequencerTimetable } from '../sequencer/timetable.js';
 
 /**
  * Encapsulates the full sequencer and publisher.
@@ -62,7 +56,7 @@ export class SequencerClient {
       worldStateSynchronizer: WorldStateSynchronizer;
       slasherClient: SlasherClientInterface | undefined;
       checkpointsBuilder: FullNodeCheckpointsBuilder;
-      l2BlockSource: L2BlockSource & L2BlockSink;
+      l2BlockSource: L2BlockSource & L2BlockSink & ProposedCheckpointSink;
       l1ToL2MessageSource: L1ToL2MessageSource;
       telemetry: TelemetryClient;
       publisherFactory?: SequencerPublisherFactory;
@@ -70,7 +64,9 @@ export class SequencerClient {
       dateProvider: DateProvider;
       epochCache?: EpochCache;
       l1TxUtils: L1TxUtils[];
+      funderL1TxUtils?: L1TxUtils;
       nodeKeyStore: KeystoreManager;
+      globalVariableBuilder: GlobalVariableBuilder;
     },
   ) {
     const {
@@ -92,41 +88,35 @@ export class SequencerClient {
       publicClient,
       l1TxUtils.map(x => x.getSenderAddress()),
     );
-    const publisherManager = new PublisherManager(
-      l1TxUtils,
-      getPublisherConfigFromSequencerConfig(config),
-      log.getBindings(),
-    );
-    const rollupContract = new RollupContract(publicClient, config.l1Contracts.rollupAddress.toString());
-    const [l1GenesisTime, slotDuration, rollupVersion, rollupManaLimit] = await Promise.all([
+    const publisherManager = new PublisherManager(l1TxUtils, getPublisherConfigFromSequencerConfig(config), {
+      bindings: log.getBindings(),
+      funder: deps.funderL1TxUtils,
+    });
+    const rollupContract = new RollupContract(publicClient, config.rollupAddress.toString());
+    const [l1GenesisTime, slotDuration, rollupManaLimit] = await Promise.all([
       rollupContract.getL1GenesisTime(),
       rollupContract.getSlotDuration(),
-      rollupContract.getVersion(),
       rollupContract.getManaLimit().then(Number),
     ] as const);
 
     const governanceProposerContract = new GovernanceProposerContract(
       publicClient,
-      config.l1Contracts.governanceProposerAddress.toString(),
+      config.governanceProposerAddress.toString(),
     );
     const epochCache =
       deps.epochCache ??
       (await EpochCache.create(
-        config.l1Contracts.rollupAddress,
+        config.rollupAddress,
         {
           l1RpcUrls: rpcUrls,
           l1ChainId: chainId,
           viemPollingIntervalMS: config.viemPollingIntervalMS,
           ethereumSlotDuration: config.ethereumSlotDuration,
+          enableProposerPipelining: config.enableProposerPipelining,
         },
         { dateProvider: deps.dateProvider },
       ));
 
-    const slashFactoryContract = new SlashFactoryContract(
-      publicClient,
-      config.l1Contracts.slashFactoryAddress?.toString() ?? EthAddress.ZERO.toString(),
-    );
-
     const publisherFactory =
       deps.publisherFactory ??
       new SequencerPublisherFactory(config, {
@@ -134,7 +124,6 @@ export class SequencerClient {
         blobClient: deps.blobClient,
         epochCache,
         governanceProposerContract,
-        slashFactoryContract,
         rollupContract,
         dateProvider: deps.dateProvider,
         publisherManager,
@@ -144,13 +133,7 @@ export class SequencerClient {
 
     const ethereumSlotDuration = config.ethereumSlotDuration;
 
-    const globalsBuilder = new GlobalVariableBuilder({
-      ...config,
-      l1GenesisTime,
-      slotDuration: Number(slotDuration),
-      ethereumSlotDuration,
-      rollupVersion,
-    });
+    const globalsBuilder = deps.globalVariableBuilder;
 
     // When running in anvil, assume we can post a tx up until one second before the end of an L1 slot.
     // Otherwise, we need the full L1 slot duration for publishing to ensure inclusion.
@@ -160,14 +143,15 @@ export class SequencerClient {
     const l1PublishingTimeBasedOnChain = isAnvilTestChain(config.l1ChainId) ? 1 : ethereumSlotDuration;
     const l1PublishingTime = config.l1PublishingTime ?? l1PublishingTimeBasedOnChain;
 
-    const { maxL2BlockGas, maxDABlockGas, maxTxsPerBlock } = computeBlockLimits(
-      config,
-      rollupManaLimit,
-      l1PublishingTime,
-      log,
-    );
+    const { maxL2BlockGas, maxDABlockGas, maxTxsPerBlock } = capPerBlockLimits(config, rollupManaLimit, log);
 
-    const l1Constants = { l1GenesisTime, slotDuration: Number(slotDuration), ethereumSlotDuration, rollupManaLimit };
+    const l1Constants = {
+      l1GenesisTime,
+      slotDuration: Number(slotDuration),
+      ethereumSlotDuration,
+      rollupManaLimit,
+      epochDuration: config.aztecEpochDuration,
+    };
 
     const sequencer = new Sequencer(
       publisherFactory,
@@ -211,7 +195,7 @@ export class SequencerClient {
     await this.validatorClient?.start();
     this.sequencer.start();
     this.l1Metrics?.start();
-    await this.publisherManager.loadState();
+    await this.publisherManager.start();
   }
 
   /**
@@ -220,10 +204,15 @@ export class SequencerClient {
   public async stop() {
     await this.sequencer.stop();
     await this.validatorClient?.stop();
-    this.publisherManager.interrupt();
+    await this.publisherManager.stop();
     this.l1Metrics?.stop();
   }
 
+  /** Triggers an immediate run of the sequencer, bypassing the polling interval. */
+  public trigger() {
+    return this.sequencer.trigger();
+  }
+
   public getSequencer(): Sequencer {
     return this.sequencer;
   }
@@ -248,88 +237,39 @@ export class SequencerClient {
 }
 
 /**
- * Computes per-block L2 gas, DA gas, and TX count budgets based on the L1 rollup limits and the timetable.
- * If the user explicitly set a limit, it is capped at the corresponding checkpoint limit.
- * Otherwise, derives it as (checkpointLimit / maxBlocks) * multiplier, capped at the checkpoint limit.
+ * Caps operator-provided per-block limits at checkpoint-level limits.
+ * Returns undefined for any limit the operator didn't set — the checkpoint builder handles redistribution.
  */
-export function computeBlockLimits(
+function capPerBlockLimits(
   config: SequencerClientConfig,
   rollupManaLimit: number,
-  l1PublishingTime: number,
   log: ReturnType<typeof createLogger>,
-): { maxL2BlockGas: number; maxDABlockGas: number; maxTxsPerBlock: number } {
-  const maxNumberOfBlocks = new SequencerTimetable({
-    ethereumSlotDuration: config.ethereumSlotDuration,
-    aztecSlotDuration: config.aztecSlotDuration,
-    l1PublishingTime,
-    p2pPropagationTime: config.attestationPropagationTime,
-    blockDurationMs: config.blockDurationMs,
-    enforce: config.enforceTimeTable ?? DefaultSequencerConfig.enforceTimeTable,
-  }).maxNumberOfBlocks;
-
-  const multiplier = config.perBlockAllocationMultiplier ?? DefaultSequencerConfig.perBlockAllocationMultiplier;
-
-  // Compute maxL2BlockGas
-  let maxL2BlockGas: number;
-  if (config.maxL2BlockGas !== undefined) {
-    if (config.maxL2BlockGas > rollupManaLimit) {
-      log.warn(
-        `Provided MAX_L2_BLOCK_GAS ${config.maxL2BlockGas} exceeds L1 rollup mana limit ${rollupManaLimit} (capping)`,
-      );
-      maxL2BlockGas = rollupManaLimit;
-    } else {
-      maxL2BlockGas = config.maxL2BlockGas;
-    }
-  } else {
-    maxL2BlockGas = Math.min(rollupManaLimit, Math.ceil((rollupManaLimit / maxNumberOfBlocks) * multiplier));
+): { maxL2BlockGas: number | undefined; maxDABlockGas: number | undefined; maxTxsPerBlock: number | undefined } {
+  let maxL2BlockGas = config.maxL2BlockGas;
+  if (maxL2BlockGas !== undefined && maxL2BlockGas > rollupManaLimit) {
+    log.warn(`Provided MAX_L2_BLOCK_GAS ${maxL2BlockGas} exceeds rollup mana limit ${rollupManaLimit} (capping)`);
+    maxL2BlockGas = rollupManaLimit;
   }
 
-  // Compute maxDABlockGas
-  const daCheckpointLimit = MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
-  let maxDABlockGas: number;
-  if (config.maxDABlockGas !== undefined) {
-    if (config.maxDABlockGas > daCheckpointLimit) {
-      log.warn(
-        `Provided MAX_DA_BLOCK_GAS ${config.maxDABlockGas} exceeds DA checkpoint limit ${daCheckpointLimit} (capping)`,
-      );
-      maxDABlockGas = daCheckpointLimit;
-    } else {
-      maxDABlockGas = config.maxDABlockGas;
-    }
-  } else {
-    maxDABlockGas = Math.min(daCheckpointLimit, Math.ceil((daCheckpointLimit / maxNumberOfBlocks) * multiplier));
+  let maxDABlockGas = config.maxDABlockGas;
+  if (maxDABlockGas !== undefined && maxDABlockGas > MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT) {
+    log.warn(
+      `Provided MAX_DA_BLOCK_GAS ${maxDABlockGas} exceeds DA checkpoint limit ${MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT} (capping)`,
+    );
+    maxDABlockGas = MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
   }
 
-  // Compute maxTxsPerBlock
-  const defaultMaxTxsPerBlock = 32;
-  let maxTxsPerBlock: number;
-  if (config.maxTxsPerBlock !== undefined) {
-    if (config.maxTxsPerCheckpoint !== undefined && config.maxTxsPerBlock > config.maxTxsPerCheckpoint) {
-      log.warn(
-        `Provided MAX_TX_PER_BLOCK ${config.maxTxsPerBlock} exceeds MAX_TX_PER_CHECKPOINT ${config.maxTxsPerCheckpoint} (capping)`,
-      );
-      maxTxsPerBlock = config.maxTxsPerCheckpoint;
-    } else {
-      maxTxsPerBlock = config.maxTxsPerBlock;
-    }
-  } else if (config.maxTxsPerCheckpoint !== undefined) {
-    maxTxsPerBlock = Math.min(
-      config.maxTxsPerCheckpoint,
-      Math.ceil((config.maxTxsPerCheckpoint / maxNumberOfBlocks) * multiplier),
+  let maxTxsPerBlock = config.maxTxsPerBlock;
+  if (
+    maxTxsPerBlock !== undefined &&
+    config.maxTxsPerCheckpoint !== undefined &&
+    maxTxsPerBlock > config.maxTxsPerCheckpoint
+  ) {
+    log.warn(
+      `Provided MAX_TX_PER_BLOCK ${maxTxsPerBlock} exceeds MAX_TX_PER_CHECKPOINT ${config.maxTxsPerCheckpoint} (capping)`,
     );
-  } else {
-    maxTxsPerBlock = defaultMaxTxsPerBlock;
+    maxTxsPerBlock = config.maxTxsPerCheckpoint;
   }
 
-  log.info(`Computed block limits L2=${maxL2BlockGas} DA=${maxDABlockGas} maxTxs=${maxTxsPerBlock}`, {
-    maxL2BlockGas,
-    maxDABlockGas,
-    maxTxsPerBlock,
-    rollupManaLimit,
-    daCheckpointLimit,
-    maxNumberOfBlocks,
-    multiplier,
-  });
-
   return { maxL2BlockGas, maxDABlockGas, maxTxsPerBlock };
 }

package/src/config.ts

@@ -5,6 +5,7 @@ import {
   booleanConfigHelper,
   getConfigFromMappings,
   numberConfigHelper,
+  optionalNumberConfigHelper,
   pickConfigMappings,
 } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
@@ -13,8 +14,11 @@ import { type P2PConfig, p2pConfigMappings } from '@aztec/p2p/config';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
   type ChainConfig,
+  DEFAULT_MAX_BLOCKS_PER_CHECKPOINT,
+  type PipelineConfig,
   type SequencerConfig,
   chainConfigMappings,
+  pipelineConfigMappings,
   sharedSequencerConfigMappings,
 } from '@aztec/stdlib/config';
 import type { ResolvedSequencerConfig } from '@aztec/stdlib/interfaces/server';
@@ -40,14 +44,17 @@ export const DefaultSequencerConfig = {
   minTxsPerBlock: 1,
   buildCheckpointIfEmpty: false,
   publishTxsWithProposals: false,
-  perBlockAllocationMultiplier: 2,
+  perBlockAllocationMultiplier: 1.2,
+  redistributeCheckpointBudget: true,
   enforceTimeTable: true,
   attestationPropagationTime: DEFAULT_P2P_PROPAGATION_TIME,
   secondsBeforeInvalidatingBlockAsCommitteeMember: 144, // 12 L1 blocks
   secondsBeforeInvalidatingBlockAsNonCommitteeMember: 432, // 36 L1 blocks
   skipCollectingAttestations: false,
   skipInvalidateBlockAsProposer: false,
+  skipWaitForValidParentCheckpointOnL1: false,
   broadcastInvalidBlockProposal: false,
+  broadcastInvalidCheckpointProposalOnly: false,
   injectFakeAttestation: false,
   injectHighSValueAttestation: false,
   injectUnrecoverableSignatureAttestation: false,
@@ -55,6 +62,7 @@ export const DefaultSequencerConfig = {
   shuffleAttestationOrdering: false,
   skipPushProposedBlocksToArchiver: false,
   skipPublishingCheckpointsPercent: 0,
+  maxBlocksPerCheckpoint: DEFAULT_MAX_BLOCKS_PER_CHECKPOINT,
 } satisfies ResolvedSequencerConfig;
 
 /**
@@ -67,6 +75,7 @@ export type SequencerClientConfig = SequencerPublisherConfig &
   SequencerConfig &
   L1ReaderConfig &
   ChainConfig &
+  PipelineConfig &
   Pick<P2PConfig, 'txPublicSetupAllowListExtend'> &
   Pick<L1ContractsConfig, 'ethereumSlotDuration' | 'aztecSlotDuration' | 'aztecEpochDuration'>;
 
@@ -79,7 +88,7 @@ export const sequencerConfigMappings: ConfigMappingsType<SequencerConfig> = {
   maxTxsPerCheckpoint: {
     env: 'SEQ_MAX_TX_PER_CHECKPOINT',
     description: 'The maximum number of txs across all blocks in a checkpoint.',
-    parseEnv: (val: string) => (val ? parseInt(val, 10) : undefined),
+    ...optionalNumberConfigHelper(),
   },
   minTxsPerBlock: {
     env: 'SEQ_MIN_TX_PER_BLOCK',
@@ -98,12 +107,12 @@ export const sequencerConfigMappings: ConfigMappingsType<SequencerConfig> = {
   maxL2BlockGas: {
     env: 'SEQ_MAX_L2_BLOCK_GAS',
     description: 'The maximum L2 block gas.',
-    parseEnv: (val: string) => (val ? parseInt(val, 10) : undefined),
+    ...optionalNumberConfigHelper(),
   },
   maxDABlockGas: {
     env: 'SEQ_MAX_DA_BLOCK_GAS',
     description: 'The maximum DA block gas.',
-    parseEnv: (val: string) => (val ? parseInt(val, 10) : undefined),
+    ...optionalNumberConfigHelper(),
   },
   perBlockAllocationMultiplier: {
     env: 'SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER',
@@ -112,9 +121,15 @@ export const sequencerConfigMappings: ConfigMappingsType<SequencerConfig> = {
       ' Values greater than one allow early blocks to use more than their even share, relying on checkpoint-level capping for later blocks.',
     ...numberConfigHelper(DefaultSequencerConfig.perBlockAllocationMultiplier),
   },
+  redistributeCheckpointBudget: {
+    env: 'SEQ_REDISTRIBUTE_CHECKPOINT_BUDGET',
+    description:
+      'Redistribute remaining checkpoint budget evenly across remaining blocks instead of allowing a single block to consume the entire remaining budget.',
+    ...booleanConfigHelper(DefaultSequencerConfig.redistributeCheckpointBudget),
+  },
   coinbase: {
     env: 'COINBASE',
-    parseEnv: (val: string) => (val ? EthAddress.fromString(val) : undefined),
+    parseEnv: (val: string) => EthAddress.fromString(val),
     description: 'Recipient of block reward.',
   },
   feeRecipient: {
@@ -143,12 +158,7 @@ export const sequencerConfigMappings: ConfigMappingsType<SequencerConfig> = {
   l1PublishingTime: {
     env: 'SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT',
     description: 'How much time (in seconds) we allow in the slot for publishing the L1 tx (defaults to 1 L1 slot).',
-    parseEnv: (val: string) => (val ? parseInt(val, 10) : undefined),
-  },
-  attestationPropagationTime: {
-    env: 'SEQ_ATTESTATION_PROPAGATION_TIME',
-    description: 'How many seconds it takes for proposals and attestations to travel across the p2p layer (one-way)',
-    ...numberConfigHelper(DefaultSequencerConfig.attestationPropagationTime),
+    ...optionalNumberConfigHelper(),
   },
   fakeProcessingDelayPerTxMs: {
     description: 'Used for testing to introduce a fake delay after processing each tx',
@@ -179,10 +189,25 @@ export const sequencerConfigMappings: ConfigMappingsType<SequencerConfig> = {
     description: 'Do not invalidate the previous block if invalid when we are the proposer (for testing only)',
     ...booleanConfigHelper(DefaultSequencerConfig.skipInvalidateBlockAsProposer),
   },
+  skipWaitForValidParentCheckpointOnL1: {
+    description:
+      'Bypass the parent checkpoint validity check before submitting a pipelined checkpoint, ' +
+      'allowing the proposer to publish even when the parent landed on L1 with invalid attestations (for testing only)',
+    ...booleanConfigHelper(DefaultSequencerConfig.skipWaitForValidParentCheckpointOnL1),
+  },
   broadcastInvalidBlockProposal: {
     description: 'Broadcast invalid block proposals with corrupted state (for testing only)',
     ...booleanConfigHelper(DefaultSequencerConfig.broadcastInvalidBlockProposal),
   },
+  invalidBlockProposalIndexWithinCheckpoint: {
+    description: 'Broadcast an invalid block proposal only at this indexWithinCheckpoint (for testing only)',
+    ...optionalNumberConfigHelper(),
+  },
+  broadcastInvalidCheckpointProposalOnly: {
+    description:
+      'Broadcast invalid checkpoint proposals while keeping the underlying block proposals valid (for testing only). When unset, the checkpoint follows broadcastInvalidBlockProposal.',
+    ...booleanConfigHelper(DefaultSequencerConfig.broadcastInvalidCheckpointProposalOnly),
+  },
   injectFakeAttestation: {
     description: 'Inject a fake attestation (for testing only)',
     ...booleanConfigHelper(DefaultSequencerConfig.injectFakeAttestation),
@@ -223,17 +248,32 @@ export const sequencerConfigMappings: ConfigMappingsType<SequencerConfig> = {
     description: 'Percent probability (0 - 100) of sequencer skipping checkpoint publishing (testing only)',
     ...numberConfigHelper(DefaultSequencerConfig.skipPublishingCheckpointsPercent),
   },
+  skipBroadcastProposals: {
+    description: 'Skip broadcasting checkpoint and block proposals via gossipsub when proposer (for testing only)',
+    ...booleanConfigHelper(false),
+  },
+  skipBroadcastCheckpointProposal: {
+    description:
+      'Skip broadcasting only the CheckpointProposal via gossipsub when proposer; the held last block is broadcast ' +
+      'standalone instead so peers still receive it as a proposed-but-uncheckpointed tip (for testing only)',
+    ...booleanConfigHelper(false),
+  },
+  pauseProposingForSlots: {
+    description:
+      'List of slots for which the sequencer will not produce a proposal (for testing only). Attestation paths are unaffected.',
+  },
   ...pickConfigMappings(p2pConfigMappings, ['txPublicSetupAllowListExtend']),
 };
 
 export const sequencerClientConfigMappings: ConfigMappingsType<SequencerClientConfig> = {
+  ...chainConfigMappings,
   ...validatorClientConfigMappings,
   ...sequencerConfigMappings,
   ...keyStoreConfigMappings,
   ...l1ReaderConfigMappings,
   ...sequencerTxSenderConfigMappings,
   ...sequencerPublisherConfigMappings,
-  ...chainConfigMappings,
+  ...pipelineConfigMappings,
   ...pickConfigMappings(l1ContractsConfigMappings, ['ethereumSlotDuration', 'aztecSlotDuration', 'aztecEpochDuration']),
 };
 

package/src/global_variable_builder/README.md

@@ -0,0 +1,44 @@
+# Fee Prediction
+
+The `FeePredictor` predicts min fees for upcoming L2 slots based on the current L1
+oracle state and an assumed mana usage pattern.
+
+## Prediction Window
+
+The prediction covers `LAG = 2` entries (the next available slot plus 1 more).
+A new oracle update can activate at `startSlot + LAG`, so only the first LAG entries
+are guaranteed stable. Beyond that, L1 fees could change unpredictably.
+
+Each entry uses:
+
+- The **actual L1 fees** the oracle would return for that slot's timestamp (pre or post,
+  depending on whether the slot is before or after `slotOfChange`).
+- A **configurable congestion assumption** (`ManaUsageEstimate`): none (0 mana), target
+  (steady state), or limit (worst case, 2x target).
+
+The client picks `max(predicted[0..LAG-1])` as their `maxFeesPerGas`.
+
+```
+predicted[0]  →  fee at next slot     (current oracle + current congestion)
+predicted[1]  →  fee at next slot + 1 (congestion may change based on usage estimate)
+```
+
+## Why LAG and not LIFETIME?
+
+The L1 gas oracle has two timing constants:
+
+- **LAG = 2 slots**: when new fees are queued, they activate LAG slots later
+- **LIFETIME = 5 slots**: after an oracle update, the next update is rejected until
+  `slotOfChange + (LIFETIME - LAG)` slots have passed
+
+If the oracle cooldown has already elapsed (i.e., no recent update), a new update can
+be enqueued at any moment. Its new values would activate LAG slots later. This means
+predictions beyond LAG slots could be invalidated by an oracle update that happens
+right after we query.
+
+With a LIFETIME-sized window, we'd give a false sense of coverage: the prediction
+would look like it covers 6 slots, but slots beyond LAG could be wrong if an update
+is enqueued after the prediction is computed.
+
+By limiting to LAG entries, we guarantee that all predicted L1 fees are the ones that
+will actually be used — no oracle update can change them within this window.

package/src/global_variable_builder/fee_predictor.ts

@@ -0,0 +1,172 @@
+import { type L1FeeData, MAX_FEE_ASSET_PRICE_MODIFIER_BPS, type RollupContract } from '@aztec/ethereum/contracts';
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { times } from '@aztec/foundation/collection';
+import type { DateProvider } from '@aztec/foundation/timer';
+import { getSlotAtNextL1Block, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
+import {
+  FEE_ORACLE_LAG,
+  GasFees,
+  MIN_ETH_PER_FEE_ASSET,
+  ManaUsageEstimate,
+  computeExcessMana,
+  computeManaMinFee,
+} from '@aztec/stdlib/gas';
+
+/** Cached rollup state for fee prediction. Refreshed once per L1 block. */
+type FeeOracleState = {
+  lastSlot: SlotNumber;
+  excessMana: bigint;
+  ethPerFeeAsset: bigint;
+  manaTarget: bigint;
+  manaLimit: bigint;
+  provingCostPerManaEth: bigint;
+  epochDuration: bigint;
+  /** Pre-resolved L1 fees for each slot in the prediction window. */
+  l1FeesBySlot: L1FeeData[];
+};
+
+/**
+ * Predicts min fees for LAG upcoming slots based on the L1 oracle state.
+ * A new oracle update can activate at startSlot + LAG, so only the first LAG entries
+ * are guaranteed stable. Caches L1 queries per L1 block and recomputes predictions
+ * for each mana usage estimate.
+ */
+export class FeePredictor {
+  private cachedState: Promise<FeeOracleState> | undefined;
+  private cachedL1BlockNumber: bigint | undefined;
+
+  private readonly slotDuration: number;
+  private readonly l1GenesisTime: bigint;
+  private readonly ethereumSlotDuration: number;
+
+  constructor(
+    private readonly rollupContract: RollupContract,
+    private readonly publicClient: { getBlockNumber: (opts?: { cacheTime?: number }) => Promise<bigint> },
+    private readonly dateProvider: DateProvider,
+    config: { slotDuration: number; l1GenesisTime: bigint; ethereumSlotDuration: number },
+  ) {
+    this.slotDuration = config.slotDuration;
+    this.l1GenesisTime = config.l1GenesisTime;
+    this.ethereumSlotDuration = config.ethereumSlotDuration;
+  }
+
+  /** Returns predicted min fees for each slot in the prediction window. */
+  async getPredictedMinFees(manaUsage: ManaUsageEstimate): Promise<GasFees[]> {
+    const state = await this.getState();
+    return this.computePredictions(state, manaUsage);
+  }
+
+  /** Fetches and caches rollup state. Refreshes when L1 block number advances. */
+  private async getState(): Promise<FeeOracleState> {
+    const blockNumber = await this.publicClient.getBlockNumber({ cacheTime: 0 });
+    if (this.cachedL1BlockNumber === undefined || blockNumber > this.cachedL1BlockNumber) {
+      this.cachedL1BlockNumber = blockNumber;
+      this.cachedState = this.fetchState(blockNumber);
+    }
+    return this.cachedState!;
+  }
+
+  private async fetchState(blockNumber: bigint): Promise<FeeOracleState> {
+    // Pin all non-constant queries to this L1 block number for a consistent snapshot.
+    const opts = { blockNumber };
+
+    // Cached constants don't need pinning
+    const [manaTarget, manaLimit, provingCostPerManaEth, epochDuration] = await Promise.all([
+      this.rollupContract.getManaTarget(),
+      this.rollupContract.getManaLimit(),
+      this.rollupContract.getProvingCostPerMana(),
+      this.rollupContract.getEpochDuration(),
+    ]);
+
+    // First, compute the earliest possible nextSlot independently of the checkpoint, so we can
+    // evaluate pruneability at the prediction start timestamp instead of the current L1 block time.
+    // This avoids an epoch-boundary edge case where the effective parent differs between now and nextSlot.
+    const slotConfig = { slotDuration: this.slotDuration, l1GenesisTime: this.l1GenesisTime };
+    const currentSlot = await this.rollupContract.getSlotNumber(opts);
+
+    const slotAtNextL1Block = getSlotAtNextL1Block(BigInt(this.dateProvider.nowInSeconds()), {
+      l1GenesisTime: this.l1GenesisTime,
+      slotDuration: this.slotDuration,
+      ethereumSlotDuration: this.ethereumSlotDuration,
+    });
+    const preliminaryNextSlot = SlotNumber(Math.max(currentSlot, slotAtNextL1Block));
+    const nextSlotTimestamp = getTimestampForSlot(preliminaryNextSlot, slotConfig);
+
+    // Resolve the effective checkpoint at the prediction start timestamp
+    const lastCheckpoint = await this.rollupContract.getEffectivePendingCheckpoint(nextSlotTimestamp, opts);
+    const lastSlot = lastCheckpoint.slotNumber;
+    // Refine nextSlot: also account for the slot after the last checkpoint
+    const nextSlot = SlotNumber(Math.max(SlotNumber.add(lastSlot, 1), preliminaryNextSlot));
+    const feeHeader = lastCheckpoint.feeHeader;
+
+    const slotCount = FEE_ORACLE_LAG;
+    const timestamps = times(slotCount, i => getTimestampForSlot(SlotNumber.add(nextSlot, i), slotConfig));
+    const l1FeesBySlot = await Promise.all(timestamps.map(ts => this.rollupContract.getL1FeesAt(ts, opts)));
+
+    return {
+      lastSlot,
+      excessMana: computeExcessMana(feeHeader.excessMana, feeHeader.manaUsed, manaTarget),
+      ethPerFeeAsset: feeHeader.ethPerFeeAsset,
+      manaTarget,
+      manaLimit,
+      provingCostPerManaEth,
+      epochDuration: BigInt(epochDuration),
+      l1FeesBySlot,
+    };
+  }
+
+  /** Computes per-slot fee predictions given cached state and a mana usage assumption. */
+  private computePredictions(state: FeeOracleState, manaUsage: ManaUsageEstimate): GasFees[] {
+    const assumedManaUsed = this.getAssumedManaUsed(state, manaUsage);
+
+    const result: GasFees[] = [];
+    let { excessMana } = state;
+    let { ethPerFeeAsset } = state;
+
+    // Slot 0: current state (next available slot after last checkpoint)
+    result.push(this.computeGasFees(state, excessMana, ethPerFeeAsset, state.l1FeesBySlot[0]));
+
+    // Slots 1..LAG-1: advance excessMana with the assumed mana usage per checkpoint,
+    // and decay ethPerFeeAsset by MAX_FEE_ASSET_PRICE_MODIFIER_BPS per slot for conservative estimates.
+    // Lower ethPerFeeAsset means higher fees in fee asset terms.
+    for (let i = 1; i < state.l1FeesBySlot.length; i++) {
+      excessMana = computeExcessMana(excessMana, assumedManaUsed, state.manaTarget);
+      const decayed = (ethPerFeeAsset * (10000n - MAX_FEE_ASSET_PRICE_MODIFIER_BPS)) / 10000n;
+      ethPerFeeAsset = decayed < MIN_ETH_PER_FEE_ASSET ? MIN_ETH_PER_FEE_ASSET : decayed;
+      result.push(this.computeGasFees(state, excessMana, ethPerFeeAsset, state.l1FeesBySlot[i]));
+    }
+
+    return result;
+  }
+
+  private getAssumedManaUsed(state: FeeOracleState, manaUsage: ManaUsageEstimate): bigint {
+    switch (manaUsage) {
+      case ManaUsageEstimate.None:
+        return 0n;
+      case ManaUsageEstimate.Target:
+        return state.manaTarget;
+      case ManaUsageEstimate.Limit:
+        return state.manaLimit;
+    }
+  }
+
+  private computeGasFees(
+    state: FeeOracleState,
+    excessMana: bigint,
+    ethPerFeeAsset: bigint,
+    l1Fees: L1FeeData,
+  ): GasFees {
+    return new GasFees(
+      0,
+      computeManaMinFee({
+        l1BaseFee: l1Fees.baseFee,
+        l1BlobFee: l1Fees.blobFee,
+        manaTarget: state.manaTarget,
+        epochDuration: state.epochDuration,
+        provingCostPerManaEth: state.provingCostPerManaEth,
+        excessMana,
+        ethPerFeeAsset,
+      }),
+    );
+  }
+}