{"id":24461018,"url":"https://github.com/kilnfi/eth-validator-watcher","last_synced_at":"2025-04-06T06:12:02.756Z","repository":{"id":170925412,"uuid":"517979693","full_name":"kilnfi/eth-validator-watcher","owner":"kilnfi","description":"Your personal real time Ethereum validator watcher","archived":false,"fork":false,"pushed_at":"2024-12-17T09:02:30.000Z","size":5672,"stargazers_count":70,"open_issues_count":11,"forks_count":29,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-30T05:07:18.319Z","etag":null,"topics":["ethereum"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kilnfi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-26T08:38:46.000Z","updated_at":"2025-01-07T06:42:27.000Z","dependencies_parsed_at":"2023-09-23T20:11:26.120Z","dependency_job_id":"1d49b1d2-24e8-4514-a0d6-10e91b573bde","html_url":"https://github.com/kilnfi/eth-validator-watcher","commit_stats":null,"previous_names":["kilnfi/eth-validator-watcher"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Feth-validator-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Feth-validator-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Feth-validator-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Feth-validator-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kilnfi","download_url":"https://codeload.github.com/kilnfi/eth-validator-watcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441057,"owners_count":20939239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum"],"created_at":"2025-01-21T04:17:03.331Z","updated_at":"2025-04-06T06:12:02.737Z","avatar_url":"https://github.com/kilnfi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ethereum Validator Watcher\n\n**This is a preview of the new version of the Ethereum Validator Watcher.**\n\n![kiln-logo](docs/img/Kiln_Logo-Transparent-Dark.svg)\n\n[![License](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/MIT)\n\nThe code is provided as-is with no warranties.\n\n- Youtube video of [Ethereum Validator Watcher talk during EthCC[6]](https://www.youtube.com/watch?v=SkyncLrME1g\u0026t=12s\u0026ab_channel=%5BEthCC%5DLivestream2)\n- Youtube video of [Ethereum Validator Watcher talk during EthStaker](https://www.youtube.com/watch?v=JrGz5FROgEg)\n\n## Overview Dashboard\n\nThe [overview dashboard](grafana/dashboard-overview.json) shows an\noverview of the entire set of watched keys and how they relate to the\nrest of the network (asset under management, state of keys,\nperformances):\n\n![overview-dashboard](docs/img/watcher-overview.png)\n\n## Breakdown Dashboard\n\nThe [breakdown dashboard](grafana/dashboard-breakdown.json) offers a\nway to compare how each set of keys in user-defined category\nperform:\n\n![breakdown-dashboard](docs/img/watcher-breakdown.png)\n\n# Description\n\n**Ethereum Validator Watcher** monitors the Ethereum beacon chain in\nreal-time and notifies you when any of your validators:\n\n- are going to propose a block in the next two epochs\n- missed a block proposal at head\n- missed a block proposal at finalized\n- did not optimally attest\n- missed an attestation\n- missed two attestations in a row\n- proposed a block with the wrong fee recipient\n- has exited\n- got slashed\n- did not had ideal source, target or head reward\n\nIt also exports some general metrics such as:\n\n- your USD assets under management\n- the total staking market cap\n- the epoch and slot\n- the number or total slashed validators\n- the ETH/USD conversion rate\n- the number of your queued validators\n- the number of your active validators\n- the number of your exited validators\n- the number of the network queued validators\n- the number of the network active validators\n- the entry queue duration estimation\n\nThe Prometheus endpoint is automatically exposed on port 8000.\n\n## Command line options\n\n```\nUsage: eth-validator-watcher [OPTIONS]\n\n  Run the Ethereum Validator Watcher.\n\nOptions:\n  --config FILE  File containing the Ethereum Validator Watcher configuration\n                 file.  [default: etc/config.local.yaml]\n  --help         Show this message and exit.\n```\n\n## Configuration\n\nThe configuration uses the YAML format:\n\n```yaml\n# Example config file for the Ethereum validator watcher.\n\nbeacon_url: http://localhost:5051/\nbeacon_timeout_sec: 90\nnetwork: mainnet\nmetrics_port: 8000\n\nwatched_keys:\n  - public_key: '0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c'\n    labels: [\"vc:validator-1\", \"region:sbg\"]\n  - public_key: '0x8619c074f403637fdc1f49b77fc295c30214ed3060573a1bfd24caea1f25f7b8e6a9076b7c721076d807003c87956dc1'\n    labels: [\"vc:validator-1\", \"region:sbg\"]\n  - public_key: '0x91c44564d1e61f7f6e35c330bd931590036d461378ab260b83e77f012a47605a393b5a375bf591466b274dad0b0e8a25'\n    labels: [\"vc:validator-2\", \"region:rbx\"]\n```\n\nIn this example, we define 3 validators which are running on two\nvalidator clients in separate regions. The labels can be anything you\nwant as long as it follows the `category:value` format. The\n[breakdown dashboard](docs/img/watcher-breakdown.png) uses it to offer\nper-value comparisons within a category. You can for instance compare your\nmissed attestations between region `rbx` and `sbg`, or between `validator-1`\nand `validator-2`. This comes handy when operating at scale, you can\nquickly isolate where an issue comes from if your groups match your\ninfrastructure.\n\nAny categories of labels is possible, some plausible examples:\n\n- by beacon instance (i.e: beacon:beacon-1)\n- by client version (i.e: prysm:v5.0.3)\n- by cluster (i.e: cluster:baremetal-1)\n- by operator (i.e: operator:kiln)\n\nBy default, the watcher exports the following labels:\n\n- `scope:watched` for the keys present in the configuration file,\n- `scope:network` for the entire network without the keys in the configuration file,\n- `scope:all-network` for the entire network including the watched keys.\n\nThose are used by the overview dashboard and the breakdown dashboard\nto offer a comparison of your validator keys with the network.\n\nThe configuration can be updated in real-time, the watcher will reload\nit dynamically on the next epoch. This allows to have growing sets of\nvalidators, for instance if you deploy new keys.\n\n## Beacon Compatibility\n\nBeacon type      | Compatibility\n-----------------|------------------\nLighthouse       | Full.\nPrysm            | Full.\nTeku             | Not (yet) tested.\nNimbus           | Not (yet) tested.\nLodestar         | Not (yet) tested.\n\nThe beacon type is relative to the beacon node connected to the\nwatcher, **not to the beacon node connected to the validator client\ncontaining a validator key you want to watch**. The watcher is\nagnostic of the infrastructure mananing validators keys you want to\nwatch, this means you can run it on an external location if you want\nblackbox monitoring.\n\n## Installation\n\nFrom source:\n\n```\ngit clone git@github.com:kilnfi/eth-validator-watcher.git\ncd eth-validator-watcher\npip install .\n```\n\nWe recommend using the Docker images.\n\n## Docker images\n\nDocker images (built for AMD64 and ARM64) are available\n[here](https://github.com/kilnfi/eth-validator-watcher/pkgs/container/eth-validator-watcher).\n\n## Developer guide\n\nWe use [Poetry](https://python-poetry.org/) to manage dependencies and packaging.\n\n**Installation:**\n\n```\ngit clone git@github.com:kilnfi/validator-watcher.git\ncd validator-watcher\npoetry install --with dev\npoetry shell # To activate Python virtual environment\n```\n\n**Running tests:**\n\n```\npoetry run pytest\n```\n\n## License\n\n[MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilnfi%2Feth-validator-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkilnfi%2Feth-validator-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilnfi%2Feth-validator-watcher/lists"}