chain_subscribeFinalizedHeads - JSON-RPC Method

Description

Creates a WebSocket subscription that emits headers for each block finalized by GRANDPA on Enjin Matrix. Use this method when you must react to blocks that are irreversibly finalized—ideal for marketplaces, cross-chain bridges, and analytics that require deterministic data.

Parameters

No parameters are required.

Returns

Notifications mirror the structure returned by chain_getHeader:

Field	Type	Description
result.number	string	Finalized block number (hex-encoded)
result.parentHash	string	Parent block hash
result.stateRoot	string	State root
result.extrinsicsRoot	string	Extrinsics root
result.digest	object	Digest logs

Subscription Example

Request

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

Sample Notification

{
  "jsonrpc": "2.0",
  "method": "chain_subscription",
  "params": {
    "subscription": "0x0000000000000001",
    "result": {
      "parentHash": "0xa0ac758e5eb9d474245a06c00882946b5d98c8e1cb5873c5f8234da327fe6c47",
      "number": "0x677b8e",
      "stateRoot": "0x55105740c8eb8345869fd67d71865eb7db7ccb6c548a172d5232809f2ae77f36",
      "extrinsicsRoot": "0x20ab30742968157af9eb59115f3f4e74bb67094ab771d9bd8236a7b237738308",
      "digest": {
        "logs": [
          "0x0661757261201c957a1100000000"
        ]
      }
    }
  }
}

Code Examples

JavaScript (Polkadot.js)

import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

await api.rpc.chain.subscribeFinalizedHeads((header) => {
  console.log(`Finalized block ${header.number.toString()} with hash ${header.hash.toHex()}`);
});

WebSocket Handshake

ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 1,
  method: 'chain_subscribeFinalizedHeads',
  params: []
}));

Unsubscribe using:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "chain_unsubscribeFinalizedHeads",
  "params": ["0x0000000000000001"]
}

Rust (jsonrpsee)

let mut finalized = client
    .subscribe::<serde_json::Value>(
        "chain_subscribeFinalizedHeads",
        None,
        "chain_unsubscribeFinalizedHeads"
    )
    .await?;

while let Some(header) = finalized.next().await {
    println!("Finalized: {:?}", header?);
}

When to Use

• Settlement-aware services – trigger payouts or NFT state transitions only after finality.
• Bridging – build commitments against finalized blocks to satisfy external light clients.
• Indexers – discard potential forks by indexing only finalized headers and blocks.