@aztec/stdlib 0.0.1-commit.ffe5b04ea → 0.0.1-commit.fff30aa

package/src/block/l2_block_source.ts

@@ -68,9 +68,8 @@ export interface L2BlockSource {
   getCheckpointedL2BlockNumber(): Promise<BlockNumber>;
 
   /**
-   * Computes the finalized block number based on the proven block number.
-   * A block is considered finalized when it's 2 epochs behind the proven block.
-   * TODO(#13569): Compute proper finalized block number based on L1 finalized block.
+   * Returns the finalized L2 block number. A block is finalized when it was proven
+   * in an L1 block that has itself been finalized on Ethereum.
    * @returns The finalized block number.
    */
   getFinalizedL2BlockNumber(): Promise<BlockNumber>;
@@ -176,14 +175,18 @@ export interface L2BlockSource {
   getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined>;
 
   /**
-   * Returns the current L2 slot number based on the currently synced L1 timestamp.
+   * Returns the last L2 slot number for which we have all L1 data needed to build the next checkpoint.
+   * Determined by the max of two signals: L1 block sync progress and latest synced checkpoint slot.
+   * The checkpoint signal handles missed L1 blocks, since a published checkpoint seals the message tree
+   * for the next checkpoint via the inbox LAG mechanism.
    */
-  getL2SlotNumber(): Promise<SlotNumber | undefined>;
+  getSyncedL2SlotNumber(): Promise<SlotNumber | undefined>;
 
   /**
-   * Returns the current L2 epoch number based on the currently synced L1 timestamp.
+   * Returns the last L2 epoch number that has been fully synchronized from L1.
+   * An epoch is fully synced when all its L2 slots have been fully synced.
    */
-  getL2EpochNumber(): Promise<EpochNumber | undefined>;
+  getSyncedL2EpochNumber(): Promise<EpochNumber | undefined>;
 
   /**
    * Returns all checkpointed block headers for a given epoch.

package/src/block/l2_block_stream/interfaces.ts

@@ -2,10 +2,14 @@ import type { PublishedCheckpoint } from '../../checkpoint/published_checkpoint.
 import type { L2Block } from '../l2_block.js';
 import type { CheckpointId, L2BlockId, L2Tips } from '../l2_block_source.js';
 
+/** Provides the current chain tips. Implemented by world-state, l2-tips-store, and AztecNode. */
+export interface L2TipsProvider {
+  getL2Tips(): Promise<L2Tips>;
+}
+
 /** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
-export interface L2BlockStreamLocalDataProvider {
+export interface L2BlockStreamLocalDataProvider extends L2TipsProvider {
   getL2BlockHash(number: number): Promise<string | undefined>;
-  getL2Tips(): Promise<L2Tips>;
 }
 
 /** Interface to a handler of events emitted. */

package/src/checkpoint/validate.ts

@@ -36,7 +36,7 @@ export function validateCheckpoint(
 ): void {
   validateCheckpointStructure(checkpoint);
   validateCheckpointLimits(checkpoint, opts);
-  validateCheckpointBlocksGasLimits(checkpoint, opts);
+  validateCheckpointBlocksLimits(checkpoint, opts);
 }
 
 /**
@@ -125,7 +125,7 @@ export function validateCheckpointStructure(checkpoint: Checkpoint): void {
 }
 
 /** Validates checkpoint blocks gas limits */
-function validateCheckpointBlocksGasLimits(
+function validateCheckpointBlocksLimits(
   checkpoint: Checkpoint,
   opts: {
     maxL2BlockGas?: number;

package/src/config/sequencer-config.ts

@@ -2,9 +2,6 @@ import type { ConfigMappingsType } from '@aztec/foundation/config';
 
 import type { SequencerConfig } from '../interfaces/configs.js';
 
-/** Default maximum number of transactions per block. */
-export const DEFAULT_MAX_TXS_PER_BLOCK = 32;
-
 /**
  * Partial sequencer config mappings for fields that need to be shared across packages.
  * The full sequencer config mappings remain in sequencer-client, but shared fields

package/src/epoch-helpers/index.ts

@@ -12,6 +12,7 @@ export type L1RollupConstants = {
   ethereumSlotDuration: number;
   proofSubmissionEpochs: number;
   targetCommitteeSize: number;
+  rollupManaLimit: number;
 };
 
 export const EmptyL1RollupConstants: L1RollupConstants = {
@@ -22,6 +23,7 @@ export const EmptyL1RollupConstants: L1RollupConstants = {
   ethereumSlotDuration: 1,
   proofSubmissionEpochs: 1,
   targetCommitteeSize: 48,
+  rollupManaLimit: Number.MAX_SAFE_INTEGER,
 };
 
 export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
@@ -33,6 +35,7 @@ export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
     ethereumSlotDuration: z.number(),
     proofSubmissionEpochs: z.number(),
     targetCommitteeSize: z.number(),
+    rollupManaLimit: z.number(),
   }),
 );
 
@@ -54,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,

package/src/gas/README.md

@@ -0,0 +1,123 @@
+# Aztec Gas and Fee Model
+
+The minimum fee per mana and its components are computed on L1 in
+`l1-contracts/src/core/libraries/rollup/FeeLib.sol`. This document describes the
+formulas, the oracle lag/lifetime mechanism, and the TypeScript types in this directory.
+
+## Mana
+
+Aztec uses **mana** as its unit of work (analogous to Ethereum gas). Transactions consume
+mana in two dimensions: **DA** (data availability) and **L2** (execution). The total fee
+is `gasUsed * feePerMana` summed across both dimensions.
+
+## Fee Components
+
+The minimum fee per mana has four components:
+
+### Sequencer Cost
+
+L1 cost to propose a checkpoint (calldata gas + blob data), amortized over `manaTarget`:
+
+```
+sequencerCost = ((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
+              + (BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * blobFee))
+              / manaTarget
+```
+
+### Prover Cost
+
+L1 cost to verify an epoch proof, amortized over epoch duration and `manaTarget`, plus a
+governance-set proving cost that compensates for off-chain proof generation:
+
+```
+proverCost = (L1_GAS_PER_EPOCH_VERIFIED * baseFee / epochDuration) / manaTarget
+           + provingCostPerMana
+```
+
+### Congestion Cost
+
+An exponential surcharge when the network is congested (inspired by EIP-1559; the
+implementation uses the `fakeExponential` Taylor series approximation from EIP-4844):
+
+```
+baseCost          = sequencerCost + proverCost
+congestionCost    = baseCost * congestionMultiplier / MINIMUM_CONGESTION_MULTIPLIER - baseCost
+```
+
+When there is no congestion the multiplier equals `MINIMUM_CONGESTION_MULTIPLIER` (1e9)
+and congestion cost is zero.
+
+### Congestion Multiplier
+
+```
+excessMana          = max(0, prevExcessMana + prevManaUsed - manaTarget)
+congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, excessMana, denominator)
+```
+
+Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
+
+### Total
+
+```
+minFeePerMana = sequencerCost + proverCost + congestionCost
+```
+
+## L1 Gas Oracle: Lag and Lifetime
+
+The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a two-phase
+(`pre` / `post`) system that smooths out L1 fee volatility.
+
+- **LAG = 2 slots** — when new L1 fees are observed, they activate `LAG` slots later
+  (`slotOfChange = currentSlot + LAG`). This gives mempool transactions time to land
+  before fees change.
+- **LIFETIME = 5 slots** — after an oracle update, the next update is rejected until
+  `slotOfChange + (LIFETIME - LAG)` = 3 more slots have passed. This rate-limits how
+  frequently L1 fee data can change.
+
+Fee resolution at a given timestamp:
+
+```
+if slot < slotOfChange  →  use pre  (old fees)
+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.
+
+## Fee Asset Price
+
+Fees are computed in ETH internally but converted to the fee asset (Fee Juice) via
+`ethPerFeeAsset` (1e12 precision). The price updates at most ±1% (±100 bps) per
+checkpoint:
+
+```
+newPrice = currentPrice * (10000 + modifierBps) / 10000
+```
+
+## Maximum Fee Change Rate
+
+| Component              | Bound                                                   |
+| ---------------------- | ------------------------------------------------------- |
+| L1 base fee / blob fee | At most once every 5 slots (oracle LIFETIME)            |
+| Fee asset price        | ±1% per checkpoint                                      |
+| Congestion multiplier  | Depends on excess mana accumulation/drain per checkpoint |
+| Sequencer/prover costs | Scale linearly with L1 fees                             |
+
+## Key Constants
+
+| Constant                       | Value          |
+| ------------------------------ | -------------- |
+| `L1_GAS_PER_CHECKPOINT_PROPOSED` | 300,000      |
+| `L1_GAS_PER_EPOCH_VERIFIED`     | 3,600,000    |
+| `BLOBS_PER_CHECKPOINT`          | 3            |
+| `BLOB_GAS_PER_BLOB`             | 2^17         |
+| `MINIMUM_CONGESTION_MULTIPLIER` | 1e9          |
+| `LAG`                           | 2 slots      |
+| `LIFETIME`                      | 5 slots      |
+
+## TypeScript Types
+
+- **`Gas`** — mana quantity in two dimensions (`daGas`, `l2Gas`).
+- **`GasFees`** — per-unit price in each dimension (`feePerDaGas`, `feePerL2Gas`).
+- **`GasSettings`** — sender-chosen fee parameters: gas limits, teardown limits, max fees, priority fees.
+- **`GasUsed`** — actual consumption after execution. Note: `billedGas` uses the teardown gas *limit*, not actual usage.

package/src/gas/gas_settings.ts

@@ -1,10 +1,4 @@
-import {
-  DEFAULT_DA_GAS_LIMIT,
-  DEFAULT_L2_GAS_LIMIT,
-  DEFAULT_TEARDOWN_DA_GAS_LIMIT,
-  DEFAULT_TEARDOWN_L2_GAS_LIMIT,
-  GAS_SETTINGS_LENGTH,
-} from '@aztec/constants';
+import { GAS_SETTINGS_LENGTH, MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT, MAX_PROCESSABLE_L2_GAS } from '@aztec/constants';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
@@ -14,6 +8,21 @@ 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.
+export const GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT = MAX_PROCESSABLE_L2_GAS;
+export const GAS_ESTIMATION_L2_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT + MAX_PROCESSABLE_L2_GAS;
+export const GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT = MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
+export const GAS_ESTIMATION_DA_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT + MAX_PROCESSABLE_DA_GAS_PER_CHECKPOINT;
+
 // docs:start:gas_settings_vars
 /** Gas usage and fees limits set by the transaction sender for different dimensions and phases. */
 export class GasSettings {
@@ -95,18 +104,62 @@ export class GasSettings {
     return new GasSettings(Gas.empty(), Gas.empty(), GasFees.empty(), GasFees.empty());
   }
 
-  /** Default gas settings to use when user has not provided them. Requires explicit max fees per gas. */
-  static default(overrides: {
+  /**
+   * Fills in gas limits high enough for transactions to be included in most cases.
+   * 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.
+   * These values won't work if:
+   *  - Teardown consumes more than the arbitrarily assigned fallback limits
+   *  - The rest of the transaction consumes more than the remaining gas after teardown
+   *  - The DA gas limit is too low for the transaction, while still within the checkpoint limit
+   */
+  static fallback(overrides: {
+    gasLimits?: Gas;
+    teardownGasLimits?: Gas;
+    maxFeesPerGas: GasFees;
+    maxPriorityFeesPerGas?: GasFees;
+  }) {
+    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,
+      },
+      maxFeesPerGas: overrides.maxFeesPerGas,
+      maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),
+    });
+  }
+
+  /**
+   * Gas settings for simulation/estimation only.
+   * Since teardown gas is reserved upfront from gasLimits during private execution (see gas_meter.nr),
+   * the effective gas available for app logic is gasLimits - teardownGasLimits - privateOverhead.
+   * To ensure estimation never hits gas caps, we set both limits above what the protocol allows:
+   * teardown gets MAX_PROCESSABLE and gasLimits gets teardown + MAX_PROCESSABLE, so the full
+   * processable amount remains available for each phase independently. To be used in conjunction
+   * with skipTxValidation: true during public simulation, or the node would reject the transaction
+   * outright due to gas limits being above protocol max.
+   */
+  static forEstimation(overrides: {
     gasLimits?: Gas;
     teardownGasLimits?: Gas;
     maxFeesPerGas: GasFees;
     maxPriorityFeesPerGas?: GasFees;
   }) {
     return GasSettings.from({
-      gasLimits: overrides.gasLimits ?? { l2Gas: DEFAULT_L2_GAS_LIMIT, daGas: DEFAULT_DA_GAS_LIMIT },
+      gasLimits: overrides.gasLimits ?? {
+        l2Gas: GAS_ESTIMATION_L2_GAS_LIMIT,
+        daGas: GAS_ESTIMATION_DA_GAS_LIMIT,
+      },
       teardownGasLimits: overrides.teardownGasLimits ?? {
-        l2Gas: DEFAULT_TEARDOWN_L2_GAS_LIMIT,
-        daGas: DEFAULT_TEARDOWN_DA_GAS_LIMIT,
+        l2Gas: GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT,
+        daGas: GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT,
       },
       maxFeesPerGas: overrides.maxFeesPerGas,
       maxPriorityFeesPerGas: overrides.maxPriorityFeesPerGas ?? GasFees.empty(),

package/src/hash/hash.ts

@@ -58,6 +58,35 @@ export function siloNullifier(contract: AztecAddress, innerNullifier: Fr): Promi
   return poseidon2HashWithSeparator([contract, innerNullifier], DomainSeparator.SILOED_NULLIFIER);
 }
 
+/**
+ * Computes the siloed private initialization nullifier for a contract, given its address and initialization hash.
+ * @param contract - The contract address.
+ * @param initializationHash - The contract's initialization hash.
+ * @returns The siloed private initialization nullifier.
+ */
+export async function computeSiloedPrivateInitializationNullifier(
+  contract: AztecAddress,
+  initializationHash: Fr,
+): Promise<Fr> {
+  const innerNullifier = await poseidon2HashWithSeparator(
+    [contract, initializationHash],
+    DomainSeparator.PRIVATE_INITIALIZATION_NULLIFIER,
+  );
+  return siloNullifier(contract, innerNullifier);
+}
+
+/**
+ * Computes the siloed public initialization nullifier for a contract. Not all contracts emit this nullifier: it is only
+ * emitted when the contract has public functions that perform initialization checks (i.e. external public functions that
+ * are not `#[noinitcheck]` or `#[only_self]`).
+ * @param contract - The contract address.
+ * @returns The siloed public initialization nullifier.
+ */
+export async function computeSiloedPublicInitializationNullifier(contract: AztecAddress): Promise<Fr> {
+  const innerNullifier = await poseidon2HashWithSeparator([contract], DomainSeparator.PUBLIC_INITIALIZATION_NULLIFIER);
+  return siloNullifier(contract, innerNullifier);
+}
+
 /**
  * Computes the protocol nullifier, which is the hash of the initial tx request siloed with the null msg sender address.
  * @param txRequestHash - The hash of the initial tx request.
@@ -69,6 +98,11 @@ export function computeProtocolNullifier(txRequestHash: Fr): Promise<Fr> {
   return siloNullifier(AztecAddress.fromBigInt(NULL_MSG_SENDER_CONTRACT_ADDRESS), txRequestHash);
 }
 
+/** Domain-separates a raw log tag with the given domain separator. */
+export function computeLogTag(rawTag: number | bigint | boolean | Fr | Buffer, domSep: DomainSeparator): Promise<Fr> {
+  return poseidon2HashWithSeparator([new Fr(rawTag)], domSep);
+}
+
 export function computeSiloedPrivateLogFirstField(contract: AztecAddress, field: Fr): Promise<Fr> {
   return poseidon2HashWithSeparator([contract, field], DomainSeparator.PRIVATE_LOG_FIRST_FIELD);
 }

package/src/interfaces/archiver.ts

@@ -114,8 +114,8 @@ export const ArchiverApiSchema: ApiSchemaFor<ArchiverApi> = {
   getL2BlockByArchive: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
   getTxEffect: z.function().args(TxHash.schema).returns(indexedTxSchema().optional()),
   getSettledTxReceipt: z.function().args(TxHash.schema).returns(TxReceipt.schema.optional()),
-  getL2SlotNumber: z.function().args().returns(schemas.SlotNumber.optional()),
-  getL2EpochNumber: z.function().args().returns(EpochNumberSchema.optional()),
+  getSyncedL2SlotNumber: z.function().args().returns(schemas.SlotNumber.optional()),
+  getSyncedL2EpochNumber: z.function().args().returns(EpochNumberSchema.optional()),
   getCheckpointsForEpoch: z.function().args(EpochNumberSchema).returns(z.array(Checkpoint.schema)),
   getCheckpointsDataForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointDataSchema)),
   getCheckpointedBlocksForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointedL2Block.schema)),

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

@@ -0,0 +1,40 @@
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
+
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/schemas.js';
+import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
+
+/**
+ * Debug interface for Aztec node available in sandbox/local-network mode.
+ */
+export interface AztecNodeDebug {
+  /**
+   * Triggers the sequencer to produce an L2 block and waits for it to appear.
+   *
+   * **Precondition**: The current L2 slot must not already contain a block. Callers must ensure L1 time has been
+   * advanced to a slot with no existing block before calling this method (e.g. via `EthCheatCodes.warp()`).
+   * If the slot is already taken, the sequencer will fail to propose and this call will time out.
+   *
+   * @throws If no sequencer is running.
+   */
+  mineBlock(): Promise<void>;
+}
+
+export const AztecNodeDebugApiSchema: ApiSchemaFor<AztecNodeDebug> = {
+  mineBlock: z.function().returns(z.void()),
+};
+
+export function createAztecNodeDebugClient(
+  url: string,
+  versions: Partial<ComponentsVersions> = {},
+  fetch = defaultFetch,
+  apiKey?: string,
+): AztecNodeDebug {
+  return createSafeJsonRpcClient<AztecNodeDebug>(url, AztecNodeDebugApiSchema, {
+    namespaceMethods: 'nodeDebug',
+    fetch,
+    onResponse: getVersioningResponseHandler(versions),
+    ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),
+  });
+}

package/src/interfaces/aztec-node.ts

@@ -25,6 +25,7 @@ import { CheckpointedL2Block } from '../block/checkpointed_l2_block.js';
 import { type DataInBlock, dataInBlockSchemaFor } from '../block/in_block.js';
 import { L2Block } from '../block/l2_block.js';
 import { type L2BlockSource, type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
+import { CheckpointDataSchema } from '../checkpoint/checkpoint_data.js';
 import { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
 import {
   type ContractClassPublic,
@@ -74,7 +75,12 @@ import { type WorldStateSyncStatus, WorldStateSyncStatusSchema } from './world_s
 export interface AztecNode
   extends Pick<
     L2BlockSource,
-    'getBlocks' | 'getCheckpoints' | 'getBlockHeader' | 'getL2Tips' | 'getCheckpointedBlocks'
+    | 'getBlocks'
+    | 'getCheckpoints'
+    | 'getBlockHeader'
+    | 'getL2Tips'
+    | 'getCheckpointedBlocks'
+    | 'getCheckpointsDataForEpoch'
   > {
   /**
    * Returns the tips of the L2 chain.
@@ -116,6 +122,7 @@ export interface AztecNode
    * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param nullifier - Nullifier we try to find the low nullifier witness for.
    * @returns The low nullifier membership witness (if found).
+   * @throws If the nullifier already exists in the tree, since non-inclusion cannot be proven.
    * @remarks Low nullifier witness can be used to perform a nullifier non-inclusion proof by leveraging the "linked
    * list structure" of leaves and proving that a lower nullifier is pointing to a bigger next value than the nullifier
    * we are trying to prove non-inclusion for.
@@ -567,6 +574,8 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
     .returns(z.array(CheckpointedL2Block.schema)),
 
+  getCheckpointsDataForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointDataSchema)),
+
   getCurrentMinFees: z.function().returns(GasFees.schema),
 
   getMaxPriorityFees: z.function().returns(GasFees.schema),

package/src/interfaces/block-builder.ts

@@ -35,7 +35,8 @@ export interface IBlockFactory extends ProcessedTxHandler {
   setBlockCompleted(expectedBlockHeader?: BlockHeader): Promise<L2Block>;
 }
 
-export interface PublicProcessorLimits {
+/** Limits passed to the public processor for tx processing within a block. */
+export type PublicProcessorLimits = {
   /** Maximum number of txs to process. */
   maxTransactions?: number;
   /** L2 and DA gas limits. */
@@ -46,14 +47,37 @@ export interface PublicProcessorLimits {
   deadline?: Date;
   /** Whether this processor is building a proposal (as opposed to re-executing one). Skipping txs due to gas or blob limits is only done during proposal building. */
   isBuildingProposal?: boolean;
-}
+};
+
+/** Base fields shared by both proposer and validator block builder options. */
+type BlockBuilderOptionsBase = PublicProcessorLimits & {
+  /** Minimum number of successfully processed txs required. Block is rejected if fewer succeed. */
+  minValidTxs: number;
+};
+
+/** Proposer mode: redistribution params are required. */
+type ProposerBlockBuilderOptions = BlockBuilderOptionsBase & {
+  isBuildingProposal: true;
+  /** Maximum number of blocks per checkpoint, derived from the timetable. */
+  maxBlocksPerCheckpoint: number;
+  /** Per-block gas budget multiplier. Budget = (remaining / remainingBlocks) * multiplier. */
+  perBlockAllocationMultiplier: number;
+};
+
+/** Validator mode: no redistribution params needed. */
+type ValidatorBlockBuilderOptions = BlockBuilderOptionsBase & {
+  isBuildingProposal: false;
+};
+
+/** Options for building a block within a checkpoint. When proposing, redistribution params are required. */
+export type BlockBuilderOptions = ProposerBlockBuilderOptions | ValidatorBlockBuilderOptions;
 
 export interface PublicProcessorValidator {
   preprocessValidator?: TxValidator<Tx>;
   nullifierCache?: { addNullifiers: (nullifiers: Buffer[]) => void };
 }
 
-export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'> &
+export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'rollupManaLimit'> &
   Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
   Pick<
     SequencerConfig,
@@ -64,10 +88,7 @@ export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime'
     | 'maxTxsPerCheckpoint'
     | 'maxL2BlockGas'
     | 'maxDABlockGas'
-  > & {
-    /** Total L2 gas (mana) allowed per checkpoint. Fetched from L1 getManaLimit(). */
-    rollupManaLimit: number;
-  };
+  >;
 
 export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[] = [
   'l1GenesisTime',
@@ -84,11 +105,15 @@ export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[
   'rollupManaLimit',
 ] as const;
 
-/** Thrown when no valid transactions are available to include in a block after processing, and this is not the first block in a checkpoint. */
-export class NoValidTxsError extends Error {
-  constructor(public readonly failedTxs: FailedTx[]) {
-    super('No valid transactions to include in block');
-    this.name = 'NoValidTxsError';
+/** Thrown when the number of successfully processed transactions is below the required minimum. */
+export class InsufficientValidTxsError extends Error {
+  constructor(
+    public readonly processedCount: number,
+    public readonly minRequired: number,
+    public readonly failedTxs: FailedTx[],
+  ) {
+    super(`Insufficient valid txs: got ${processedCount} but need ${minRequired}`);
+    this.name = 'InsufficientValidTxsError';
   }
 }
 
@@ -103,11 +128,12 @@ export type BuildBlockInCheckpointResult = {
 
 /** Interface for building blocks within a checkpoint context. */
 export interface ICheckpointBlockBuilder {
+  /** Builds a single block within this checkpoint. Throws InsufficientValidTxsError if fewer than minValidTxs succeed. */
   buildBlock(
     pendingTxs: Iterable<Tx> | AsyncIterable<Tx>,
     blockNumber: BlockNumber,
     timestamp: bigint,
-    opts: PublicProcessorLimits,
+    opts: BlockBuilderOptions,
   ): Promise<BuildBlockInCheckpointResult>;
 }
 

package/src/interfaces/client.ts

@@ -1,5 +1,6 @@
 export * from './aztec-node.js';
 export * from './aztec-node-admin.js';
+export * from './aztec-node-debug.js';
 export * from './private_kernel_prover.js';
 export * from './get_logs_response.js';
 export * from './api_limit.js';

package/src/interfaces/configs.ts

@@ -27,6 +27,8 @@ export interface SequencerConfig {
   maxDABlockGas?: number;
   /** Per-block gas budget multiplier for both L2 and DA gas. Budget = (checkpointLimit / maxBlocks) * multiplier. */
   perBlockAllocationMultiplier?: 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. */
   coinbase?: EthAddress;
   /** Address to receive fees. */
@@ -94,6 +96,7 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     publishTxsWithProposals: z.boolean().optional(),
     maxDABlockGas: z.number().optional(),
     perBlockAllocationMultiplier: z.number().optional(),
+    redistributeCheckpointBudget: z.boolean().optional(),
     coinbase: schemas.EthAddress.optional(),
     feeRecipient: schemas.AztecAddress.optional(),
     acvmWorkingDirectory: z.string().optional(),
@@ -142,7 +145,7 @@ type SequencerConfigOptionalKeys =
   | 'maxTxsPerCheckpoint'
   | 'maxL2BlockGas'
   | 'maxDABlockGas'
-  | 'perBlockAllocationMultiplier';
+  | 'redistributeCheckpointBudget';
 
 export type ResolvedSequencerConfig = Prettify<
   Required<Omit<SequencerConfig, SequencerConfigOptionalKeys>> & Pick<SequencerConfig, SequencerConfigOptionalKeys>