feat(rpc)!: updated rpc api for blocks and checkpoints

[spalladino]

Implements the new JSON RPC API proposal for blocks and checkpoints. Next steps:

• Remove the methods flagged as deprecated
• Align the internal archiver API (and potentially storage) with this new external node API so we can get rid of the block response adapters
• Review the chain tips structure (in particular the proposedCheckpoint)
• Review the APIs that return checkpoints on when we return proposed vs mined checkpoints

Fixes A-974

[spalladino]

Proposal for new API methods

Current State

Block Data Types

/** Metadata only, no transaction data. */
type BlockData = {
  header: BlockHeader;
  archive: AppendOnlyTreeSnapshot;
  blockHash: Fr;
  checkpointNumber: CheckpointNumber;
  indexWithinCheckpoint: IndexWithinCheckpoint;
};

/** Full block with transaction data. */
class L2Block {
  archive: AppendOnlyTreeSnapshot;
  header: BlockHeader;
  body: Body;
  checkpointNumber: CheckpointNumber;
  indexWithinCheckpoint: IndexWithinCheckpoint;
}

/** Full block bundled with L1 checkpoint context. */
class CheckpointedL2Block {
  checkpointNumber: CheckpointNumber;
  block: L2Block;
  l1: L1PublishedData;            // { blockNumber: bigint, timestamp: bigint, blockHash: string }
  attestations: CommitteeAttestation[];
}

Checkpoint Data Types

/** Full checkpoint with blocks and L1 context. Returned by getCheckpoints. */
class PublishedCheckpoint {
  checkpoint: Checkpoint;
  l1: L1PublishedData;
  attestations: CommitteeAttestation[];
}

/** The checkpoint itself, containing full blocks. */
class Checkpoint {
  archive: AppendOnlyTreeSnapshot;
  header: CheckpointHeader;
  blocks: L2Block[];
  number: CheckpointNumber;
  feeAssetPriceModifier: bigint;
}

/** Lightweight checkpoint metadata without blocks. Returned by getCheckpointsDataForEpoch. */
type CheckpointData = {
  checkpointNumber: CheckpointNumber;
  header: CheckpointHeader;
  archive: AppendOnlyTreeSnapshot;
  checkpointOutHash: Fr;
  startBlock: BlockNumber;
  blockCount: number;
  attestations: CommitteeAttestation[];
  l1: L1PublishedData;
};

/** L1 publication info, shared by checkpoint and block types. */
class L1PublishedData {
  blockNumber: bigint;
  timestamp: bigint;
  blockHash: string;
}

Block Parameter

/** Currently: block number, block hash, or 'latest'. */
type BlockParameter = BlockNumber | BlockHash | 'latest';

Chain Tips

type L2Tips = {
  proposed: L2BlockId;              // { number: BlockNumber, hash: string }
  checkpointed: L2TipId;           // { block: L2BlockId, checkpoint: CheckpointId }
  proposedCheckpoint: L2TipId;
  proven: L2TipId;
  finalized: L2TipId;
};

Current Methods (block/checkpoint related)

Method	Signature
getBlock	(param: BlockParameter) => L2Block?
getBlockByHash	(hash: BlockHash) => L2Block?
getBlockByArchive	(archive: Fr) => L2Block?
getBlocks	(from: BlockNumber, limit: number) => L2Block[]
getBlockHeader	(param?: BlockParameter) => BlockHeader?
getBlockHeaderByArchive	(archive: Fr) => BlockHeader?
getBlockNumber	() => BlockNumber
getProvenBlockNumber	() => BlockNumber
getCheckpointedBlockNumber	() => BlockNumber
getCheckpointNumber	() => CheckpointNumber
getCheckpoints	(from: CheckpointNumber, limit: number) => PublishedCheckpoint[]
getCheckpointedBlocks	(from: BlockNumber, limit: number) => CheckpointedL2Block[]
getCheckpointsDataForEpoch	(epoch: EpochNumber) => CheckpointData[]
getL2Tips	() => L2Tips
getBlockHashMembershipWitness	(ref: BlockParameter, hash: BlockHash) => MembershipWitness?
getWorldStateSyncStatus	() => WorldStateSyncStatus
getL2ToL1Messages	(epoch: EpochNumber) => Fr[][][][]
getL1ToL2MessageCheckpoint	(msg: Fr) => CheckpointNumber?

---

Proposal

1. Unified Block Response Type

Consolidate BlockData, L2Block, and CheckpointedL2Block into a single response type. The base is always the block metadata (what BlockData is today). The transaction body and L1 publish info are optionally included based on request parameters.

type BlockResponse = {
  header: BlockHeader;
  archive: Fr;
  hash: Fr;
  checkpointNumber: CheckpointNumber;
  indexWithinCheckpoint: IndexWithinCheckpoint;

  /** Included when `includeTxs: true`. Undefined (not present) otherwise. */
  body?: Body;

  /** Included when `includeL1PublishInfo: true`. */
  l1?: L1PublishInfo;
};

/** L1 publish info, present only when requested via includeL1PublishInfo. */
type L1PublishInfo =
  | { published: false }
  | { published: true; blockNumber: bigint; timestamp: bigint; blockHash: string };

When includeL1PublishInfo is requested but the block has not yet been published to L1, l1 is { published: false }. When published, it carries the full L1 data.

2. Unified Block Parameter

Extend BlockParameter to support more lookup strategies and chain tip names.

type ChainTip = 'proposed' | 'checkpointed' | 'proven' | 'finalized';

type BlockParameter =
  | BlockNumber                     // by number: getBlock(10)
  | BlockHash                       // by hash: getBlock(blockHash)
  | ChainTip                        // by tip name: getBlock('proven')
  | 'latest'                        // alias for 'proposed' (backwards compat)
  | { number: BlockNumber }         // explicit: getBlock({ number: 10 })
  | { hash: BlockHash }             // explicit: getBlock({ hash: '0x...' })
  | { archive: Fr }                 // by archive root: getBlock({ archive: fr })
  ;

'latest' remains as an alias for 'proposed' for backwards compatibility.

3. Block Include Options

type BlockIncludeOptions = {
  /** Include the block body (transaction data). Default: false. */
  includeTxs?: boolean;
  /** Include L1 publish info. Default: false. */
  includeL1PublishInfo?: boolean;
};

4. Consolidated getBlock

Replace all getBlock* single-block methods with one:

getBlock(param: BlockParameter, options?: BlockIncludeOptions): Promise<BlockResponse | undefined>;

Examples:

// By number, metadata only (lightweight)
await node.getBlock(10);

// By hash, with tx data
await node.getBlock(blockHash, { includeTxs: true });

// Latest proven, with L1 info
await node.getBlock('proven', { includeL1PublishInfo: true });

// By archive root
await node.getBlock({ archive: archiveFr }, { includeTxs: true });

// Backwards compat: 'latest' still works
await node.getBlock('latest');

5. Consolidated getBlockNumber

Replace getBlockNumber, getProvenBlockNumber, and getCheckpointedBlockNumber:

getBlockNumber(tip?: ChainTip): Promise<BlockNumber>;

• getBlockNumber() or getBlockNumber('proposed') = current getBlockNumber()
• getBlockNumber('proven') = current getProvenBlockNumber()
• getBlockNumber('checkpointed') = current getCheckpointedBlockNumber()

6. Rename getL2Tips to getChainTips

getChainTips(): Promise<ChainTips>;

Where ChainTips is the same as L2Tips but renamed. The type L2Tips would be kept as a deprecated alias during transition.

7. getBlocks (batch)

Keep getBlocks but update to return BlockResponse[] and accept include options:

getBlocks(from: BlockNumber, limit: number, options?: BlockIncludeOptions): Promise<BlockResponse[]>;

8. Unified Checkpoint Response Type

Consolidate PublishedCheckpoint, CheckpointData, and Checkpoint into a single response type. The base is checkpoint metadata (similar to what CheckpointData is today, minus attestations). Full blocks and L1 publish info are optionally included based on request parameters.

type CheckpointResponse = {
  number: CheckpointNumber;
  header: CheckpointHeader;
  archive: Fr;
  checkpointOutHash: Fr;
  startBlock: BlockNumber;
  blockCount: number;
  feeAssetPriceModifier: bigint;

  /** Included when `includeBlocks: true`. */
  blocks?: L2Block[];

  /** Included when `includeL1PublishInfo: true`. */
  l1?: L1PublishInfo;
};

