grandpa_roundState - JSON-RPC Method

Description

Returns the current state of the GRANDPA finality gadget including round number, voter set, and voting progress. This JSON-RPC method is essential for monitoring the finality process and debugging consensus issues.

Parameters

This method does not require any parameters.

Returns

Field	Type	Description
round	number	Current round number
totalWeight	number	Total weight of all voters
thresholdWeight	number	Weight threshold for supermajority
prevotes	object	Current prevotes in the round
precommits	object	Current precommits in the round
bestRoundState	object	Best round state information

Request Example

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

Response Example

{
  "jsonrpc": "2.0",
  "result": {
    "round": 12345,
    "totalWeight": 1000,
    "thresholdWeight": 667,
    "prevotes": {
      "currentWeight": 750,
      "missing": ["0x1234...", "0x5678..."]
    },
    "precommits": {
      "currentWeight": 700,
      "missing": ["0x1234..."]
    },
    "bestRoundState": {
      "round": 12345,
      "totalWeight": 1000,
      "thresholdWeight": 667,
      "prevotes": {
        "currentWeight": 750
      },
      "precommits": {
        "currentWeight": 700
      }
    }
  },
  "id": 1
}

Code Examples

JavaScript

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

// Monitor GRANDPA progress
const roundState = await getGrandpaRoundState();
console.log(`GRANDPA Round: ${roundState.round}`);
console.log(`Prevote progress: ${roundState.prevotes.currentWeight}/${roundState.totalWeight}`);
console.log(`Precommit progress: ${roundState.precommits.currentWeight}/${roundState.totalWeight}`);

// Check if supermajority reached
const prevoteComplete = roundState.prevotes.currentWeight >= roundState.thresholdWeight;
const precommitComplete = roundState.precommits.currentWeight >= roundState.thresholdWeight;
console.log(`Prevote complete: ${prevoteComplete}`);
console.log(`Precommit complete: ${precommitComplete}`);

Python

import requests
import json

def get_grandpa_round_state():
    url = "https://api-polkadot.n.dwellir.com"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {
        "jsonrpc": "2.0",
        "method": "grandpa_roundState",
        "params": [],
        "id": 1
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()["result"]

# Analyze round state
round_state = get_grandpa_round_state()
print(f"Round: {round_state['round']}")
print(f"Total weight: {round_state['totalWeight']}")
print(f"Threshold: {round_state['thresholdWeight']}")

# Calculate progress percentages
prevote_pct = (round_state['prevotes']['currentWeight'] / round_state['totalWeight']) * 100
precommit_pct = (round_state['precommits']['currentWeight'] / round_state['totalWeight']) * 100

print(f"Prevote progress: {prevote_pct:.1f}%")
print(f"Precommit progress: {precommit_pct:.1f}%")

# Check missing voters
if round_state['prevotes'].get('missing'):
    print(f"Missing prevotes from: {len(round_state['prevotes']['missing'])} validators")

GRANDPA Finality Process

Voting Stages

1. Prevote: Validators vote for blocks they consider final
2. Precommit: After prevote supermajority, validators commit
3. Finalization: Block becomes final after precommit supermajority

Weight Calculation

• Each validator has voting weight
• Supermajority requires >2/3 of total weight
• Missing votes delay finalization

Use Cases

1. Finality Monitoring: Track finalization progress
2. Validator Analysis: Identify missing or slow validators
3. Network Health: Detect consensus issues
4. Performance Metrics: Measure finalization speed
5. Debugging: Investigate finalization stalls

Related Methods

• chain_getFinalizedHead - Get finalized block
• beefy_getFinalizedHead - BEEFY finalized head
• system_health - Overall node health