@aztec/stdlib 5.0.0-private.20260319 → 5.0.0-rc.2

package/src/contract/interfaces/contract_data_source.ts

@@ -25,11 +25,9 @@ export interface ContractDataSource {
   /**
    * Returns a publicly deployed contract instance given its address.
    * @param address - Address of the deployed contract.
-   * @param timestamp - Timestamp at which to retrieve the contract instance. If not provided, the latest block should
-   * be used.
-   * TODO(#15170): Fix the implementations ignoring the timestamp param and make timestamp required.
+   * @param timestamp - Timestamp at which to resolve the contract instance's current class id.
    */
-  getContract(address: AztecAddress, timestamp?: UInt64): Promise<ContractInstanceWithAddress | undefined>;
+  getContract(address: AztecAddress, timestamp: UInt64): Promise<ContractInstanceWithAddress | undefined>;
 
   /**
    * Returns the list of all class ids known.

package/src/contract/interfaces/contract_instance.ts

@@ -6,7 +6,7 @@ import { AztecAddress } from '../../aztec-address/index.js';
 import { PublicKeys } from '../../keys/public_keys.js';
 import { schemas, zodFor } from '../../schemas/index.js';
 
-const VERSION = 1 as const;
+const VERSION = 2 as const;
 
 /**
  * A contract instance is a concrete deployment of a contract class. It always references a contract class,
@@ -26,6 +26,8 @@ export interface ContractInstance {
   originalContractClassId: Fr;
   /** Hash of the selector and arguments to the constructor. */
   initializationHash: Fr;
+  /** Hash of Immutables Values the contract is deployed with. */
+  immutablesHash: Fr;
   /** Public keys associated with this instance. */
   publicKeys: PublicKeys;
 }
@@ -40,6 +42,7 @@ export const ContractInstanceSchema = zodFor<ContractInstance>()(
     currentContractClassId: schemas.Fr,
     originalContractClassId: schemas.Fr,
     initializationHash: schemas.Fr,
+    immutablesHash: schemas.Fr,
     publicKeys: PublicKeys.schema,
   }),
 );
@@ -54,12 +57,13 @@ export const ContractInstanceWithAddressSchema = zodFor<ContractInstanceWithAddr
  */
 export function contractInstanceFromPlainObject(obj: any): ContractInstance {
   return {
-    version: 1,
+    version: 2,
     salt: Fr.fromPlainObject(obj.salt),
     deployer: AztecAddress.fromPlainObject(obj.deployer),
     currentContractClassId: Fr.fromPlainObject(obj.currentContractClassId),
     originalContractClassId: Fr.fromPlainObject(obj.originalContractClassId),
     initializationHash: Fr.fromPlainObject(obj.initializationHash),
+    immutablesHash: Fr.fromPlainObject(obj.immutablesHash),
     publicKeys: PublicKeys.fromPlainObject(obj.publicKeys),
   };
 }

package/src/contract/interfaces/node-info.ts

@@ -5,6 +5,12 @@ import { z } from 'zod';
 
 import { type ProtocolContractAddresses, ProtocolContractAddressesSchema } from './protocol_contract_addresses.js';
 
+/** Limits a single transaction may declare on a network. */
+export interface TxsLimits {
+  /** Maximum gas limits a single tx may declare: the smaller of the per-tx maximum and the per-block allocation. */
+  gas: { daGas: number; l2Gas: number };
+}
+
 /** Provides basic information about the running node. */
 export interface NodeInfo {
   /** Version as tracked in the aztec-packages repository. */
@@ -21,6 +27,8 @@ export interface NodeInfo {
   protocolContractAddresses: ProtocolContractAddresses;
   /** Whether the node requires real proofs for transaction submission. */
   realProofs: boolean;
+  /** Limits a single tx may declare on this network. Clients rely on this to set fallback gas limits. */
+  txsLimits: TxsLimits;
 }
 
 export const NodeInfoSchema: ZodFor<NodeInfo> = z
@@ -32,5 +40,8 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,
     realProofs: z.boolean(),
+    txsLimits: z.object({
+      gas: z.object({ daGas: z.number().int().nonnegative(), l2Gas: z.number().int().nonnegative() }),
+    }),
   })
   .transform(obj => ({ enr: undefined, ...obj }));

package/src/contract/private_function.ts

@@ -3,6 +3,7 @@ import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/cry
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
 
