Cosmos Node Status Report

🔍 Asynchronously test RPC, REST, and gRPC endpoints for any Cosmos SDK blockchain and generate comprehensive status reports.

This tool fetches chain data directly from GitHub's chain-registry and tests node availability and sync status. All nodes are tested concurrently to eliminate timing bias and ensure fair comparison.

Features

✨ No Setup Required - Fetches chain data directly from GitHub
📊 Multiple Endpoints - Tests RPC, REST/LCD, and gRPC endpoints
🎯 Sync Status - Identifies which nodes are fully synced vs. behind
📝 Detailed Reports - Generates markdown reports with executive summaries
⚡ Fast - Tests 80+ endpoints in ~20 seconds
🔄 Concurrent Testing - All nodes tested simultaneously for accurate results
📡 Direct Source - Uses official cosmos/chain-registry data

Installation

# Clone the repository
git clone https://github.com/jasbanza/cosmos-node-status-report.git
cd cosmos-node-status-report

# Install dependencies
pip install -r requirements.txt

Usage

Basic Usage (Fetches from GitHub)

# Check any chain by name
python check_nodes.py osmosis
python check_nodes.py cosmoshub
python check_nodes.py juno

With Custom Output

python check_nodes.py osmosis -o my_custom_report.md

Using Local Files

# If you have chain-registry cloned locally
python check_nodes.py path/to/chain.json
python check_nodes.py ../chain-registry/osmosis/chain.json

Using Wrapper Scripts

Windows (PowerShell):

.\check_chain.ps1 osmosis
.\check_chain.ps1 cosmoshub

Linux/Mac (Bash):

./check_chain.sh osmosis
./check_chain.sh cosmoshub

Report Output

The tool generates a comprehensive markdown report with:

Executive Summary

• Overview table with success rates for all endpoint types
• Key findings and health metrics
• Sync status percentages

Detailed Node Lists

• RPC nodes with block heights and sync status
• REST/LCD nodes with availability
• gRPC nodes with connectivity status

Status Indicators

• 🟢 Working and synced (within 5 blocks)
• 🟠 Working but behind (>5 blocks behind)
• 🟡 Reachable (gRPC - port open but can't verify height)
• 🔴 Offline/not responding
• ✅/❌ Listed in cosmos.directory

Example Report

# Osmosis Node Status Report

**Generated:** 2025-10-23 16:20:57 UTC
**Latest Block Height:** 46,838,411
**Test Duration:** 20.42 seconds

## Executive Summary

| Endpoint Type | Total | Working | Synced | Success Rate |
|---------------|-------|---------|--------|--------------|
| **RPC**       | 35    | 16      | 14     | 45.7%        |
| **REST**      | 30    | 15      | 12     | 50.0%        |
| **gRPC**      | 19    | 1       | 1      | 47.4%        |
| **TOTAL**     | 84    | 32      | 27     | 47.6%        |

How It Works

Testing Methodology

1. Concurrent Requests - All nodes are queried simultaneously using async HTTP
2. No Timing Bias - Eliminates the issue of sequential testing where later nodes appear behind
3. Multiple Verification Methods:
   • RPC: Direct /status endpoint query
   • REST: Cosmos SDK REST API (/cosmos/base/tendermint/v1beta1/blocks/latest)
   • gRPC: Attempts gRPC-gateway, then TCP connectivity check

Sync Status Determination

• Identifies the highest block height among all working nodes
• Nodes within 5 blocks are marked as 🟢 fully synced
• Nodes >5 blocks behind are marked as 🟠 behind
• Offline nodes are marked as 🔴

Requirements

• Python 3.8+
• aiohttp

How It Works

The tool automatically fetches chain data from the Cosmos Chain Registry on GitHub. No need to clone the repository!

Chain JSON Format

The tool expects a chain.json file in the chain-registry format:

{
  "chain_name": "osmosis",
  "pretty_name": "Osmosis",
  "apis": {
    "rpc": [
      {
        "address": "https://rpc.osmosis.zone/",
        "provider": "Osmosis Foundation"
      }
    ],
    "rest": [...],
    "grpc": [...]
  }
}

Use Cases

• 🔍 Monitor node health across the ecosystem
• 🛠️ Validate new node deployments
• 📊 Report on infrastructure status
• ✅ Verify cosmos.directory listings
• 🔧 Identify outdated or offline nodes

Performance

• Sequential Testing: ~42+ seconds for 84 nodes
• Async Testing: ~20 seconds for 84 nodes
• Speed Improvement: ~50% faster ⚡

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

See LICENSE file for details.

Acknowledgments

• Cosmos Chain Registry - Source of chain data
• All the node operators maintaining Cosmos infrastructure

---

Made with ❤️ for the Cosmos ecosystem