Skip to main content

chain_getFinalizedHead - JSON-RPC Method

Description#

Returns the block hash of the most recently finalized block on the Acala network. Finalized blocks have completed the GRANDPA finality gadget consensus process and are considered irreversible - they will never be reverted or reorganized regardless of network conditions. This makes finalized block data essential for applications requiring absolute certainty, such as payment confirmations, cross-chain bridges, and permanent record keeping. The finalization process typically lags a few blocks behind the latest produced block as validators coordinate on finality votes.

Request Example#

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

Parameters#

This method accepts no parameters.

Response Format#

Returns a 32-byte block hash in hexadecimal format representing the latest finalized block. This hash can be used with other RPC methods to query the finalized block's content, header, or state.

Finalization Explained#

In Substrate-based chains like Acala, blocks go through two stages: production and finalization. Blocks are first produced by block authors (validators selected by BABE consensus), then separately finalized by the GRANDPA finality gadget through a voting process among validators. Finalization provides deterministic finality guarantees, unlike probabilistic finality in proof-of-work chains. Once finalized, a block's transactions are permanently committed to the canonical chain.

Use Cases#

  • Payment Confirmation: Ensure transactions are irreversibly confirmed before releasing goods or services
  • Cross-Chain Bridges: Use finalized state for secure cross-chain message passing and asset transfers
  • Data Integrity: Reference finalized blocks for immutable historical data that won't change due to chain reorganizations
  • Compliance: Meet regulatory requirements for transaction finality in financial applications
  • State Snapshots: Create reliable state snapshots at finalized heights for backups or analysis

Best Practices#

Always use finalized blocks when absolute certainty is required for business-critical operations. For applications displaying real-time data where near-instant updates are preferred over absolute finality, consider using the latest block instead. Poll this endpoint periodically or use the WebSocket subscription variant chain_subscribeFinalizedHeads for continuous finalization updates.

Finalization Lag#

Finalization typically lags the latest block by approximately 2-6 blocks on Acala, depending on network conditions and validator participation in the GRANDPA voting process. This lag is normal and ensures thorough consensus before declaring blocks final.