obolnetwork/distributed-validators

Distributed Validators

Monitor distributed validator (DV) clusters using the Obol API. Check cluster health, validator performance, operator status, and exit progress.

A distributed validator splits signing across multiple operators so no single party holds the full key. Obol's middleware (Charon) coordinates this. A cluster has N operators with a threshold (e.g. 3-of-4) needed to sign.

When to Use

• Checking cluster health or validator performance
• Looking up operator reputation or badges
• Checking exit coordination progress
• Exploring network-wide DV statistics

When NOT to Use

• Creating clusters or running DKG (write operations)
• Ethereum RPC queries — use ethereum-networks
• Kubernetes diagnostics — use obol-stack

API Base

All endpoints are public, no authentication needed:

https://api.obol.tech

Key Identifiers

• lock_hash: Identifies a cluster after key generation (post-DKG). 0x + 64 hex chars.
• config_hash: Identifies a cluster definition before key generation (pre-DKG).
• operator address: Standard Ethereum address, 0x + 40 hex chars.

Lookup by lock_hash

# Cluster config
curl -s "https://api.obol.tech/v1/lock/0x..."

# Validator performance (0-1 scale, >0.95 is healthy)
curl -s "https://api.obol.tech/v1/effectiveness/0x..."

# Validator beacon chain states
curl -s "https://api.obol.tech/v1/state/0x..."

# Exit status summary
curl -s "https://api.obol.tech/v1/exp/exit/status/summary/0x..."

# Detailed exit status
curl -s "https://api.obol.tech/v1/exp/exit/status/0x..."

Lookup by config_hash

# Pre-DKG cluster definition
curl -s "https://api.obol.tech/v1/definition/0x..."

# Get lock (if DKG completed)
curl -s "https://api.obol.tech/v1/lock/configHash/0x..."

Lookup by operator address

# All clusters for this operator
curl -s "https://api.obol.tech/v1/lock/operator/0x..."

# Reputation level (base < bronze < silver)
curl -s "https://api.obol.tech/v1/address/techne/0x..."

# Protocol badges (Lido, EtherFi, etc.)
curl -s "https://api.obol.tech/v1/address/badges/0x..."

# Terms & conditions signed?
curl -s "https://api.obol.tech/v1/termsAndConditions/0x..."

Network-wide queries

# Network summary stats
curl -s "https://api.obol.tech/v1/lock/network/summary/mainnet"

# Search clusters
curl -s "https://api.obol.tech/v1/lock/search/mainnet?q=..."

# All operators on a network
curl -s "https://api.obol.tech/v1/address/network/mainnet"

Networks: mainnet, hoodi, holesky, sepolia

Common Workflows

Check cluster health

# 1. Get cluster info
curl -s "https://api.obol.tech/v1/lock/0x..." | python3 -c "
import sys, json
d = json.load(sys.stdin)
if 'error' in d or 'name' not in d:
    print('Error or cluster not found:', json.dumps(d, indent=2))
else:
    ops = d.get('operators', [])
    print(f'Cluster: {d.get(\"name\",\"?\")} | {d.get(\"threshold\",\"?\")}-of-{len(ops)} | {d.get(\"network\",\"?\")}')
"

# 2. Check validator effectiveness
curl -s "https://api.obol.tech/v1/effectiveness/0x..." | python3 -c "
import sys, json
d = json.load(sys.stdin)
for v in d.get('effectiveness', []):
    eff = v.get('effectiveness', 0)
    status = 'healthy' if eff > 0.95 else 'degraded' if eff > 0.8 else 'CRITICAL'
    print(f'{v.get(\"public_key\", \"?\")[:16]}...  {eff:.3f}  [{status}]')
if not d.get('effectiveness'):
    print('No effectiveness data found')
"

Check exit progress

curl -s "https://api.obol.tech/v1/exp/exit/status/summary/0x..." | python3 -c "
import sys, json
d = json.load(sys.stdin)
if not isinstance(d, dict) or 'total_validators' not in d:
    print('No exit data or cluster not found:', json.dumps(d, indent=2))
else:
    print(f'Ready to exit: {d.get(\"validators_ready_to_exit\", 0)}/{d.get(\"total_validators\", 0)}')
    for op in d.get('operators', []):
        print(f'  {op.get(\"address\", \"?\")[:12]}...  signed: {op.get(\"signed_exits\", 0)}')
"

Exit broadcasts automatically once enough operators have signed (threshold reached).

Constraints

• Read-only — creating clusters, running DKG, and submitting exits require authenticated endpoints
• Exit status endpoints (/v1/exp/) are experimental — pagination is 1-indexed
• If timeouts occur, check GET /v1/_health first
• Shell is sh, not bash — do not use bashisms
• Always check for null/missing data — API responses may return errors or empty results. Always check before accessing nested fields

See references/api-examples.md for response shapes and field reference.

See Also

• ethereum-networks — blockchain RPC queries (validator balances, beacon chain data)
• obol-stack — Kubernetes cluster monitoring (pod status, logs)