@aztec/stdlib 0.0.1-commit.3100065 → 0.0.1-commit.330febf

package/src/abi/function_call.ts

@@ -5,7 +5,7 @@ import { z } from 'zod';
 
 import { AztecAddress } from '../aztec-address/index.js';
 import { schemas } from '../schemas/index.js';
-import { type AbiType, AbiTypeSchema, FunctionType } from './abi.js';
+import { type AbiType, AbiTypeSchema, FunctionType, getFunctionReturnType } from './abi.js';
 import { FunctionSelector } from './function_selector.js';
 
 /** A request to call a function on a contract. */
@@ -25,8 +25,8 @@ export class FunctionCall {
     public isStatic: boolean,
     /** The encoded args */
     public args: Fr[],
-    /** The return type for decoding */
-    public returnTypes: AbiType[],
+    /** The type the call returns, for decoding, or undefined if it returns nothing */
+    public returnType?: AbiType,
   ) {}
 
   static getFields(fields: FieldsOf<FunctionCall>) {
@@ -38,7 +38,7 @@ export class FunctionCall {
       fields.hideMsgSender,
       fields.isStatic,
       fields.args,
-      fields.returnTypes,
+      fields.returnType,
     ] as const;
   }
 
@@ -56,9 +56,22 @@ export class FunctionCall {
         isStatic: z.boolean(),
         hideMsgSender: z.boolean(),
         args: z.array(schemas.Fr),
-        returnTypes: z.array(AbiTypeSchema),
+        returnType: AbiTypeSchema.optional(),
+        // Old consumers send `returnTypes`, not `returnType`. So we accept both for now, until we can safely remove
+        // the old version.
+        returnTypes: z.array(AbiTypeSchema).optional(),
       })
-      .transform(FunctionCall.from);
+      .transform(({ returnType, returnTypes, ...fields }) =>
+        FunctionCall.from({ ...fields, returnType: getFunctionReturnType({ returnType, returnTypes }) }),
+      );
+  }
+
+  /**
+   * Serializes the deprecated `returnTypes` alongside `returnType`, so that peers that still require the old field can
+   * parse calls sent by this version.
+   */
+  public toJSON() {
+    return { ...this, returnTypes: this.returnType ? [this.returnType] : [] };
   }
 
   public isPublicStatic(): boolean {
@@ -78,7 +91,6 @@ export class FunctionCall {
       hideMsgSender: false,
       isStatic: false,
       args: [],
-      returnTypes: [],
     });
   }
 }

package/src/avm/avm.ts

@@ -1,4 +1,3 @@
-import { DEFAULT_MAX_DEBUG_LOG_MEMORY_READS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
 
@@ -1384,6 +1383,10 @@ export class PublicTxResult {
   }
 }
 
+// Excessive memory reads due to debug logging can open a DOS vector to nodes that perform public tx simulation for users.
+// This default limit (4MB) can be configured further by node runners via the `RPC_SIMULATE_PUBLIC_MAX_DEBUG_LOG_MEMORY_READS` environment variable.
+export const DEFAULT_MAX_DEBUG_LOG_MEMORY_READS = 125000;
+
 export class CollectionLimitsConfig {
   constructor(
     public readonly maxDebugLogMemoryReads: number,

package/src/avm/index.ts

@@ -3,10 +3,5 @@ export * from './avm_accumulated_data.js';
 export * from './avm_circuit_public_inputs.js';
 export * from './revert_code.js';
 export * from './public_data_write.js';
-export * from './public_data_update_request.js';
-export * from './contract_storage_update_request.js';
-export * from './contract_storage_read.js';
-export * from './public_inner_call_request.js';
-export * from './public_call_stack_item_compressed.js';
 export * from './avm_proving_request.js';
 export * from './message_pack.js';

package/src/block/l2_block_source.ts

@@ -19,6 +19,7 @@ import type { CheckpointData, ProposedCheckpointData, ProposedCheckpointInput }
 import type { CheckpointInfo } from '../checkpoint/checkpoint_info.js';
 import type { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
+import { MAX_RPC_CHECKPOINTS_DATA_LEN } from '../interfaces/api_limit.js';
 import type { L2ToL1MembershipWitness } from '../messaging/l2_to_l1_membership.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import type { IndexedTxEffect } from '../tx/indexed_tx_effect.js';
@@ -89,9 +90,20 @@ export const CheckpointQuerySchema: z.ZodType<CheckpointQuery, unknown> = z.unio
   z.object({ tag: z.union([z.literal('checkpointed'), z.literal('proven'), z.literal('finalized')]) }).strict(),
 ]);
 
+const checkpointsQueryLimitSchema = () =>
+  z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_RPC_CHECKPOINTS_DATA_LEN, {
+      message: `limit must be at most ${MAX_RPC_CHECKPOINTS_DATA_LEN}`,
+    });
+
 export const CheckpointsQuerySchema: z.ZodType<CheckpointsQuery, unknown> = z.union([
-  z.object({ from: CheckpointNumberSchema, limit: z.number().int().min(1) }).strict(),
-  z.object({ fromSlot: SlotNumberSchema, limit: z.number().int().min(1), reverse: z.boolean().optional() }).strict(),
+  z.object({ from: CheckpointNumberSchema, limit: checkpointsQueryLimitSchema() }).strict(),
+  z
+    .object({ fromSlot: SlotNumberSchema, limit: checkpointsQueryLimitSchema(), reverse: z.boolean().optional() })
+    .strict(),
   z.object({ epoch: EpochNumberSchema }).strict(),
 ]);
 

