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

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/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/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
@@ -115,6 +146,98 @@ newPrice = currentPrice * (10000 + modifierBps) / 10000
 | `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`).

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

package/src/gas/gas.ts

@@ -1,6 +1,6 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { inspect } from 'util';
@@ -79,8 +79,13 @@ export class Gas {
     return new Gas(reader.readNumber(), reader.readNumber());
   }
 
-  toBuffer() {
-    return serializeToBuffer(this.daGas, this.l2Gas);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.daGas, this.l2Gas);
   }
 
   [inspect.custom]() {

package/src/gas/gas_fees.ts

@@ -1,12 +1,6 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import {
-  BufferReader,
-  FieldReader,
-  bigintToUInt128BE,
-  serializeToBuffer,
-  serializeToFields,
-} from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { inspect } from 'util';
@@ -15,6 +9,17 @@ import { z } from 'zod';
 import type { UInt128 } from '../types/shared.js';
 import type { GasDimensions } from './gas.js';
 
+/**
+ * Multiplies a bigint by a non-integer scalar and returns the ceiling of the result.
+ * Avoids converting the bigint to Number (which loses precision above 2^53) by instead
+ * scaling the scalar into a bigint rational and performing ceiling division.
+ */
+function bigintMulCeil(value: bigint, scalar: number): bigint {
+  const SCALE = 1_000_000_000_000n; // 1e12
+  const scaledScalar = BigInt(Math.round(scalar * 1e12));
+  return (value * scaledScalar + SCALE - 1n) / SCALE;
+}
+
 /** Gas prices for each dimension. */
 export class GasFees {
   public readonly feePerDaGas: UInt128;
@@ -60,10 +65,7 @@ export class GasFees {
       const s = BigInt(scalar);
       return new GasFees(this.feePerDaGas * s, this.feePerL2Gas * s);
     } else {
-      return new GasFees(
-        BigInt(Math.ceil(Number(this.feePerDaGas) * scalar)),
-        BigInt(Math.ceil(Number(this.feePerL2Gas) * scalar)),
-      );
+      return new GasFees(bigintMulCeil(this.feePerDaGas, scalar), bigintMulCeil(this.feePerL2Gas, scalar));
     }
   }
 
@@ -102,8 +104,14 @@ export class GasFees {
     return new GasFees(reader.readUInt128(), reader.readUInt128());
   }
 
-  toBuffer() {
-    return serializeToBuffer(bigintToUInt128BE(this.feePerDaGas), bigintToUInt128BE(this.feePerL2Gas));
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    sink.writeBigInt(this.feePerDaGas, 16);
+    sink.writeBigInt(this.feePerL2Gas, 16);
   }
 
   static fromFields(fields: Fr[] | FieldReader) {
@@ -126,3 +134,8 @@ export class GasFees {
     return `GasFees { feePerDaGas=${this.feePerDaGas} feePerL2Gas=${this.feePerL2Gas} }`;
   }
 }
+
+/** Provides projected minimum gas fees for the next block. */
+export interface BlockMinFeesProvider {
+  getCurrentMinFees(): Promise<GasFees>;
+}

package/src/gas/gas_settings.ts

@@ -1,12 +1,6 @@
-import {
-  DEFAULT_DA_GAS_LIMIT,
-  DEFAULT_L2_GAS_LIMIT,
-  DEFAULT_TEARDOWN_DA_GAS_LIMIT,
-  DEFAULT_TEARDOWN_L2_GAS_LIMIT,
-  GAS_SETTINGS_LENGTH,
-} from '@aztec/constants';
+import { GAS_SETTINGS_LENGTH, MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT, MAX_PROCESSABLE_L2_GAS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
@@ -14,6 +8,14 @@ import { z } from 'zod';
 import { Gas, GasDimensions } from './gas.js';
 import { GasFees } from './gas_fees.js';
 
+// For gas estimation, we use intentionally high limits above what the network can process,
+// so the simulation runs without hitting gas caps. Since teardown gas is counted towards total,
+// the total estimation limit is teardown + max processable.
+export const GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT = MAX_PROCESSABLE_L2_GAS;
+export const GAS_ESTIMATION_L2_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT + MAX_PROCESSABLE_L2_GAS;
+export const GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT = MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
+export const GAS_ESTIMATION_DA_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT + MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
+
 // docs:start:gas_settings_vars
 /** Gas usage and fees limits set by the transaction sender for different dimensions and phases. */
 export class GasSettings {
@@ -95,18 +97,59 @@ export class GasSettings {
     return new GasSettings(Gas.empty(), Gas.empty(), GasFees.empty(), GasFees.empty());
   }
 
-  /** Default gas settings to use when user has not provided them. Requires explicit max fees per gas. */
-  static default(overrides: {
+  /**
+   * Fills in gas limits high enough for transactions to be included in most cases.
+   * Callers must supply `gasLimits` — typically the most a single tx may declare on the network
+   * (`min(per-tx max, per-block allocation)`), i.e. a node's advertised `txsLimits.gas`. Since teardown gas
+   * is reserved from gasLimits during private execution (see gas_meter.nr), the effective gas available for
+   * app logic is gasLimits - teardownGasLimits - privateOverhead; the teardown default is derived from the
+   * effective total so it always stays below it.
+   * These values won't work if:
+   *  - Teardown consumes more than the arbitrarily assigned fallback limits
+   *  - The rest of the transaction consumes more than the remaining gas after teardown
+   *  - The DA gas limit is too low for the transaction, while still within the checkpoint limit
+   */
+  static fallback(overrides: {
+    gasLimits: Gas;
+    teardownGasLimits?: Gas;
+    maxFeesPerGas: GasFees;
+    maxPriorityFeesPerGas?: GasFees;
+  }) {
+    const gasLimits = overrides.gasLimits;
+    const teardownGasLimits =
+      overrides.teardownGasLimits ?? new Gas(Math.floor(gasLimits.daGas / 2), Math.floor(gasLimits.l2Gas / 8));
+    return GasSettings.from({
+      gasLimits,
+      teardownGasLimits,
+      maxFeesPerGas: overrides.maxFeesPerGas,
+      maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),
+    });
+  }
+
+  /**
+   * Gas settings for simulation/estimation only.
+   * Since teardown gas is reserved upfront from gasLimits during private execution (see gas_meter.nr),
+   * the effective gas available for app logic is gasLimits - teardownGasLimits - privateOverhead.
+   * To ensure estimation never hits gas caps, we set both limits above what the protocol allows:
+   * teardown gets MAX_PROCESSABLE and gasLimits gets teardown + MAX_PROCESSABLE, so the full
+   * processable amount remains available for each phase independently. To be used in conjunction
+   * with skipTxValidation: true during public simulation, or the node would reject the transaction
+   * outright due to gas limits being above protocol max.
+   */
+  static forEstimation(overrides: {
     gasLimits?: Gas;
     teardownGasLimits?: Gas;
     maxFeesPerGas: GasFees;
     maxPriorityFeesPerGas?: GasFees;
   }) {
     return GasSettings.from({
-      gasLimits: overrides.gasLimits ?? { l2Gas: DEFAULT_L2_GAS_LIMIT, daGas: DEFAULT_DA_GAS_LIMIT },
+      gasLimits: overrides.gasLimits ?? {
+        l2Gas: GAS_ESTIMATION_L2_GAS_LIMIT,
+        daGas: GAS_ESTIMATION_DA_GAS_LIMIT,
+      },
       teardownGasLimits: overrides.teardownGasLimits ?? {
-        l2Gas: DEFAULT_TEARDOWN_L2_GAS_LIMIT,
-        daGas: DEFAULT_TEARDOWN_DA_GAS_LIMIT,
+        l2Gas: GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT,
+        daGas: GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT,
       },
       maxFeesPerGas: overrides.maxFeesPerGas,
       maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),
@@ -141,8 +184,13 @@ export class GasSettings {
     );
   }
 
-  toBuffer() {
-    return serializeToBuffer(...GasSettings.getFields(this));
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, ...GasSettings.getFields(this));
   }
 
   static fromFields(fields: Fr[] | FieldReader): GasSettings {

package/src/gas/index.ts

@@ -1,4 +1,6 @@
+export * from './fee_math.js';
 export * from './gas.js';
 export * from './gas_fees.js';
 export * from './gas_settings.js';
 export * from './gas_used.js';
+export * from './tx_gas_limits.js';