chain_getFinalizedHead - Moonriver RPC Method

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

Why Moonriver? Build on the Moonbeam canary network on Kusama for real-world testing of EVM dApps with Moonbeam code ships here first, full EVM compatibility on Kusama, 80% fee burn mechanism, and XCM cross-chain messaging.

When to Use This Method

chain_getFinalizedHead is critical for dApp developers testing on Kusama, early adopters, and teams requiring production-ready experimentation:

• Exchange Deposits — Only credit user funds after the block has been finalized on Moonriver
• Transaction Confirmation — Verify transactions have achieved irreversible finality for production-grade dApp testing, early feature deployment, and Kusama-based EVM applications
• 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 Moonriver:

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