package/src/block/l2_block_stream/interfaces.ts

@@ -1,5 +1,6 @@
 import type { BlockNumber } from '@aztec/foundation/branded-types';
 
+import type { BlockHeader } from '../../tx/block_header.js';
 import type { L2Block } from '../l2_block.js';
 import type { CheckpointId, L2BlockId, L2TipId, L2Tips, LocalL2Tips } from '../l2_block_source.js';
 
@@ -81,13 +82,14 @@ export type L2BlockStreamEvent =
     }
   | /**
    * Reports the new proposed tip of the chain. Emitted once per sync pass when the source's proposed tip differs
-   * from the pre-pass local one (downloads, a prune, or a thin tip movement). Carries only the block id; in block
-   * mode the corresponding payloads arrive via preceding `blocks-added` events, while in tips-only mode this is the
-   * sole signal that the proposed tip moved. Consumers that only track the proposed tip can ignore `blocks-added`
-   * entirely and anchor on this event instead.
+   * from the pre-pass local one (downloads, a prune, or a thin tip movement). In block mode the corresponding
+   * payloads also arrive via preceding `blocks-added` events, while in tips-only mode this is the sole signal that
+   * the proposed tip moved. Consumers that only track the proposed tip can ignore `blocks-added` entirely and
+   * anchor on this event instead.
    */ {
       type: 'chain-proposed';
       block: L2BlockId;
+      header: BlockHeader;
     }
   | /**
    * Reports a new checkpointed tip. Emitted at most once per sync pass when the source's checkpointed tip

package/src/block/l2_block_stream/l2_block_stream.ts

@@ -3,6 +3,8 @@ import { AbortError } from '@aztec/foundation/error';
 import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 
+import type { BlockHeader } from '../../tx/block_header.js';
+import { BlockHash } from '../block_hash.js';
 import type { L2Block } from '../l2_block.js';
 import { type L2BlockId, type L2BlockSource, type LocalL2Tips, makeL2BlockId } from '../l2_block_source.js';
 import {
@@ -100,6 +102,13 @@ export class L2BlockStream {
       // Baseline for the chain-proposed event; captured before the local store mutates during the pass.
       const prePassProposed = localTips.proposed;
 
+      // In tips-only mode there is no download loop to supply the chain-proposed event's header, so it must be
+      // fetched. Start the read now so it runs in parallel with the walk-back below.
+      const prefetch: ProposedHeaderPrefetch | undefined =
+        this.opts.tipsOnly && localBlockIdDiffers(prePassProposed, sourceTips.proposed)
+          ? { hash: sourceTips.proposed.hash, header: this.getHeaderFromSource(sourceTips.proposed.hash) }
+          : undefined;
+
       // Walk back to find a reorg, floored at the local finalized tip (a legitimate reorg can never reach it, since
       // finalized means the proving tx is itself L1-finalized). Seed the cache with ONLY the proposed tip: a stale
       // tier seed at a reorged height equals the local old-fork hash, faking agreement and stopping the walk above the
@@ -169,17 +178,29 @@ export class L2BlockStream {
       }
 
       // Pass atomicity: a prune mid-download leaves the source unable to serve the planned blocks, so the snapshot's
-      // tier tips may reference blocks the consumer never saw — skip tier reconciliation in that case. Tips-only mode
-      // has no download plan (the snapshot is one atomic getL2Tips read), so it always reconciles.
-      if (!this.opts.tipsOnly && !(await this.downloadBlocks(latestBlockNumber, sourceTips))) {
-        return;
-      }
+      // tier tips may reference blocks the consumer never saw — downloadBlocks aborts the pass in that case.
+      // Tips-only mode has no download plan (the snapshot is one atomic getL2Tips read), so it always reconciles.
+      const deliveredProposedHeader = this.opts.tipsOnly
+        ? undefined
+        : await this.downloadBlocks(latestBlockNumber, sourceTips);
 
       // End-of-pass reconciliation: chain-proposed fires against the pre-pass baseline (a post-prune re-read would
       // equal the source tip and suppress it), then the tiers highest-to-lowest so the finalized <= proven <=
       // checkpointed <= proposed invariant holds mid-pass.
       if (localBlockIdDiffers(prePassProposed, sourceTips.proposed)) {
-        await this.emitEvent({ type: 'chain-proposed', block: sourceTips.proposed });
+        const availableHeader =
+          prefetch?.hash === sourceTips.proposed.hash ? await prefetch.header : deliveredProposedHeader;
+        const header = availableHeader ?? (await this.getHeaderFromSource(sourceTips.proposed.hash));
+        if (header === undefined) {
+          // Abort the pass rather than skip just this event: the later tier events must not get ahead of a
+          // proposed tip the consumer never received. Nothing advanced, so the next pass retries.
+          this.log.warn(`No header for the proposed tip; aborting this sync pass`, {
+            blockNumber: sourceTips.proposed.number,
+            blockHash: sourceTips.proposed.hash,
+          });
+          throw new AbortError();
+        }
+        await this.emitEvent({ type: 'chain-proposed', block: sourceTips.proposed, header });
       }
 
       const reconcileTips = pruned ? await this.localData.getL2Tips() : localTips;
@@ -222,13 +243,15 @@ export class L2BlockStream {
   }
 
   /**
-   * Downloads every block from the post-prune cursor through the source's proposed tip, emitting `blocks-added`
-   * events. The return value gates tier-cursor advancement (pass atomicity): tier tips may only be reconciled when
-   * the plan that backs them ran to the proposed tip.
-   * @returns `true` if the plan completed (caught up, or delivered the proposed tip with a matching hash); `false` if
-   * the source no longer has a promised block, or served a fork at the proposed height mid-pass.
+   * Delivers every block from the agreed-on point through the advertised proposed tip as `blocks-added` events,
+   * aborting the pass when the source's own answers prove that tip is no longer real.
+   * @returns The delivered tip's header, so the caller can avoid a re-fetch; undefined when there was nothing to
+   * download (already at the tip, or startingBlock past it).
    */
