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

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

@@ -3,7 +3,8 @@ import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rp
 import { z } from 'zod';
 
 import type { ApiSchemaFor } from '../schemas/schemas.js';
-import { type Offense, OffenseSchema, type SlashPayloadRound, SlashPayloadRoundSchema } from '../slashing/index.js';
+import { optional } from '../schemas/schemas.js';
+import { type Offense, OffenseSchema } from '../slashing/index.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 import { type ArchiverSpecificConfig, ArchiverSpecificConfigSchema } from './archiver.js';
 import { type SequencerConfig, SequencerConfigSchema } from './configs.js';
@@ -36,8 +37,9 @@ export interface AztecNodeAdmin {
    * Pauses syncing and rolls back the database to the target L2 block number.
    * @param targetBlockNumber - The block number to roll back to.
    * @param force - If true, clears the world state db and p2p dbs if rolling back to behind the finalized block.
+   * @param resumeSync - If true (default), resumes archiver and world state sync after rollback.
    */
-  rollbackTo(targetBlockNumber: number, force?: boolean): Promise<void>;
+  rollbackTo(targetBlockNumber: number, force?: boolean, resumeSync?: boolean): Promise<void>;
 
   /** Pauses archiver and world state syncing. */
   pauseSync(): Promise<void>;
@@ -45,9 +47,6 @@ export interface AztecNodeAdmin {
   /** Resumes archiver and world state syncing. */
   resumeSync(): Promise<void>;
 
-  /** Returns all monitored payloads by the slasher for the current round. */
-  getSlashPayloads(): Promise<SlashPayloadRound[]>;
-
   /** Returns all offenses applicable for the given round. */
   getSlashOffenses(round: bigint | 'all' | 'current'): Promise<Offense[]>;
 
@@ -82,6 +81,8 @@ export type AztecNodeAdminConfig = Omit<ValidatorClientFullConfig, 'l1Contracts'
     'archiverPollingIntervalMS' | 'archiverBatchSize' | 'skipValidateCheckpointAttestations'
   > & {
     maxPendingTxCount: number;
+    // Keep in sync with P2PConfig.skipIncomingProposals (circular dep prevents Pick<P2PConfig, ...> here)
+    skipIncomingProposals?: boolean;
   };
 
 export const AztecNodeAdminConfigSchema = SequencerConfigSchema.merge(ProverConfigSchema)
@@ -94,16 +95,15 @@ export const AztecNodeAdminConfigSchema = SequencerConfigSchema.merge(ProverConf
       skipValidateCheckpointAttestations: true,
     }),
   )
-  .merge(z.object({ maxPendingTxCount: z.number() }));
+  .merge(z.object({ maxPendingTxCount: z.number(), skipIncomingProposals: z.boolean().optional() }));
 
 export const AztecNodeAdminApiSchema: ApiSchemaFor<AztecNodeAdmin> = {
   getConfig: z.function().returns(AztecNodeAdminConfigSchema),
   setConfig: z.function().args(AztecNodeAdminConfigSchema.partial()).returns(z.void()),
   startSnapshotUpload: z.function().args(z.string()).returns(z.void()),
-  rollbackTo: z.function().args(z.number()).returns(z.void()),
+  rollbackTo: z.function().args(z.number(), optional(z.boolean()), optional(z.boolean())).returns(z.void()),
   pauseSync: z.function().returns(z.void()),
   resumeSync: z.function().returns(z.void()),
-  getSlashPayloads: z.function().returns(z.array(SlashPayloadRoundSchema)),
   getSlashOffenses: z
     .function()
     .args(z.union([z.bigint(), z.literal('all'), z.literal('current')]))

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

@@ -1,13 +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,
-  CheckpointNumber,
+  type CheckpointNumber,
   CheckpointNumberPositiveSchema,
   CheckpointNumberSchema,
-  EpochNumber,
+  type EpochNumber,
   EpochNumberSchema,
   type SlotNumber,
 } from '@aztec/foundation/branded-types';
