validator-stats

Ethereum validator performance tracker. Monitors validator attestation effectiveness, block proposals, balance trends, slashing events, and network-wide stats via public Beacon Chain APIs.

Features

• Network Overview — active validators, total staked ETH, participation rate, epoch info
• Validator Profile — balance, attestation hit rate, proposals, slashing status, balance trend
• Batch Comparison — compare multiple validators side-by-side (range or specific indices)
• Slashing Monitor — recent slashing events with reasons
• Balance Tracking — 30-day balance history per validator
• No API Key — free beaconcha.in API (10 req/min), optional key for higher limits
• Zero Dependencies — pure Python 3.8+ stdlib

Install

git clone https://github.com/technicalanalysis00005-cell/validator-stats.git
cd validator-stats
# No install needed — pure stdlib

Usage

Network Overview

python validator_stats.py network

Output:

============================================================
  ETHEREUM BEACON CHAIN - Network Overview
============================================================
  Epoch:                289456
  Active Validators:    987,654
  Total Validators:     1,012,345
  Exited Validators:    24,691
  Total Staked:         31,605,230.00 ETH
  Avg Balance:          32.000100 ETH
  Participation Rate:   99.45%

Single Validator Profile

# Profile validator #100000
python validator_stats.py validator 100000

Output:

============================================================
  VALIDATOR #100000 - Profile
============================================================
  Status:             [ON] active_online
  Balance:            32.015400 ETH
  Effective Balance:  32.000000 ETH
  Activation Epoch:   4785

  Attestations:
    Tracked:          10
    Missed:           0
    Hit Rate:         100.00%

  Proposals:
    Total:            3
    Proposed:         3
    Missed:           0

  Balance Trend:
    Current:          32.015400 ETH
    Min:              32.001200 ETH
    Max:              32.020100 ETH
    Avg:              32.012500 ETH
    Change:           +0.003200 ETH

Batch Validator Comparison

# Compare validators 100000-100020
python validator_stats.py batch --range 100000:100020

# Compare specific validators
python validator_stats.py batch --indices 100000,100001,200000,300000

# JSON output for analysis
python validator_stats.py batch --range 100000:100010 --json | jq '.[] | select(.attestation_hit_rate < 99)'

Output:

================================================================================
  VALIDATOR COMPARISON
================================================================================
  Index      Status           Balance  Att %  Props Missed Slashed
  ---------------------------------------------------------------------------
  100000     active_online     32.0154  100.0%     3      0       -
  100001     active_online     32.0089   99.8%     1      0       -
  100002     active_online     31.9945   98.5%     0      0       -

  ---------------------------------------------------------------------------
  Summary:
    Validators:       21
    Slashed:          0
    Avg Balance:      32.0045 ETH
    Avg Att. Rate:    99.62%
    Total Missed Att: 3
    Total Missed Prop:0

Slashing Events

# Recent slashings
python validator_stats.py slashings --limit 20

Output:

============================================================
  RECENT SLASHINGS (20 events)
============================================================
  Validator #452312 - attestation (epoch 289400, slot 9259840)
  Validator #398715 - block (epoch 289250, slot 9256000)

JSON Output

All commands support --json for scripting:

# Network stats as JSON
python validator_stats.py network --json | jq '.total_staked_eth'

# Validator balance tracking
python validator_stats.py validator 100000 --json | jq '.balance_trend'

Architecture

validator_stats.py
├── API Layer
│   ├── api_get()              — HTTP client with rate limiting + retry
│   ├── get_validator_*()      — validator lookup (index, pubkey, batch)
│   ├── get_validator_attestations/proposals/balance()
│   ├── get_network_stats()    — epoch-level network data
│   └── get_slashings()        — slashing event feed
├── Analysis Classes
│   ├── ValidatorProfiler      — single validator deep dive
│   ├── NetworkStats           — network-wide metrics
│   ├── BatchAnalyzer          — multi-validator comparison
│   └── SlashingMonitor        — slashing event tracking
└── CLI
    ├── network                — network overview
    ├── validator <index>      — single validator profile
    ├── batch --range/--indices — batch comparison
    └── slashings              — recent slashing events

API Sources

Source	Endpoint	Rate Limit
beaconcha.in	beaconcha.in/api/v1	10 req/min (free)

Set BEACONCHA_API_KEY environment variable for higher limits (100+ req/min).

Rate Limiting

The tool handles rate limits automatically:

• 1.2s delay between validator fetches in batch mode
• Auto-retry with 10s wait on HTTP 429 responses
• Batch size of 100 validators per API call

Dependencies

None. Pure Python 3.8+ stdlib.

License

MIT