@aztec/stdlib 0.0.1-commit.d431d1c → 0.0.1-commit.d939eb5aa

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,11 +19,13 @@ import { MembershipWitness, SiblingPath } from '@aztec/foundation/trees';
 import { z } from 'zod';
 
 import type { AztecAddress } from '../aztec-address/index.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 { L2BlockNew } from '../block/l2_block_new.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,
@@ -39,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,12 +77,11 @@ export interface AztecNode
   extends Pick<
     L2BlockSource,
     | 'getBlocks'
-    | 'getL2BlocksNew'
-    | 'getPublishedBlocks'
-    | 'getPublishedCheckpoints'
+    | 'getCheckpoints'
     | 'getBlockHeader'
     | 'getL2Tips'
     | 'getCheckpointedBlocks'
+    | 'getCheckpointsDataForEpoch'
   > {
   /**
    * Returns the tips of the L2 chain.
@@ -98,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>;
 
@@ -229,24 +203,24 @@ 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<L2BlockNew | 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<L2BlockNew | undefined>;
+  getBlockByHash(blockHash: BlockHash): Promise<L2Block | undefined>;
 
   /**
    * Get a block specified by its archive root.
    * @param archive - The archive root being requested.
    * @returns The requested block.
    */
-  getBlockByArchive(archive: Fr): Promise<L2BlockNew | undefined>;
+  getBlockByArchive(archive: Fr): Promise<L2Block | undefined>;
 
   /**
    * Method to fetch the latest block number synchronized by the node.
@@ -260,6 +234,18 @@ export interface AztecNode
    */
   getProvenBlockNumber(): Promise<BlockNumber>;
 
+  /**
+   * Fetches the latest checkpointed block number.
+   * @returns The block number.
+   */
+  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.
@@ -279,7 +265,7 @@ export interface AztecNode
    * @param limit - The maximum number of blocks to return.
    * @returns The blocks requested.
    */
-  getBlocks(from: BlockNumber, limit: number): Promise<L2BlockNew[]>;
+  getBlocks(from: BlockNumber, limit: number): Promise<L2Block[]>;
 
   /**
    * Method to fetch the current min fees.
@@ -287,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.
@@ -347,10 +342,14 @@ export interface AztecNode
    * array implies no logs match that tag.
    * @param tags - The tags to search for.
    * @param page - The page number (0-indexed) for pagination.
+   * @param referenceBlock - Optional block hash used to ensure the block still exists before logs are retrieved.
+   * This block is expected to represent the latest block to which the client has synced (called anchor block in PXE).
+   * If specified and the block is not found, an error is thrown. This helps detect reorgs, which could result in
+   * undefined behavior in the client's code.
    * @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): 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
@@ -358,6 +357,10 @@ export interface AztecNode
    * @param contractAddress - The contract address to search logs for.
    * @param tags - The tags to search for.
    * @param page - The page number (0-indexed) for pagination.
+   * @param referenceBlock - Optional block hash used to ensure the block still exists before logs are retrieved.
+   * This block is expected to represent the latest block to which the client has synced (called anchor block in PXE).
+   * If specified and the block is not found, an error is thrown. This helps detect reorgs, which could result in
+   * undefined behavior in the client's code.
    * @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.
    */
@@ -365,6 +368,7 @@ export interface AztecNode
     contractAddress: AztecAddress,
     tags: Tag[],
     page?: number,
+    referenceBlock?: BlockHash,
   ): Promise<TxScopedL2Log[][]>;
 
   /**
@@ -423,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'.
@@ -464,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)
@@ -508,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)
@@ -543,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
@@ -558,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()),
 
@@ -567,16 +551,20 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(EpochNumberSchema)
     .returns(z.array(z.array(z.array(z.array(schemas.Fr))))),
 
-  getBlock: z.function().args(BlockParameterSchema).returns(L2BlockNew.schema.optional()),
+  getBlock: z.function().args(BlockParameterSchema).returns(L2Block.schema.optional()),
 
-  getBlockByHash: z.function().args(schemas.Fr).returns(L2BlockNew.schema.optional()),
+  getBlockByHash: z.function().args(BlockHash.schema).returns(L2Block.schema.optional()),
 
-  getBlockByArchive: z.function().args(schemas.Fr).returns(L2BlockNew.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),
+
   isReady: z.function().returns(z.boolean()),
 
   getNodeInfo: z.function().returns(NodeInfoSchema),
@@ -584,30 +572,27 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
   getBlocks: z
     .function()
     .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
-    .returns(z.array(L2BlockNew.schema)),
+    .returns(z.array(L2Block.schema)),
 
-  getPublishedBlocks: z
-    .function()
-    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
-    .returns(z.array(CheckpointedL2Block.schema)),
-
-  getPublishedCheckpoints: z
+  getCheckpoints: z
     .function()
     .args(CheckpointNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_CHECKPOINTS_LEN))
     .returns(z.array(PublishedCheckpoint.schema)),
 
-  getL2BlocksNew: z
-    .function()
-    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
-    .returns(z.array(L2BlockNew.schema)),
-
   getCheckpointedBlocks: z
     .function()
-    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN), optional(z.boolean()))
+    .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()),
@@ -631,12 +616,17 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getPrivateLogsByTags: z
     .function()
-    .args(z.array(SiloedTag.schema).max(MAX_RPC_LEN), optional(z.number().gte(0)))
+    .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
     .function()
-    .args(schemas.AztecAddress, z.array(Tag.schema).max(MAX_RPC_LEN), optional(z.number().gte(0)))
+    .args(
+      schemas.AztecAddress,
+      z.array(Tag.schema).max(MAX_RPC_LEN),
+      optional(z.number().gte(0)),
+      optional(BlockHash.schema),
+    )
     .returns(z.array(z.array(TxScopedL2Log.schema))),
 
   sendTx: z.function().args(Tx.schema).returns(z.void()),

package/src/interfaces/block-builder.ts

@@ -1,7 +1,8 @@
 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 { L2BlockNew } from '../block/l2_block_new.js';
+import type { L2Block } from '../block/l2_block.js';
 import type { ChainConfig, SequencerConfig } from '../config/chain-config.js';
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
 import type { Gas } from '../gas/gas.js';
@@ -31,54 +32,108 @@ export interface IBlockFactory extends ProcessedTxHandler {
   /**
    * Assembles the block and updates the archive tree.
    */
-  setBlockCompleted(expectedBlockHeader?: BlockHeader): Promise<L2BlockNew>;
+  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 {
-  block: L2BlockNew;
-  publicGas: Gas;
+export type BuildBlockInCheckpointResult = {
+  block: L2Block;
   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';