ethereum-head-watcher

Ethereum head watcher is a specialized bot designed to monitor the Ethereum network for critical validator events. It specifically tracks new slashing events, unexpected exits, and forking incidents. The system is built to integrate with Lido validators by default but supports custom validator monitoring through configuration files. It operates by watching the Ethereum head and handling events, subsequently sending notifications through Alertmanager to Discord channels. The application supports multiple deployment methods, including Docker for production and local Python execution for development. Configuration is flexible, allowing settings to be overridden via environment variables or JSON files, which is particularly useful for Kubernetes deployments using secret stores like OpenBao. This feature enables hot-swapping of node and Alertmanager endpoints without restarting the service, ensuring continuous monitoring. Key features include: - **Event Handling:** Monitors slashing, unexpected exits, consolidations, and execution-layer triggered exits. - **Flexible Key Sources:** Can fetch validator keys from a Keys API or a local file. - **Monitoring & Metrics:** Exposes Prometheus metrics and health check endpoints for integration with monitoring stacks. - **Testing:** Includes both hermetic offline tests and integration tests that replay real mainnet slot ranges. The bot is highly configurable with numerous environment variables controlling logging, alerting behavior, API endpoints, timeouts, and retry logic. It is released under the MIT license.