Uses the same L1PublishInfo discriminated union as BlockResponse:

type L1PublishInfo =
  | { published: false }
  | { published: true; blockNumber: bigint; timestamp: bigint; blockHash: string };

9. Checkpoint Include Options

type CheckpointIncludeOptions = {
  /** Include full L2 blocks in the checkpoint. Default: false. */
  includeBlocks?: boolean;
  /** Include L1 publish info. Default: false. */
  includeL1PublishInfo?: boolean;
};

10. Checkpoint Parameter

type CheckpointParameter =
  | CheckpointNumber                // by number: getCheckpoint(5)
  | ChainTip                        // by tip name: getCheckpoint('proven')
  | 'latest'                        // alias for 'proposed'
  | { number: CheckpointNumber }    // explicit: getCheckpoint({ number: 5 })
  | { slot: SlotNumber }            // by slot: getCheckpoint({ slot: 100 })
  ;

11. Consolidated getCheckpoint

Single-checkpoint fetch, mirrors getBlock:

getCheckpoint(param: CheckpointParameter, options?: CheckpointIncludeOptions): Promise<CheckpointResponse | undefined>;

Examples:

// Metadata only
await node.getCheckpoint(5);

// With full blocks
await node.getCheckpoint('proposed', { includeBlocks: true });

// By slot, with L1 info
await node.getCheckpoint({ slot: 100 }, { includeL1PublishInfo: true });

12. Consolidated getCheckpoints (batch)

getCheckpoints(from: CheckpointNumber, limit: number, options?: CheckpointIncludeOptions): Promise<CheckpointResponse[]>;

13. Consolidated getCheckpointNumber

Replace standalone getCheckpointNumber:

getCheckpointNumber(tip?: ChainTip): Promise<CheckpointNumber>;

• getCheckpointNumber() or getCheckpointNumber('proposed') = current getCheckpointNumber()
• getCheckpointNumber('proven') = proven checkpoint number
• getCheckpointNumber('finalized') = finalized checkpoint number

---

Deprecation Plan

Replaced by consolidated getBlock

Method	Replacement
getBlockByHash(hash)	getBlock(hash) or getBlock({ hash })
getBlockByArchive(archive)	getBlock({ archive })
getBlockHeader(param)	getBlock(param) (response always includes header)
getBlockHeaderByArchive(archive)	getBlock({ archive })
getCheckpointedBlocks(from, limit)	getBlocks(from, limit, { includeL1PublishInfo: true }) (with limiting to last checkpointed block number)

Replaced by consolidated getBlockNumber

Method	Replacement
getProvenBlockNumber()	getBlockNumber('proven')
getCheckpointedBlockNumber()	getBlockNumber('checkpointed')

Renamed

Method	Replacement
getL2Tips()	getChainTips()

Not used, candidates for removal

Method	Notes
getBlockByHash	Zero usage in client or e2e tests
getCheckpointsDataForEpoch(epoch)	getCheckpoints(from, limit) with appropriate range for epoch (zero usage today)

Unchanged (kept as-is, unrelated)

Method	Reason
getBlockHashMembershipWitness	Distinct concern (archive tree witness)
getWorldStateSyncStatus	Distinct concern (sync status)
getL2ToL1Messages	Distinct concern (cross-chain)
getL1ToL2MessageCheckpoint	Distinct concern (cross-chain)

---

Open Questions

• Naming: BlockResponse vs BlockView vs BlockInfo vs something else?
  • Go with BlockResponse
• Naming: includeTxs vs includeBody vs includeTransactions?
  • includeTransactions
• Naming: includeL1PublishInfo vs includeL1Data vs includeCheckpointInfo?
  • includeL1PublishInfo
• Attestations: CheckpointedL2Block currently includes attestations. Should BlockResponse include those when includeL1PublishInfo is set, or are attestations a separate concern?
  • Make attestations a separate concern
• Attestations: The current PublishedCheckpoint and CheckpointedL2Block include attestations. These are dropped from CheckpointResponse. Should they be available via a separate option or method?
  • Make them available via a separate option

[PhilWindle]

A big improvement. Can you make some issues for the follow up work?