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

package/src/interfaces/aztec-node-admin.ts

@@ -133,7 +133,7 @@ export function createAztecNodeAdminClient(
   apiKey?: string,
 ): AztecNodeAdmin {
   return createSafeJsonRpcClient<AztecNodeAdmin>(url, AztecNodeAdminApiSchema, {
-    namespaceMethods: 'nodeAdmin',
+    namespaceMethods: 'aztecAdmin',
     fetch,
     onResponse: getVersioningResponseHandler(versions),
     ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),

package/src/interfaces/aztec-node-debug.ts

@@ -1,8 +1,9 @@
+import { type CheckpointNumber, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
 import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
 
 import { z } from 'zod';
 
-import type { ApiSchemaFor } from '../schemas/schemas.js';
+import { type ApiSchemaFor, optional } from '../schemas/schemas.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 
 /**
@@ -19,10 +20,24 @@ export interface AztecNodeDebug {
    * @throws If no sequencer is running.
    */
   mineBlock(): Promise<void>;
+
+  /**
+   * Synthetically proves the L2 chain up to the given checkpoint (default: the latest checkpointed
+   * checkpoint), writing epoch out hashes into the L1 Outbox so L2-to-L1 messages become consumable
+   * and advancing the rollup's proven tip. There is no real proof — this is the local-network
+   * equivalent of an epoch proof landing on L1. The target is clamped to the latest checkpointed
+   * checkpoint and the call no-ops when it is already proven.
+   *
+   * @param upToCheckpoint - Checkpoint to prove up to; defaults to the latest checkpointed checkpoint.
+   * @returns The proven checkpoint number after the call.
+   * @throws If no automine sequencer is running (only the automine sequencer supports synthetic proving).
+   */
+  prove(upToCheckpoint?: CheckpointNumber): Promise<CheckpointNumber>;
 }
 
 export const AztecNodeDebugApiSchema: ApiSchemaFor<AztecNodeDebug> = {
   mineBlock: z.function({ input: z.tuple([]), output: z.void() }),
+  prove: z.function({ input: z.tuple([optional(CheckpointNumberSchema)]), output: CheckpointNumberSchema }),
 };
 
 export function createAztecNodeDebugClient(
@@ -32,7 +47,7 @@ export function createAztecNodeDebugClient(
   apiKey?: string,
 ): AztecNodeDebug {
   return createSafeJsonRpcClient<AztecNodeDebug>(url, AztecNodeDebugApiSchema, {
-    namespaceMethods: 'nodeDebug',
+    namespaceMethods: 'aztecDebug',
     fetch,
     onResponse: getVersioningResponseHandler(versions),
     ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),

package/src/interfaces/aztec-node.ts

@@ -7,9 +7,11 @@ import {
   type CheckpointNumber,
   CheckpointNumberPositiveSchema,
   CheckpointNumberSchema,
+  type CheckpointProposalHash,
   type EpochNumber,
   EpochNumberSchema,
   type SlotNumber,
+  SlotNumberSchema,
 } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { EthAddress } from '@aztec/foundation/eth-address';
@@ -35,6 +37,7 @@ import {
   type ProtocolContractAddresses,
   ProtocolContractAddressesSchema,
 } from '../contract/index.js';
+import { type L1RollupConstants, L1RollupConstantsSchema } from '../epoch-helpers/index.js';
 import { ManaUsageEstimate } from '../gas/fee_math.js';
 import { GasFees } from '../gas/gas_fees.js';
 import { type LogResult, LogResultSchema } from '../logs/log_result.js';
@@ -45,7 +48,8 @@ import {
   PublicLogsQuerySchema,
 } from '../logs/logs_query.js';
 import { type L2ToL1MembershipWitness, L2ToL1MembershipWitnessSchema } from '../messaging/l2_to_l1_membership.js';
-import { type ApiSchemaFor, type ZodFor, optional, schemas } from '../schemas/schemas.js';
+import { CheckpointAttestation } from '../p2p/checkpoint_attestation.js';
+import { type ApiSchemaFor, optional, schemas } from '../schemas/schemas.js';
 import { MerkleTreeId } from '../trees/merkle_tree_id.js';
 import { NullifierMembershipWitness } from '../trees/nullifier_membership_witness.js';
 import { PublicDataWitness } from '../trees/public_data_witness.js';
@@ -84,18 +88,12 @@ import {
   type CheckpointResponse,
   CheckpointResponseSchema,
 } from './checkpoint_response.js';
+import { type GetTxByHashOptions, GetTxByHashOptionsSchema } from './get_tx_by_hash_options.js';
+import { type PeerInfo, PeerInfoSchema, type ProposalsForSlot, ProposalsForSlotSchema } from './p2p.js';
 import { type WorldStateSyncStatus, WorldStateSyncStatusSchema } from './world_state.js';
 
-/** Options for retrieving txs via {@link AztecNode.getTxByHash} and {@link AztecNode.getTxsByHash}. */
-export type GetTxByHashOptions = {
-  /** Keep the proof on the returned tx; stripped by default. */
-  includeProof?: boolean;
-};
-
-/** Zod schema for {@link GetTxByHashOptions}. */
-export const GetTxByHashOptionsSchema: ZodFor<GetTxByHashOptions> = z.object({
-  includeProof: z.boolean().optional(),
-});
+export type { GetTxByHashOptions } from './get_tx_by_hash_options.js';
+export { GetTxByHashOptionsSchema } from './get_tx_by_hash_options.js';
 
 /**
  * The aztec node.
@@ -252,6 +250,22 @@ export interface AztecNode {
   /** Returns the tips of the L2 chain. */
   getChainTips(): Promise<ChainTips>;
 
+  /** Returns the rollup constants for the current chain. */
+  getL1Constants(): Promise<L1RollupConstants>;
+
+  /**
+   * Returns the last L2 slot number for which the node has all L1 data needed to build the next checkpoint.
+   */
+  getSyncedL2SlotNumber(): Promise<SlotNumber | undefined>;
+
+  /**
+   * Returns the last L2 epoch number that has been fully synchronized from L1.
+   */
+  getSyncedL2EpochNumber(): Promise<EpochNumber | undefined>;
+
+  /** Returns the latest L1 timestamp according to the archiver's synced L1 view. */
+  getSyncedL1Timestamp(): Promise<bigint | undefined>;
+
   /**
    * Gets lightweight checkpoint metadata for a contiguous range or for an entire epoch.
    * @param query - Either `{ from, limit }` or `{ epoch }`.
@@ -329,7 +343,7 @@ export interface AztecNode {
    * Each entry accounts for the L1 gas oracle transition and congestion growth based on the
    * given mana usage estimate. Defaults to target usage (steady state).
    * @param manaUsage - Expected mana usage per checkpoint (none, target, or limit).
-   * @returns An array of GasFees, one per slot in the prediction window.
+   * @returns An array of GasFees with current min fees first, followed by one entry per predicted slot.
    */
   getPredictedMinFees(manaUsage?: ManaUsageEstimate): Promise<GasFees[]>;
 
@@ -526,6 +540,30 @@ export interface AztecNode {
    * @returns The list of allowed elements.
    */
   getAllowedPublicSetup(): Promise<AllowedElement[]>;
+
+  /**
+   * Returns info for all connected, dialing, and cached peers. Only available when P2P is enabled.
+   * @param includePending - If true, also include peers in the pending state.
+   */
+  getPeers(includePending?: boolean): Promise<PeerInfo[]>;
+
+  /**
+   * Queries the attestation pool for checkpoint attestations for the given slot.
+   * @param slot - The slot to query.
+   * @param proposalPayloadHash - Hex-encoded keccak256 of the target proposal's signed payload hash.
+   *        When provided, only attestations whose payload hash matches are returned.
+   *        When omitted, all attestations for the slot are returned.
+   */
+  getCheckpointAttestationsForSlot(
+    slot: SlotNumber,
+    proposalPayloadHash?: CheckpointProposalHash,
+  ): Promise<CheckpointAttestation[]>;
+
+  /**
+   * Returns block and checkpoint proposals retained in the attestation pool for the given slot.
+   * Only available when P2P is enabled.
+   */
+  getProposalsForSlot(slot: SlotNumber): Promise<ProposalsForSlot>;
 }
 
 const MAX_SIGNATURES_PER_REGISTER_CALL = 100;
@@ -590,6 +628,14 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getChainTips: z.function({ input: z.tuple([]), output: ChainTipsSchema }),
 
+  getL1Constants: z.function({ input: z.tuple([]), output: L1RollupConstantsSchema }),
+
+  getSyncedL2SlotNumber: z.function({ input: z.tuple([]), output: SlotNumberSchema.optional() }),
+
+  getSyncedL2EpochNumber: z.function({ input: z.tuple([]), output: EpochNumberSchema.optional() }),
+
+  getSyncedL1Timestamp: z.function({ input: z.tuple([]), output: schemas.BigInt.optional() }),
+
   getCheckpointsData: z.function({ input: z.tuple([CheckpointsQuerySchema]), output: z.array(CheckpointDataSchema) }),
 
   getBlock: z.function({
@@ -730,6 +776,21 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
   getEncodedEnr: z.function({ input: z.tuple([]), output: z.string().optional() }),
 
   getAllowedPublicSetup: z.function({ input: z.tuple([]), output: z.array(AllowedElementSchema) }),
+
+  getPeers: z.function({ input: z.tuple([optional(z.boolean())]), output: z.array(PeerInfoSchema) }),
+
+  getCheckpointAttestationsForSlot: z.function({
+    input: z.tuple([
+      schemas.SlotNumber,
+      optional(z.string().regex(/^0x[0-9a-fA-F]+$/) as unknown as z.ZodType<CheckpointProposalHash>),
+    ]),
+    output: z.array(CheckpointAttestation.schema),
+  }),
+
+  getProposalsForSlot: z.function({
+    input: z.tuple([schemas.SlotNumber]),
+    output: ProposalsForSlotSchema,
+  }),
 };
 
 export function createAztecNodeClient(
@@ -739,7 +800,7 @@ export function createAztecNodeClient(
   batchWindowMS = 0,
 ): AztecNode {
   return createSafeJsonRpcClient<AztecNode>(url, AztecNodeApiSchema, {
-    namespaceMethods: 'node',
+    namespaceMethods: 'aztec',
     fetch,
     batchWindowMS,
     onResponse: getVersioningResponseHandler(versions),

package/src/interfaces/block-builder.ts

@@ -64,6 +64,8 @@ type ProposerBlockBuilderOptions = BlockBuilderOptionsBase & {
   maxBlocksPerCheckpoint: number;
   /** Per-block gas budget multiplier. Budget = (remaining / remainingBlocks) * multiplier. */
   perBlockAllocationMultiplier: number;
+  /** Per-block budget multiplier for DA gas and blob fields. Falls back to perBlockAllocationMultiplier when unset. */
+  perBlockDAAllocationMultiplier?: number;
 };
 
 /** Validator mode: no redistribution params needed. */

package/src/interfaces/client.ts

@@ -1,6 +1,7 @@
 export * from './aztec-node.js';
 export * from './aztec-node-admin.js';
 export * from './aztec-node-debug.js';
+export { type PeerInfo, type ProposalsForSlot } from './p2p.js';
 export * from './block_response.js';
 export * from './chain_tips.js';
 export * from './checkpoint_parameter.js';

package/src/interfaces/configs.ts

@@ -30,6 +30,11 @@ export interface SequencerConfig {
   maxDABlockGas?: number;
   /** Per-block gas budget multiplier for both L2 and DA gas. Budget = (checkpointLimit / maxBlocks) * multiplier. */
   perBlockAllocationMultiplier?: number;
+  /**
+   * Per-block budget multiplier applied to DA gas and blob fields in place of `perBlockAllocationMultiplier`.
+   * Defaults higher than the general multiplier so the largest contract class deploy fits a single block.
+   */
+  perBlockDAAllocationMultiplier?: number;
   /** Redistribute remaining checkpoint budget evenly across remaining blocks instead of allowing a single block to consume the entire remaining budget. */
   redistributeCheckpointBudget?: boolean;
   /** Recipient of block reward. */
@@ -44,8 +49,6 @@ export interface SequencerConfig {
   txPublicSetupAllowListExtend?: AllowedElement[];
   /** Payload address to vote for */
   governanceProposerPayload?: EthAddress;
-  /** Whether to enforce the time table when building blocks */
-  enforceTimeTable?: boolean;
   /**
    * Minimum block-building time (`min_block_duration`) still worth allocating if the proposer starts
    * late, in seconds.
@@ -56,6 +59,8 @@ export interface SequencerConfig {
    * checkpoint proposal being ready for p2p send, in seconds.
    */
   checkpointProposalPrepareTime?: number;
+  /** How much time (in seconds) we allow in the slot for publishing the L1 tx. */
+  l1PublishingTime?: number;
   /** Used for testing to introduce a fake delay after processing each tx */
   fakeProcessingDelayPerTxMs?: number;
   /** Used for testing to throw an error after processing N txs */
@@ -95,7 +100,7 @@ export interface SequencerConfig {
   fishermanMode?: boolean;
   /** Shuffle attestation ordering to create invalid ordering (for testing only) */
   shuffleAttestationOrdering?: boolean;
-  /** Duration per block in milliseconds when building multiple blocks per slot (default: undefined = single block per slot) */
+  /** Duration per block in milliseconds, used to derive how many blocks fit in a slot (defaults to 3000 ms). */
   blockDurationMs?: number;
   /** Consensus grace in seconds for a received checkpoint proposal to materialize into local proposed state. */
   checkpointProposalSyncGraceSeconds?: number;
@@ -135,6 +140,7 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     publishTxsWithProposals: z.boolean().optional(),
     maxDABlockGas: z.number().optional(),
     perBlockAllocationMultiplier: z.number().optional(),
+    perBlockDAAllocationMultiplier: z.number().optional(),
     redistributeCheckpointBudget: z.boolean().optional(),
     coinbase: schemas.EthAddress.optional(),
     feeRecipient: schemas.AztecAddress.optional(),
@@ -144,7 +150,7 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     governanceProposerPayload: schemas.EthAddress.optional(),
     minBlockDuration: z.number().positive().optional(),
     checkpointProposalPrepareTime: z.number().nonnegative().optional(),
-    enforceTimeTable: z.boolean().optional(),
+    l1PublishingTime: z.number().optional(),
     fakeProcessingDelayPerTxMs: z.number().optional(),
     fakeThrowAfterProcessingTxCount: z.number().optional(),
     attestationPropagationTime: z.number().optional(),
@@ -176,8 +182,6 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
 
 type SequencerConfigOptionalKeys =
   | 'governanceProposerPayload'
-  | 'blockDurationMs'
-  | 'checkpointProposalSyncGraceSeconds'
   | 'expectedBlockProposalsPerSlot'
   | 'coinbase'
   | 'feeRecipient'

package/src/interfaces/get_tx_by_hash_options.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+import type { ZodFor } from '../schemas/schemas.js';
+
+/** Options for retrieving txs via {@link AztecNode.getTxByHash} and {@link AztecNode.getTxsByHash}. */
+export type GetTxByHashOptions = {
+  /** Keep the proof on the returned tx; stripped by default. */
+  includeProof?: boolean;
+};
+
+/** Zod schema for {@link GetTxByHashOptions}. */
+export const GetTxByHashOptionsSchema: ZodFor<GetTxByHashOptions> = z.object({
+  includeProof: z.boolean().optional(),
+});

package/src/interfaces/p2p.ts

@@ -1,22 +1,23 @@
 import type { CheckpointProposalHash, SlotNumber } from '@aztec/foundation/branded-types';
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
-import type { BlockProposal } from '../p2p/block_proposal.js';
+import { BlockProposal } from '../p2p/block_proposal.js';
 import { CheckpointAttestation } from '../p2p/checkpoint_attestation.js';
-import type { CheckpointProposalCore } from '../p2p/checkpoint_proposal.js';
+import { CheckpointProposal, type CheckpointProposalCore } from '../p2p/checkpoint_proposal.js';
 import { type ApiSchemaFor, optional, schemas } from '../schemas/index.js';
 import { Tx } from '../tx/tx.js';
 import { TxHash } from '../tx/tx_hash.js';
 import { MAX_RPC_TXS_LEN } from './api_limit.js';
-import { type GetTxByHashOptions, GetTxByHashOptionsSchema } from './aztec-node.js';
+import { type GetTxByHashOptions, GetTxByHashOptionsSchema } from './get_tx_by_hash_options.js';
 
 export type PeerInfo =
   | { status: 'connected'; score: number; id: string }
   | { status: 'dialing'; dialStatus: string; id: string; addresses: string[] }
   | { status: 'cached'; id: string; addresses: string[]; enr: string; dialAttempts: number };
 
-const PeerInfoSchema = z.discriminatedUnion('status', [
+export const PeerInfoSchema = z.discriminatedUnion('status', [
   z.object({ status: z.literal('connected'), score: z.number(), id: z.string() }),
   z.object({ status: z.literal('dialing'), dialStatus: z.string(), id: z.string(), addresses: z.array(z.string()) }),
   z.object({
@@ -69,20 +70,32 @@ export interface P2PApi {
   ): Promise<CheckpointAttestation[]>;
 }
 
+export type ProposalsForSlot = {
+  blockProposals: BlockProposal[];
+  checkpointProposals: CheckpointProposalCore[];
+};
+
 export interface P2PClient extends P2PApi {
   /** Manually adds checkpoint attestations to the p2p client attestation pool. */
   addOwnCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void>;
 
   /** Returns retained signed proposals for a slot. */
-  getProposalsForSlot(slot: SlotNumber): Promise<{
-    blockProposals: BlockProposal[];
-    checkpointProposals: CheckpointProposalCore[];
-  }>;
+  getProposalsForSlot(slot: SlotNumber): Promise<ProposalsForSlot>;
 
   /** Returns whether a checkpoint proposal was retained for a slot. */
   hasCheckpointProposalForSlot(slot: SlotNumber): Promise<boolean>;
 }
 
+const MAX_PROPOSALS_FOR_SLOT_RPC_LEN = 256;
+
+export const BlockProposalSchema = bufferSchemaFor(BlockProposal);
+export const CheckpointProposalSchema = bufferSchemaFor(CheckpointProposal);
+
+export const ProposalsForSlotSchema = z.object({
+  blockProposals: z.array(BlockProposalSchema).max(MAX_PROPOSALS_FOR_SLOT_RPC_LEN),
+  checkpointProposals: z.array(CheckpointProposalSchema).max(MAX_PROPOSALS_FOR_SLOT_RPC_LEN),
+});
+
 export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
   getCheckpointAttestationsForSlot: z.function({
     input: z.tuple([

package/src/interfaces/validator.ts

@@ -83,10 +83,10 @@ export type ValidatorClientConfig = ValidatorHASignerConfig &
   };
 
 export type ValidatorClientFullConfig = ValidatorClientConfig &
-  Pick<
-    SequencerConfig,
-    'txPublicSetupAllowListExtend' | 'broadcastInvalidBlockProposal' | 'maxBlocksPerCheckpoint' | 'blockDurationMs'
-  > &
+  Pick<SequencerConfig, 'txPublicSetupAllowListExtend' | 'broadcastInvalidBlockProposal' | 'maxBlocksPerCheckpoint'> &
+  // `blockDurationMs` is optional on the loose `SequencerConfig` but is always populated via the shared
+  // `numberConfigHelper(3000)` mapping, so it is required on the fully-resolved validator config.
+  Required<Pick<SequencerConfig, 'blockDurationMs'>> &
   Pick<
     SlasherConfig,
     | 'slashBroadcastedInvalidBlockPenalty'
@@ -132,8 +132,8 @@ export const ValidatorClientFullConfigSchema = zodFor<Omit<ValidatorClientFullCo
   ValidatorClientConfigSchema.extend({
     txPublicSetupAllowListExtend: z.array(AllowedElementSchema).optional(),
     broadcastInvalidBlockProposal: z.boolean().optional(),
+    blockDurationMs: z.number().positive(),
     maxBlocksPerCheckpoint: z.number().positive().optional(),
-    blockDurationMs: z.number().positive().optional(),
     slashBroadcastedInvalidBlockPenalty: schemas.BigInt,
     slashBroadcastedInvalidCheckpointProposalPenalty: schemas.BigInt,
     slashDuplicateProposalPenalty: schemas.BigInt,

package/src/tests/factories.ts

@@ -26,6 +26,7 @@ import {
   MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL,
   MAX_PRIVATE_LOGS_PER_CALL,
   MAX_PRIVATE_LOGS_PER_TX,
+  MAX_PROCESSABLE_L2_GAS,
   MAX_PROTOCOL_CONTRACTS,
   MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
   MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
@@ -232,7 +233,12 @@ export function makeTxContext(seed: number = 1): TxContext {
  * Creates a default instance of gas settings. No seed value is used to ensure we allocate a sensible amount of gas for testing.
  */
 export function makeGasSettings() {
-  return GasSettings.fallback({ maxFeesPerGas: new GasFees(10, 10) });
+  return GasSettings.fallback({
+    // Arbitrary daGas pinned to the pre-existing fixture value so avm_inputs.testdata.bin (consumed by
+    // the C++ vm2 tests) stays byte-stable; teardown derives to the same values the old fallback produced.
+    gasLimits: new Gas(196_608, MAX_PROCESSABLE_L2_GAS),
+    maxFeesPerGas: new GasFees(10, 10),
+  });
 }
 
 /**

package/src/tests/mocks.ts

@@ -1,7 +1,9 @@
 import {
   MAX_ENQUEUED_CALLS_PER_TX,
   MAX_NULLIFIERS_PER_TX,
+  MAX_PROCESSABLE_L2_GAS,
   MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
+  MAX_TX_DA_GAS,
   MAX_TX_LIFETIME,
   PRIVATE_TX_L2_GAS_OVERHEAD,
   PUBLIC_TX_L2_GAS_OVERHEAD,
@@ -110,7 +112,7 @@ export const mockTx = async (
     publicCalldataSize = 2,
     feePayer,
     chonkProof = ChonkProof.random(),
-    gasLimits,
+    gasLimits = new Gas(MAX_TX_DA_GAS, MAX_PROCESSABLE_L2_GAS),
     maxFeesPerGas = new GasFees(10, 10),
     maxPriorityFeesPerGas,
     gasUsed = Gas.empty(),
@@ -212,7 +214,10 @@ export async function mockProcessedTx({
   db,
   chainId = Fr.ZERO,
   version = Fr.ZERO,
-  gasSettings = GasSettings.fallback({ maxFeesPerGas: new GasFees(10, 10) }),
+  gasSettings = GasSettings.fallback({
+    gasLimits: new Gas(MAX_TX_DA_GAS, MAX_PROCESSABLE_L2_GAS),
+    maxFeesPerGas: new GasFees(10, 10),
+  }),
   vkTreeRoot = Fr.ZERO,
   protocolContracts = makeProtocolContracts(seed + 0x100),
   globalVariables = GlobalVariables.empty(),

package/src/timetable/README.md

@@ -275,12 +275,20 @@ where `block_index` is zero-based.
 
 Sub-slot starts and deadlines do not move when earlier blocks finish early or late. If block `k` finishes early, the proposer waits until `block_build_deadline(k)` before attempting block `k + 1`. If block `k` finishes late, the next sub-slot keeps its original deadline and therefore has less remaining headroom.
 
-The maximum number of full-duration block sub-slots is:
+The number of full-duration block sub-slots a node's local operational budgets compute is:
 
 ```text
-max_blocks_per_checkpoint = floor((last_block_build_time - first_subslot_start) / block_duration)
+computed_blocks_per_checkpoint = floor((last_block_build_time - first_subslot_start) / block_duration)
 ```
 
+The effective `max_blocks_per_checkpoint` is this computed value, clamped down to the explicit network value when
+the network value is lower. A network value at or above the computed count has no effect and the computed count is
+used. When the local budgets compute more blocks than the network allows, the computed count is clamped down to the
+network value and a warning is emitted. Clamping never raises the effective value above what the local budgets can
+fit, preserving the invariant that every offered sub-slot's build deadline stays within `last_block_build_time`.
+
+`max_blocks_per_checkpoint` is also an input to the network tx admission limits (it divides the per-checkpoint gas budgets into a per-block share); see [`../gas/README.md`](../gas/README.md) under "Gas and Data Limits".
+
 The start deadline is the latest time at which the proposer can still squeeze one minimum-duration block and make the ideal L1 publish path:
 
 ```text

package/src/timetable/budgets.ts

@@ -1,3 +1,6 @@
+/** Default block sub-slot duration (`D`) in seconds, used to derive how many blocks fit in a slot. */
+export const DEFAULT_BLOCK_DURATION = 3;
+
 /** Default minimum block-building duration (`min_block_duration`) in seconds. */
 export const DEFAULT_MIN_BLOCK_DURATION = 2;
 
@@ -49,8 +52,8 @@ export type ResolvedTimingBudgets = {
 };
 
 /** Default consensus grace for received checkpoint proposals to materialize locally. */
-export function getDefaultCheckpointProposalSyncGrace(blockDuration: number | undefined): number {
-  return 2 * (blockDuration ?? DEFAULT_MIN_BLOCK_DURATION);
+export function getDefaultCheckpointProposalSyncGrace(blockDuration: number): number {
+  return 2 * blockDuration;
 }
 
 /**

package/src/timetable/build_proposer_timetable.ts

@@ -0,0 +1,42 @@
+import {
+  DEFAULT_BLOCK_DURATION,
+  DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
+  DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+  DEFAULT_MIN_BLOCK_DURATION,
+  DEFAULT_P2P_PROPAGATION_TIME,
+} from './budgets.js';
+import type { SlotTimingConstants } from './consensus_timetable.js';
+import { ProposerTimetable } from './proposer_timetable.js';
+
+/**
+ * Subset of the sequencer/p2p config the proposer timetable derives its operational budgets from. Both
+ * {@link SequencerConfig} and {@link P2PConfig} structurally satisfy this, so the same builder is used by
+ * the sequencer, the p2p layer, and the node's `getNodeInfo`.
+ */
+export type ProposerTimetableConfig = {
+  blockDurationMs?: number;
+  minBlockDuration?: number;
+  attestationPropagationTime?: number;
+  checkpointProposalPrepareTime?: number;
+  checkpointProposalSyncGraceSeconds?: number;
+};
+
+/**
+ * Builds the proposer timetable from a sequencer/p2p config and the slot-timing protocol constants,
+ * applying the shared stdlib budget defaults. Single source of truth shared by the sequencer, the p2p
+ * layer, and the node's `getNodeInfo` so they all derive the same `maxBlocksPerCheckpoint`.
+ */
+export function buildProposerTimetable(
+  config: ProposerTimetableConfig,
+  l1Constants: SlotTimingConstants,
+): ProposerTimetable {
+  return new ProposerTimetable({
+    l1Constants,
+    blockDuration: config.blockDurationMs !== undefined ? config.blockDurationMs / 1000 : DEFAULT_BLOCK_DURATION,
+    minBlockDuration: config.minBlockDuration ?? DEFAULT_MIN_BLOCK_DURATION,
+    p2pPropagationTime: config.attestationPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME,
+    checkpointProposalPrepareTime: config.checkpointProposalPrepareTime ?? DEFAULT_CHECKPOINT_PROPOSAL_PREPARE_TIME,
+    checkpointProposalInitTime: DEFAULT_CHECKPOINT_PROPOSAL_INIT_TIME,
+    checkpointProposalSyncGrace: config.checkpointProposalSyncGraceSeconds,
+  });
+}

package/src/timetable/consensus_timetable.ts

@@ -24,8 +24,8 @@ export class ConsensusTimetable {
   /** Ethereum slot duration (`E`) in seconds. */
   public readonly ethereumSlotDuration: number;
 
-  /** Block sub-slot duration (`D`) in seconds, or undefined in single-block mode. */
-  public readonly blockDuration: number | undefined;
+  /** Block sub-slot duration (`D`) in seconds. */
+  public readonly blockDuration: number;
 
   /** L1 genesis timestamp in seconds (`genesis`), the anchor all slot timings derive from. */
   public readonly genesisTime: bigint;
@@ -33,11 +33,7 @@ export class ConsensusTimetable {
   /** Consensus grace for received checkpoint proposals to materialize into local proposed state. */
   public readonly checkpointProposalSyncGrace: number;
 
-  constructor(opts: {
-    l1Constants: SlotTimingConstants;
-    blockDuration: number | undefined;
-    checkpointProposalSyncGrace?: number;
-  }) {
+  constructor(opts: { l1Constants: SlotTimingConstants; blockDuration: number; checkpointProposalSyncGrace?: number }) {
     const { l1Constants, blockDuration } = opts;
     const checkpointProposalSyncGrace =
       opts.checkpointProposalSyncGrace ?? getDefaultCheckpointProposalSyncGrace(blockDuration);
@@ -47,8 +43,8 @@ export class ConsensusTimetable {
     if (l1Constants.ethereumSlotDuration <= 0) {
       throw new Error(`ethereumSlotDuration must be positive (got ${l1Constants.ethereumSlotDuration})`);
     }
-    if (blockDuration !== undefined && blockDuration <= 0) {
-      throw new Error(`blockDuration must be positive when provided (got ${blockDuration})`);
+    if (blockDuration <= 0) {
+      throw new Error(`blockDuration must be positive (got ${blockDuration})`);
     }
     if (checkpointProposalSyncGrace < 0) {
       throw new Error(`checkpointProposalSyncGrace must be non-negative (got ${checkpointProposalSyncGrace})`);
@@ -85,12 +81,10 @@ export class ConsensusTimetable {
 
   /**
    * Hard consensus receive deadline for a checkpoint proposal: `target_slot_start - E - D`. Validators
-   * reject proposals arriving after this, and the next proposer does not build on them. In single-block
-   * mode (`blockDuration` undefined) the `D` term drops to zero, giving `target_slot_start - E` (the
-   * next proposer's build-frame boundary), so this remains usable rather than throwing.
+   * reject proposals arriving after this, and the next proposer does not build on them.
    */
   public getCheckpointProposalReceiveDeadline(slot: SlotNumber): number {
-    return this.getTargetSlotStart(slot) - this.ethereumSlotDuration - (this.blockDuration ?? 0);
+    return this.getTargetSlotStart(slot) - this.ethereumSlotDuration - this.blockDuration;
   }
 
   /**
@@ -100,7 +94,7 @@ export class ConsensusTimetable {
    */
   public getCheckpointProposalSyncedDeadline(slot: SlotNumber): number {
     return Math.ceil(
-      this.getCheckpointProposalReceiveDeadline(slot) + (this.blockDuration ?? 0) + this.checkpointProposalSyncGrace,
+      this.getCheckpointProposalReceiveDeadline(slot) + this.blockDuration + this.checkpointProposalSyncGrace,
     );
   }
 

package/src/timetable/index.ts

@@ -1,3 +1,4 @@
 export * from './budgets.js';
+export * from './build_proposer_timetable.js';
 export * from './consensus_timetable.js';
 export * from './proposer_timetable.js';