@aztec/stdlib 0.0.1-commit.3f296a7d2 → 0.0.1-commit.3f5453c7b

package/src/avm/revert_code.ts

@@ -5,35 +5,17 @@ import { BufferReader, FieldReader } from '@aztec/foundation/serialize';
 import { inspect } from 'util';
 import { z } from 'zod';
 
-/**
- * Tracks which revertible phases of a transaction's public execution reverted.
- *
- * A transaction executes in three sequential phases:
- *   1. SETUP     – non-revertible; if this fails the entire transaction is rejected.
- *   2. APP_LOGIC – revertible; its state changes are rolled back on failure.
- *   3. TEARDOWN  – revertible; always runs (even after app-logic revert) so the fee-payment contract can clean up.
- *
- * Only APP_LOGIC and TEARDOWN can produce a revert code. SETUP failures throw instead and discard the transaction
- * entirely.
- */
+/** Whether a transaction's public execution reverted. */
 export enum RevertCodeEnum {
   /** All phases completed successfully; no state was rolled back. */
   OK = 0,
-  /** APP_LOGIC reverted; its state changes were discarded. If present, TEARDOWN still ran and succeeded. */
-  APP_LOGIC_REVERTED = 1,
-  /** TEARDOWN reverted; its state changes were discarded. APP_LOGIC succeeded. */
-  TEARDOWN_REVERTED = 2,
-  /** Both APP_LOGIC and TEARDOWN reverted; only SETUP effects are kept. */
-  BOTH_REVERTED = 3,
+  /** One or more revertible phases reverted; their state changes were discarded. */
+  REVERTED = 1,
 }
 
