getBlockCommitment

Overview

The getBlockCommitment JSON-RPC method is a highly granular query used to ascertain the raw commitment status of a specific block within the Solana cluster. Unlike higher-level commitment settings like processed, confirmed, or finalized which provide simplified abstractions of transaction finality, getBlockCommitment exposes the underlying supermajority vote distribution for a given slot. It provides a detailed, low-level insight into the cluster's consensus progress for a particular block, indicating how much of the active stake has attested to its validity.

This method is crucial for advanced applications, network analysis tools, or validators that require a deep understanding of the cluster's BFT (Byzantine Fault Tolerance) state for a specific block. It's particularly useful when debugging consensus issues, monitoring validator participation, or building custom finality metrics beyond the standard confirmed and finalized levels. By examining the commitment array returned, developers can observe the precise progression of stake-weighted votes for a block, discerning at what point various supermajority thresholds were achieved.

When a client needs to verify the robustness of a block's finality beyond a simple "yes/no" answer, or to analyze the historical voting patterns for a particular slot, getBlockCommitment becomes invaluable. It helps in understanding not just if a block is committed, but how committed it is by the cluster's staked validators, offering a quantitative measure of consensus agreement for that slot.

Parameters

Expected Response

The expected response is a JSON object with a result field containing an object representing the block commitment data, or an error field if the request fails.

1{
2  "jsonrpc": "2.0",
3  "result": {
4    "commitment": [
5      // array of uint64 integers
6    ],
7    "totalStake": "uint64"
8  },
9  "id": 1
10}

Or, in case of an error (e.g., invalid slot number, node unable to fulfill request):

1{
2  "jsonrpc": "2.0",
3  "error": {
4    "code": -32602,
5    "message": "Invalid params",
6    "data": {
7      "err": "Invalid block argument"
8    }
9  },
10  "id": 1
11}

Key Properties of the result Object:

• commitment: Array<number | null>

  • This is an array of unsigned 64-bit integers (uint64). The index i into this array corresponds to the (i * 4)% supermajority of stake that has voted for this specific block. The value at that index is the number of slots since genesis when that (i * 4)% supermajority threshold was reached for the block.
  • For example:
    • commitment[0] would represent the number of slots when the first 0-3% of stake voted for the block.
    • commitment[24] would represent the number of slots when 96-99% of stake voted for the block. (Note: 24 * 4 = 96%)
    • A null value at a particular index indicates that the corresponding supermajority threshold has not yet been achieved for the requested block, or the information is not available.
  • This array provides a very fine-grained view of the consensus progression. It's important to understand that achieving finalized status on Solana typically implies that a supermajority of 2/3 (or ~66.6%) of the active stake has voted for the block, which would correspond to an index like commitment[16] or commitment[17].
  • If the requested block is too old and the RPC node has pruned its historical commitment data, or if the block has not yet been processed to a sufficient degree, the commitment array might be null or contain null entries.

• totalStake: string (representing a uint64)

  • This field represents the total amount of active stake (in Lamports) currently participating in the cluster's consensus. This value is given as a string to accurately represent potentially very large uint64 numbers. It provides context for the percentages represented in the commitment array, showing the total denominator for the stake-weighted votes.

Usage Examples

TypeScript (Fetch)

1const response = await fetch("http://[IP_ADDRESS]:[PORT]", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5  },
6  body: JSON.stringify({
7    jsonrpc: "2.0",
8    id: 1,
9    method: "getBlockCommitment",
10    params: [] // Add relevant parameters here
11  }),
12});
13
14const data = await response.json();
15console.log(data);

Python (Requests)

1import requests
2import json
3
4url = "http://[IP_ADDRESS]:[PORT]"
5payload = json.dumps({
6  "jsonrpc": "2.0",
7  "id": 1,
8  "method": "getBlockCommitment",
9  "params": [] # Add relevant parameters here
10})
11headers = {
12  'Content-Type': 'application/json'
13}
14
15response = requests.request("POST", url, headers=headers, data=payload)
16print(response.text)

Rust (reqwest)

1use reqwest::Client;
2use serde_json::json;
3
4#[tokio::main]
5async fn main() -> Result<(), Box<dyn std::error::Error>> {
6    let client = Client::new();
7    let res = client.post("http://[IP_ADDRESS]:[PORT]")
8        .json(&json!({
9            "jsonrpc": "2.0",
10            "id": 1,
11            "method": "getBlockCommitment",
12            "params": [] // Add relevant parameters here
13        }))
14        .send()
15        .await?
16        .text()
17        .await?;
18
19    println!("{}", res);
20    Ok(())
21}