ValidatorPulse

Is my validator operating correctly?

Self-hosted validator monitoring for Ethereum, Polkadot, Cosmos, Solana, and more — Prometheus metrics and multi-channel alerts. A FastAPI dashboard watches operator duties, consensus health, and host infrastructure so you catch downtime and penalties early.

It does not scan external security surfaces. One CHAIN per process.

Contents

• Installation
• What it monitors
• Chains
• RPC and TLS
• Per-chain setup
• Auth and Prometheus
• Configuration
• Alerts
• API
• Scoring
• Tests
• License

Installation

All three start in demo mode so you can confirm the UI without a node. One CHAIN per process — ethereum,solana is invalid; run a second instance for a second network.

Option A — PyPI

1. Python 3.11 or newer (python3 --version), then:

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -U pip
pip install validator-pulse

2. Demo with no config file:

CHAIN=ethereum DEMO_MODE=true validator-pulse

Or download the sample env (it is not inside the wheel) and start from that directory:

curl -fsSL -o .env.local https://raw.githubusercontent.com/ehsanhajian/ValidatorPulse/main/.env.example
validator-pulse

The app reads .env.local, then .env, from the current working directory. Leave DEMO_MODE=true and CHAIN=ethereum for the first run.

3. Open http://127.0.0.1:3000. You should see the Ethereum demo dashboard.

Go live: edit .env.local, then Ctrl+C and start validator-pulse again.

CHAIN=ethereum
DEMO_MODE=false
BEACON_API_URL=http://127.0.0.1:5052
VALIDATOR_INDICES=123456

Option B — Git checkout (venv)

Use this to hack on the code. pip install -e . is required; requirements.txt alone is not enough.

git clone https://github.com/ehsanhajian/ValidatorPulse.git
cd ValidatorPulse
python3 --version    # must print 3.11 or newer

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -U pip
pip install -r requirements.txt
pip install -e .

cp .env.example .env.local
python -m validator_pulse

Open http://127.0.0.1:3000. Live-mode edits are the same as Option A (edit .env.local, restart).

Option C — Docker Compose + Caddy

The app port stays on the Compose network. Caddy is the only published entrypoint.

1. Install Docker with the Compose plugin, then:

git clone https://github.com/ehsanhajian/ValidatorPulse.git
cd ValidatorPulse
docker compose version

2. Copy the Compose sample (this file is .env, not .env.example):

cp compose.env.example .env
docker compose up --build

3. Wait until validator-pulse is healthy and Caddy has started. Open http://127.0.0.1 — port 80. Port 3000 is not published.

Compose loads .env (Caddy + CHAIN / DEMO_MODE) and optional .env.local (full app settings).

Go live: copy the full sample, then point RPC at the host node with host.docker.internal (not 127.0.0.1 — that is the container itself):

cp .env.example .env.local

# .env and .env.local
CHAIN=ethereum
DEMO_MODE=false
BEACON_API_URL=http://host.docker.internal:5052
VALIDATOR_INDICES=123456

docker compose up --build

Caddyfile.restrict is fail-closed: an empty allowlist denies everyone. Set WEB_AUTH_USERNAME / WEB_AUTH_PASSWORD as well if Caddy is reachable beyond this machine. Single-host only — not Kubernetes.

If the install fails

What it monitors

Adapters supply labels (risk_label, duty names, consensus node name). Scoring, alerts, metrics, and the dashboard stay chain-agnostic.

Chains

CHAIN=ethereum

RPC and TLS

Shared HTTP(S) client for beacon, Substrate, and other adapters.

Per-chain setup

Each block is the live-mode minimum. Demo mode needs only CHAIN (and a profile/role where listed). Full variable list: .env.example.

Ethereum

CHAIN=ethereum
DEMO_MODE=false
BEACON_API_URL=https://beacon.example.com:8443
VALIDATOR_INDICES=123456,789012

• Live rewards are signed Beacon consensus rewards — never balance − effective_balance. Execution tips / MEV are excluded.
• Display-name order: beaconcha.in → Rated → ENS → graffiti → index/pubkey.

Polkadot

CHAIN=polkadot
POLKADOT_ROLE=collator
DEMO_MODE=false
SUBSTRATE_RPC_URL=http://127.0.0.1:9933
COLLATOR_ADDRESSES=5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
PARACHAIN_ID=2006

PARACHAIN_ID is ignored on relay (DOT unless you override the token). Relay live mode uses era points + block production until full staking-storage decoding lands.

Cosmos

