@aztec/stdlib 0.0.1-commit.e558bd1c → 0.0.1-commit.e5a3663dd

package/src/interfaces/aztec-node.ts

@@ -1,11 +1,13 @@
 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,
+  type BlockNumber,
   BlockNumberPositiveSchema,
   BlockNumberSchema,
+  type CheckpointNumber,
   CheckpointNumberPositiveSchema,
-  EpochNumber,
+  CheckpointNumberSchema,
+  type EpochNumber,
   EpochNumberSchema,
   type SlotNumber,
 } from '@aztec/foundation/branded-types';
@@ -21,9 +23,8 @@ 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 { PublishedCheckpoint } from '../checkpoint/published_checkpoint.js';
+import { type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
+import { type CheckpointData, CheckpointDataSchema } from '../checkpoint/checkpoint_data.js';
 import {
   type ContractClassPublic,
   ContractClassPublicSchema,
@@ -34,6 +35,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';
@@ -57,6 +59,20 @@ import type { SingleValidatorStats, ValidatorsStats } from '../validators/types.
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 import { type AllowedElement, AllowedElementSchema } from './allowed_element.js';
 import { MAX_RPC_BLOCKS_LEN, MAX_RPC_CHECKPOINTS_LEN, MAX_RPC_LEN, MAX_RPC_TXS_LEN } from './api_limit.js';
+import {
+  type BlockIncludeOptions,
+  BlockIncludeOptionsSchema,
+  type BlockResponse,
+  BlockResponseSchema,
+} from './block_response.js';
+import { type ChainTip, ChainTipSchema, type ChainTips, ChainTipsSchema } from './chain_tips.js';
+import { type CheckpointParameter, CheckpointParameterSchema } from './checkpoint_parameter.js';
+import {
+  type CheckpointIncludeOptions,
+  CheckpointIncludeOptionsSchema,
+  type CheckpointResponse,
+  CheckpointResponseSchema,
+} from './checkpoint_response.js';
 import {
   type GetContractClassLogsResponse,
   GetContractClassLogsResponseSchema,
@@ -69,16 +85,7 @@ import { type WorldStateSyncStatus, WorldStateSyncStatusSchema } from './world_s
  * The aztec node.
  * We will probably implement the additional interfaces by means other than Aztec Node as it's currently a privacy leak
  */
-export interface AztecNode
-  extends Pick<
-    L2BlockSource,
-    'getBlocks' | 'getCheckpoints' | 'getBlockHeader' | 'getL2Tips' | 'getCheckpointedBlocks'
-  > {
-  /**
-   * Returns the tips of the L2 chain.
-   */
-  getL2Tips(): Promise<L2Tips>;
-
+export interface AztecNode {
   /**
    * Returns the sync status of the node's world state
    */
@@ -114,6 +121,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.
@@ -172,14 +180,14 @@ export interface AztecNode
     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>;
 
@@ -192,43 +200,76 @@ export interface AztecNode
   getL2ToL1Messages(epoch: EpochNumber): Promise<Fr[][][][]>;
 
   /**
-   * Get a block specified by its block number or 'latest'.
-   * @param blockParameter - The block parameter (block number, block hash, or 'latest').
-   * @returns The requested block.
+   * Returns the block number at a given chain tip, or the latest proposed block number when
+   * `tip` is omitted.
    */
-  getBlock(blockParameter: BlockParameter): Promise<L2Block | undefined>;
+  getBlockNumber(tip?: ChainTip): Promise<BlockNumber>;
 
   /**
-   * Get a block specified by its hash.
-   * @param blockHash - The block hash being requested.
-   * @returns The requested block.
+   * Returns the checkpoint number at a given chain tip, or the latest checkpoint number when
+   * `tip` is omitted.
+   *
+   * @remarks **Semantic foot-gun**: block-side `'proposed'` means "latest proposed block" (chain
+   * head), but checkpoint-side `'proposed'` means "latest confirmed checkpoint" — pre-L1-confirm
+   * checkpoints are not exposed over RPC. `'checkpointed'` on the checkpoint side is equivalent.
    */
-  getBlockByHash(blockHash: BlockHash): Promise<L2Block | undefined>;
+  getCheckpointNumber(tip?: ChainTip): Promise<CheckpointNumber>;
+
+  /** Returns the tips of the L2 chain. */
+  getChainTips(): Promise<ChainTips>;
+
+  // TODO(spl/new-rpc-api): the following methods are kept on the interface as a stop-gap because
+  // `L2BlockStream` (used by PXE's block synchronizer) and `computeL2ToL1MembershipWitness` (used
+  // by end-to-end tests) still consume the internal archiver shapes. Remove them when those
+  // consumers are rewired to the unified `BlockResponse` / `CheckpointResponse` API.
+  /** @deprecated Scheduled for removal; use `getChainTips` for public callers. */
+  getL2Tips(): Promise<L2Tips>;
+  /** @deprecated Scheduled for removal; use `getBlock(param).then(r => r?.header)`. */
+  getBlockHeader(number: BlockNumber | 'latest'): Promise<BlockHeader | undefined>;
+  /** @deprecated Scheduled for removal; use `getBlocks(from, limit, { includeL1PublishInfo: true, includeAttestations: true })`. */
+  getCheckpointedBlocks(from: BlockNumber, limit: number): Promise<CheckpointedL2Block[]>;
+  /** @deprecated Scheduled for removal; use `getCheckpoints(from, limit)` over an explicit checkpoint range. */
+  getCheckpointsDataForEpoch(epoch: EpochNumber): Promise<CheckpointData[]>;
 
   /**
-   * Get a block specified by its archive root.
-   * @param archive - The archive root being requested.
-   * @returns The requested block.
+   * Unified block fetch. Returns the block identified by `param`, with optional fields controlled
+   * by `options`.
+   * @param param - A block number, block hash, archive root, chain-tip name, or object variant.
+   * @param options - Narrowing options: `includeTransactions`, `includeL1PublishInfo`, `includeAttestations`.
    */
-  getBlockByArchive(archive: Fr): Promise<L2Block | undefined>;
+  getBlock<Opts extends BlockIncludeOptions = {}>(
+    param: BlockParameter,
+    options?: Opts,
+  ): Promise<BlockResponse<Opts> | undefined>;
 
   /**
-   * Method to fetch the latest block number synchronized by the node.
-   * @returns The block number.
+   * Returns up to `limit` blocks starting from `from`, projected to the {@link BlockResponse}
+   * shape determined by `options`.
    */
-  getBlockNumber(): Promise<BlockNumber>;
+  getBlocks<Opts extends BlockIncludeOptions = {}>(
+    from: BlockNumber,
+    limit: number,
+    options?: Opts,
+  ): Promise<BlockResponse<Opts>[]>;
 
   /**
-   * Fetches the latest proven block number.
-   * @returns The block number.
+   * Unified checkpoint fetch. Returns the checkpoint identified by `param`, with optional fields
+   * controlled by `options`.
    */
-  getProvenBlockNumber(): Promise<BlockNumber>;
+  getCheckpoint<Opts extends CheckpointIncludeOptions = {}>(
+    param: CheckpointParameter,
+    options?: Opts,
+  ): Promise<CheckpointResponse<Opts> | undefined>;
 
   /**
-   * Fetches the latest checkpointed block number.
-   * @returns The block number.
+   * Returns up to `limit` checkpoints starting from `from`, projected to the
+   * {@link CheckpointResponse} shape determined by `options`.
    */
-  getCheckpointedBlockNumber(): Promise<BlockNumber>;
+  getCheckpoints<Opts extends CheckpointIncludeOptions = {}>(
+    from: CheckpointNumber,
+    limit: number,
+    options?: Opts,
+  ): Promise<CheckpointResponse<Opts>[]>;
 
   /**
    * Method to determine if the node is ready to accept transactions.
@@ -243,20 +284,21 @@ export interface AztecNode
    */
   getNodeInfo(): Promise<NodeInfo>;
 
-  /**
-   * Method to request blocks. Will attempt to return all requested blocks but will return only those available.
-   * @param from - The start of the range of blocks to return.
-   * @param limit - The maximum number of blocks to return.
-   * @returns The blocks requested.
-   */
-  getBlocks(from: BlockNumber, limit: number): Promise<L2Block[]>;
-
   /**
    * Method to fetch the current min fees.
    * @returns The current min fees.
    */
   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.
@@ -409,20 +451,6 @@ export interface AztecNode
    */
   getPublicStorageAt(referenceBlock: BlockParameter, contract: AztecAddress, slot: Fr): Promise<Fr>;
 
-  /**
-   * Returns the block header for a given block number, block hash, or 'latest'.
-   * @param block - The block parameter (block number, block hash, or 'latest'). Defaults to 'latest'.
-   * @returns The requested block header.
-   */
-  getBlockHeader(block?: BlockParameter): Promise<BlockHeader | undefined>;
-
-  /**
-   * Get a block header specified by its archive root.
-   * @param archive - The archive root being requested.
-   * @returns The requested block header.
-   */
-  getBlockHeaderByArchive(archive: Fr): Promise<BlockHeader | undefined>;
-
   /** Returns stats for validators if enabled. */
   getValidatorsStats(): Promise<ValidatorsStats>;
 
@@ -443,7 +471,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)
@@ -478,8 +506,6 @@ const MAX_SIGNATURES_PER_REGISTER_CALL = 100;
 const MAX_SIGNATURE_LEN = 10000;
 
 export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
-  getL2Tips: z.function().args().returns(L2TipsSchema),
-
   getWorldStateSyncStatus: z.function().args().returns(WorldStateSyncStatusSchema),
 
   findLeavesIndexes: z
@@ -517,7 +543,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()),
 
@@ -526,39 +552,61 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     .args(EpochNumberSchema)
     .returns(z.array(z.array(z.array(z.array(schemas.Fr))))),
 
-  getBlock: z.function().args(BlockParameterSchema).returns(L2Block.schema.optional()),
+  getBlockNumber: z.function().args(optional(ChainTipSchema)).returns(BlockNumberSchema),
 
-  getBlockByHash: z.function().args(BlockHash.schema).returns(L2Block.schema.optional()),
+  getCheckpointNumber: z.function().args(optional(ChainTipSchema)).returns(CheckpointNumberSchema),
 
-  getBlockByArchive: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
+  getChainTips: z.function().args().returns(ChainTipsSchema),
 
-  getBlockNumber: z.function().returns(BlockNumberSchema),
+  getL2Tips: z.function().args().returns(L2TipsSchema),
 
-  getProvenBlockNumber: z.function().returns(BlockNumberSchema),
+  getBlockHeader: z
+    .function()
+    .args(z.union([BlockNumberSchema, z.literal('latest')]))
+    .returns(BlockHeader.schema.optional()),
 
-  getCheckpointedBlockNumber: z.function().returns(BlockNumberSchema),
+  getCheckpointedBlocks: z
+    .function()
+    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
+    .returns(z.array(CheckpointedL2Block.schema)),
 
-  isReady: z.function().returns(z.boolean()),
+  getCheckpointsDataForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointDataSchema)),
 
-  getNodeInfo: z.function().returns(NodeInfoSchema),
+  getBlock: z
+    .function()
+    .args(BlockParameterSchema, optional(BlockIncludeOptionsSchema))
+    .returns(BlockResponseSchema.optional()),
 
   getBlocks: z
     .function()
-    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
-    .returns(z.array(L2Block.schema)),
+    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN), optional(BlockIncludeOptionsSchema))
+    .returns(z.array(BlockResponseSchema)),
 