+import { computeMerkleHash } from '../hash/hash.js';
 import type { PrivateFunction } from './interfaces/contract_class.js';
 
 // Memoize the merkle tree calculators to avoid re-computing the zero-hash for each level in each call
@@ -42,7 +43,8 @@ async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator>
     privateFunctionTreeCalculator = await MerkleTreeCalculator.create(
       FUNCTION_TREE_HEIGHT,
       functionTreeZeroLeaf,
-      async (left, right) => (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
+      async (left, right) =>
+        (await computeMerkleHash(Fr.fromBuffer(left), Fr.fromBuffer(right))).toBuffer() as Buffer<ArrayBuffer>,
     );
   }
   return privateFunctionTreeCalculator;

package/src/database-version/version_manager.ts

@@ -9,6 +9,7 @@ import { DatabaseVersion } from './database_version.js';
 export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
 
 export const DATABASE_VERSION_FILE_NAME = 'db_version';
+export type SchemaVersionMismatchPolicy = 'reset' | 'throw';
 
 export type DatabaseVersionManagerOptions<T> = {
   schemaVersion: number;
@@ -16,6 +17,7 @@ export type DatabaseVersionManagerOptions<T> = {
   dataDirectory: string;
   onOpen: (dataDir: string) => Promise<T>;
   onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  schemaVersionMismatchPolicy?: SchemaVersionMismatchPolicy;
   fileSystem?: DatabaseVersionManagerFs;
   log?: Logger;
 };
@@ -34,6 +36,7 @@ export class DatabaseVersionManager<T> {
   private dataDirectory: string;
   private onOpen: (dataDir: string) => Promise<T>;
   private onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  private schemaVersionMismatchPolicy: SchemaVersionMismatchPolicy;
   private fileSystem: DatabaseVersionManagerFs;
   private log: Logger;
 
@@ -45,6 +48,7 @@ export class DatabaseVersionManager<T> {
    * @param dataDirectory - The directory where version information will be stored
    * @param onOpen - A callback to the open the database at the given location
    * @param onUpgrade - An optional callback to upgrade the database before opening. If not provided it will reset the database
+   * @param schemaVersionMismatchPolicy - Whether schema mismatches should reset data or throw
    * @param fileSystem - An interface to access the filesystem
    * @param log - Optional custom logger
    * @param options - Configuration options
@@ -55,6 +59,7 @@ export class DatabaseVersionManager<T> {
     dataDirectory,
     onOpen,
     onUpgrade,
+    schemaVersionMismatchPolicy = 'reset',
     fileSystem = fs,
     log = createLogger(`foundation:version-manager`),
   }: DatabaseVersionManagerOptions<T>) {
@@ -68,6 +73,7 @@ export class DatabaseVersionManager<T> {
     this.dataDirectory = dataDirectory;
     this.onOpen = onOpen;
     this.onUpgrade = onUpgrade;
+    this.schemaVersionMismatchPolicy = schemaVersionMismatchPolicy;
     this.fileSystem = fileSystem;
     this.log = log;
   }
@@ -115,10 +121,21 @@ export class DatabaseVersionManager<T> {
         try {
           await this.onUpgrade(this.dataDirectory, storedVersion.schemaVersion, this.currentVersion.schemaVersion);
         } catch (error) {
+          if (this.schemaVersionMismatchPolicy === 'throw') {
+            throw new Error(
+              `Failed to upgrade database at ${this.dataDirectory} from schema version ${storedVersion.schemaVersion} to ${this.currentVersion.schemaVersion}`,
+              { cause: error },
+            );
+          }
           this.log.error(`Failed to upgrade: ${error}. Falling back to reset.`);
           needsReset = true;
         }
       } else if (cmp !== 0) {
+        if (this.schemaVersionMismatchPolicy === 'throw') {
+          throw new Error(
+            `Cannot open database at ${this.dataDirectory}: stored schema version ${storedVersion.schemaVersion} is incompatible with expected schema version ${this.currentVersion.schemaVersion}`,
+          );
+        }
         if (shouldLogDataReset) {
           this.log.info(
             `Can't upgrade from version ${storedVersion} to ${this.currentVersion}. Resetting database at ${this.dataDirectory}`,

package/src/deserialization/index.ts

@@ -11,8 +11,41 @@ export const MAX_TXS_PER_BLOCK = 2 ** 16;
 /** Max committee size - theoretical max from bitmap design (256 bytes × 8 bits) */
 export const MAX_COMMITTEE_SIZE = 2048;
 
-/** Max blocks per checkpoint */
-export const MAX_BLOCKS_PER_CHECKPOINT = 72;
+/**
+ * Maximum number of L2 blocks in a provable checkpoint. Used for deserialization and when ingesting
+ * checkpoints already accepted by L1.
+ *
+ * This MUST be >= the number of blocks the proving system can carry, or a structurally-valid, provable
+ * checkpoint that L1 accepts would be rejected on ingest (`validateCheckpoint`) and wedge the archiver.
+ * The circuits and L1 impose no explicit per-checkpoint block count; the ceiling comes from the
+ * blob-field budget:
+ *
+ *   budget = BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB = 6 * 4096 = 24,576 fields
+ *
+ *   per-block minimal blob footprint:
+ *     first block  (may be empty)   = 7 fields   (NUM_FIRST_BLOCK_END_BLOB_FIELDS)
+ *     every other  (needs >= 1 tx)  = 6 + 4 = 10 fields
+ *                                     (NUM_BLOCK_END_BLOB_FIELDS + a 4-field minimal tx:
+ *                                      tx start marker + tx hash + fee + 1 mandatory nullifier)
+ *     + 1 checkpoint-end marker      (NUM_CHECKPOINT_END_MARKER_FIELDS)
+ *
+ *   max N:  7 + 10*(N - 1) + 1 <= 24,576  =>  10*(N - 1) <= 24,568  =>  N <= 2,457
+ *
+ * Only the first block may be empty; every other block needs >= 1 tx (the circuits have no empty-tx
+ * variant for non-first blocks), so 2457 is the largest provable checkpoint. The blob format can encode
+ * more blocks than this (up to ~4095 with all-empty blocks), but such a checkpoint is unprovable and
+ * can only reach L1 with a malicious committee supermajority — a terminal network compromise where a
+ * wedged archiver is an acceptable outcome. We therefore bound ingest to the provable maximum.
+ * Invariant checked by the unit test in deserialization.test.ts.
+ */
+export const MAX_CAPACITY_BLOCKS_PER_CHECKPOINT = 2457;
+
+/**
+ * Max blocks per checkpoint we are willing to build or attest to (conservative client policy, and the
+ * default block-count limit for `validateCheckpoint`). Distinct from {@link MAX_CAPACITY_BLOCKS_PER_CHECKPOINT},
+ * which is the higher ceiling we tolerate when deserializing checkpoints already accepted by L1.
+ */
+export const MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT = 72;
 
 /** Max tx effects per body (based on blob capacity per checkpoint) */
 export const MAX_TX_EFFECTS_PER_BODY = BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB;

package/src/epoch-helpers/index.ts

@@ -57,6 +57,25 @@ export function getSlotAtTimestamp(
     : SlotNumber.fromBigInt((ts - constants.l1GenesisTime) / BigInt(constants.slotDuration));
 }
 
+/** Returns the timestamp of the next L1 slot boundary after the given wall-clock time. */
+export function getNextL1SlotTimestamp(
+  nowInSeconds: number,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'ethereumSlotDuration'>,
+): bigint {
+  const now = BigInt(nowInSeconds);
+  const elapsed = now - constants.l1GenesisTime;
+  const currentL1Slot = elapsed / BigInt(constants.ethereumSlotDuration);
+  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,
@@ -143,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,9 +1,10 @@
 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 { InMemoryFileStore } from './memory.js';
 import { S3FileStore } from './s3.js';
 
 const supportedExamples = [
@@ -21,6 +22,12 @@ export async function createFileStore(
 ): Promise<FileStore | undefined> {
   if (config === undefined) {
     return undefined;
+  } else if (config.startsWith('mem://')) {
+    // In-memory store for tests (see InMemoryFileStore). The namespace is everything after the
+    // scheme, so `mem://X` and a later `mem://X` share data, like two file:// stores over one dir.
+    const namespace = config.slice('mem://'.length).replace(/\/+$/, '');
+    logger.info(`Creating in-memory file store at ${namespace}`);
+    return new InMemoryFileStore(namespace);
   } else if (config.startsWith('file://')) {
     const url = new URL(config);
     if (url.host) {
@@ -59,17 +66,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,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`).