-  private async downloadBlocks(latestBlockNumber: BlockNumber, sourceTips: LocalL2Tips): Promise<boolean> {
+  private async downloadBlocks(
+    latestBlockNumber: BlockNumber,
+    sourceTips: LocalL2Tips,
+  ): Promise<BlockHeader | undefined> {
     // The post-prune cursor: the highest block number both sides agree on. Block downloads resume from here.
     let nextBlockNumber = latestBlockNumber + 1;
 
@@ -258,12 +281,12 @@ export class L2BlockStream {
       if (blocks.length === 0) {
         // The source no longer has a block the snapshot promised: the snapshot is provably stale, so report the plan
         // incomplete and skip reconciliation this pass.
-        this.log.warn(`Block source returned no blocks for a promised range; skipping reconciliation this pass`, {
+        this.log.warn(`Block source returned no blocks for a promised range; aborting this sync pass`, {
           from: nextBlockNumber,
           limit,
           sourceProposed: sourceTips.proposed.number,
         });
-        return false;
+        throw new AbortError();
       }
       await this.emitEvent({ type: 'blocks-added', blocks });
       lastDeliveredBlock = blocks.at(-1)!;
@@ -271,22 +294,23 @@ export class L2BlockStream {
     }
 
     if (lastDeliveredBlock === undefined) {
-      // Loop never ran: caught up before the plan started, or startingBlock past the tip (A-1061). Trivially complete.
-      return true;
+      // Loop never ran (caught up before the plan started, or startingBlock past the tip, see A-1061), so nothing
+      // was downloaded that could disprove the snapshot.
+      return undefined;
     }
 
-    // Complete iff the block delivered at the proposed height carries the snapshot's proposed hash; a different hash
-    // means a same-height fork swap happened mid-pass, so the snapshot is stale.
+    // The block delivered at the proposed height must carry the snapshot's proposed hash; a different hash means a
+    // same-height fork swap happened mid-pass, so the snapshot is stale.
     const deliveredHash = (await lastDeliveredBlock.hash()).toString();
     if (deliveredHash !== sourceTips.proposed.hash) {
-      this.log.warn(`Delivered proposed-block hash differs from snapshot; skipping reconciliation this pass`, {
+      this.log.warn(`Delivered proposed-block hash differs from snapshot; aborting this sync pass`, {
         blockNumber: lastDeliveredBlock.number,
         deliveredHash,
         snapshotHash: sourceTips.proposed.hash,
       });
-      return false;
+      throw new AbortError();
     }
-    return true;
+    return lastDeliveredBlock.header;
   }
 
   /**
@@ -342,6 +366,16 @@ export class L2BlockStream {
       .then(hash => hash?.toString());
   }
 
+  private getHeaderFromSource(hash: string): Promise<BlockHeader | undefined> {
+    return this.l2BlockSource
+      .getBlockData({ hash: BlockHash.fromString(hash) })
+      .then(data => data?.header)
+      .catch(err => {
+        this.log.error(`Failed to read header for block`, err, { blockHash: hash });
+        return undefined;
+      });
+  }
+
   private async emitEvent(event: L2BlockStreamEvent) {
     this.log.debug(
       `Emitting ${event.type} (${
@@ -359,6 +393,9 @@ export class L2BlockStream {
   }
 }
 
+/** A speculative proposed-tip header read, tagged with the hash it targets so a moved tip is detectable. */
+type ProposedHeaderPrefetch = { hash: string; header: Promise<BlockHeader | undefined> };
+
 class BlockHashCache {
   private readonly cache: Map<number, string> = new Map();
 

package/src/block/test/l2_tips_store_test_suite.ts

@@ -10,6 +10,7 @@ import {
   type L2TipId,
 } from '@aztec/stdlib/block';
 import { Checkpoint, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { BlockHeader } from '@aztec/stdlib/tx';
 
 import { expect } from 'vitest';
 
@@ -132,6 +133,7 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-proposed',
       block: { number: BlockNumber(5), hash: new Fr(500).toString() },
+      header: BlockHeader.empty(),
     });
 
     const tips = await tipsStore.getL2Tips();
@@ -145,10 +147,12 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-proposed',
       block: { number: BlockNumber(4), hash: new Fr(400).toString() },
+      header: BlockHeader.empty(),
     });
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-proposed',
       block: { number: BlockNumber(9), hash: new Fr(900).toString() },
+      header: BlockHeader.empty(),
     });
 
     // Both recorded heights resolve; the heights between them were never seen and stay undefined.
@@ -165,6 +169,7 @@ export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
     await tipsStore.handleBlockStreamEvent({
       type: 'chain-proposed',
       block: { number: BlockNumber(9), hash: new Fr(900).toString() },
+      header: BlockHeader.empty(),
     });
 
     // Record sparse witnesses at heights below the tip (e.g. a consumer materializing per-height state).

package/src/config/node-rpc-config.ts

@@ -1,6 +1,7 @@
-import { DEFAULT_MAX_DEBUG_LOG_MEMORY_READS } from '@aztec/constants';
 import { type ConfigMappingsType, numberConfigHelper } from '@aztec/foundation/config';
 
+import { DEFAULT_MAX_DEBUG_LOG_MEMORY_READS } from '../avm/avm.js';
+
 export const nodeRpcConfigMappings: ConfigMappingsType<NodeRPCConfig> = {
   rpcSimulatePublicMaxGasLimit: {
     env: 'RPC_SIMULATE_PUBLIC_MAX_GAS_LIMIT',

package/src/contract/artifact_hash.ts

@@ -6,7 +6,13 @@ import { MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
 
 import deterministicStringify from 'json-stringify-deterministic';
 
-import { type ContractArtifact, type FunctionArtifact, FunctionSelector, FunctionType } from '../abi/index.js';
+import {
+  type ContractArtifact,
+  type FunctionArtifact,
+  FunctionSelector,
+  FunctionType,
+  getFunctionReturnType,
+} from '../abi/index.js';
 
 const VERSION = 1;
 
@@ -104,8 +110,14 @@ export async function computeFunctionArtifactHash(
   return sha256Fr(Buffer.concat([numToUInt8(VERSION), selector.toBuffer(), metadataHash.toBuffer(), bytecodeHash]));
 }
 
-export function computeFunctionMetadataHash(fn: FunctionArtifact) {
-  return sha256Fr(Buffer.from(deterministicStringify(fn.returnTypes), 'utf8'));
+export function computeFunctionMetadataHash(fn: Pick<FunctionArtifact, 'returnType' | 'returnTypes'>) {
+  // Wrap the type in a list (empty when the function returns nothing) so the hash preimage is identical to
+  // what it was when this hash consumed the deprecated `returnTypes` list. This hash is part of the
+  // artifact hash preimage, which contract class ids commit to - changing it would move the computed
+  // class id and address of every contract, and break artifact validation against already-registered
+  // classes.
+  const returnType = getFunctionReturnType(fn);
+  return sha256Fr(Buffer.from(deterministicStringify(returnType ? [returnType] : []), 'utf8'));
 }
 
 function getLogger() {

package/src/contract/contract_class.ts

@@ -1,4 +1,5 @@
-import { vkAsFieldsMegaHonk } from '@aztec/foundation/crypto/keys';
+import { CircuitKind } from '@aztec/bb.js';
+import { vkAsFields } from '@aztec/foundation/crypto/keys';
 import { Fr } from '@aztec/foundation/curves/bn254';
 
 import { type ContractArtifact, type FunctionArtifact, FunctionSelector, FunctionType } from '../abi/index.js';
@@ -60,5 +61,5 @@ export async function computeVerificationKeyHash(f: FunctionArtifact) {
   if (!f.verificationKey) {
     throw new Error(`Private function ${f.name} must have a verification key`);
   }
-  return hashVK(await vkAsFieldsMegaHonk(Buffer.from(f.verificationKey, 'base64')));
+  return hashVK(await vkAsFields(Buffer.from(f.verificationKey, 'base64'), CircuitKind.App));
 }

package/src/contract/index.ts

@@ -9,5 +9,4 @@ export * from './private_function.js';
 export * from './interfaces/index.js';
 export * from './contract_function_dao.js';
 export * from './partial_address.js';
-export * from './deployment_info.js';
 export * from './complete_address.js';

package/src/gas/README.md

@@ -1,47 +1,69 @@
 # 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.
+`l1-contracts/src/core/libraries/rollup/FeeLib.sol` (`fee_math.ts` in this directory is a
+TypeScript port of those formulas, used to predict fees a few slots ahead). This document
+describes the formulas, the oracle lag/lifetime mechanism, how a transaction's fee is
+derived from them, the gas and data limits, 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.
+Aztec meters work as gas in two dimensions: **DA** (data availability, i.e. blob data
+published to L1) and **L2** (execution). The L2 dimension is called **mana** (analogous to
+Ethereum gas): block headers track `totalManaUsed`, and the fee model below prices one unit
+of mana. The total fee is `gasUsed * feePerGas` summed across both dimensions.
+
+### The DA dimension is priced at zero
+
+Only the L2 dimension currently carries a price. When building checkpoint global variables,
+the sequencer sets `feePerDaGas = 0` and sets `feePerL2Gas` to the L1-computed minimum fee
+per mana (`sequencer-client/src/global_variable_builder/global_builder.ts` and
+`fee_provider.ts` in the same directory). The cost of publishing data is still recovered:
+the blob gas a checkpoint pays on L1 is part of the *sequencer cost* component of the mana
+fee below. DA gas remains fully metered and limited (see
+[Gas and Data Limits](#gas-and-data-limits)) — it bounds how much data a tx or checkpoint
+may publish — it just contributes nothing to the fee today.
 
 ## Fee Components
 
-The minimum fee per mana has four components:
+The minimum fee per mana has four components. All are computed in ETH (wei) per mana and
+converted to the fee asset at the end (see [Fee Asset Price](#fee-asset-price)).
 
 ### Sequencer Cost
 
 L1 cost to propose a checkpoint (calldata gas + blob data), amortized over `manaTarget`:
 
 ```
-sequencerCost = ((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
+sequencerCost = ceil(((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
               + (BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * blobFee))
-              / manaTarget
+              / manaTarget)
 ```
 
+Note that `BLOBS_PER_CHECKPOINT` here is FeeLib's own constant (3), not the protocol blob
+capacity of the same name (6) — see the note under [Key Constants](#key-constants).
+
 ### 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
+proverCost = ceil(ceil((L1_GAS_PER_EPOCH_VERIFIED * baseFee) / epochDuration) / manaTarget)
            + provingCostPerMana
 ```
 
+Updates to `provingCostPerMana` are rate-limited on L1 (`FeeLib.updateProvingCostPerMana`):
+at most one update every 30 days, each moving the value by at most ×1.5 (or ÷1.5), with a
+floor of 2 wei per mana.
+
 ### 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
+baseCost       = sequencerCost + proverCost
+congestionCost = floor(baseCost * congestionMultiplier / MINIMUM_CONGESTION_MULTIPLIER) - baseCost
 ```
 
 When there is no congestion the multiplier equals `MINIMUM_CONGESTION_MULTIPLIER` (1e9)
@@ -50,11 +72,15 @@ and congestion cost is zero.
 ### Congestion Multiplier
 
 ```
-excessMana          = max(0, prevExcessMana + prevManaUsed - manaTarget)
-congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, excessMana, denominator)
+excessMana           = max(0, prevExcessMana + prevManaUsed - manaTarget)
+denominator          = manaTarget * 854,700,854 / 1e8    ≈ 8.547 * manaTarget
+congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER,
+                                       min(excessMana, 100 * denominator), denominator)
 ```
 
-Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
+Each additional `manaTarget` of excess mana multiplies the fee by `e^(1/8.547) ≈ 1.124`,
+i.e. ~12.5%. The exponent is capped at 100 (multiplier ≤ ~2.7e43 × the minimum) to keep
+the Taylor series from overflowing.
 
 ### Total
 
@@ -62,6 +88,11 @@ Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
 minFeePerMana = sequencerCost + proverCost + congestionCost
 ```
 
+Each component is converted from ETH to the fee asset individually (rounding up) before
+summing. The sum is capped at `type(uint128).max` (`FeeLib.summedMinFee`) so it always fits
+the proposal header's `feePerL2Gas` field — without the cap, extreme congestion could
+produce a fee no valid header can represent, halting the chain.
+
 ## L1 Gas Oracle: Lag and Lifetime
 
 The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a two-phase
@@ -70,9 +101,9 @@ The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a t
 - **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.
+- **LIFETIME = 5 slots** — after an oracle update, further updates are ignored
+  (`updateL1GasFeeOracle` returns without effect) 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:
 
@@ -84,6 +115,12 @@ 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.
 
+Because queued values only activate `LAG` slots later, the min fee for the next `LAG`
+slots is fully determined by current on-chain state. `fee_math.ts` ports the FeeLib
+formulas so the sequencer can predict min fees over that window (`FeePredictor` in
+`sequencer-client/src/global_variable_builder`), under a configurable mana-usage
+assumption (`ManaUsageEstimate`: none / target / limit).
+
 ### Worked Example
 
 Suppose the oracle is updated at slot 10 with new L1 fees. Here is the timeline:
@@ -117,34 +154,68 @@ Key observations:
 
 ## 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:
+Fees are computed in ETH (wei) internally and converted to the fee asset (Fee Juice) via
+`ethPerFeeAsset` (1e12 precision), rounding up (`PriceLib.toFeeAsset` in
+`l1-contracts/src/core/libraries/compressed-data/fees/FeeConfig.sol`).
+
+Each checkpoint proposal carries a fee-asset price modifier (`OracleInput`) chosen by the
+proposer, bounded to ±1% (±100 bps) per checkpoint:
 
 ```
 newPrice = currentPrice * (10000 + modifierBps) / 10000
 ```
 
+The result is clamped to [`MIN_ETH_PER_FEE_ASSET` = 100, `MAX_ETH_PER_FEE_ASSET` = 1e14],
+i.e. 1e-10 to 100 ETH per fee asset. The floor of 100 guarantees a ±1% step always moves
+the integer price by at least 1.
+
+## Transaction Fees
+
+The checkpoint's `gasFees` (the L1-computed min fee per mana, with DA priced at zero) act
+as a base fee. Senders declare `GasSettings`: gas limits, teardown gas limits,
+`maxFeesPerGas`, and `maxPriorityFeesPerGas`. A tx is only includable if `maxFeesPerGas`
+covers the checkpoint's `gasFees` in both dimensions. The effective fee adds an
+EIP-1559-style priority fee on top of the base, capped by the max
+(`computeEffectiveGasFees` in `stdlib/src/fees/transaction_fee.ts`):
+
+```
+effectiveFeePerGas = gasFees + min(maxPriorityFeePerGas, maxFeesPerGas - gasFees)   (per dimension)
+transactionFee     = billedGas.daGas * effectiveFeePerDaGas + billedGas.l2Gas * effectiveFeePerL2Gas
+```
+
+`billedGas` is actual consumption except for the teardown phase, which is billed at the
+declared `teardownGasLimits` rather than actual usage — the fee is charged during teardown
+itself, before actual teardown consumption is known.
+
 ## 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                                      |
+| Component              | Bound                                                    |
+| ---------------------- | -------------------------------------------------------- |
+| L1 base fee / blob fee | At most once every 5 slots (oracle LIFETIME)             |
+| Fee asset price        | ±1% per checkpoint                                       |
+| Proving cost per mana  | At most ×1.5 (or ÷1.5) per update, one update per 30 days |
 | Congestion multiplier  | Depends on excess mana accumulation/drain per checkpoint |
-| Sequencer/prover costs | Scale linearly with L1 fees                             |
+| 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      |
+| Constant                        | Value          |
+| ------------------------------- | -------------- |
+| `L1_GAS_PER_CHECKPOINT_PROPOSED` | 300,000       |
+| `L1_GAS_PER_EPOCH_VERIFIED`     | 3,600,000      |
+| `BLOBS_PER_CHECKPOINT` (FeeLib) | 3              |
+| `BLOB_GAS_PER_BLOB`             | 2^17           |
+| `MINIMUM_CONGESTION_MULTIPLIER` | 1e9            |
+| `LAG`                           | 2 slots        |
+| `LIFETIME`                      | 5 slots        |
+| `MIN_ETH_PER_FEE_ASSET`         | 100 (1e-10 ETH) |
+| `MAX_ETH_PER_FEE_ASSET`         | 1e14 (100 ETH) |
+
+⚠️ Name clash: `FeeLib.sol` (and its port `fee_math.ts`) defines `BLOBS_PER_CHECKPOINT = 3`,
+used only to price the sequencer's blob costs. The protocol constant of the same name in
+`@aztec/constants` is **6** — the actual blob capacity of a checkpoint, used throughout the
+limits section below. The FeeLib value is a holdover from the pre-checkpoint
+`BLOBS_PER_BLOCK`, so the fee model prices half of a full checkpoint's blobs.
 
 ## Gas and Data Limits
 
@@ -196,7 +267,7 @@ advertises them in `NodeInfo.txsLimits` (a required field); wallets read it and
 `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
+and pending-pool admission (`p2p/src/client/factory.ts`). They are deliberately *not* enforced at req/resp or
 block-proposal validation — admission is relay policy, not block validity.
 
 ### Per-block builder budgets
@@ -240,7 +311,8 @@ The outermost limits, enforced as proposal validity in `validateCheckpointLimits
 
 ## TypeScript Types
 
-- **`Gas`** — mana quantity in two dimensions (`daGas`, `l2Gas`).
+- **`Gas`** — gas 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.
+- **`fee_math.ts`** — TypeScript port of the FeeLib formulas, used for fee prediction over the oracle LAG window.