@aztec/stdlib 5.0.0-nightly.20260611 → 5.0.0-nightly.20260613

package/src/config/network-consensus-config.ts

@@ -0,0 +1,302 @@
+import { type L1ContractsConfig, l1ContractsConfigMappings } from '@aztec/ethereum/config';
+import { type EnvVar, pickConfigMappings } from '@aztec/foundation/config';
+
+import type { SequencerConfig } from '../interfaces/configs.js';
+import {
+  DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
+  DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+  DEFAULT_MIN_BLOCK_DURATION,
+  DEFAULT_P2P_PROPAGATION_TIME,
+} from '../timetable/budgets.js';
+import { ProposerTimetable } from '../timetable/proposer_timetable.js';
+import { sharedSequencerConfigMappings } from './sequencer-config.js';
+
+/**
+ * Environment variables whose values must be identical across every node of a network. They fall into three
+ * categories, all consensus-critical:
+ *
+ * - Timing/protocol consensus: slot and epoch durations, block sub-slot duration, max blocks per checkpoint, and
+ *   the checkpoint-proposal materialization grace. Proposers and validators must agree on these to land on the
+ *   same proposed chain and the same checkpoint-proposal receive/handoff deadlines.
+ * - Network identity and L1-posted deployment params: the L1 chain id and the staking/governance/slashing
+ *   parameters baked into the deployed rollup contract (committee size, lags, thresholds, mana target, fee
+ *   pricing, governance/slashing round sizes, quorums, slash amounts, etc.). A node disagreeing with the rollup
+ *   it points at would compute the wrong epoch geometry, fees, or slashing rounds.
+ * - Node-side slashing offense consensus: the offense detection/penalty parameters validators apply locally to
+ *   decide which payloads to sign. Validators must agree on these to reach the on-chain slashing quorum.
+ *
+ * Deliberately excluded: bootnodes, P2P/store/OTEL/sentinel settings, SEQ_MIN_TX_PER_BLOCK, SEQ_MAX_TX_PER_*,
+ * AZTEC_SLASHER_ENABLED, PROVER_REAL_PROOFS, TRANSACTIONS_DISABLED, and AZTEC_ENTRY_QUEUE_* (mainnet-only genesis
+ * params enforced by L1).
+ */
+export const NETWORK_CONSENSUS_ENV_VARS = [
+  // Timing/protocol consensus.
+  'ETHEREUM_SLOT_DURATION',
+  'AZTEC_SLOT_DURATION',
+  'AZTEC_EPOCH_DURATION',
+  'SEQ_BLOCK_DURATION_MS',
+  'MAX_BLOCKS_PER_CHECKPOINT',
+  'CHECKPOINT_PROPOSAL_SYNC_GRACE_SECONDS',
+
+  // Network identity / L1-posted deployment params.
+  'L1_CHAIN_ID',
+  'AZTEC_TARGET_COMMITTEE_SIZE',
+  'AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET',
+  'AZTEC_LAG_IN_EPOCHS_FOR_RANDAO',
+  'AZTEC_ACTIVATION_THRESHOLD',
+  'AZTEC_EJECTION_THRESHOLD',
+  'AZTEC_LOCAL_EJECTION_THRESHOLD',
+  'AZTEC_EXIT_DELAY_SECONDS',
+  'AZTEC_INBOX_LAG',
+  'AZTEC_PROOF_SUBMISSION_EPOCHS',
+  'AZTEC_MANA_TARGET',
+  'AZTEC_PROVING_COST_PER_MANA',
+  'AZTEC_INITIAL_ETH_PER_FEE_ASSET',
+  'AZTEC_GOVERNANCE_PROPOSER_ROUND_SIZE',
+  'AZTEC_GOVERNANCE_PROPOSER_QUORUM',
+  'AZTEC_SLASHING_QUORUM',
+  'AZTEC_SLASHING_ROUND_SIZE_IN_EPOCHS',
+  'AZTEC_SLASHING_LIFETIME_IN_ROUNDS',
+  'AZTEC_SLASHING_OFFSET_IN_ROUNDS',
+  'AZTEC_SLASHING_EXECUTION_DELAY_IN_ROUNDS',
+  'AZTEC_SLASHING_VETOER',
+  'AZTEC_SLASHING_DISABLE_DURATION',
+  'AZTEC_SLASH_AMOUNT_SMALL',
+  'AZTEC_SLASH_AMOUNT_MEDIUM',
+  'AZTEC_SLASH_AMOUNT_LARGE',
+
+  // Node-side slashing offense consensus.
+  'SLASH_OFFENSE_EXPIRATION_ROUNDS',
+  'SLASH_MAX_PAYLOAD_SIZE',
+  'SLASH_EXECUTE_ROUNDS_LOOK_BACK',
+  'SLASH_DATA_WITHHOLDING_TOLERANCE_SLOTS',
+  'SLASH_DATA_WITHHOLDING_PENALTY',
+  'SLASH_INACTIVITY_TARGET_PERCENTAGE',
+  'SLASH_INACTIVITY_CONSECUTIVE_EPOCH_THRESHOLD',
+  'SLASH_INACTIVITY_PENALTY',
+  'SLASH_PROPOSE_INVALID_ATTESTATIONS_PENALTY',
+  'SLASH_DUPLICATE_PROPOSAL_PENALTY',
+  'SLASH_DUPLICATE_ATTESTATION_PENALTY',
+  'SLASH_PROPOSE_DESCENDANT_OF_CHECKPOINT_WITH_INVALID_ATTESTATIONS_PENALTY',
+  'SLASH_ATTEST_INVALID_CHECKPOINT_PROPOSAL_PENALTY',
+  'SLASH_UNKNOWN_PENALTY',
+  'SLASH_INVALID_BLOCK_PENALTY',
+  'SLASH_INVALID_CHECKPOINT_PROPOSAL_PENALTY',
+  'SLASH_GRACE_PERIOD_L2_SLOTS',
+] as const satisfies readonly EnvVar[];
+
+/** A consensus-critical environment variable name; see {@link NETWORK_CONSENSUS_ENV_VARS}. */
+export type ConsensusEnvVar = (typeof NETWORK_CONSENSUS_ENV_VARS)[number];
+
+/**
+ * The subset of consensus-critical timing config whose geometry can be validated in isolation. Composed by
+ * picking the canonical fields from their owning config types so the field set never drifts from the config
+ * layer: slot durations from {@link L1ContractsConfig}, block sub-slot/checkpoint timings from
+ * {@link SequencerConfig} (whose fields are optional there, hence `Required`).
+ */
+export type NetworkConsensusConfig = Pick<L1ContractsConfig, 'aztecSlotDuration' | 'ethereumSlotDuration'> &
+  Required<Pick<SequencerConfig, 'blockDurationMs' | 'maxBlocksPerCheckpoint' | 'checkpointProposalSyncGraceSeconds'>>;
+
+/** Config mappings for the slot-timing fields of {@link NetworkConsensusConfig}, picked from their owners. */
+const networkConsensusConfigMappings = {
+  ...pickConfigMappings(l1ContractsConfigMappings, ['aztecSlotDuration', 'ethereumSlotDuration']),
+  ...pickConfigMappings(sharedSequencerConfigMappings, [
+    'blockDurationMs',
+    'maxBlocksPerCheckpoint',
+    'checkpointProposalSyncGraceSeconds',
+  ]),
+};
+
+/**
+ * Extracts the timing {@link NetworkConsensusConfig} from a generated network config object. The env-var names
+ * and the per-field parsing both come from the canonical config mappings (`l1ContractsConfigMappings` and
+ * `sharedSequencerConfigMappings`), so each field is parsed exactly as the node's config layer would parse it.
+ * A field whose env var is absent becomes `NaN`, which {@link validateNetworkConsensusConfig} reports as an
+ * error. Never throws: parse helpers that would throw or yield `undefined` are coerced to `NaN`.
+ */
+export function getConsensusConfigFromNetworkEnv(
+  values: Record<string, string | number | boolean>,
+): NetworkConsensusConfig {
+  const result = {} as Record<keyof NetworkConsensusConfig, number>;
+  for (const [field, mapping] of Object.entries(networkConsensusConfigMappings)) {
+    const raw = mapping.env !== undefined ? values[mapping.env] : undefined;
+    if (raw === undefined) {
+      result[field as keyof NetworkConsensusConfig] = NaN;
+      continue;
+    }
+    let parsed: number | undefined;
+    try {
+      parsed = mapping.parseEnv ? mapping.parseEnv(String(raw)) : Number(raw);
+    } catch {
+      parsed = NaN;
+    }
+    result[field as keyof NetworkConsensusConfig] = parsed ?? NaN;
+  }
+  return result;
+}
+
+/**
+ * Validates a {@link NetworkConsensusConfig} for self-consistency, returning a list of error messages (empty
+ * when valid). Used by the cli unit test that gates the generated network configs.
+ *
+ * The check requires `maxBlocksPerCheckpoint` to be *exactly* what a {@link ProposerTimetable} built from the
+ * same slot timings and the production default budgets derives. This exact-equality requirement ensures the
+ * published network value is precisely what the production default budgets produce, so every node running those
+ * defaults agrees on the per-checkpoint block count without clamping.
+ */
+export function validateNetworkConsensusConfig(config: NetworkConsensusConfig): string[] {
+  const errors: string[] = [];
+
+  for (const [field, value] of Object.entries(config)) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      errors.push(`${field} must be a finite number (got ${value})`);
+    }
+  }
+  if (errors.length > 0) {
+    return errors;
+  }
+
+  if (config.ethereumSlotDuration <= 0) {
+    errors.push(`ethereumSlotDuration must be positive (got ${config.ethereumSlotDuration})`);
+  }
+  if (config.blockDurationMs <= 0) {
+    errors.push(`blockDurationMs must be positive (got ${config.blockDurationMs})`);
+  }
+  if (config.aztecSlotDuration <= 0) {
+    errors.push(`aztecSlotDuration must be positive (got ${config.aztecSlotDuration})`);
+  }
+  if (config.ethereumSlotDuration > 0 && config.aztecSlotDuration % config.ethereumSlotDuration !== 0) {
+    errors.push(
+      `aztecSlotDuration (${config.aztecSlotDuration}s) must be a multiple of ethereumSlotDuration ` +
+        `(${config.ethereumSlotDuration}s)`,
+    );
+  }
+  if (config.blockDurationMs / 1000 > config.aztecSlotDuration) {
+    errors.push(
+      `blockDurationMs (${config.blockDurationMs}ms) exceeds aztecSlotDuration (${config.aztecSlotDuration}s)`,
+    );
+  }
+  if (config.maxBlocksPerCheckpoint < 1) {
+    errors.push(`maxBlocksPerCheckpoint must be at least 1 (got ${config.maxBlocksPerCheckpoint})`);
+  }
+  if (config.checkpointProposalSyncGraceSeconds < 0) {
+    errors.push(
+      `checkpointProposalSyncGraceSeconds must be non-negative (got ${config.checkpointProposalSyncGraceSeconds})`,
+    );
+  }
+  if (errors.length > 0) {
+    return errors;
+  }
+
+  let computed: number;
+  try {
+    computed = new ProposerTimetable({
+      l1Constants: {
+        l1GenesisTime: 0n,
+        slotDuration: config.aztecSlotDuration,
+        ethereumSlotDuration: config.ethereumSlotDuration,
+      },
+      blockDuration: config.blockDurationMs / 1000,
+      minBlockDuration: DEFAULT_MIN_BLOCK_DURATION,
+      p2pPropagationTime: DEFAULT_P2P_PROPAGATION_TIME,
+      checkpointProposalPrepareTime: DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+      checkpointProposalInitTime: DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
+      checkpointProposalSyncGrace: config.checkpointProposalSyncGraceSeconds,
+    }).getMaxBlocksPerCheckpoint();
+  } catch (err) {
+    // The timetable constructor throws when not even one block fits the default budgets; report instead.
+    errors.push(
+      `maxBlocksPerCheckpoint (${config.maxBlocksPerCheckpoint}) cannot be achieved: the default operational ` +
+        `budgets fit fewer than one block for slot duration ${config.aztecSlotDuration}s and block duration ` +
+        `${config.blockDurationMs / 1000}s (${err instanceof Error ? err.message : String(err)})`,
+    );
+    return errors;
+  }
+
+  if (computed !== config.maxBlocksPerCheckpoint) {
+    errors.push(
+      `maxBlocksPerCheckpoint (${config.maxBlocksPerCheckpoint}) does not match the ${computed} blocks the ` +
+        `production default budgets derive for slot duration ${config.aztecSlotDuration}s and block duration ` +
+        `${config.blockDurationMs / 1000}s`,
+    );
+  }
+
+  return errors;
+}
+
+/**
+ * Enforces that operators do not silently override consensus-critical values diverging from the network config.
+ *
+ * For each var in {@link NETWORK_CONSENSUS_ENV_VARS} present in `networkConfig`: if the operator set it in `env`
+ * to a conflicting value, this throws unless `ALLOW_OVERRIDING_NETWORK_CONFIG` is truthy (in which case it logs
+ * and keeps the operator value).
+ *
+ * This function is pure: it never writes to `env`. Instead it returns the canonical env writes the caller
+ * should apply — a map of env-var name to canonical string value for every numeric var whose env value matched
+ * the network value numerically. Applying these closes a bypass where the config layer parses some vars with
+ * `parseInt` (which reads '6e3' as 6); rewriting them to the network value's string form keeps the operator's
+ * numerically-equal value but in canonical form. Vars kept under `ALLOW_OVERRIDING_NETWORK_CONFIG` (genuine
+ * conflicts) are not included, so the operator value is preserved untouched.
+ *
+ * @returns Canonical env writes (env-var name -> canonical string value) for the caller to apply.
+ */
+export function checkConsensusEnvOverrides(
+  networkConfig: Record<string, string | number | boolean>,
+  env: { [key: string]: string | undefined } = process.env,
+  log?: (msg: string) => void,
+): Record<string, string> {
+  const allowOverride = allowsNetworkConfigOverride(env);
+  const canonical: Record<string, string> = {};
+  const conflicts: string[] = [];
+
+  for (const envVar of NETWORK_CONSENSUS_ENV_VARS) {
+    const networkValue = networkConfig[envVar];
+    if (networkValue === undefined) {
+      continue;
+    }
+
+    const current = env[envVar];
+    if (current === undefined || current === '') {
+      continue;
+    }
+
+    const networkIsNumeric = typeof networkValue === 'number';
+    const matches = networkIsNumeric ? Number(current) === networkValue : current === String(networkValue);
+    if (matches) {
+      if (networkIsNumeric) {
+        canonical[envVar] = String(networkValue);
+      }
+      continue;
+    }
+
+    const conflict = `${envVar}=${current} conflicts with the network value ${networkValue}`;
+    if (allowOverride) {
+      log?.(
+        `Environment variable ${conflict}. Consensus-critical values must match across the network, but ` +
+          `ALLOW_OVERRIDING_NETWORK_CONFIG is set so the operator value is kept (only do this if you know what ` +
+          `you are doing).`,
+      );
+      continue;
+    }
+    conflicts.push(conflict);
+  }
+
+  // Accumulate every conflict so the operator sees all the env vars they need to reconcile at once, rather than
+  // fixing them one failed startup at a time.
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Environment variables conflict with consensus-critical network values:\n` +
+        conflicts.map(c => `  - ${c}`).join('\n') +
+        `\nConsensus-critical values must match across the network. Set ALLOW_OVERRIDING_NETWORK_CONFIG=1 to ` +
+        `override (only do this if you know what you are doing).`,
+    );
+  }
+
+  return canonical;
+}
+
+/** Whether the env opts into overriding network-wide consensus values (`ALLOW_OVERRIDING_NETWORK_CONFIG`). */
+export function allowsNetworkConfigOverride(env: { [key: string]: string | undefined } = process.env): boolean {
+  const value = env.ALLOW_OVERRIDING_NETWORK_CONFIG;
+  return value === '1' || value?.toLowerCase() === 'true';
+}

package/src/config/sequencer-config.ts

@@ -7,12 +7,16 @@ import {
 
 import type { SequencerConfig } from '../interfaces/configs.js';
 import {
+  DEFAULT_BLOCK_DURATION,
   DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
   DEFAULT_MIN_BLOCK_DURATION,
   DEFAULT_P2P_PROPAGATION_TIME,
   getDefaultCheckpointProposalSyncGrace,
 } from '../timetable/index.js';
 
+/** Default duration per block in milliseconds, used to derive how many blocks fit in a slot. */
+export const DEFAULT_BLOCK_DURATION_MS = DEFAULT_BLOCK_DURATION * 1000;
+
 /** Default maximum number of transactions per block. */
 export const DEFAULT_MAX_TXS_PER_BLOCK = 32;
 
@@ -40,10 +44,8 @@ export const sharedSequencerConfigMappings: ConfigMappingsType<
 > = {
   blockDurationMs: {
     env: 'SEQ_BLOCK_DURATION_MS',
-    description:
-      'Duration per block in milliseconds when building multiple blocks per slot. ' +
-      'If undefined (default), builds a single block per slot using the full slot duration.',
-    ...optionalNumberConfigHelper(),
+    description: 'Duration per block in milliseconds, used to derive how many blocks fit in a slot.',
+    ...numberConfigHelper(DEFAULT_BLOCK_DURATION_MS),
   },
   expectedBlockProposalsPerSlot: {
     env: 'SEQ_EXPECTED_BLOCK_PROPOSALS_PER_SLOT',
@@ -57,7 +59,7 @@ export const sharedSequencerConfigMappings: ConfigMappingsType<
     description:
       'Consensus grace in seconds for a received checkpoint proposal to materialize into local proposed state. ' +
       'Defaults to twice the block duration.',
-    defaultValue: getDefaultCheckpointProposalSyncGrace(undefined),
+    defaultValue: getDefaultCheckpointProposalSyncGrace(DEFAULT_BLOCK_DURATION_MS / 1000),
     ...optionalNumberConfigHelper(),
   },
   maxTxsPerBlock: {

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/gas/README.md

@@ -146,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/gas_settings.ts

@@ -8,13 +8,6 @@ import { z } from 'zod';
 import { Gas, GasDimensions } from './gas.js';
 import { GasFees } from './gas_fees.js';
 
-/** Approximate max DA gas limit. Arbitrary, assuming 4 blocks per checkpoint — users should use gas estimation. */
-export const APPROXIMATE_MAX_DA_GAS_PER_BLOCK = Math.floor(MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT / 4);
-/** Fallback teardown L2 gas limit. Arbitrary — users should use gas estimation. */
-export const FALLBACK_TEARDOWN_L2_GAS_LIMIT = Math.floor(MAX_PROCESSABLE_L2_GAS / 8);
-/** Fallback teardown DA gas limit. Arbitrary — users should use gas estimation. */
-export const FALLBACK_TEARDOWN_DA_GAS_LIMIT = Math.floor(APPROXIMATE_MAX_DA_GAS_PER_BLOCK / 2);
-
 // 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.
@@ -106,31 +99,28 @@ export class GasSettings {
 
   /**
    * Fills in gas limits high enough for transactions to be included in most cases.
-   * gasLimits is set to the maximum the protocol allows; since teardown gas is reserved
-   * from gasLimits during private execution (see gas_meter.nr), the effective gas available
-   * for app logic will be gasLimits - teardownGasLimits - privateOverhead.
-   * The DA gas limit is set to an approximate max per block assuming 4 blocks per checkpoint,
-   * since using the maximum per checkpoint would cause nodes to reject transactions.
+   * 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;
+    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: overrides.gasLimits ?? {
-        l2Gas: MAX_PROCESSABLE_L2_GAS,
-        daGas: APPROXIMATE_MAX_DA_GAS_PER_BLOCK,
-      },
-      teardownGasLimits: overrides.teardownGasLimits ?? {
-        l2Gas: FALLBACK_TEARDOWN_L2_GAS_LIMIT,
-        daGas: FALLBACK_TEARDOWN_DA_GAS_LIMIT,
-      },
+      gasLimits,
+      teardownGasLimits,
       maxFeesPerGas: overrides.maxFeesPerGas,
       maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),
     });

package/src/gas/index.ts

@@ -3,3 +3,4 @@ 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';

package/src/gas/tx_gas_limits.ts

@@ -0,0 +1,123 @@
+import {
+  NUM_BLOCK_END_BLOB_FIELDS,
+  NUM_CHECKPOINT_END_MARKER_FIELDS,
+  NUM_FIRST_BLOCK_END_BLOB_FIELDS,
+} from '@aztec/blob-lib/encoding';
+import {
+  BLOBS_PER_CHECKPOINT,
+  DA_GAS_PER_FIELD,
+  FIELDS_PER_BLOB,
+  MAX_PROCESSABLE_L2_GAS,
+  MAX_TX_DA_GAS,
+} from '@aztec/constants';
+
+import { type ProposerTimetableConfig, buildProposerTimetable } from '../timetable/build_proposer_timetable.js';
+import type { SlotTimingConstants } from '../timetable/consensus_timetable.js';
+import { Gas } from './gas.js';
+
+/**
+ * Network-minimum per-block budget multiplier for L2 gas and tx-count allocation. A block packer must
+ * grant at least this share of the even per-block split to a single tx; operators may configure a higher
+ * multiplier (more generous), but not a lower one — enforced at sequencer startup. Also used as the default
+ * for `SequencerConfig.perBlockAllocationMultiplier`.
+ */
+export const MIN_PER_BLOCK_ALLOCATION_MULTIPLIER = 1.2;
+
+/**
+ * Network-minimum per-block budget multiplier for DA gas, applied in place of the general
+ * {@link MIN_PER_BLOCK_ALLOCATION_MULTIPLIER}. Higher than the general multiplier so the largest tx we
+ * want to support — a maximal contract class registration (~97k DA gas) — fits a single block under v5
+ * mainnet geometry (72s slots, 6s blocks → 10 blocks per checkpoint). A builder may configure a higher
+ * multiplier but never a lower one. Also used as the default for
+ * `SequencerConfig.perBlockDAAllocationMultiplier`.
+ */
+export const MIN_PER_BLOCK_DA_ALLOCATION_MULTIPLIER = 1.5;
+
+/**
+ * The DA gas budget available to tx data within a checkpoint of `maxBlocksPerCheckpoint` blocks. This is the
+ * raw blob capacity (`BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB * DA_GAS_PER_FIELD`) minus the fields the blob
+ * encoding reserves for overhead that no tx pays DA gas for:
+ *
+ * - one checkpoint-end marker field (`NUM_CHECKPOINT_END_MARKER_FIELDS`),
+ * - the first block's block-end fields (`NUM_FIRST_BLOCK_END_BLOB_FIELDS`, 7), and
+ * - `NUM_BLOCK_END_BLOB_FIELDS` (6) for each of the `blocks - 1` subsequent blocks.
+ *
+ * Subtracting the overhead for every block (not just the first) keeps the network DA admission limit 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 (assuming
+ * the checkpoint is full of blocks, each spending its share) is what guarantees admitted ⇒ buildable: a tx
+ * admitted under this budget always fits the first block's blob-field cap, regardless of how many blocks the
+ * builder ends up packing.
+ *
+ * @param maxBlocksPerCheckpoint - Number of blocks the checkpoint may contain; clamped to at least 1.
+ */
+export function getDaCheckpointBudgetForTxs(maxBlocksPerCheckpoint: number): number {
+  const blocks = Math.max(1, maxBlocksPerCheckpoint);
+  // Clamp at zero: for absurd geometries (blocks greater than ~4094) the per-block overhead alone exceeds the
+  // raw blob capacity, which would otherwise yield a negative advertised DA budget.
+  const fields = Math.max(
+    0,
+    BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB -
+      NUM_CHECKPOINT_END_MARKER_FIELDS -
+      NUM_FIRST_BLOCK_END_BLOB_FIELDS -
+      (blocks - 1) * NUM_BLOCK_END_BLOB_FIELDS,
+  );
+  return fields * DA_GAS_PER_FIELD;
+}
+
+/**
+ * Computes the maximum gas a single tx may declare on a network: the smaller of the per-tx protocol
+ * maximum and the per-block allocation a proposer grants to the first block of a checkpoint. The per-block
+ * allocation mirrors `CheckpointBuilder.capLimitsByCheckpointBudgets`
+ * (`ceil(checkpointBudget / maxBlocksPerCheckpoint * multiplier)`) using the network-minimum multipliers, so
+ * a tx declaring this much is admissible into a block under that geometry.
+ *
+ * This is a *network* limit: a function of network-wide constants only (timetable-derived
+ * blocks-per-checkpoint, checkpoint budgets, the network-minimum multipliers). It must NOT depend on a
+ * node's local restrictiveness — its multipliers configured above the network minimum, or its
+ * `maxDABlockGas` / `validateMaxDABlockGas` caps — because those make a node stricter at block-building
+ * time but cannot define what the network considers a valid tx for relay. The same value is advertised by
+ * `getNodeInfo` and enforced by the RPC/gossip/pool gas validators.
+ *
+ * The DA budget is {@link getDaCheckpointBudgetForTxs} evaluated at the clamped blocks-per-checkpoint — the
+ * raw blob capacity net of encoding overhead for every block — so the admission limit is consistent with the
+ * builder's blob-field cap.
+ *
+ * @param manaCheckpointBudget - L2 (mana) budget per checkpoint (`rollupManaLimit`).
+ */
+export function computeNetworkTxGasLimits(opts: { maxBlocksPerCheckpoint: number; manaCheckpointBudget: number }): Gas {
+  const blocks = Math.max(1, opts.maxBlocksPerCheckpoint);
+  const daBudget = getDaCheckpointBudgetForTxs(blocks);
+
+  // Clamp by the whole-checkpoint budget too: at small block counts the per-block share scaled by the
+  // multiplier can exceed the checkpoint budget itself (e.g. at blocks=1 a >1 multiplier overshoots), which
+  // would admit a tx no builder can ever pack — the builder caps each block by the remaining budget. Clamping
+  // by the budget makes "admitted ⇒ buildable" unconditional. (For DA the per-tx maximum always binds first,
+  // so the budget clamp is currently moot, but it keeps the invariant explicit.)
+  const daGas = Math.min(
+    MAX_TX_DA_GAS,
+    daBudget,
+    Math.ceil((daBudget / blocks) * MIN_PER_BLOCK_DA_ALLOCATION_MULTIPLIER),
+  );
+  const l2Gas = Math.min(
+    MAX_PROCESSABLE_L2_GAS,
+    opts.manaCheckpointBudget,
+    Math.ceil((opts.manaCheckpointBudget / blocks) * MIN_PER_BLOCK_ALLOCATION_MULTIPLIER),
+  );
+
+  return new Gas(daGas, l2Gas);
+}
+
+/**
+ * Network tx gas limits derived from a sequencer/p2p config and the L1 slot-timing + mana constants. The
+ * single source of truth shared by `getNodeInfo` (advertising) and the RPC/gossip/pool gas validators
+ * (enforcing), so a node never rejects a tx it advertised as admissible. Always uses the network-minimum
+ * multipliers, never the node's (possibly higher) configured multipliers.
+ */
+export function getNetworkTxGasLimits(
+  config: ProposerTimetableConfig,
+  l1Constants: SlotTimingConstants & { rollupManaLimit: number },
+): Gas {
+  const maxBlocksPerCheckpoint = buildProposerTimetable(config, l1Constants).getMaxBlocksPerCheckpoint();
+  return computeNetworkTxGasLimits({ maxBlocksPerCheckpoint, manaCheckpointBudget: l1Constants.rollupManaLimit });
+}