Skip to main content

chain_subscribeFinalizedHeads - JSON-RPC Method

Description#

Establishes a WebSocket subscription that delivers notifications for finalized block headers on the Acala network. Unlike chain_subscribeNewHeads, this method only emits headers that have achieved finality through the network's consensus mechanism, meaning they are irreversible and permanently part of the canonical chain. Finalization typically occurs several blocks behind the latest imported block, providing absolute certainty that transactions in these blocks cannot be reverted through chain reorganization. This is the preferred method for applications requiring guaranteed transaction permanence, such as payment processing, asset transfers, or any operation where irreversibility is critical.

Examples#

const ws = new WebSocket('wss://api-acala.n.dwellir.com/YOUR_API_KEY');
ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'chain_subscribeFinalizedHeads',
    params: []
  }));
};
ws.onmessage = (e) => console.log(JSON.parse(e.data));

Parameters#

This method requires no parameters. The subscription activates immediately and continues indefinitely until unsubscribed.

Response Format#

Each finalized header notification contains complete block header information including block number, parent hash, state root, extrinsics root, and consensus digest. The initial response provides a subscription ID for managing the subscription lifecycle. Headers are delivered in sequential order as finality is achieved.

Finality Guarantees#

Acala uses GRANDPA finality, which provides deterministic finalization with strong security guarantees. Once a block is finalized, it becomes an immutable part of the chain history. The finalization process typically lags behind block production by several blocks, creating a small delay between block import and finalization. This delay represents the time required for validators to reach consensus on finality.

Use Cases#

  • Payment Confirmations: Confirm customer payments with absolute certainty before delivering goods or services
  • Cross-chain Bridges: Wait for finality before processing bridge transfers to prevent double-spending
  • Exchange Deposits: Credit user accounts only after deposit transactions reach finality
  • Smart Contract Events: Process critical contract events that require irreversibility guarantees
  • Audit Trails: Record finalized state for compliance and auditing purposes
  • Settlement Systems: Execute final settlement operations based on confirmed, immutable transactions

Best Practices#

Always use this method rather than chain_subscribeNewHeads for operations involving financial transfers or irreversible actions. The additional wait for finality is a small price for the security guarantee it provides. Implement WebSocket reconnection logic to maintain subscription continuity during network disruptions. Store the subscription ID for proper cleanup when the subscription is no longer needed. Consider displaying both "imported" and "finalized" status in user interfaces to set appropriate expectations about transaction permanence.

Performance Considerations#

Finalized headers arrive less frequently than imported headers due to the consensus finalization process. Expect finalization to lag several blocks behind the chain head. In normal network conditions, finalization occurs regularly, but during periods of high validator disagreement or network partitions, finalization may slow or pause temporarily. Monitor finalization progress to detect potential network issues.