chain_subscribeFinalizedHeads | Asset Hub RPC Docs

Subscribe to finalized block headers on Asset Hub. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on Polkadot's system parachain managing $4.5B+ in DOT tokens, native USDC/USDT, and NFTs.

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

Why Asset Hub? Build on Polkadot's system parachain managing $4.5B+ in DOT tokens, native USDC/USDT, and NFTs with 50-90% lower fees than Relay Chain, fee payment in any supported asset, 1.5M+ accounts migrated, and trustless Ethereum bridge access.

When to Use This Method

chain_subscribeFinalizedHeads is critical for asset issuers, stablecoin integrators, and teams requiring low-cost token management on Polkadot:

Exchange Deposits — Only credit funds after finalization for native stablecoin transfers (USDC, USDT), DOT staking and governance, and cross-chain asset management via XCM
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://asset-hub-polkadot-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 Asset Hub:

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 - Asset Hub 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