CHAIN=cosmos
COSMOS_PROFILE=cosmoshub
DEMO_MODE=false
COSMOS_REST_URL=http://127.0.0.1:1317
COSMOS_RPC_URL=http://127.0.0.1:26657
COSMOS_VALIDATOR_OPERATOR_ADDRESSES=cosmosvaloper1...

Never copy a live consensus key/state directory between nodes (double-sign / tombstone). ValidatorPulse only reads remote APIs.

Solana

Optional: SOLANA_IDENTITY_PUBKEYS when vote accounts are unknown. Credits → primary duty; skip rate → secondary / risk; delinquents → critical.

NEAR

Optional: NEAR_METRICS_URL. Tracks blocks / chunks / endorsements, set membership, kickout vs slash.

Cardano

Uses local cardano-tracer Prometheus (node 10.2+). No invented leader slots when the tracer is down. Operational / reward risk only.

Tezos

Optional: TEZOS_METRICS_URL, TEZOS_BAKER_LOG_PATH (soft-fail). Forbidden / denounced delegates are critical slashing alerts.

Algorand

Committee selection is private — only observed votes/proposals are recorded. Offline / suspension is operational risk, not slashing.

BNB Smart Chain

Optional: BSC_METRICS_URL, contract overrides, BSC_MISDEMEANOR_THRESHOLD / BSC_FELONY_THRESHOLD. Downtime thresholds come from getSlashThresholds() unless you override them. Double-sign and malicious finality votes are immediately critical.

Aptos

Optional: APTOS_METRICS_URL, APTOS_API_KEY. Failed proposals cost rewards; there is no principal slashing.

Sui

Optional local Prometheus: SUI_METRICS_URL (9184/metrics). Safe mode and confirmed reward slashing are critical; low-stake atRisk stays a separate signal.

Monad

Optional local evidence: MONAD_METRICS_URL, MONAD_LEDGER_TAIL_PATH, MONAD_STATUS_PATH. EVM RPC alone cannot claim missed duties. Automated slashing is not implemented — reward / eligibility risk only.

Avalanche

Primary Network only. Reliable uptime needs a local node (info.uptime). Public info.uptime is never treated as the configured validator. Reward forfeiture is not principal slashing.

Mina

Optional: MINA_CLIENT_COMMAND, MINA_ARCHIVE_DATABASE_URL, MINA_LOG_PATH. Public GraphQL cannot list another producer’s private VRF duties. Query-only. No producer-stake slash.

MultiversX

Optional: MULTIVERSX_SHARD_ID, MULTIVERSX_JAIL_RATING_THRESHOLD. Each key on a multikey host is scored independently. Low-rating jail ≠ serious-offence stake slash.

TON

Native token displays as GRAM (formerly Toncoin / TON). The network is still TON; CHAIN=ton is unchanged. Base unit stays nanoton. Complaints / fines are fine risk, not Ethereum-style principal slashing. Zero efficiency at round start is ignored.

Auth and Prometheus

Auth is off when unset (local demos stay open). Set both username and password for HTTP Basic on the dashboard and APIs.

WEB_METRICS_TOKEN does not unlock the dashboard. Binding off loopback without credentials logs a warning.

scrape_configs:
  - job_name: validatorpulse
    static_configs:
      - targets: ["127.0.0.1:9091"]   # Compose; use :3000 for venv
    authorization:
      type: Bearer
      credentials: scrape-token-here

To scrape a public Caddy site instead, add the scraper CIDR to CADDY_ALLOW_IPS.

Configuration

Restart after changing .env.local (or rely on reload with python -m validator_pulse). Chain-specific variables live in Per-chain setup. Everything else:

Process

Lookups

Caddy (Compose)

Shared alerts

Alerts

# A / B (PyPI or venv)
curl -X POST http://127.0.0.1:3000/api/alerts/test
# C (Compose / Caddy)
curl -X POST http://127.0.0.1/api/alerts/test

API

GET /api/status is schema_version: 2 (operator_id, *_base_units, duties, risk_score). Prometheus emits operator_* (preferred; chain / operator_id labels) and legacy validator_*. *_gwei is the same integer as *_base_units.

Scoring

Adapters set risk_kind / risk_label (slashing, kickout, jail, downtime, …). Confirmed slash / jail / tombstone events use protocol_events.

Tests

pytest

Pull requests and main run the same suite in GitHub Actions. Publishing a GitHub release (vX.Y.Z) runs tests again, then uploads to PyPI.

License

MIT. See LICENSE.

Support the project

If ValidatorPulse helps you, donations are welcome — ETH or ERC-20 on Ethereum:

0xE5B2f8a35c0f12304c5aBDa9477159b53f622cAA