Skip to content

feat: add Backend::latest_best_block_ref and OnlineClient::at_current_best_block - #2284

Open
ilchu wants to merge 2 commits into
masterfrom
ic/latest-best-block-ref
Open

ilchu wants to merge 2 commits into
masterfrom
ic/latest-best-block-ref

Conversation

@ilchu

@ilchu ilchu commented Sep 21, 2026

Copy link
Copy Markdown

A one-shot accessor for the current best block, next to the finalized one. Defaults stay on finalized; this is an opt-in for callers that want the newest view and accept that it can be reorged or pruned.

Motivation

#1126 added Backend::latest_best_block_ref; #1161 moved every default to the finalized block because the best block "might actually be pruned in the near future" (#1161 (comment)) and dropped the method as unused, noting a user "can still provide a block hash that they prefer" (#1161 (comment)). There is no direct way to get that hash with a pin from a chainHead-backed client: stream_best_blocks() replays the finalized hashes, buffered NewBlocks and the latest BestBlockChanged with no end marker, each item behind a chainHead_v1_header round trip (the integration tests use a 200 ms timer, consume_initial_blocks, for the same problem on the finalized stream); LegacyRpcMethods::chain_get_block_hash(None) is legacy-only and unpinned.

Use case: a server authorising requests against chain state wants to read at its newest block instead of making a client that already saw finality wait for the server's (paritytech/web3-storage#384).

Changes

  • Backend::latest_best_block_ref; the trait is sealed, all four in-tree backends implement it.
  • chainHead: FollowStreamDriverSubscription::latest_best_block awaits Initialized, drains the already-queued events with now_or_never, returns the last BestBlockChanged else the last finalized hash. A queued Stop restarts the wait (those blocks are unpinned). The BlockRef keeps the block pinned like latest_finalized_block_ref. Right after a (re)subscription, before the node reports a best block, it returns the finalized head.
  • legacy: chain_getBlockHash(None) in retry(), as in Introduce Backend trait to allow different RPC (or other) backends to be implemented #1126. archive: error. combined: chainHead, then legacy.
  • OnlineClient::at_current_best_block(), plus a mention in the introduction docs.

No existing behaviour changes.

Tests

follow_stream_driver.rs: replayed BestBlockChanged wins over the finalized head; empty replay falls back to it; Stop in the replay restarts and returns the new finalized head (fails without the restart). Integration: best_block_is_at_or_ahead_of_finalized_block (full client, all backend/rpc combinations) and best_block_lookup (light client).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant