chainHead_v1_follow - Bittensor RPC Method
Start following the chain head to receive new blocks and finality notifications on Bittensor using the new JSON-RPC v2 spec.
Starts a follow subscription that tracks the chain head in real time over a WebSocket connection. The subscription emits events as new blocks are produced, finalized, or pruned. Blocks reported by the subscription are "pinned" and can be queried with chainHead_v1_header, chainHead_v1_body, chainHead_v1_call, and chainHead_v1_storage. This is the entry point for the new JSON-RPC v2 chain head API.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
withRuntime | boolean | Yes | If true, the subscription includes runtime information (spec version, APIs) in newBlock events. Set to true if you need to detect runtime upgrades. |
Response
Returns a subscription ID and begins streaming events:
| Event | Description |
|---|---|
initialized | Emitted once with finalizedBlockHashes and, when requested, runtime info. |
newBlock | A new block has been imported. Contains the block hash, parent hash, and optional runtime info. |
bestBlockChanged | The best (most recent non-finalized) block has changed. |
finalized | One or more blocks have been finalized. Contains arrays of finalized and pruned block hashes. |
stop | The subscription has been terminated by the server (e.g. too many pinned blocks). |
Code Examples
Use Cases
- Real-time block processing -- Build indexers or explorers that react to new Bittensor blocks as they arrive, without polling.
- Finality tracking -- Know exactly when blocks are finalized by GRANDPA, enabling safe database commits and user confirmations.
- Runtime upgrade detection -- With
withRuntime: true, detect spec version changes immediately to update your type registry and decoders. - Fork awareness -- The
finalizedevent reports pruned blocks, allowing your application to handle chain reorganizations correctly.
Notes
- This method is the foundation of the new JSON-RPC v2 chain head API. All other
chainHead_v1_*methods require an active follow subscription. - The server limits the number of pinned (non-finalized) blocks. If the limit is reached, the subscription is stopped with a
stopevent. Unpin blocks by callingchainHead_v1_unpinwhen you are done with them. - This method is experimental and may not be enabled on public shared RPC endpoints.
- Use
chainHead_v1_unfollowto cleanly stop the subscription.
Related Methods
chainHead_v1_unfollow-- Stop the follow subscriptionchainHead_v1_header-- Get a header for a pinned blockchainHead_v1_body-- Get the body of a pinned blockchainHead_v1_call-- Execute a runtime call at a pinned blockchainHead_v1_storage-- Query storage at a pinned blockchain_subscribeNewHeads-- Legacy subscription for new block headers