chain_subscribeFinalizedHeads | Bifrost RPC Docs

Subscribe to finalized block headers on Bifrost. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on Polkadot's largest liquid staking appchain with 60% DOT LST market share and $125M+ TVL.

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

Why Bifrost? Build on Polkadot's largest liquid staking appchain with 60% DOT LST market share and $125M+ TVL with first LST governance on OpenGov, 60% DOT market share, Hyperbridge ETH integration, and 500K DOT treasury support.

When to Use This Method

chain_subscribeFinalizedHeads is critical for liquid staking developers, DeFi builders, and teams requiring cross-chain yield solutions:

Exchange Deposits — Only credit funds after finalization for omnichain liquid staking (vDOT, vKSM, vGLMR, vMOVR, vASTR), cross-chain vToken governance, and DOT/ETH liquidity bridging
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://api-bifrost-polkadot.n.dwellir.com/YOUR_API_KEY -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 Bifrost:

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 - Bifrost 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