chain_getFinalizedHead - JSON-RPC Method

Description

Returns the hash of the latest finalized block. In Moonbase Alpha, blocks are finalized through the GRANDPA finality gadget, providing deterministic finality. This JSON-RPC method is crucial for applications that need to ensure transactions are irreversible.

Parameters

This method does not require any parameters.

Returns

Field	Type	Description
result	string	Hex-encoded hash of the latest finalized block

Request Example

{
  "jsonrpc": "2.0",
  "method": "chain_getFinalizedHead",
  "params": [],
  "id": 1
}

Response Example

{
  "jsonrpc": "2.0",
  "result": "0xa39d25f8cf7ad27e6a739dc15d4d013bdc48b6e2819bb74c72822a930adb5649",
  "id": 1
}

Code Examples

cURL

curl https://api-moonbase-alpha.n.dwellir.com/YOUR_API_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "chain_getFinalizedHead",
    "params": [],
    "id": 1
  }'

Python

import requests
import json

def get_finalized_head():
    url = "https://api-moonbase-alpha.n.dwellir.com/YOUR_API_KEY"
    headers = {
        "Content-Type": "application/json"
    }
    
    payload = {
        "jsonrpc": "2.0",
        "method": "chain_getFinalizedHead",
        "params": [],
        "id": 1
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    data = response.json()
    
    if "error" in data:
        raise Exception(f"RPC Error: {data['error']}")
    
    return data["result"]

# Monitor finalization
finalized_hash = get_finalized_head()
print(f"Finalized block hash: {finalized_hash}")

JavaScript

const getFinalizedHead = async () => {
  const response = await fetch('https://api-moonbase-alpha.n.dwellir.com/YOUR_API_KEY', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'chain_getFinalizedHead',
      params: [],
      id: 1
    })
  });
  
  const data = await response.json();
  return data.result;
};

// Get finalized block details
const finalizedHash = await getFinalizedHead();
console.log('Latest finalized block:', finalizedHash);

// Get full block data
const blockData = await getBlock(finalizedHash);
console.log('Finalized block number:', parseInt(blockData.block.header.number, 16));

TypeScript

import { ApiPromise, WsProvider } from '@moonbase-alpha/api';

async function trackFinalization() {
  const provider = new WsProvider('wss://api-moonbase-alpha.n.dwellir.com/YOUR_API_KEY');
  const api = await ApiPromise.create({ provider });
  
  // Get current finalized head
  const finalizedHash = await api.rpc.chain.getFinalizedHead();
  console.log('Finalized hash:', finalizedHash.toHex());
  
  // Get finalized block details
  const finalizedBlock = await api.rpc.chain.getBlock(finalizedHash);
  const blockNumber = finalizedBlock.block.header.number.toNumber();
  console.log('Finalized block number:', blockNumber);
  
  // Calculate finalization lag
  const latestHeader = await api.rpc.chain.getHeader();
  const latestNumber = latestHeader.number.toNumber();
  const lag = latestNumber - blockNumber;
  console.log(`Finalization lag: ${lag} blocks`);
  
  await api.disconnect();
}

Finality in Moonbase Alpha

GRANDPA Finality

• Deterministic: Once finalized, blocks cannot be reverted
• Fast: Typically finalizes within 12-60 seconds
• Byzantine Fault Tolerant: Secure with up to 1/3 malicious validators

Finalization Process

1. Block is produced by BABE
2. Block propagates through network
3. GRANDPA validators vote on chains
4. Super-majority agreement finalizes block

Use Cases

1. Exchange Deposits: Wait for finalization before crediting
2. Smart Contract Events: Ensure events are permanent
3. Cross-chain Bridges: Transfer assets after finalization
4. Block Explorers: Display finalized vs unfinalized blocks
5. Monitoring Tools: Track finalization performance

Finalization Monitoring

// Monitor finalization progress
async function monitorFinalization() {
  let lastFinalized = await getFinalizedHead();
  
  setInterval(async () => {
    const currentFinalized = await getFinalizedHead();
    
    if (currentFinalized !== lastFinalized) {
      console.log('New finalized block:', currentFinalized);
      
      // Check how many blocks were finalized
      const oldBlock = await getBlock(lastFinalized);
      const newBlock = await getBlock(currentFinalized);
      
      const oldNumber = parseInt(oldBlock.block.header.number, 16);
      const newNumber = parseInt(newBlock.block.header.number, 16);
      
      console.log(`Finalized ${newNumber - oldNumber} blocks`);
      lastFinalized = currentFinalized;
    }
  }, 6000); // Check every 6 seconds
}

Notes

• Finalized blocks are immutable and cannot be reverted
• Finalization typically lags 2-10 blocks behind the latest block
• During network issues, finalization may stall temporarily
• Always use finalized blocks for critical operations
• Finalization provides stronger guarantees than probabilistic finality

Related Methods

• chain_getBlock - Get full block data
• chain_getBlockHash - Get block hash by number
• state_getMetadata - Get runtime metadata
• system_health - Check node status