-function isRevertCodeEnum(value: number): value is RevertCodeEnum {
-  return (
-    (value as RevertCodeEnum) === RevertCodeEnum.OK ||
-    (value as RevertCodeEnum) === RevertCodeEnum.APP_LOGIC_REVERTED ||
-    (value as RevertCodeEnum) === RevertCodeEnum.TEARDOWN_REVERTED ||
-    (value as RevertCodeEnum) === RevertCodeEnum.BOTH_REVERTED
-  );
+/** Returns a valid RevertCodeEnum, coercing any value >= 1 to REVERTED. */
+function toRevertCodeEnum(value: number): RevertCodeEnum {
+  return value >= 1 ? RevertCodeEnum.REVERTED : RevertCodeEnum.OK;
 }
 
 /**
@@ -45,9 +27,13 @@ export class RevertCode {
     this.code = e.valueOf();
   }
   static readonly OK: RevertCode = new RevertCode(RevertCodeEnum.OK);
-  static readonly APP_LOGIC_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.APP_LOGIC_REVERTED);
-  static readonly TEARDOWN_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.TEARDOWN_REVERTED);
-  static readonly BOTH_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.BOTH_REVERTED);
+  static readonly REVERTED: RevertCode = new RevertCode(RevertCodeEnum.REVERTED);
+  /** @deprecated Use REVERTED instead. */
+  static readonly APP_LOGIC_REVERTED: RevertCode = RevertCode.REVERTED;
+  /** @deprecated Use REVERTED instead. */
+  static readonly TEARDOWN_REVERTED: RevertCode = RevertCode.REVERTED;
+  /** @deprecated Use REVERTED instead. */
+  static readonly BOTH_REVERTED: RevertCode = RevertCode.REVERTED;
 
   public getCode(): RevertCodeEnum {
     return this.code;
@@ -65,12 +51,8 @@ export class RevertCode {
     switch (this.code as RevertCodeEnum) {
       case RevertCodeEnum.OK:
         return 'OK';
-      case RevertCodeEnum.APP_LOGIC_REVERTED:
-        return 'Application logic reverted';
-      case RevertCodeEnum.TEARDOWN_REVERTED:
-        return 'Teardown reverted';
-      case RevertCodeEnum.BOTH_REVERTED:
-        return 'Both reverted';
+      case RevertCodeEnum.REVERTED:
+        return 'Reverted';
       default:
         return `Unknown RevertCode: ${this.code}`;
     }
@@ -81,7 +63,11 @@ export class RevertCode {
   }
 
   static get schema(): ZodFor<RevertCode> {
-    return z.nativeEnum(RevertCodeEnum).transform(value => new RevertCode(value));
+    return z
+      .number()
+      .int()
+      .min(0)
+      .transform(value => new RevertCode(toRevertCodeEnum(value)));
   }
 
   /**
@@ -96,10 +82,10 @@ export class RevertCode {
       return obj;
     }
     const code = typeof obj === 'number' ? obj : (obj.code ?? obj);
-    if (!isRevertCodeEnum(code)) {
+    if (typeof code !== 'number' || code < 0) {
       throw new Error(`Invalid RevertCode: ${code}`);
     }
-    return new RevertCode(code);
+    return new RevertCode(toRevertCodeEnum(code));
   }
 
   /**
@@ -131,10 +117,10 @@ export class RevertCode {
   }
 
   public static fromNumber(code: number): RevertCode {
-    if (!isRevertCodeEnum(code)) {
+    if (code < 0) {
       throw new Error(`Invalid RevertCode: ${code}`);
     }
-    return new RevertCode(code);
+    return new RevertCode(toRevertCodeEnum(code));
   }
 
   public static fromField(field: Fr): RevertCode {
@@ -152,7 +138,7 @@ export class RevertCode {
     return RevertCode.fromNumber(code);
   }
 
-  private static readonly NUM_OPTIONS = 4;
+  private static readonly NUM_OPTIONS = 2;
   static random(): RevertCode {
     return new RevertCode(Math.floor(Math.random() * RevertCode.NUM_OPTIONS));
   }

package/src/block/l2_block_source.ts

@@ -13,7 +13,7 @@ import type { TypedEventEmitter } from '@aztec/foundation/types';
 import { z } from 'zod';
 
 import type { Checkpoint } from '../checkpoint/checkpoint.js';
-import type { CheckpointData } from '../checkpoint/checkpoint_data.js';
+import type { CheckpointData, CommonCheckpointData, ProposedCheckpointData } from '../checkpoint/checkpoint_data.js';
 import type { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
@@ -229,6 +229,12 @@ export interface L2BlockSource {
    */
   getPendingChainValidationStatus(): Promise<ValidateCheckpointResult>;
 
+  /** Returns the checkpoint at the proposed chain tip. */
+  getProposedCheckpoint(): Promise<CommonCheckpointData | undefined>;
+
+  /** Returns proposed checkpoint, if set, undefined if not*/
+  getProposedCheckpointOnly(): Promise<ProposedCheckpointData | undefined>;
+
   /** Force a sync. */
   syncImmediate(): Promise<void>;
 
@@ -312,12 +318,13 @@ export interface L2BlockSourceEventEmitter extends L2BlockSource {
  * - proven: Proven block on L1.
  * - finalized: Proven block on a finalized L1 block (not implemented, set to proven for now).
  */
-export type L2BlockTag = 'proposed' | 'checkpointed' | 'proven' | 'finalized';
+export type L2BlockTag = 'proposed' | 'proposedCheckpoint' | 'checkpointed' | 'proven' | 'finalized';
 
 /** Tips of the L2 chain. */
 export type L2Tips = {
   proposed: L2BlockId;
   checkpointed: L2TipId;
+  proposedCheckpoint: L2TipId;
   proven: L2TipId;
   finalized: L2TipId;
 };
@@ -362,6 +369,7 @@ const L2TipIdSchema = z.object({
 export const L2TipsSchema = z.object({
   proposed: L2BlockIdSchema,
   checkpointed: L2TipIdSchema,
+  proposedCheckpoint: L2TipIdSchema,
   proven: L2TipIdSchema,
   finalized: L2TipIdSchema,
 });

package/src/block/l2_block_stream/l2_tips_store_base.ts

@@ -66,24 +66,29 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
 
   public getL2Tips(): Promise<L2Tips> {
     return this.runInTransaction(async () => {
-      const [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId] = await Promise.all([
-        this.getBlockId('proposed'),
-        this.getBlockId('finalized'),
-        this.getBlockId('proven'),
-        this.getBlockId('checkpointed'),
-      ]);
-
-      const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId] = await Promise.all([
-        this.getCheckpointId('finalized'),
-        this.getCheckpointId('proven'),
-        this.getCheckpointId('checkpointed'),
-      ]);
+      const [proposedBlockId, finalizedBlockId, provenBlockId, checkpointedBlockId, proposedCheckpointBlockId] =
+        await Promise.all([
+          this.getBlockId('proposed'),
+          this.getBlockId('finalized'),
+          this.getBlockId('proven'),
+          this.getBlockId('checkpointed'),
+          this.getBlockId('proposedCheckpoint'),
+        ]);
+
+      const [finalizedCheckpointId, provenCheckpointId, checkpointedCheckpointId, proposedCheckpointId] =
+        await Promise.all([
+          this.getCheckpointId('finalized'),
+          this.getCheckpointId('proven'),
+          this.getCheckpointId('checkpointed'),
+          this.getCheckpointId('proposedCheckpoint'),
+        ]);
 
       return {
         proposed: proposedBlockId,
         finalized: { block: finalizedBlockId, checkpoint: finalizedCheckpointId },
         proven: { block: provenBlockId, checkpoint: provenCheckpointId },
         checkpointed: { block: checkpointedBlockId, checkpoint: checkpointedCheckpointId },
+        proposedCheckpoint: { block: proposedCheckpointBlockId, checkpoint: proposedCheckpointId },
       };
     });
   }
@@ -164,6 +169,12 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     await this.runInTransaction(async () => {
       await this.saveTag('checkpointed', event.block);
       await this.saveCheckpoint(event.checkpoint);
+      // proposedCheckpoint is always >= checkpointed. If checkpointed has caught up
+      // or surpassed it, advance proposedCheckpoint to match.
+      const proposedCheckpointBlock = await this.getBlockId('proposedCheckpoint');
+      if (event.block.number > proposedCheckpointBlock.number) {
+        await this.saveTag('proposedCheckpoint', event.block);
+      }
     });
   }
 
@@ -174,6 +185,7 @@ export abstract class L2TipsStoreBase implements L2BlockStreamEventHandler, L2Bl
     await this.runInTransaction(async () => {
       await this.saveTag('proposed', event.block);
       await this.saveTag('checkpointed', event.block);
+      await this.saveTag('proposedCheckpoint', event.block);
       const storeProven = await this.getBlockId('proven');
       if (storeProven.number > event.block.number) {
         await this.saveTag('proven', event.block);

package/src/block/test/l2_tips_store_test_suite.ts

@@ -67,11 +67,18 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     checkpoint: makeCheckpointIdForBlock(blockNumber),
   });
 
-  const makeTips = (proposed: number, proven: number, finalized: number, checkpointed: number = 0) => ({
+  const makeTips = (
+    proposed: number,
+    proven: number,
+    finalized: number,
+    checkpointed: number = 0,
+    proposedCheckpoint: number = 0,
+  ) => ({
     proposed: makeTip(proposed),
     proven: makeTipId(proven),
     finalized: makeTipId(finalized),
     checkpointed: makeTipId(checkpointed),
+    proposedCheckpoint: makeTipId(proposedCheckpoint),
   });
 
   const makeCheckpoint = async (checkpointNumber: number, blocks: L2Block[]): Promise<PublishedCheckpoint> => {

package/src/checkpoint/checkpoint.ts

@@ -100,7 +100,16 @@ export class Checkpoint {
    * checkpoints up to and including this one in the epoch.
    */
   public getCheckpointOutHash(): Fr {
-    const msgs = this.blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
+    return Checkpoint.getCheckpointOutHash(this.blocks);
+  }
+
+  /**
+   * Returns the out hash computed from all l2-to-l1 messages in this checkpoint.
+   * Note: This value is different from the out hash in the header, which is the **accumulated** out hash over all
+   * checkpoints up to and including this one in the epoch.
+   */
+  static getCheckpointOutHash(blocks: L2Block[]): Fr {
+    const msgs = blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
     return computeCheckpointOutHash(msgs);
   }
 
@@ -165,6 +174,7 @@ export class Checkpoint {
     let lastArchive = previousArchive;
     for (let i = 0; i < numBlocks; i++) {
       const block = await L2Block.random(BlockNumber(startBlockNumber + i), {
+        checkpointNumber,
         indexWithinCheckpoint: IndexWithinCheckpoint(i),
         ...options,
         ...(lastArchive ? { lastArchive } : {}),

package/src/checkpoint/checkpoint_data.ts

@@ -14,18 +14,54 @@ import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { L1PublishedData } from './published_checkpoint.js';
 
-/** Lightweight checkpoint metadata without full block data. */
-export type CheckpointData = {
+/** Base type for checkpoint data */
+export type CommonCheckpointData = {
   checkpointNumber: CheckpointNumber;
   header: CheckpointHeader;
-  archive: AppendOnlyTreeSnapshot;
-  checkpointOutHash: Fr;
   startBlock: BlockNumber;
   blockCount: number;
+};
+
+/** Data stored with checkpoint data after publishing on l1 */
+export type L1EnrichedCheckpointData = {
   attestations: CommitteeAttestation[];
   l1: L1PublishedData;
 };
 
+/** Data stored alongside checkpoint data in storage */
+export type StorageEnrichedCheckpointData = {
+  archive: AppendOnlyTreeSnapshot;
+  checkpointOutHash: Fr;
+};
+
+/** Data stored only with proposed checkpoint data  */
+export type ProposedOnlyCheckpointData = {
+  totalManaUsed: bigint;
+  feeAssetPriceModifier: bigint;
+};
+
+/** Lightweight checkpoint metadata without full block data. */
+export type CheckpointData = CommonCheckpointData & StorageEnrichedCheckpointData & L1EnrichedCheckpointData;
+
+/** Input for setting a proposed checkpoint. The archive and checkpointOutHash are computed
+ *  internally by the block store from the stored blocks. */
+export type ProposedCheckpointInput = CommonCheckpointData & ProposedOnlyCheckpointData;
+
+/** Full data for a proposed checkpoint (proposed but not yet L1-confirmed).
+ *  Includes fee-relevant fields used during pipelining to compute the fee header override. */
+export type ProposedCheckpointData = ProposedCheckpointInput & StorageEnrichedCheckpointData;
+
+export const ProposedCheckpointDataSchema = z.object({
+  checkpointNumber: CheckpointNumberSchema,
+  header: CheckpointHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  checkpointOutHash: schemas.Fr,
+  startBlock: BlockNumberSchema,
+  blockCount: z.number(),
+  totalManaUsed: schemas.BigInt,
+  feeAssetPriceModifier: schemas.BigInt,
+});
+
 export const CheckpointDataSchema = z
   .object({
     checkpointNumber: CheckpointNumberSchema,

package/src/config/sequencer-config.ts

@@ -1,6 +1,7 @@
 import type { ConfigMappingsType } from '@aztec/foundation/config';
 
 import type { SequencerConfig } from '../interfaces/configs.js';
+import { DEFAULT_P2P_PROPAGATION_TIME } from '../timetable/index.js';
 
 /** Default maximum number of transactions per block. */
 export const DEFAULT_MAX_TXS_PER_BLOCK = 32;
@@ -12,7 +13,10 @@ export const DEFAULT_MAX_TXS_PER_BLOCK = 32;
  * to avoid duplication.
  */
 export const sharedSequencerConfigMappings: ConfigMappingsType<
-  Pick<SequencerConfig, 'blockDurationMs' | 'expectedBlockProposalsPerSlot' | 'maxTxsPerBlock'>
+  Pick<
+    SequencerConfig,
+    'blockDurationMs' | 'expectedBlockProposalsPerSlot' | 'maxTxsPerBlock' | 'attestationPropagationTime'
+  >
 > = {
   blockDurationMs: {
     env: 'SEQ_BLOCK_DURATION_MS',
@@ -34,4 +38,10 @@ export const sharedSequencerConfigMappings: ConfigMappingsType<
     description: 'The maximum number of txs to include in a block.',
     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).',
+    parseEnv: (val: string) => (val ? parseFloat(val) : undefined),
+    defaultValue: DEFAULT_P2P_PROPAGATION_TIME,
+  },
 };

package/src/epoch-helpers/index.ts

@@ -68,6 +68,14 @@ export function getNextL1SlotTimestamp(
   return constants.l1GenesisTime + (currentL1Slot + 1n) * BigInt(constants.ethereumSlotDuration);
 }
 
+/** Returns the timestamp of the last L1 slot within a given L2 slot. */
+export function getLastL1SlotTimestampForL2Slot(
+  slot: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): bigint {
+  return getTimestampForSlot(slot, constants) + BigInt(constants.slotDuration - constants.ethereumSlotDuration);
+}
+
 /** Returns the L2 slot number at the next L1 block based on the current timestamp. */
 export function getSlotAtNextL1Block(
   currentL1Timestamp: bigint,
@@ -154,6 +162,11 @@ export function getProofSubmissionDeadlineTimestamp(
   return getTimestampForSlot(deadlineSlot, constants);
 }
 
+/** Computes the quorum size required for a committee (⌊2n/3⌋ + 1). */
+export function computeQuorum(committeeSize: number): number {
+  return Math.floor((committeeSize * 2) / 3) + 1;
+}
+
 /** Returns the timestamp to start building a block for a given L2 slot. Computed as the start timestamp of the slot minus one L1 slot duration. */
 export function getSlotStartBuildTimestamp(
   slotNumber: SlotNumber,

package/src/file-store/factory.ts

@@ -1,7 +1,7 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
 
 import { GoogleCloudFileStore } from './gcs.js';
-import { HttpFileStore } from './http.js';
+import { HttpFileStore, type HttpFileStoreOptions } from './http.js';
 import type { FileStore, ReadOnlyFileStore } from './interface.js';
 import { LocalFileStore } from './local.js';
 import { S3FileStore } from './s3.js';
@@ -59,17 +59,26 @@ export async function createFileStore(
   }
 }
 
-export async function createReadOnlyFileStore(config: string, logger?: Logger): Promise<ReadOnlyFileStore>;
-export async function createReadOnlyFileStore(config: undefined, logger?: Logger): Promise<undefined>;
+export async function createReadOnlyFileStore(
+  config: string,
+  logger?: Logger,
+  options?: HttpFileStoreOptions,
+): Promise<ReadOnlyFileStore>;
+export async function createReadOnlyFileStore(
+  config: undefined,
+  logger?: Logger,
+  options?: HttpFileStoreOptions,
+): Promise<undefined>;
 export async function createReadOnlyFileStore(
   config: string | undefined,
   logger = createLogger('stdlib:file-store'),
+  options?: HttpFileStoreOptions,
 ): Promise<ReadOnlyFileStore | undefined> {
   if (config === undefined) {
     return undefined;
   } else if (config.startsWith('http://') || config.startsWith('https://')) {
     logger.info(`Creating read-only HTTP file store at ${config}`);
-    return new HttpFileStore(config, logger);
+    return new HttpFileStore(config, logger, options);
   } else {
     return await createFileStore(config, logger);
   }

package/src/file-store/http.ts

@@ -10,6 +10,14 @@ import { pipeline } from 'stream/promises';
 
 import type { ReadOnlyFileStore } from './interface.js';
 
+/** Options for configuring HttpFileStore behavior. */
+export interface HttpFileStoreOptions {
+  /** Retry backoff intervals in seconds. Empty array disables retries. Default: [1, 1, 3]. */
+  retryBackoff?: number[];
+  /** Request timeout in milliseconds. Default: no timeout (axios default). */
+  timeoutMs?: number;
+}
+
 export class HttpFileStore implements ReadOnlyFileStore {
   private readonly axiosInstance: AxiosInstance;
   private readonly fetch: <T>(config: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
@@ -17,17 +25,28 @@ export class HttpFileStore implements ReadOnlyFileStore {
   constructor(
     private readonly baseUrl: string,
     private readonly log: Logger = createLogger('stdlib:http-file-store'),
+    options?: HttpFileStoreOptions,
   ) {
-    this.axiosInstance = axios.create();
-    this.fetch = async <T>(config: AxiosRequestConfig) => {
-      return await retry(
-        () => this.axiosInstance.request<T>(config),
-        `Fetching ${config.url}`,
-        makeBackoff([1, 1, 3]),
-        this.log,
-        /*failSilently=*/ true,
-      );
-    };
+    this.axiosInstance = axios.create({
+      ...(options?.timeoutMs !== undefined && { timeout: options.timeoutMs }),
+    });
+
+    const retryBackoff = options?.retryBackoff ?? [1, 1, 3];
+    if (retryBackoff.length > 0) {
+      this.fetch = async <T>(config: AxiosRequestConfig) => {
+        return await retry(
+          () => this.axiosInstance.request<T>(config),
+          `Fetching ${config.url}`,
+          makeBackoff(retryBackoff),
+          this.log,
+          /*failSilently=*/ true,
+        );
+      };
+    } else {
+      this.fetch = async <T>(config: AxiosRequestConfig) => {
+        return await this.axiosInstance.request<T>(config);
+      };
+    }
   }
 
   public async read(pathOrUrl: string): Promise<Buffer> {

package/src/file-store/index.ts

@@ -1,2 +1,3 @@
 export * from './interface.js';
 export * from './factory.js';
+export { type HttpFileStoreOptions } from './http.js';

package/src/gas/README.md

@@ -84,6 +84,37 @@ else                    →  use post (new fees)
 **Net effect**: L1 fee changes reach L2 with a 2-slot delay and can update at most once
 every 5 slots.
 
+### Worked Example
+
+Suppose the oracle is updated at slot 10 with new L1 fees. Here is the timeline:
+
+```
+Slot  Oracle state          Active fees   Notes
+────  ────────────────────  ────────────  ──────────────────────────────────
+ 10   pre=A, post=B, soc=12   A           Update queued. slotOfChange = 10 + LAG = 12.
+ 11   (same)                  A           Still before slotOfChange → pre (A).
+ 12   (same)                  B           slot >= slotOfChange → post (B) activates.
+ 13   (same)                  B           B remains active.
+ 14   (same)                  B           B remains active.
+ 15   Update allowed again    B           Earliest next update: soc + (LIFETIME - LAG)
+                                          = 12 + 3 = 15.
+```
+ 
+Key observations:
+
+1. **Slots 10-11**: The old fees (A) are still in effect. Transactions submitted during
+   these slots see the old L1 cost. This is the **LAG** window — it gives pending
+   transactions 2 slots to land before fees change.
+
+2. **Slot 12**: The new fees (B) activate. Any checkpoint proposed at slot >= 12 uses B
+   for its sequencer/prover cost calculation.
+
+3. **Slots 12-14**: No new oracle update is accepted. The system is in a **cooldown**
+   period of `LIFETIME - LAG = 3` slots after the transition.
+
+4. **Slot 15**: A new oracle update can be queued (earliest `acceptableSlot`). If
+   triggered, the new values would activate at slot 15 + LAG = 17.
+
 ## Fee Asset Price
 
 Fees are computed in ETH internally but converted to the fee asset (Fee Juice) via

package/src/gas/fee_math.ts

@@ -0,0 +1,120 @@
+/**
+ * TypeScript port of fee computation logic from FeeLib.sol.
+ * Used to predict worst-case min fees over a future window of L2 slots.
+ */
+
+// Constants matching FeeLib.sol
+export const MINIMUM_CONGESTION_MULTIPLIER = 1_000_000_000n;
+export const L1_GAS_PER_CHECKPOINT_PROPOSED = 300_000n;
+export const L1_GAS_PER_EPOCH_VERIFIED = 3_600_000n;
+export const BLOBS_PER_CHECKPOINT = 3n;
+export const BLOB_GAS_PER_BLOB = 2n ** 17n;
+export const MAGIC_CONGESTION_VALUE_MULTIPLIER = 854_700_854n;
+export const MAGIC_CONGESTION_VALUE_DIVISOR = 100_000_000n;
+export const ETH_PER_FEE_ASSET_PRECISION = 1_000_000_000_000n;
+export const MIN_ETH_PER_FEE_ASSET = 100n;
+
+/** Number of L2 slots of lag before new oracle values activate. Defines the prediction window. */
+export const FEE_ORACLE_LAG = 2;
+
+/** Expected mana usage per checkpoint for fee prediction. */
+export enum ManaUsageEstimate {
+  /** No usage — fees decrease as congestion drains. */
+  None = 'none',
+  /** Target usage — congestion stays roughly flat (steady state). */
+  Target = 'target',
+  /** Limit usage (2x target) — worst case, congestion grows maximally. */
+  Limit = 'limit',
+}
+
+/** Parameters for computing the mana min fee at a given point in time. */
+export type ManaMinFeeParams = {
+  l1BaseFee: bigint;
+  l1BlobFee: bigint;
+  manaTarget: bigint;
+  epochDuration: bigint;
+  provingCostPerManaEth: bigint;
+  excessMana: bigint;
+  ethPerFeeAsset: bigint;
+};
+
+/**
+ * Taylor series approximation of `factor * e^(numerator/denominator)`.
+ * Direct port of FeeLib.sol fakeExponential (EIP-4844 style).
+ */
+export function fakeExponential(factor: bigint, numerator: bigint, denominator: bigint): bigint {
+  let i = 1n;
+  let output = 0n;
+  let numeratorAccumulator = factor * denominator;
+  while (numeratorAccumulator > 0n) {
+    output += numeratorAccumulator;
+    numeratorAccumulator = (numeratorAccumulator * numerator) / (denominator * i);
+    i += 1n;
+  }
+  return output / denominator;
+}
+
+/** Computes excess mana for the next checkpoint, clamped to zero. */
+export function computeExcessMana(prevExcessMana: bigint, prevManaUsed: bigint, manaTarget: bigint): bigint {
+  const sum = prevExcessMana + prevManaUsed;
+  return sum > manaTarget ? sum - manaTarget : 0n;
+}
+
+/** Computes the congestion multiplier from excess mana (1e9 = no congestion). */
+export function computeCongestionMultiplier(excessMana: bigint, manaTarget: bigint): bigint {
+  const denominator = (manaTarget * MAGIC_CONGESTION_VALUE_MULTIPLIER) / MAGIC_CONGESTION_VALUE_DIVISOR;
+  const cappedNumerator = excessMana < denominator * 100n ? excessMana : denominator * 100n;
+  return fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, cappedNumerator, denominator);
+}
+
+/** Ceiling division for positive bigints. */
+function ceilDiv(a: bigint, b: bigint): bigint {
+  return (a + b - 1n) / b;
+}
+
+/** Converts an ETH value to fee asset value using ethPerFeeAsset (1e12 precision). */
+function toFeeAsset(ethValue: bigint, ethPerFeeAsset: bigint): bigint {
+  if (ethPerFeeAsset === 0n) {
+    return 0n;
+  }
+  return ceilDiv(ethValue * ETH_PER_FEE_ASSET_PRECISION, ethPerFeeAsset);
+}
+
+/**
+ * Computes the full mana min fee (sequencer + prover + congestion) in fee asset terms.
+ * Mirrors FeeLib.getManaMinFeeComponentsAt + summedMinFee.
+ */
+export function computeManaMinFee(params: ManaMinFeeParams): bigint {
+  const { l1BaseFee, l1BlobFee, manaTarget, epochDuration, provingCostPerManaEth, excessMana, ethPerFeeAsset } = params;
+
+  if (manaTarget === 0n) {
+    return 0n;
+  }
+
+  // Sequencer cost per mana (in ETH)
+  const ethUsed = L1_GAS_PER_CHECKPOINT_PROPOSED * l1BaseFee + BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * l1BlobFee;
+  const sequencerCostEth = ceilDiv(ethUsed, manaTarget);
+
+  // Prover cost per mana (in ETH): L1 verification gas + governance-set proving cost
+  const proverCostEth =
+    ceilDiv(ceilDiv(L1_GAS_PER_EPOCH_VERIFIED * l1BaseFee, epochDuration), manaTarget) + provingCostPerManaEth;
+
+  // Total base cost in ETH (congestion is computed on this)
+  const totalEth = sequencerCostEth + proverCostEth;
+
+  // Congestion multiplier and cost (in ETH)
+  const congestionMul = computeCongestionMultiplier(excessMana, manaTarget);
+  const congestionCostEth = (totalEth * congestionMul) / MINIMUM_CONGESTION_MULTIPLIER - totalEth;
+
+  // Convert all components to fee asset
+  const clampedEthPerFeeAsset = ethPerFeeAsset < MIN_ETH_PER_FEE_ASSET ? MIN_ETH_PER_FEE_ASSET : ethPerFeeAsset;
+  const sequencerCost = toFeeAsset(sequencerCostEth, clampedEthPerFeeAsset);
+  const proverCost = toFeeAsset(proverCostEth, clampedEthPerFeeAsset);
+  const congestionCost = toFeeAsset(congestionCostEth, clampedEthPerFeeAsset);
+
+  const total = sequencerCost + proverCost + congestionCost;
+
+  // Cap at uint128 max (matching FeeLib.summedMinFee)
+  const UINT128_MAX = (1n << 128n) - 1n;
+  return total < UINT128_MAX ? total : UINT128_MAX;
+}