chain_subscribeFinalizedHeads | Centrifuge RPC

Subscribe to finalized block headers on Centrifuge. Real-time WebSocket notifications for blocks that have achieved GRANDPA finality — essential for exchanges, bridges, and applications requiring irreversibility on the RWA tokenization platform bridging traditional finance with $1B+ Janus Henderson backing.

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

Why Centrifuge? Build on the RWA tokenization platform bridging traditional finance with $1B+ Janus Henderson backing with ERC-7540 RWA standards, multichain via Wormhole, 97% securitization cost savings, and BlockTower $220M fund integration.

When to Use This Method

chain_subscribeFinalizedHeads is critical for institutional RWA developers, asset managers, and teams tokenizing real-world assets:

Exchange Deposits — Only credit funds after finalization for tokenized treasury funds, SME invoice financing, and institutional-grade RWA infrastructure
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-centrifuge.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 Centrifuge:

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