chain_getFinalizedHead - XX Network RPC Method

Returns the hash of the last finalized block on XX Network. Finalized blocks have been confirmed by the GRANDPA finality gadget and are guaranteed to never be reverted.

Why XX Network? Build on a privacy-focused decentralized messaging and payment platform with quantum-resistant cryptography and metadata privacy through cMix.

When to Use This Method

chain_getFinalizedHead is critical for XX Network developers building privacy-preserving applications:

• Exchange Deposits — Only credit user funds after the block has been finalized on XX Network
• Transaction Confirmation — Verify transactions have achieved irreversible finality for secure messaging, private payments, and quantum-resistant cryptography
• Safe Checkpoints — Use finalized blocks as safe anchors for indexing and state queries
• Bridge Operations — Confirm source-chain finality before executing cross-chain transfers

Code Examples

Common Use Cases

1. Exchange Deposit Confirmation

Wait for finality before crediting deposits on XX Network:

async function waitForFinality(api, txBlockHash) {
  return new Promise((resolve) => {
    const unsub = api.rpc.chain.subscribeFinalizedHeads(async (header) => {
      const finalizedHash = await api.rpc.chain.getBlockHash(header.number);

      // Check if the transaction block has been finalized
      const finalizedNumber = header.number.toNumber();
      const txBlock = await api.rpc.chain.getBlock(txBlockHash);
      const txNumber = txBlock.block.header.number.toNumber();

      if (finalizedNumber >= txNumber) {
        console.log(`Transaction finalized at block #${txNumber}`);
        unsub();
        resolve(txBlockHash);
      }
    });
  });
}

2. Safe State Queries

Query chain state at the finalized block to avoid reading data that could be reverted:

async function getSafeBalance(api, address) {
  const finalizedHash = await api.rpc.chain.getFinalizedHead();
  const apiAt = await api.at(finalizedHash);
  const account = await apiAt.query.system.account(address);

  return {
    free: account.data.free.toString(),
    reserved: account.data.reserved.toString(),
    finalizedAt: finalizedHash.toHex()
  };
}

3. Finality Lag Monitor

Track the gap between best and finalized blocks for health monitoring:

async function monitorFinalityLag(api, threshold = 10) {
  const bestHeader = await api.rpc.chain.getHeader();
  const finalizedHash = await api.rpc.chain.getFinalizedHead();
  const finalizedHeader = await api.rpc.chain.getHeader(finalizedHash);

  const lag = bestHeader.number.toNumber() - finalizedHeader.number.toNumber();
  console.log(`Finality lag: ${lag} blocks`);

  if (lag > threshold) {
    console.warn(`WARNING: Finality lag (${lag}) exceeds threshold (${threshold})`);
  }

  return lag;
}

Error Handling

Related Methods

• chain_getBlock — Get full block data by hash
• chain_getBlockHash — Get block hash by number
• chain_subscribeFinalizedHeads — Subscribe to finalized block headers
• grandpa_roundState — Monitor GRANDPA finality progress