chain_getFinalizedHead - Acala RPC Method

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

Why Acala? Build on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT) with $250M aUSD ecosystem fund, 150%+ LDOT TVL growth, micro gas fees payable in any token, and Coinbase Cloud partnership.

When to Use This Method

chain_getFinalizedHead is critical for DeFi developers, stablecoin builders, and teams requiring cross-chain liquidity:

• Exchange Deposits — Only credit user funds after the block has been finalized on Acala
• Transaction Confirmation — Verify transactions have achieved irreversible finality for decentralized stablecoin (aUSD), liquid DOT staking (LDOT), and cross-chain AMM DEX
• 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 Acala:

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