@aztec/stdlib 0.0.1-commit.b655e406 → 0.0.1-commit.b8a057fa

package/src/file-store/http.ts

@@ -6,10 +6,18 @@ import { createWriteStream } from 'fs';
 import { mkdir } from 'fs/promises';
 import { dirname } from 'path';
 import { Readable } from 'stream';
-import { finished } from 'stream/promises';
+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> {
@@ -43,11 +62,14 @@ export class HttpFileStore implements ReadOnlyFileStore {
   public async download(pathOrUrl: string, destPath: string): Promise<void> {
     const url = this.getUrl(pathOrUrl);
     try {
+      this.log.debug(`Downloading file from ${url} to ${destPath}`);
       const response = await this.fetch<Readable>({ url, method: 'GET', responseType: 'stream' });
+      this.log.debug(`Response ${response.status} (${response.statusText}) from ${url}, writing to ${destPath}`);
       await mkdir(dirname(destPath), { recursive: true });
-      await finished(response.data.pipe(createWriteStream(destPath)));
+      await pipeline(response.data, createWriteStream(destPath));
+      this.log.debug(`Download of ${url} to ${destPath} complete`);
     } catch (error) {
-      throw new Error(`Error fetching file from ${url}: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Error fetching file from ${url}`, { cause: error });
     }
   }
 

package/src/file-store/index.ts

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

package/src/file-store/local.ts

@@ -1,15 +1,21 @@
 import { access, mkdir, readFile, writeFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
-import type { FileStore } from './interface.js';
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
 
 export class LocalFileStore implements FileStore {
   constructor(private readonly basePath: string) {}
 
-  public async save(path: string, data: Buffer): Promise<string> {
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
     const fullPath = this.getFullPath(path);
     await mkdir(dirname(fullPath), { recursive: true });
-    await writeFile(fullPath, data);
+    const toWrite = opts?.compress ? await gzip(data) : data;
+    await writeFile(fullPath, toWrite);
     return `file://${fullPath}`;
   }
 
@@ -18,9 +24,13 @@ export class LocalFileStore implements FileStore {
     return this.save(destPath, data);
   }
 
-  public read(pathOrUrlStr: string): Promise<Buffer> {
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
     const fullPath = this.getFullPath(pathOrUrlStr);
-    return readFile(fullPath);
+    const data = await readFile(fullPath);
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/file-store/memory.ts

@@ -0,0 +1,94 @@
+import { writeFile } from 'fs/promises';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
+// Backing data is shared per namespace so that a store created for writing and a (read-only) store
+// created later from the same `mem://` URL observe the same files — mirroring how two `file://`
+// stores over the same directory share state on disk. Without this, `FileStoreTxSource`, which
+// builds its own store from the URL, would never see what a test wrote through a different instance.
+const namespaces = new Map<string, Map<string, Buffer>>();
+
+/**
+ * In-memory {@link FileStore}, addressed via `mem://<namespace>/...`. Reads and writes are synchronous
+ * map operations with no disk I/O, so it is deterministic — useful for tests that exercise consumers
+ * of a file store (e.g. the tx file store) rather than the on-disk store itself, where a real
+ * filesystem can introduce timing flakes.
+ */
+export class InMemoryFileStore implements FileStore {
+  private readonly files: Map<string, Buffer>;
+
+  constructor(private readonly namespace: string) {
+    let files = namespaces.get(namespace);
+    if (!files) {
+      files = new Map();
+      namespaces.set(namespace, files);
+    }
+    this.files = files;
+  }
+
+  /** Clears all in-memory file store data, or a single namespace. Intended for test isolation. */
+  static clear(namespace?: string): void {
+    if (namespace === undefined) {
+      namespaces.clear();
+    } else {
+      namespaces.delete(namespace);
+    }
+  }
+
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
+    const toStore = opts?.compress ? await gzip(data) : data;
+    const key = this.key(path);
+    this.files.set(key, Buffer.from(toStore));
+    return `mem://${this.namespace}/${key}`;
+  }
+
+  public async upload(destPath: string, srcPath: string, opts?: FileStoreSaveOptions): Promise<string> {
+    const { readFile } = await import('fs/promises');
+    return this.save(destPath, await readFile(srcPath), opts);
+  }
+
+  public async read(pathOrUrl: string): Promise<Buffer> {
+    const data = this.files.get(this.key(pathOrUrl));
+    if (data === undefined) {
+      throw new Error(`File not found in memory store: ${pathOrUrl}`);
+    }
+    // Match LocalFileStore: transparently gunzip content that was stored compressed.
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
+  }
+
+  public async download(pathOrUrl: string, destPath: string): Promise<void> {
+    await writeFile(destPath, await this.read(pathOrUrl));
+  }
+
+  public exists(pathOrUrl: string): Promise<boolean> {
+    return Promise.resolve(this.files.has(this.key(pathOrUrl)));
+  }
+
+  /** Lists stored file keys, optionally restricted to those under `prefix`. Not part of {@link FileStore}. */
+  public listFiles(prefix = ''): string[] {
+    const keys = [...this.files.keys()];
+    const normalizedPrefix = prefix.replace(/^\/+/, '');
+    return normalizedPrefix ? keys.filter(k => k.startsWith(normalizedPrefix)) : keys;
+  }
+
+  /** Resolves a relative path or a `mem://` URI (as returned by `save`) to the registry key. */
+  private key(pathOrUrl: string): string {
+    const ownPrefix = `mem://${this.namespace}/`;
+    if (pathOrUrl.startsWith(ownPrefix)) {
+      return pathOrUrl.slice(ownPrefix.length);
+    }
+    if (pathOrUrl.startsWith('mem://')) {
+      // A mem:// URI for some namespace: drop the scheme and the leading namespace segment.
+      return pathOrUrl.slice('mem://'.length).replace(/^[^/]*\//, '');
+    }
+    return pathOrUrl.replace(/^\/+/, '');
+  }
+}

package/src/file-store/s3.ts

@@ -12,11 +12,15 @@ import { mkdir, mkdtemp, stat, unlink } from 'fs/promises';
 import { tmpdir } from 'os';
 import { basename, dirname, join } from 'path';
 import { Readable } from 'stream';
-import { finished } from 'stream/promises';
-import { createGzip } from 'zlib';
+import { pipeline } from 'stream/promises';
+import { promisify } from 'util';
+import { createGzip, gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
 import type { FileStore, FileStoreSaveOptions } from './interface.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 function normalizeBasePath(path: string): string {
   return path?.replace(/^\/+|\/+$/g, '') ?? '';
 }
@@ -52,7 +56,7 @@ export class S3FileStore implements FileStore {
     const key = this.getFullPath(path);
     const shouldCompress = !!opts.compress;
 
-    const body = shouldCompress ? (await import('zlib')).gzipSync(data) : data;
+    const body = shouldCompress ? await gzip(data) : data;
     const contentLength = body.length;
     const contentType = this.detectContentType(key, shouldCompress);
     const put = new PutObjectCommand({
@@ -60,6 +64,7 @@ export class S3FileStore implements FileStore {
       Key: key,
       Body: body,
       ContentType: contentType,
+      ContentEncoding: shouldCompress ? 'gzip' : undefined,
       CacheControl: opts.metadata?.['Cache-control'],
       Metadata: this.extractUserMetadata(opts.metadata),
       ContentLength: contentLength,
@@ -88,11 +93,8 @@ export class S3FileStore implements FileStore {
       // Pre-gzip to a temp file so we know the exact length for R2/S3 headers
       const tmpDir = await mkdtemp(join(tmpdir(), 's3-upload-'));
       const gzPath = join(tmpDir, `${basename(srcPath)}.gz`);
-      const source = createReadStream(srcPath);
-      const gz = createGzip();
-      const out = createWriteStream(gzPath);
       try {
-        await finished(source.pipe(gz).pipe(out));
+        await pipeline(createReadStream(srcPath), createGzip(), createWriteStream(gzPath));
         const st = await stat(gzPath);
         contentLength = st.size;
         bodyPath = gzPath;
@@ -137,15 +139,18 @@ export class S3FileStore implements FileStore {
     for await (const chunk of stream) {
       chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
     }
-    return Buffer.concat(chunks);
+    const buffer = Buffer.concat(chunks);
+    if (out.ContentEncoding === 'gzip') {
+      return await gunzip(buffer);
+    }
+    return buffer;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {
     const { bucket, key } = this.getBucketAndKey(pathOrUrlStr);
     const out: GetObjectCommandOutput = await this.s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
     await mkdir(dirname(destPath), { recursive: true });
-    const write = createWriteStream(destPath);
-    await finished((out.Body as Readable).pipe(write));
+    await pipeline(out.Body as Readable, createWriteStream(destPath));
   }
 
   public async exists(pathOrUrlStr: string): Promise<boolean> {

package/src/gas/README.md

@@ -0,0 +1,246 @@
+# Aztec Gas and Fee Model
+
+The minimum fee per mana and its components are computed on L1 in
+`l1-contracts/src/core/libraries/rollup/FeeLib.sol`. This document describes the
+formulas, the oracle lag/lifetime mechanism, and the TypeScript types in this directory.
+
+## Mana
+
+Aztec uses **mana** as its unit of work (analogous to Ethereum gas). Transactions consume
+mana in two dimensions: **DA** (data availability) and **L2** (execution). The total fee
+is `gasUsed * feePerMana` summed across both dimensions.
+
+## Fee Components
+
+The minimum fee per mana has four components:
+
+### Sequencer Cost
+
+L1 cost to propose a checkpoint (calldata gas + blob data), amortized over `manaTarget`:
+
+```
+sequencerCost = ((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
+              + (BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * blobFee))
+              / manaTarget
+```
+
+### Prover Cost
+
+L1 cost to verify an epoch proof, amortized over epoch duration and `manaTarget`, plus a
+governance-set proving cost that compensates for off-chain proof generation:
+
+```
+proverCost = (L1_GAS_PER_EPOCH_VERIFIED * baseFee / epochDuration) / manaTarget
+           + provingCostPerMana
+```
+
+### Congestion Cost
+
+An exponential surcharge when the network is congested (inspired by EIP-1559; the
+implementation uses the `fakeExponential` Taylor series approximation from EIP-4844):
+
+```
+baseCost          = sequencerCost + proverCost
+congestionCost    = baseCost * congestionMultiplier / MINIMUM_CONGESTION_MULTIPLIER - baseCost
+```
+
+When there is no congestion the multiplier equals `MINIMUM_CONGESTION_MULTIPLIER` (1e9)
+and congestion cost is zero.
+
+### Congestion Multiplier
+
+```
+excessMana          = max(0, prevExcessMana + prevManaUsed - manaTarget)
+congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, excessMana, denominator)
+```
+
+Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
+
+### Total
+
+```
+minFeePerMana = sequencerCost + proverCost + congestionCost
+```
+
+## L1 Gas Oracle: Lag and Lifetime
+
+The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a two-phase
+(`pre` / `post`) system that smooths out L1 fee volatility.
+
+- **LAG = 2 slots** — when new L1 fees are observed, they activate `LAG` slots later
+  (`slotOfChange = currentSlot + LAG`). This gives mempool transactions time to land
+  before fees change.
+- **LIFETIME = 5 slots** — after an oracle update, the next update is rejected until
+  `slotOfChange + (LIFETIME - LAG)` = 3 more slots have passed. This rate-limits how
+  frequently L1 fee data can change.
+
+Fee resolution at a given timestamp:
+
+```
+if slot < slotOfChange  →  use pre  (old fees)
+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
+`ethPerFeeAsset` (1e12 precision). The price updates at most ±1% (±100 bps) per
+checkpoint:
+
+```
+newPrice = currentPrice * (10000 + modifierBps) / 10000
+```
+
+## Maximum Fee Change Rate
+
+| Component              | Bound                                                   |
+| ---------------------- | ------------------------------------------------------- |
+| L1 base fee / blob fee | At most once every 5 slots (oracle LIFETIME)            |
+| Fee asset price        | ±1% per checkpoint                                      |
+| Congestion multiplier  | Depends on excess mana accumulation/drain per checkpoint |
+| Sequencer/prover costs | Scale linearly with L1 fees                             |
+
+## Key Constants
+
+| Constant                       | Value          |
+| ------------------------------ | -------------- |
+| `L1_GAS_PER_CHECKPOINT_PROPOSED` | 300,000      |
+| `L1_GAS_PER_EPOCH_VERIFIED`     | 3,600,000    |
+| `BLOBS_PER_CHECKPOINT`          | 3            |
+| `BLOB_GAS_PER_BLOB`             | 2^17         |
+| `MINIMUM_CONGESTION_MULTIPLIER` | 1e9          |
+| `LAG`                           | 2 slots      |
+| `LIFETIME`                      | 5 slots      |
+
+## Gas and Data Limits
+
+The fee model above is *how much you pay* per unit of gas; this section is *how much you may use*. Limits
+form a hierarchy from a single transaction up to a whole checkpoint, and a tx that is admissible for relay
+must also be buildable into a block and fit a valid checkpoint.
+
+### Per-tx protocol maxima
+
+Hard ceilings on what any single tx may declare, independent of network configuration. Declaring more is
+rejected everywhere a tx is validated.
+
+- **`MAX_TX_DA_GAS`** (271,200) — `MAX_TX_BLOB_DATA_SIZE_IN_FIELDS` (8,475) × `DA_GAS_PER_FIELD` (32). This
+  is the most DA a single tx's effects can encode into a blob, so it is the most DA gas a tx could ever use.
+  Defined in `constants/src/constants.ts`.
+- **`MAX_PROCESSABLE_L2_GAS`** (6,540,000) — the AVM's maximum processable L2 gas, derived in Noir as
+  `PUBLIC_TX_L2_GAS_OVERHEAD + AVM_MAX_PROCESSABLE_L2_GAS` (`constants/src/constants.gen.ts`).
+
+### Network admission limits
+
+The most a single tx may *declare* and still be relayed across the network. Computed by
+`computeNetworkTxGasLimits` in `tx_gas_limits.ts` per dimension as:
+
+```
+min(per-tx max, ceil(checkpointBudget / blocksPerCheckpoint * minMultiplier))
+```
+
+The per-block share mirrors what a proposer grants the first block of a checkpoint
+(`CheckpointBuilder.capLimitsByCheckpointBudgets`), so a tx declaring this much is packable into a block.
+The network-minimum multipliers are `MIN_PER_BLOCK_ALLOCATION_MULTIPLIER` (1.2, L2 and tx count) and
+`MIN_PER_BLOCK_DA_ALLOCATION_MULTIPLIER` (1.5, DA). DA's is higher so a maximal contract class
+registration (~97k DA gas) fits a single block at mainnet geometry (72s slots, 6s blocks → 10 blocks per
+checkpoint).
+
+The DA budget is `getDaCheckpointBudgetForTxs(maxBlocksPerCheckpoint)`, not the raw
+`MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT` (786,432). Blob encoding spends overhead fields that no tx pays DA
+gas for — one checkpoint-end marker field and the per-block block-end fields (7 for the first block, 6 for
+each subsequent block, `blob-lib/src/encoding/block_blob_data.ts`) — so the raw constant is unattainable. The
+getter nets out the full overhead for a checkpoint of `maxBlocksPerCheckpoint` blocks: at mainnet geometry
+(10 blocks) that is `(24,576 − 1 − 7 − 9×6) × 32 = 24,514 × 32 = 784,448` DA gas. Subtracting every block's
+overhead (not just the first) keeps admission at or below the builder's first-block blob-field cap at every
+geometry — the builder is the most generous for the first block (it only reserves that block's own block-end
+overhead), so being conservative here is what guarantees admitted ⇒ buildable. Without this netting a tx
+near the raw limit would be admitted but never buildable.
+
+These limits depend on network-wide inputs only (timetable-derived blocks-per-checkpoint, checkpoint
+budgets, the network-minimum multipliers), never on a node's local restrictiveness. Every node always
+advertises them in `NodeInfo.txsLimits` (a required field); wallets read it and pass `txsLimits.gas` to
+`GasSettings.fallback` as the default gas limits when sending without explicit limits, and they are enforced
+by `GasLimitsValidator` (clamped to the per-tx protocol maxima) at three points: RPC tx acceptance
+(`aztec-node/src/aztec-node/server.ts`), gossip validation (`p2p/src/services/libp2p/libp2p_service.ts`),
+and pending-pool admission (`p2p/src/client/factory.ts`). They are deliberately *not* enforced at reqresp or
+block-proposal validation — admission is relay policy, not block validity.
+
+### Per-block builder budgets
+
+While packing a checkpoint, `CheckpointBuilder.capLimitsByCheckpointBudgets`
+(`validator-client/src/checkpoint_builder.ts`) computes each block's budget as a fair share of the remaining
+checkpoint budget across the remaining blocks, scaled by the configured multipliers. Operators may raise the
+multipliers above the network minimums but not lower them — the sequencer fails startup otherwise
+(`assertConfigMeetsNetworkTxLimits` in `sequencer-client/src/sequencer/sequencer.ts`), since a node that
+allocates less than it admits would accept txs over RPC/gossip that its builder can never pack.
+
+The fair share is then min'ed with the operator's absolute per-block caps `maxL2BlockGas` / `maxDABlockGas`
+and the blob-field cap (checkpoint capacity net of the checkpoint-end marker and this block's block-end
+overhead). The absolute caps are allowed to be restrictive: a cap below the network admission limit only
+produces a startup warning, not a failure, because such txs simply stay in the pool for other proposers to
+include.
+
+### Per-checkpoint budgets
+
+The outermost limits, enforced as proposal validity in `validateCheckpointLimits`
+(`stdlib/src/checkpoint/validate.ts`) and physically by blob encoding:
+
+- **Mana** — total L2 gas across all blocks ≤ `rollupManaLimit` (= `manaTarget × 2` on L1,
+  `l1-contracts/src/core/libraries/rollup/FeeLib.sol`).
+- **DA gas** — total DA gas ≤ raw `MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT` (786,432).
+- **Blob fields** — total ≤ `BLOBS_PER_CHECKPOINT × FIELDS_PER_BLOB` (6 × 4,096 = 24,576).
+- **Tx counts** — total txs ≤ `maxTxsPerCheckpoint` when configured.
+
+### Summary
+
+| Limit                                   | Value (mainnet defaults)        | Scope         | Where enforced                                              |
+| --------------------------------------- | ------------------------------- | ------------- | ----------------------------------------------------------- |
+| `MAX_TX_DA_GAS`                         | 271,200                         | per-tx        | every gas validator (hard ceiling)                          |
+| `MAX_PROCESSABLE_L2_GAS`                | 6,540,000                       | per-tx        | every gas validator (hard ceiling)                          |
+| Network DA admission limit              | min(271,200, ceil(784,448/10×1.5)) = 117,668 | per-tx (relay) | RPC, gossip, pending pool (`GasLimitsValidator`)         |
+| Network L2 admission limit              | min(6,540,000, ceil(manaLimit/10×1.2)) | per-tx (relay) | RPC, gossip, pending pool (`GasLimitsValidator`)         |
+| Per-block fair share + caps             | remaining budget / blocks × multiplier, min absolute caps & blob-field cap | per-block | `CheckpointBuilder.capLimitsByCheckpointBudgets`         |
+| `rollupManaLimit`                       | `manaTarget × 2`                | per-checkpoint | `validateCheckpointLimits`                                |
+| `MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT` | 786,432                         | per-checkpoint | `validateCheckpointLimits` + blob encoding                |
+| `BLOBS_PER_CHECKPOINT × FIELDS_PER_BLOB`| 24,576                          | per-checkpoint | `validateCheckpointLimits` + blob encoding                |
+
+## TypeScript Types
+
+- **`Gas`** — mana quantity in two dimensions (`daGas`, `l2Gas`).
+- **`GasFees`** — per-unit price in each dimension (`feePerDaGas`, `feePerL2Gas`).
+- **`GasSettings`** — sender-chosen fee parameters: gas limits, teardown limits, max fees, priority fees.
+- **`GasUsed`** — actual consumption after execution. Note: `billedGas` uses the teardown gas *limit*, not actual usage.

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;
+}