stellar-rpc-ping

A lightweight, high-performance Node.js/TypeScript CLI tool for monitoring the real-time health and telemetry of public Stellar network nodes (RPC endpoints). It concurrently pings multiple endpoints, measures latency, tracks the current ledger sequence, and detects nodes that are lagging behind the network tip.

Built for Web3 DevOps / core-tools workloads — minimal dependencies, robust exception handling, and zero fragile magic.

---

✨ Features

• Concurrent health checks — queries all RPC endpoints in parallel (Promise.all).
• Latency measurement — round-trip time (RTT) in milliseconds per node.
• Ledger sequence tracking — reads getLatestLedger and flags nodes that lag the tip.
• Sync status classification — synced, lagging, unknown, or unreachable.
• Live CLI dashboard — a colorized table that redraws every --interval seconds.
• Automatic telemetry export — appends results to a JSON or CSV file.
• Dead / timed-out node handling — graceful errors, never a crash.
• Configurable timeout & expected tip — adapt to slow or fast networks.

---

📦 Installation

npm install
npm run build

Requires Node.js >= 20.

---

🚀 Usage

node dist/index.js [urls...] [options]

Monitor the default public Stellar nodes

node dist/index.js

Monitor specific endpoints every 5 seconds

node dist/index.js \
  https://soroban-rpc.mainnet.stellar.org \
  https://mainnet.stellar.rpcpool.com \
  --interval 5

Export telemetry to a file

# JSON (default)
node dist/index.js -o health.json

# CSV
node dist/index.js -f csv -o health.csv

---

⚙️ Options

Flag	Default	Description
urls...	(built-in list)	RPC endpoint URLs to monitor
-i, --interval <seconds>	10	Polling interval in seconds
-o, --output <path>	—	Export results to a file (appends each cycle)
-f, --format <format>	json	Output format: json or csv
-t, --timeout <ms>	5000	Request timeout in milliseconds
--tip-ledger <ledger>	auto	Manually set the expected tip ledger sequence
-h, --help	—	Show help
-V, --version	—	Show version

Stop with Ctrl+C. On exit, any open JSON export array is closed cleanly so the file stays valid.

---

📐 Output

Dashboard

A live, colorized table showing status, node, latency, ledger, network passphrase, HTTP status, and error per node, plus a summary line (synced / lagging / unreachable / avg latency).

JSON export

[
{
  "timestamp": "2026-09-04T02:12:22.952Z",
  "intervalMs": 5000,
  "nodes": [
    {
      "url": "https://soroban-rpc.mainnet.stellar.org",
      "latencyMs": 42.9,
      "ledgerSequence": 52134010,
      "networkPassphrase": "Public Global Stellar Network ; September 2015",
      "version": "21.3.0",
      "syncStatus": "synced",
      "httpStatus": 200,
      "error": null,
      "timestamp": "2026-09-04T02:12:22.952Z"
    }
  ]
}
]

CSV export

timestamp,url,latency_ms,ledger_sequence,network_passphrase,version,http_status,sync_status,error

---

🛠 Development

npm run dev        # run via tsx without building
npm run build      # compile TypeScript -> dist/
npm run lint       # type-check only (tsc --noEmit)
npm test           # run tests (node --test)

Folder layout

src/
├── index.ts      # Engine / entry point & main loop
├── cli.ts        # Argument & config schema parsing
├── monitor.ts    # Concurrent RPC ping logic
├── dashboard.ts  # Live CLI table rendering
├── export.ts     # JSON / CSV telemetry export
└── types.ts      # Shared TypeScript types & defaults

---

🐳 Docker

An optional Dockerfile is included for running in containers.

docker build -t stellar-rpc-ping .
docker run --rm stellar-rpc-ping --interval 5 -o /data/health.json

---

🧾 License

MIT