@aztec/stdlib 0.0.1-commit.d1f2d6c → 0.0.1-commit.d20b825a7

package/src/interfaces/aztec-node.ts

@@ -1,16 +1,12 @@
-import {
-  ARCHIVE_HEIGHT,
-  L1_TO_L2_MSG_TREE_HEIGHT,
-  NOTE_HASH_TREE_HEIGHT,
-  NULLIFIER_TREE_HEIGHT,
-  PUBLIC_DATA_TREE_HEIGHT,
-} from '@aztec/constants';
+import { ARCHIVE_HEIGHT, L1_TO_L2_MSG_TREE_HEIGHT, NOTE_HASH_TREE_HEIGHT } from '@aztec/constants';
 import { type L1ContractAddresses, L1ContractAddressesSchema } from '@aztec/ethereum/l1-contract-addresses';
 import {
   BlockNumber,
   BlockNumberPositiveSchema,
   BlockNumberSchema,
+  CheckpointNumber,
   CheckpointNumberPositiveSchema,
+  CheckpointNumberSchema,
   EpochNumber,
   EpochNumberSchema,
   type SlotNumber,
@@ -23,12 +19,13 @@ import { MembershipWitness, SiblingPath } from '@aztec/foundation/trees';
 import { z } from 'zod';
 
 import type { AztecAddress } from '../aztec-address/index.js';
-import { L2BlockHash } from '../block/block_hash.js';
+import { BlockHash } from '../block/block_hash.js';
 import { type BlockParameter, BlockParameterSchema } from '../block/block_parameter.js';
 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,
@@ -40,6 +37,7 @@ import {
   type ProtocolContractAddresses,
   ProtocolContractAddressesSchema,
 } from '../contract/index.js';
+import { ManaUsageEstimate } from '../gas/fee_math.js';
 import { GasFees } from '../gas/gas_fees.js';
 import { SiloedTag, Tag, TxScopedL2Log } from '../logs/index.js';
 import { type LogFilter, LogFilterSchema } from '../logs/log_filter.js';
@@ -78,7 +76,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.
@@ -93,124 +96,100 @@ export interface AztecNode
   /**
    * Find the indexes of the given leaves in the given tree along with a block metadata pointing to the block in which
    * the leaves were inserted.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param treeId - The tree to search in.
    * @param leafValues - The values to search for.
    * @returns The indices of leaves and the block metadata of a block in which the leaves were inserted.
    */
   findLeavesIndexes(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     treeId: MerkleTreeId,
     leafValues: Fr[],
   ): Promise<(DataInBlock<bigint> | undefined)[]>;
 
-  /**
-   * Returns a sibling path for the given index in the nullifier tree.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
-   * @param leafIndex - The index of the leaf for which the sibling path is required.
-   * @returns The sibling path for the leaf index.
-   */
-  getNullifierSiblingPath(block: BlockParameter, leafIndex: bigint): Promise<SiblingPath<typeof NULLIFIER_TREE_HEIGHT>>;
-
-  /**
-   * Returns a sibling path for the given index in the note hash tree.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
-   * @param leafIndex - The index of the leaf for which the sibling path is required.
-   * @returns The sibling path for the leaf index.
-   */
-  getNoteHashSiblingPath(block: BlockParameter, leafIndex: bigint): Promise<SiblingPath<typeof NOTE_HASH_TREE_HEIGHT>>;
-
-  /**
-   * Returns a sibling path for a leaf in the committed historic blocks tree.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
-   * @param leafIndex - Index of the leaf in the tree.
-   * @returns The sibling path.
-   */
-  getArchiveSiblingPath(block: BlockParameter, leafIndex: bigint): Promise<SiblingPath<typeof ARCHIVE_HEIGHT>>;
-
-  /**
-   * Returns a sibling path for a leaf in the committed public data tree.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
-   * @param leafIndex - Index of the leaf in the tree.
-   * @returns The sibling path.
-   */
-  getPublicDataSiblingPath(
-    block: BlockParameter,
-    leafIndex: bigint,
-  ): Promise<SiblingPath<typeof PUBLIC_DATA_TREE_HEIGHT>>;
-
   /**
    * Returns a nullifier membership witness for a given nullifier at a given block.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param nullifier - Nullifier we try to find witness for.
    * @returns The nullifier membership witness (if found).
    */
-  getNullifierMembershipWitness(block: BlockParameter, nullifier: Fr): Promise<NullifierMembershipWitness | undefined>;
+  getNullifierMembershipWitness(
+    referenceBlock: BlockParameter,
+    nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined>;
 
   /**
    * Returns a low nullifier membership witness for a given nullifier at a given block.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @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.
    */
   getLowNullifierMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     nullifier: Fr,
   ): Promise<NullifierMembershipWitness | undefined>;
 
   /**
    * Returns a public data tree witness for a given leaf slot at a given block.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param leafSlot - The leaf slot we try to find the witness for.
    * @returns The public data witness (if found).
    * @remarks The witness can be used to compute the current value of the public data tree leaf. If the low leaf preimage corresponds to an
    * "in range" slot, means that the slot doesn't exist and the value is 0. If the low leaf preimage corresponds to the exact slot, the current value
    * is contained in the leaf preimage.
    */
-  getPublicDataWitness(block: BlockParameter, leafSlot: Fr): Promise<PublicDataWitness | undefined>;
+  getPublicDataWitness(referenceBlock: BlockParameter, leafSlot: Fr): Promise<PublicDataWitness | undefined>;
 
   /**
-   * Returns a membership witness for a given archive leaf at a given block.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
-   * @param archive - The archive leaf we try to find the witness for.
+   * Returns a membership witness for a given block hash in the archive tree.
+   *
+   * Block hashes are the leaves of the archive tree. Each time a new block is added to the chain,
+   * its block hash is appended as a new leaf to the archive tree. This method finds the membership
+   * witness (leaf index and sibling path) for a given block hash, which can be used to prove that
+   * a specific block exists in the chain's history.
+   *
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data
+   * (which contains the root of the archive tree in which we are searching for the block hash).
+   * @param blockHash - The block hash to find in the archive tree.
    */
-  getArchiveMembershipWitness(
-    block: BlockParameter,
-    archive: Fr,
+  getBlockHashMembershipWitness(
+    referenceBlock: BlockParameter,
+    blockHash: BlockHash,
   ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined>;
 
   /**
    * Returns a membership witness for a given note hash at a given block.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param noteHash - The note hash we try to find the witness for.
    */
   getNoteHashMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     noteHash: Fr,
   ): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT> | undefined>;
 
   /**
    * Returns the index and a sibling path for a leaf in the committed l1 to l2 data tree.
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param l1ToL2Message - The l1ToL2Message to get the index / sibling path for.
    * @returns A tuple of the index and the sibling path of the L1ToL2Message (undefined if not found).
    */
   getL1ToL2MessageMembershipWitness(
-    block: BlockParameter,
+    referenceBlock: BlockParameter,
     l1ToL2Message: Fr,
   ): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>] | undefined>;
 
-  /** Returns the L2 block number in which this L1 to L2 message becomes available, or undefined if not found. */
-  getL1ToL2MessageBlock(l1ToL2Message: Fr): Promise<BlockNumber | undefined>;
+  /** Returns the L2 checkpoint number in which this L1 to L2 message becomes available, or undefined if not found. */
+  getL1ToL2MessageCheckpoint(l1ToL2Message: Fr): Promise<CheckpointNumber | undefined>;
 
   /**
    * Returns whether an L1 to L2 message is synced by archiver.
    * @param l1ToL2Message - The L1 to L2 message to check.
    * @returns Whether the message is synced.
-   * @deprecated Use `getL1ToL2MessageBlock` instead. This method may return true even if the message is not ready to use.
+   * @deprecated Use `getL1ToL2MessageCheckpoint` instead. This method may return true even if the message is not ready to use.
    */
   isL1ToL2MessageSynced(l1ToL2Message: Fr): Promise<boolean>;
 
@@ -224,17 +203,17 @@ export interface AztecNode
 
   /**
    * Get a block specified by its block number or 'latest'.
-   * @param number - The block number or 'latest'.
+   * @param blockParameter - The block parameter (block number, block hash, or 'latest').
    * @returns The requested block.
    */
-  getBlock(number: BlockParameter): Promise<L2Block | undefined>;
+  getBlock(blockParameter: BlockParameter): Promise<L2Block | undefined>;
 
   /**
    * Get a block specified by its hash.
    * @param blockHash - The block hash being requested.
    * @returns The requested block.
    */
-  getBlockByHash(blockHash: Fr): Promise<L2Block | undefined>;
+  getBlockByHash(blockHash: BlockHash): Promise<L2Block | undefined>;
 
   /**
    * Get a block specified by its archive root.
@@ -261,6 +240,12 @@ export interface AztecNode
    */
   getCheckpointedBlockNumber(): Promise<BlockNumber>;
 
+  /**
+   * Method to fetch the latest checkpoint number synchronized by the node.
+   * @returns The checkpoint number.
+   */
+  getCheckpointNumber(): Promise<CheckpointNumber>;
+
   /**
    * Method to determine if the node is ready to accept transactions.
    * @returns - Flag indicating the readiness for tx submission.
@@ -288,6 +273,15 @@ export interface AztecNode
    */
   getCurrentMinFees(): Promise<GasFees>;
 
+  /**
+   * Returns predicted min fees for the current slot and next N slots.
+   * 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.
+   */
+  getPredictedMinFees(manaUsage?: ManaUsageEstimate): Promise<GasFees[]>;
+
   /**
    * Method to fetch the current max priority fee of txs in the mempool.
    * @returns The current max priority fees.
@@ -355,7 +349,7 @@ export interface AztecNode
    * @returns An array of log arrays, one per tag. Returns at most 10 logs per tag per page. If 10 logs are returned
    * for a tag, the caller should fetch the next page to check for more logs.
    */
-  getPrivateLogsByTags(tags: SiloedTag[], page?: number, referenceBlock?: L2BlockHash): Promise<TxScopedL2Log[][]>;
+  getPrivateLogsByTags(tags: SiloedTag[], page?: number, referenceBlock?: BlockHash): Promise<TxScopedL2Log[][]>;
 
   /**
    * Gets public logs that match any of the `tags` from the specified contract. For each tag, an array of matching
@@ -374,7 +368,7 @@ export interface AztecNode
     contractAddress: AztecAddress,
     tags: Tag[],
     page?: number,
-    referenceBlock?: L2BlockHash,
+    referenceBlock?: BlockHash,
   ): Promise<TxScopedL2Log[][]>;
 
   /**
@@ -433,12 +427,12 @@ export interface AztecNode
    * @remarks The storage slot here refers to the slot as it is defined in Noir not the index in the merkle tree.
    * Aztec's version of `eth_getStorageAt`.
    *
-   * @param block - The block parameter (block number, block hash, or 'latest') at which to get the data.
+   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
    * @param contract - Address of the contract to query.
    * @param slot - Slot to query.
    * @returns Storage value at the given contract slot.
    */
-  getPublicStorageAt(block: BlockParameter, contract: AztecAddress, slot: Fr): Promise<Fr>;
+  getPublicStorageAt(referenceBlock: BlockParameter, contract: AztecAddress, slot: Fr): Promise<Fr>;
 
   /**
    * Returns the block header for a given block number, block hash, or 'latest'.
@@ -474,7 +468,7 @@ export interface AztecNode
   /**
    * Returns true if the transaction is valid for inclusion at the current state. Valid transactions can be
    * made invalid by *other* transactions if e.g. they emit the same nullifiers, or come become invalid
-   * due to e.g. the include_by_timestamp property.
+   * due to e.g. the expiration_timestamp property.
    * @param tx - The transaction to validate for correctness.
    * @param isSimulation - True if the transaction is a simulated one without generated proofs. (Optional)
    * @param skipFeeEnforcement - True if the validation of the fee should be skipped. Useful when the simulation is for estimating fee (Optional)
@@ -518,26 +512,6 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(BlockParameterSchema, z.nativeEnum(MerkleTreeId), z.array(schemas.Fr).max(MAX_RPC_LEN))
     .returns(z.array(optional(dataInBlockSchemaFor(schemas.BigInt)))),
 
-  getNullifierSiblingPath: z
-    .function()
-    .args(BlockParameterSchema, schemas.BigInt)
-    .returns(SiblingPath.schemaFor(NULLIFIER_TREE_HEIGHT)),
-
-  getNoteHashSiblingPath: z
-    .function()
-    .args(BlockParameterSchema, schemas.BigInt)
-    .returns(SiblingPath.schemaFor(NOTE_HASH_TREE_HEIGHT)),
-
-  getArchiveSiblingPath: z
-    .function()
-    .args(BlockParameterSchema, schemas.BigInt)
-    .returns(SiblingPath.schemaFor(ARCHIVE_HEIGHT)),
-
-  getPublicDataSiblingPath: z
-    .function()
-    .args(BlockParameterSchema, schemas.BigInt)
-    .returns(SiblingPath.schemaFor(PUBLIC_DATA_TREE_HEIGHT)),
-
   getNullifierMembershipWitness: z
     .function()
     .args(BlockParameterSchema, schemas.Fr)
@@ -553,9 +527,9 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(BlockParameterSchema, schemas.Fr)
     .returns(PublicDataWitness.schema.optional()),
 
-  getArchiveMembershipWitness: z
+  getBlockHashMembershipWitness: z
     .function()
-    .args(BlockParameterSchema, schemas.Fr)
+    .args(BlockParameterSchema, BlockHash.schema)
     .returns(MembershipWitness.schemaFor(ARCHIVE_HEIGHT).optional()),
 
   getNoteHashMembershipWitness: z
@@ -568,7 +542,7 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(BlockParameterSchema, schemas.Fr)
     .returns(z.tuple([schemas.BigInt, SiblingPath.schemaFor(L1_TO_L2_MSG_TREE_HEIGHT)]).optional()),
 
-  getL1ToL2MessageBlock: z.function().args(schemas.Fr).returns(BlockNumberSchema.optional()),
+  getL1ToL2MessageCheckpoint: z.function().args(schemas.Fr).returns(CheckpointNumberSchema.optional()),
 
   isL1ToL2MessageSynced: z.function().args(schemas.Fr).returns(z.boolean()),
 
@@ -579,12 +553,14 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getBlock: z.function().args(BlockParameterSchema).returns(L2Block.schema.optional()),
 
-  getBlockByHash: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
+  getBlockByHash: z.function().args(BlockHash.schema).returns(L2Block.schema.optional()),
 
   getBlockByArchive: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
 
   getBlockNumber: z.function().returns(BlockNumberSchema),
 
+  getCheckpointNumber: z.function().returns(CheckpointNumberSchema),
+
   getProvenBlockNumber: z.function().returns(BlockNumberSchema),
 
   getCheckpointedBlockNumber: z.function().returns(BlockNumberSchema),
@@ -608,8 +584,15 @@ 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),
 
+  getPredictedMinFees: z
+    .function()
+    .args(optional(z.nativeEnum(ManaUsageEstimate)))
+    .returns(z.array(GasFees.schema)),
+
   getMaxPriorityFees: z.function().returns(GasFees.schema),
 
   getNodeVersion: z.function().returns(z.string()),
@@ -633,7 +616,7 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getPrivateLogsByTags: z
     .function()
-    .args(z.array(SiloedTag.schema).max(MAX_RPC_LEN), optional(z.number().gte(0)), optional(L2BlockHash.schema))
+    .args(z.array(SiloedTag.schema).max(MAX_RPC_LEN), optional(z.number().gte(0)), optional(BlockHash.schema))
     .returns(z.array(z.array(TxScopedL2Log.schema))),
 
   getPublicLogsByTagsFromContract: z
@@ -642,7 +625,7 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
       schemas.AztecAddress,
       z.array(Tag.schema).max(MAX_RPC_LEN),
       optional(z.number().gte(0)),
-      optional(L2BlockHash.schema),
+      optional(BlockHash.schema),
     )
     .returns(z.array(z.array(TxScopedL2Log.schema))),
 

package/src/interfaces/block-builder.ts

@@ -1,5 +1,6 @@
 import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
 import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { LoggerBindings } from '@aztec/foundation/log';
 
 import type { L2Block } from '../block/l2_block.js';
 import type { ChainConfig, SequencerConfig } from '../config/chain-config.js';
@@ -34,51 +35,105 @@ 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;
-  maxBlockSize?: number;
+  /** L2 and DA gas limits. */
   maxBlockGas?: Gas;
+  /** Maximum number of blob fields allowed. */
   maxBlobFields?: number;
+  /** Deadline for processing the txs. Processor will stop as soon as it hits this time. */
   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, 'txPublicSetupAllowList' | 'fakeProcessingDelayPerTxMs' | 'fakeThrowAfterProcessingTxCount'>;
+  Pick<
+    SequencerConfig,
+    | 'txPublicSetupAllowListExtend'
+    | 'fakeProcessingDelayPerTxMs'
+    | 'fakeThrowAfterProcessingTxCount'
+    | 'maxTxsPerBlock'
+    | 'maxTxsPerCheckpoint'
+    | 'maxL2BlockGas'
+    | 'maxDABlockGas'
+  >;
 
 export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[] = [
   'l1GenesisTime',
   'slotDuration',
   'l1ChainId',
   'rollupVersion',
-  'txPublicSetupAllowList',
+  'txPublicSetupAllowListExtend',
   'fakeProcessingDelayPerTxMs',
   'fakeThrowAfterProcessingTxCount',
+  'maxTxsPerBlock',
+  'maxTxsPerCheckpoint',
+  'maxL2BlockGas',
+  'maxDABlockGas',
+  'rollupManaLimit',
 ] as const;
 
+/** 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';
+  }
+}
+
 /** Result of building a block within a checkpoint. */
-export interface BuildBlockInCheckpointResult {
+export type BuildBlockInCheckpointResult = {
   block: L2Block;
-  publicGas: Gas;
   publicProcessorDuration: number;
   numTxs: number;
   failedTxs: FailedTx[];
   usedTxs: Tx[];
-  usedTxBlobFields: number;
-}
+};
 
 /** 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>;
 }
 
@@ -89,8 +144,10 @@ export interface ICheckpointsBuilder {
   startCheckpoint(
     checkpointNumber: CheckpointNumber,
     constants: CheckpointGlobalVariables,
+    feeAssetPriceModifier: bigint,
     l1ToL2Messages: Fr[],
     previousCheckpointOutHashes: Fr[],
     fork: MerkleTreeWriteOperations,
+    bindings?: LoggerBindings,
   ): Promise<ICheckpointBlockBuilder>;
 }

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

@@ -13,6 +13,8 @@ export interface SequencerConfig {
   sequencerPollingIntervalMS?: number;
   /** The maximum number of txs to include in a block. */
   maxTxsPerBlock?: number;
+  /** The maximum number of txs across all blocks in a checkpoint. */
+  maxTxsPerCheckpoint?: number;
   /** The minimum number of txs to include in a block. */
   minTxsPerBlock?: number;
   /** The minimum number of valid txs (after execution) to include in a block. If not set, falls back to minTxsPerBlock. */
@@ -23,6 +25,10 @@ export interface SequencerConfig {
   maxL2BlockGas?: number;
   /** The maximum DA block gas. */
   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. */
@@ -31,10 +37,8 @@ export interface SequencerConfig {
   acvmWorkingDirectory?: string;
   /** The path to the ACVM binary */
   acvmBinaryPath?: string;
-  /** The list of functions calls allowed to run in setup */
-  txPublicSetupAllowList?: AllowedElement[];
-  /** Max block size */
-  maxBlockSizeInBytes?: number;
+  /** Additional entries to extend the default setup allow list. */
+  txPublicSetupAllowListExtend?: AllowedElement[];
   /** Payload address to vote for */
   governanceProposerPayload?: EthAddress;
   /** Whether to enforce the time table when building blocks */
@@ -59,33 +63,45 @@ export interface SequencerConfig {
   broadcastInvalidBlockProposal?: boolean;
   /** Inject a fake attestation (for testing only) */
   injectFakeAttestation?: boolean;
+  /** Inject a malleable attestation with a high-s value (for testing only) */
+  injectHighSValueAttestation?: boolean;
+  /** Inject an attestation with an unrecoverable signature (for testing only) */
+  injectUnrecoverableSignatureAttestation?: boolean;
   /** Whether to run in fisherman mode: builds blocks on every slot for validation without publishing */
   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) */
   blockDurationMs?: number;
+  /** Expected number of block proposals per slot for P2P peer scoring. 0 disables scoring, undefined falls back to blocksPerSlot - 1. */
+  expectedBlockProposalsPerSlot?: number;
   /** Have sequencer build and publish an empty checkpoint if there are no txs */
   buildCheckpointIfEmpty?: boolean;
   /** Skip pushing proposed blocks to archiver (default: false) */
   skipPushProposedBlocksToArchiver?: boolean;
+  /** Minimum number of blocks required for a checkpoint proposal (test only, defaults to undefined = no minimum) */
+  minBlocksForCheckpoint?: number;
+  /** Skip publishing checkpoint proposals probability (for testing checkpoint prunes only) */
+  skipPublishingCheckpointsPercent?: number;
 }
 
 export const SequencerConfigSchema = zodFor<SequencerConfig>()(
   z.object({
     sequencerPollingIntervalMS: z.number().optional(),
     maxTxsPerBlock: z.number().optional(),
+    maxTxsPerCheckpoint: z.number().optional(),
     minValidTxsPerBlock: z.number().optional(),
     minTxsPerBlock: z.number().optional(),
     maxL2BlockGas: z.number().optional(),
     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(),
     acvmBinaryPath: z.string().optional(),
-    txPublicSetupAllowList: z.array(AllowedElementSchema).optional(),
-    maxBlockSizeInBytes: z.number().optional(),
+    txPublicSetupAllowListExtend: z.array(AllowedElementSchema).optional(),
     governanceProposerPayload: schemas.EthAddress.optional(),
     l1PublishingTime: z.number().optional(),
     enforceTimeTable: z.boolean().optional(),
@@ -98,17 +114,23 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     secondsBeforeInvalidatingBlockAsNonCommitteeMember: z.number(),
     broadcastInvalidBlockProposal: z.boolean().optional(),
     injectFakeAttestation: z.boolean().optional(),
+    injectHighSValueAttestation: z.boolean().optional(),
+    injectUnrecoverableSignatureAttestation: z.boolean().optional(),
     fishermanMode: z.boolean().optional(),
     shuffleAttestationOrdering: z.boolean().optional(),
     blockDurationMs: z.number().positive().optional(),
+    expectedBlockProposalsPerSlot: z.number().nonnegative().optional(),
     buildCheckpointIfEmpty: z.boolean().optional(),
     skipPushProposedBlocksToArchiver: z.boolean().optional(),
+    minBlocksForCheckpoint: z.number().positive().optional(),
+    skipPublishingCheckpointsPercent: z.number().gte(0).lte(100).optional(),
   }),
 );
 
 type SequencerConfigOptionalKeys =
   | 'governanceProposerPayload'
   | 'blockDurationMs'
+  | 'expectedBlockProposalsPerSlot'
   | 'coinbase'
   | 'feeRecipient'
   | 'acvmWorkingDirectory'
@@ -116,8 +138,14 @@ type SequencerConfigOptionalKeys =
   | 'fakeProcessingDelayPerTxMs'
   | 'fakeThrowAfterProcessingTxCount'
   | 'l1PublishingTime'
-  | 'txPublicSetupAllowList'
-  | 'minValidTxsPerBlock';
+  | 'txPublicSetupAllowListExtend'
+  | 'minValidTxsPerBlock'
+  | 'minBlocksForCheckpoint'
+  | 'maxTxsPerBlock'
+  | 'maxTxsPerCheckpoint'
+  | 'maxL2BlockGas'
+  | 'maxDABlockGas'
+  | 'redistributeCheckpointBudget';
 
 export type ResolvedSequencerConfig = Prettify<
   Required<Omit<SequencerConfig, SequencerConfigOptionalKeys>> & Pick<SequencerConfig, SequencerConfigOptionalKeys>