svetekllc/evm-height-checker repository overview

⁠evm-height-checker

evm-height-checker is a lightweight monitoring service for EVM-compatible nodes.

It periodically calls eth_blockNumber on a local RPC endpoint and a remote RPC endpoint, compares the block height delta, and reports whether the local node is within the allowed lag threshold.

⁠Features

• Compare local and remote EVM node block heights
• Configurable lag threshold
• Configurable polling interval
• RPC timeouts and retries
• /healthz liveness endpoint
• /readyz readiness endpoint
• /status detailed JSON status endpoint
• /metrics Prometheus metrics endpoint
• Docker-friendly deployment

⁠Use Cases

• Monitor sync status of EVM nodes
• Detect when a local node falls behind a trusted remote RPC
• Export health and sync metrics to Prometheus
• Run simple node lag checks in Docker environments

⁠Endpoints

• GET /healthz - process liveness
• GET /readyz - readiness status
• GET /status - detailed checker state in JSON
• GET /metrics - Prometheus metrics

⁠Supported Networks

This service is network-agnostic and can be used with any EVM-compatible chain, including:

• Ethereum
• Arbitrum
• Optimism
• Polygon
• BNB Chain
• Base
• Avalanche C-Chain

⁠Configuration

The service is configured through environment variables, including:

• LOCAL_RPC_URL
• REMOTE_RPC_URL
• MAX_BEHIND_BLOCKS
• POLL_INTERVAL_SECONDS
• RPC_TIMEOUT_SECONDS
• RPC_RETRY_COUNT
• RETRY_DELAY_SECONDS
• STATE_TTL_SECONDS
• HTTP_HOST
• HTTP_PORT

⁠Docker

Example:

docker run -d \
  --name evm-height-checker \
  --restart unless-stopped \
  -p 8080:8080 \
  -e LOCAL_RPC_URL="https://your-local-rpc" \
  -e REMOTE_RPC_URL="https://your-remote-rpc" \
  -e MAX_BEHIND_BLOCKS="0" \
  svetekllc/evm-height-checker:latest