@@ -23,10 +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 { CheckpointDataSchema } from '../checkpoint/checkpoint_data.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,
@@ -37,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';
@@ -60,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,
@@ -72,21 +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'
-    | 'getCheckpointsDataForEpoch'
-  > {
-  /**
-   * Returns the tips of the L2 chain.
-   */
-  getL2Tips(): Promise<L2Tips>;
-
+export interface AztecNode {
   /**
    * Returns the sync status of the node's world state
    */
@@ -201,49 +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>;
 
-  /**
-   * Get a block specified by its archive root.
-   * @param archive - The archive root being requested.
-   * @returns The requested block.
-   */
-  getBlockByArchive(archive: Fr): Promise<L2Block | undefined>;
+  /** 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[]>;
 
   /**
-   * Method to fetch the latest block number synchronized by the node.
-   * @returns The block number.
+   * 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`.
    */
-  getBlockNumber(): Promise<BlockNumber>;
+  getBlock<Opts extends BlockIncludeOptions = {}>(
+    param: BlockParameter,
+    options?: Opts,
+  ): Promise<BlockResponse<Opts> | undefined>;
 
   /**
-   * Fetches the latest proven block number.
-   * @returns The block number.
+   * Returns up to `limit` blocks starting from `from`, projected to the {@link BlockResponse}
+   * shape determined by `options`.
    */
-  getProvenBlockNumber(): Promise<BlockNumber>;
+  getBlocks<Opts extends BlockIncludeOptions = {}>(
+    from: BlockNumber,
+    limit: number,
+    options?: Opts,
+  ): Promise<BlockResponse<Opts>[]>;
 
   /**
-   * Fetches the latest checkpointed block number.
-   * @returns The block number.
+   * Unified checkpoint fetch. Returns the checkpoint identified by `param`, with optional fields
+   * controlled by `options`.
    */
-  getCheckpointedBlockNumber(): Promise<BlockNumber>;
+  getCheckpoint<Opts extends CheckpointIncludeOptions = {}>(
+    param: CheckpointParameter,
+    options?: Opts,
+  ): Promise<CheckpointResponse<Opts> | undefined>;
 
   /**
-   * Method to fetch the latest checkpoint number synchronized by the node.
-   * @returns The checkpoint number.
+   * Returns up to `limit` checkpoints starting from `from`, projected to the
+   * {@link CheckpointResponse} shape determined by `options`.
    */
-  getCheckpointNumber(): Promise<CheckpointNumber>;
+  getCheckpoints<Opts extends CheckpointIncludeOptions = {}>(
+    from: CheckpointNumber,
+    limit: number,
+    options?: Opts,
+  ): Promise<CheckpointResponse<Opts>[]>;
 
   /**
    * Method to determine if the node is ready to accept transactions.
@@ -258,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.
@@ -424,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>;
 
@@ -493,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
@@ -541,43 +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()),
-
-  getBlockByHash: z.function().args(BlockHash.schema).returns(L2Block.schema.optional()),
+  getBlockNumber: z.function().args(optional(ChainTipSchema)).returns(BlockNumberSchema),
 
-  getBlockByArchive: z.function().args(schemas.Fr).returns(L2Block.schema.optional()),
+  getCheckpointNumber: z.function().args(optional(ChainTipSchema)).returns(CheckpointNumberSchema),
 
-  getBlockNumber: z.function().returns(BlockNumberSchema),
+  getChainTips: z.function().args().returns(ChainTipsSchema),
 
-  getCheckpointNumber: z.function().returns(CheckpointNumberSchema),
+  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)),
 
-  getCheckpointsDataForEpoch: z.function().args(EpochNumberSchema).returns(z.array(CheckpointDataSchema)),
+  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()),
@@ -633,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_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>;

package/src/interfaces/checkpoint_response.ts

@@ -0,0 +1,84 @@
+import { BlockNumberSchema, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
+import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+import type { IfFlag, Prettify } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { type BlockResponse, BlockResponseSchema } from './block_response.js';
+import { type L1PublishInfo, L1PublishInfoSchema } from './l1_publish_info.js';
+
+/** Options for narrowing the response of `getCheckpoint` / `getCheckpoints`. */
+export type CheckpointIncludeOptions = {
+  /** Include the nested blocks. Off by default. */
+  includeBlocks?: boolean;
+  /** When `includeBlocks` is true, include each block's body (tx effects). Off by default. No-op if `includeBlocks` is false. */
+  includeTransactions?: boolean;
+  /** Include L1 publish info. Off by default. */
+  includeL1PublishInfo?: boolean;
+  /** Include committee attestations. Off by default. */
+  includeAttestations?: boolean;
+};
+
+export const CheckpointIncludeOptionsSchema: z.ZodType<CheckpointIncludeOptions> = z.object({
+  includeBlocks: z.boolean().optional(),
+  includeTransactions: z.boolean().optional(),
+  includeL1PublishInfo: z.boolean().optional(),
+  includeAttestations: z.boolean().optional(),
+});
+
+/** Required metadata always present on a {@link CheckpointResponse}. */
+export type CheckpointResponseBase = {
+  /** Checkpoint number. */
+  number: CheckpointNumber;
+  /** Checkpoint header. */
+  header: CheckpointHeader;
+  /** Archive tree snapshot after this checkpoint. */
+  archive: AppendOnlyTreeSnapshot;
+  /** Hash of the checkpoint out messages. */
+  checkpointOutHash: Fr;
+  /** First block number in this checkpoint. */
+  startBlock: BlockNumber;
+  /** Number of blocks in this checkpoint. */
+  blockCount: number;
+  /** Fee asset price modifier in basis points applied during this checkpoint. */
+  feeAssetPriceModifier: bigint;
+};
+
+// Only forward `includeTransactions` to nested blocks — the other include-flags on the checkpoint
+// options do not apply to the nested block responses (those carry no independent L1 / attestations).
+type NestedBlockOpts<Opts> = Opts extends { includeTransactions: true } ? { includeTransactions: true } : {};
+
+/**
+ * RPC-surface representation of an L2 checkpoint.
+ *
+ * Generic over the include-options so that flagged fields become required when the caller passes a
+ * literal `true`. Only `includeTransactions` is forwarded to nested blocks, so
+ * `includeL1PublishInfo` / `includeAttestations` on a checkpoint request do not imply the same on
+ * its nested blocks. The default type argument ({@link CheckpointIncludeOptions}) yields the
+ * widest shape — what the JSON-RPC wire layer validates against.
+ */
+export type CheckpointResponse<Opts extends CheckpointIncludeOptions = CheckpointIncludeOptions> = Prettify<
+  CheckpointResponseBase &
+    IfFlag<CheckpointIncludeOptions, Opts, 'includeBlocks', { blocks: BlockResponse<NestedBlockOpts<Opts>>[] }> &
+    IfFlag<CheckpointIncludeOptions, Opts, 'includeL1PublishInfo', { l1: L1PublishInfo }> &
+    IfFlag<CheckpointIncludeOptions, Opts, 'includeAttestations', { attestations: CommitteeAttestation[] }>
+>;
+
+/** Zod schema for the widest {@link CheckpointResponse} shape (all include-gated fields optional). */
+export const CheckpointResponseSchema = z.object({
+  number: CheckpointNumberSchema,
+  header: CheckpointHeader.schema,
+  archive: AppendOnlyTreeSnapshot.schema,
+  checkpointOutHash: schemas.Fr,
+  startBlock: BlockNumberSchema,
+  blockCount: z.number(),
+  feeAssetPriceModifier: schemas.BigInt,
+  blocks: z.array(BlockResponseSchema).optional(),
+  l1: L1PublishInfoSchema.optional(),
+  attestations: z.array(CommitteeAttestation.schema).optional(),
+});

package/src/interfaces/client.ts

@@ -1,5 +1,11 @@
 export * from './aztec-node.js';
 export * from './aztec-node-admin.js';
+export * from './aztec-node-debug.js';
+export * from './block_response.js';
+export * from './chain_tips.js';
+export * from './checkpoint_parameter.js';
+export * from './checkpoint_response.js';
+export * from './l1_publish_info.js';
 export * from './private_kernel_prover.js';
 export * from './get_logs_response.js';
 export * from './api_limit.js';