beefy_getFinalizedHead - Moonbeam RPC Method

Returns the block hash of the latest BEEFY-finalized block on Moonbeam. BEEFY (Bridge Efficiency Enabling Finality Yielder) provides additional finality proofs that are optimized for light clients and cross-chain bridges, using compact aggregated signatures instead of full GRANDPA justifications.

Why Moonbeam? Build on the cross-chain connected EVM platform on Polkadot with $65M+ TVL and 100+ projects with full EVM compatibility on Polkadot, native XCM cross-chain messaging, 10K+ TPS, 24% staking APR, and $0.015 transaction costs.

When to Use This Method

beefy_getFinalizedHead is important for cross-chain dApp developers, Polkadot builders, and teams requiring multi-chain interoperability:

• Cross-Chain Bridges — Verify finality proofs efficiently for bridge operations on cross-chain DeFi, multi-chain dApps, and Ethereum-to-Polkadot bridging via XCM, Axelar, LayerZero, and Wormhole
• Light Clients — Verify finality without downloading full GRANDPA justifications
• Trustless Bridges — Generate compact finality proofs that can be verified on external chains
• Bridge Monitoring — Track BEEFY finality progress relative to GRANDPA finality

Code Examples

Common Use Cases

1. Bridge Finality Verification

Verify BEEFY finality before relaying messages on a cross-chain bridge:

async function verifyBridgeFinality(api, targetBlockHash) {
  const beefyHead = await api.rpc.beefy.getFinalizedHead();
  const beefyBlock = await api.rpc.chain.getBlock(beefyHead);
  const beefyNumber = beefyBlock.block.header.number.toNumber();

  const targetBlock = await api.rpc.chain.getBlock(targetBlockHash);
  const targetNumber = targetBlock.block.header.number.toNumber();

  if (beefyNumber >= targetNumber) {
    console.log(`Block #${targetNumber} has BEEFY finality — safe to relay`);
    return true;
  } else {
    console.log(`Waiting: BEEFY at #${beefyNumber}, target at #${targetNumber}`);
    return false;
  }
}

2. BEEFY vs GRANDPA Finality Monitor

Track the gap between the two finality gadgets:

async function monitorFinalityGadgets(api) {
  setInterval(async () => {
    try {
      const [beefyHead, grandpaHead] = await Promise.all([
        api.rpc.beefy.getFinalizedHead(),
        api.rpc.chain.getFinalizedHead()
      ]);

      const [beefyBlock, grandpaBlock] = await Promise.all([
        api.rpc.chain.getBlock(beefyHead),
        api.rpc.chain.getBlock(grandpaHead)
      ]);

      const beefyNum = beefyBlock.block.header.number.toNumber();
      const grandpaNum = grandpaBlock.block.header.number.toNumber();
      const lag = grandpaNum - beefyNum;

      console.log(`GRANDPA: #${grandpaNum} | BEEFY: #${beefyNum} | Lag: ${lag} blocks`);
    } catch (error) {
      console.error('Monitor error:', error.message);
    }
  }, 12000);
}

BEEFY vs GRANDPA Finality

Availability

BEEFY is enabled on Polkadot and Kusama relay chains and some parachains. If BEEFY is not active on the chain you are querying, this method will return an error. Check chain documentation or try calling the method to confirm availability.

Error Handling

Related Methods

• chain_getFinalizedHead — Get GRANDPA finalized head
• grandpa_roundState — Monitor GRANDPA consensus state
• chain_subscribeFinalizedHeads — Subscribe to GRANDPA finalized blocks