chain_subscribeFinalizedHeads

Description

Streams headers for blocks finalized by the Polkadot relay chain. Useful when you need deterministic confirmation before acting on state changes, such as releasing cross-chain assets or updating accounting ledgers.

Parameters

No parameters are required.

Returns

Each notification includes the same header structure as chain_subscribeNewHeads, guaranteed to be finalized.

Subscription Example

{
  "jsonrpc": "2.0",
  "method": "chain_subscribeFinalizedHeads",
  "params": [],
  "id": 1
}

Sample Notification

{
  "jsonrpc": "2.0",
  "method": "chain_subscribeFinalizedHeads",
  "params": {
    "result": {
      "parentHash": "0x9653b6043e7d8e3a1edb0726503797cff98a2dd12c96575e30766090085d909c",
      "number": "0x9055ea",
      "stateRoot": "0xf5f6d3f1ac60d23d6ae5b65cdbcd6b373176b2b00aa748422453c3cb1f8490e6",
      "extrinsicsRoot": "0x2a1a0fbe1cf1e2ef25a2a5dab687cb0b8fb4799cdaf9aa1319200b0a5bee13c8",
      "digest": {
        "logs": [
          "0x0661757261208a2c7a1100000000",
          "0x0452505352903006d1651014effe612aeb9e2bed207fca849e69a1d4594bdab580afc68677458a62ad06"
        ]
      }
    },
    "subscription": 1
  }
}

JavaScript Usage

const unsub = await api.rpc.chain.subscribeFinalizedHeads((header) => {
  console.log(`Finalized block #${header.number.toString()} hash=${header.hash.toHex()}`);
});

Notes

• Finalized heads may lag best heads by a few blocks (~6–12 seconds). Design systems to tolerate this gap.
• Combine with chain_getBlock to fetch the full extrinsics for finalized blocks.