-  getCheckpoints: z
+  getCheckpoint: z
     .function()
-    .args(CheckpointNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_CHECKPOINTS_LEN))
-    .returns(z.array(PublishedCheckpoint.schema)),
+    .args(CheckpointParameterSchema, optional(CheckpointIncludeOptionsSchema))
+    .returns(CheckpointResponseSchema.optional()),
 
-  getCheckpointedBlocks: z
+  getCheckpoints: z
     .function()
-    .args(BlockNumberPositiveSchema, z.number().gt(0).lte(MAX_RPC_BLOCKS_LEN))
-    .returns(z.array(CheckpointedL2Block.schema)),
+    .args(
+      CheckpointNumberPositiveSchema,
+      z.number().gt(0).lte(MAX_RPC_CHECKPOINTS_LEN),
+      optional(CheckpointIncludeOptionsSchema),
+    )
+    .returns(z.array(CheckpointResponseSchema)),
+
+  isReady: z.function().returns(z.boolean()),
+
+  getNodeInfo: z.function().returns(NodeInfoSchema),
 
   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()),
@@ -614,10 +662,6 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getPublicStorageAt: z.function().args(BlockParameterSchema, schemas.AztecAddress, schemas.Fr).returns(schemas.Fr),
 
-  getBlockHeader: z.function().args(optional(BlockParameterSchema)).returns(BlockHeader.schema.optional()),
-
-  getBlockHeaderByArchive: z.function().args(schemas.Fr).returns(BlockHeader.schema.optional()),
-
   getValidatorsStats: z.function().returns(ValidatorsStatsSchema),
 
   getValidatorStats: z

package/src/interfaces/block-builder.ts

@@ -35,59 +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 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';
   }
 }
 
 /** Result of building a block within a checkpoint. */
 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>;
 }
 
@@ -98,6 +144,7 @@ export interface ICheckpointsBuilder {
   startCheckpoint(
     checkpointNumber: CheckpointNumber,
     constants: CheckpointGlobalVariables,
+    feeAssetPriceModifier: bigint,
     l1ToL2Messages: Fr[],
     previousCheckpointOutHashes: Fr[],
     fork: MerkleTreeWriteOperations,

package/src/interfaces/block_response.ts

@@ -0,0 +1,79 @@
+import {
+  BlockNumberSchema,
+  CheckpointNumberSchema,
+  IndexWithinCheckpointSchema,
+} from '@aztec/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber, IndexWithinCheckpoint } from '@aztec/foundation/branded-types';
+import type { IfFlag, Prettify } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { BlockHash } from '../block/block_hash.js';
+import { Body } from '../block/body.js';
+import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { BlockHeader } from '../tx/block_header.js';
+import { type L1PublishInfo, L1PublishInfoSchema } from './l1_publish_info.js';
+
+/** Options for narrowing the response of `getBlock` / `getBlocks`. */
+export type BlockIncludeOptions = {
+  /** Include the block body (tx effects). Off by default. */
+  includeTransactions?: boolean;
+  /** Include L1 publish info (populated with `published: false` if not yet on L1). Off by default. */
+  includeL1PublishInfo?: boolean;
+  /** Include committee attestations. Empty array until the block's checkpoint is published. Off by default. */
+  includeAttestations?: boolean;
+};
+
+export const BlockIncludeOptionsSchema: z.ZodType<BlockIncludeOptions> = z.object({
+  includeTransactions: z.boolean().optional(),
+  includeL1PublishInfo: z.boolean().optional(),
+  includeAttestations: z.boolean().optional(),
+});
+
+/** Required metadata always present on a {@link BlockResponse}. */
+export type BlockResponseBase = {
+  /** Block header. */
+  header: BlockHeader;
+  /** Archive tree snapshot after this block. */
+  archive: AppendOnlyTreeSnapshot;
+  /** Hash of the block header. */
+  hash: BlockHash;
+  /** Checkpoint number this block belongs to. */
+  checkpointNumber: CheckpointNumber;
+  /** Position of the block within its checkpoint. */
+  indexWithinCheckpoint: IndexWithinCheckpoint;
+  /** L2 block number. */
+  number: BlockNumber;
+};
+
+/**
+ * RPC-surface representation of an L2 block.
+ *
+ * Generic over the include-options so that flagged fields become required when the caller passes a
+ * literal `true`. The default type argument ({@link BlockIncludeOptions}) yields the widest shape
+ * (all include-fields optional) — this is what the JSON-RPC wire layer validates against.
+ *
+ * @example
+ * const b: BlockResponse<{ includeTransactions: true }> = await node.getBlock(1, { includeTransactions: true });
+ * b.body; // required, not optional
+ */
+export type BlockResponse<Opts extends BlockIncludeOptions = BlockIncludeOptions> = Prettify<
+  BlockResponseBase &
+    IfFlag<BlockIncludeOptions, Opts, 'includeTransactions', { body: Body }> &
+    IfFlag<BlockIncludeOptions, Opts, 'includeL1PublishInfo', { l1: L1PublishInfo }> &
+    IfFlag<BlockIncludeOptions, Opts, 'includeAttestations', { attestations: CommitteeAttestation[] }>
+>;
+
+/** Zod schema for the widest {@link BlockResponse} shape (all include-gated fields optional). */
+export const BlockResponseSchema = z.object({
+  header: BlockHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  hash: BlockHash.schema,
+  checkpointNumber: CheckpointNumberSchema,
+  indexWithinCheckpoint: IndexWithinCheckpointSchema,
+  number: BlockNumberSchema,
+  body: Body.schema.optional(),
+  l1: L1PublishInfoSchema.optional(),
+  attestations: z.array(CommitteeAttestation.schema).optional(),
+});

package/src/interfaces/chain_tips.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+import { type L2BlockTag, type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
+
+/**
+ * Public chain-tip selectors usable in RPC requests.
+ * Omits internal-only tags (e.g. `proposedCheckpoint`) from {@link L2BlockTag}.
+ */
+export type ChainTip = Exclude<L2BlockTag, 'proposedCheckpoint'>;
+
+export const ChainTipSchema = z.union([
+  z.literal('proposed'),
+  z.literal('checkpointed'),
+  z.literal('proven'),
+  z.literal('finalized'),
+]) satisfies z.ZodType<ChainTip>;
+
+/**
+ * Tips of the L2 chain.
+ * Omits the sequencer-internal `proposedCheckpoint` from the public RPC surface.
+ */
+export type ChainTips = Omit<L2Tips, 'proposedCheckpoint'>;
+
+export const ChainTipsSchema = L2TipsSchema.omit({ proposedCheckpoint: true });

package/src/interfaces/checkpoint_parameter.ts

@@ -0,0 +1,22 @@
+import { CheckpointNumberSchema, SlotNumberSchema } from '@aztec/foundation/branded-types';
+
+import { z } from 'zod';
+
+import { ChainTipSchema } from './chain_tips.js';
+
+/**
+ * Selector for a checkpoint in RPC calls.
+ *
+ * Accepts a numeric checkpoint number (or `{ number }`), a slot number (`{ slot }`), a chain-tip
+ * name (e.g. `'proven'`), or `'latest'` (alias for `'proposed'` — on the checkpoint side, this
+ * means the most recent confirmed checkpoint).
+ */
+export const CheckpointParameterSchema = z.union([
+  CheckpointNumberSchema,
+  ChainTipSchema,
+  z.literal('latest'),
+  z.object({ number: CheckpointNumberSchema }),
+  z.object({ slot: SlotNumberSchema }),
+]);
+
+export type CheckpointParameter = z.infer<typeof CheckpointParameterSchema>;