chain_subscribeFinalizedHeads | Kusama RPC Docs

Subscribe to finalized block headers on Kusama. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on Polkadot's canary network for real-world testing with live economic conditions.

Subscribe to receive notifications when blocks are finalized on Kusama. Finalized blocks are guaranteed to never be reverted by the GRANDPA finality gadget, making this the safest way to track confirmed state changes.

Why Kusama? Build on Polkadot's canary network for real-world testing with live economic conditions with 7-day governance cycles (vs 1 month on Polkadot), lower bonding requirements, live KSM token economy, and first-to-market feature testing.

When to Use This Method

chain_subscribeFinalizedHeads is critical for experimental dApp developers, parachain teams, and early adopters validating new features:

Exchange Deposits — Only credit funds after finalization for parachain experimentation, early feature deployment, and production-grade testing with real value
Bridge Operations — Wait for finality before executing cross-chain transfers
Critical State Changes — Ensure irreversibility before acting on important transactions
Compliance Workflows — Record-keeping that requires provably irreversible state

Code Examples

Bash

# WebSocket subscription (requires wscat or similar tool)
wscat -c wss://kusama-rpc.n.dwellir.com -x '{
  "jsonrpc": "2.0",
  "method": "chain_subscribeFinalizedHeads",
  "params": [],
  "id": 1
}'

Common Use Cases

1. Exchange Deposit Watcher

Watch for finalized transfers and credit user accounts on Kusama:

JavaScript

async function watchDeposits(api, depositAddresses) {
  const unsub = await api.rpc.chain.subscribeFinalizedHeads(async (header) => {
    const blockHash = header.hash;
    const block = await api.rpc.chain.getBlock(blockHash);
    const apiAt = await api.at(blockHash);
    const events = await apiAt.query.system.events();

    // Check for transfer events in the finalized block
    events.forEach((record) => {
      const { event } = record;
      if (event.section === 'balances' && event.method === 'Transfer') {
        const [from, to, amount] = event.data;
        if (depositAddresses.includes(to.toString())) {
          console.log(`Finalized deposit: ${amount} from ${from} to ${to}`);
          // Credit user account — this block will never be reverted
        }
      }
    });
  });

  return unsub;
}

2. Finality Lag Tracker

Monitor the gap between best and finalized blocks:

JavaScript

async function trackFinalityLag(api) {
  let bestNumber = 0;

  api.rpc.chain.subscribeNewHeads((header) => {
    bestNumber = header.number.toNumber();
  });

  api.rpc.chain.subscribeFinalizedHeads((header) => {
    const finalizedNumber = header.number.toNumber();
    const lag = bestNumber - finalizedNumber;

    console.log(`Best: #${bestNumber} | Finalized: #${finalizedNumber} | Lag: ${lag} blocks`);

    if (lag > 10) {
      console.warn('WARNING: High finality lag detected — GRANDPA may be stalling');
    }
  });
}

3. Cross-Chain Bridge Relay

Relay finalized headers to a bridge contract:

JavaScript

async function relayFinalizedHeaders(api, bridgeContract) {
  const unsub = await api.rpc.chain.subscribeFinalizedHeads(async (header) => {
    const headerData = {
      number: header.number.toNumber(),
      stateRoot: header.stateRoot.toHex(),
      extrinsicsRoot: header.extrinsicsRoot.toHex(),
      parentHash: header.parentHash.toHex()
    };

    console.log(`Relaying finalized header #${headerData.number}`);
    await bridgeContract.submitHeader(headerData);
  });

  return unsub;
}

Finality Lag

Finalized blocks typically lag behind the best block by a few blocks due to GRANDPA consensus requirements. This lag is normal and ensures Byzantine fault tolerance. The typical lag is 2-3 blocks under healthy network conditions.

Error Handling

Error Code	Description	Solution
-32603	Internal error	Node may be syncing or GRANDPA not running — retry connection
-32601	Method not found	Verify the node supports WebSocket subscriptions
-32005	Rate limit exceeded	Reduce subscription count per connection
Connection closed	WebSocket disconnected	Implement automatic reconnection with backoff

chain_subscribeNewHeads — Subscribe to all new blocks (not just finalized)
chain_getFinalizedHead — Get current finalized block hash (one-shot)
grandpa_roundState — Monitor GRANDPA consensus progress
chain_getBlock — Get full block data for a finalized hash

chain_subscribeFinalizedHeads - Kusama RPC Method

When to Use This Method

Code Examples

Common Use Cases

1. Exchange Deposit Watcher

2. Finality Lag Tracker

3. Cross-Chain Bridge Relay

Finality Lag

Error Handling

On this page