{"id":17135994,"url":"https://github.com/kilnfi/cosmos-validator-watcher","last_synced_at":"2025-04-05T23:05:49.558Z","repository":{"id":194088806,"uuid":"690101617","full_name":"kilnfi/cosmos-validator-watcher","owner":"kilnfi","description":"Real-time Cosmos-based chains monitoring","archived":false,"fork":false,"pushed_at":"2025-03-15T08:56:58.000Z","size":756,"stargazers_count":83,"open_issues_count":10,"forks_count":33,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T22:04:30.471Z","etag":null,"topics":["cosmos","cosmos-sdk","prometheus"],"latest_commit_sha":null,"homepage":"","language":"Go","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":"2023-09-11T14:30:58.000Z","updated_at":"2025-03-20T08:43:48.000Z","dependencies_parsed_at":"2023-09-11T18:00:19.007Z","dependency_job_id":"83ef7060-98d4-4b9d-b9ba-416568db1b45","html_url":"https://github.com/kilnfi/cosmos-validator-watcher","commit_stats":{"total_commits":44,"total_committers":2,"mean_commits":22.0,"dds":"0.022727272727272707","last_synced_commit":"1245caff6abd7ddb82d9e8af0abe725a2dac01e4"},"previous_names":["kilnfi/cosmos-validator-watcher"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Fcosmos-validator-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Fcosmos-validator-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Fcosmos-validator-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilnfi%2Fcosmos-validator-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kilnfi","download_url":"https://codeload.github.com/kilnfi/cosmos-validator-watcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411226,"owners_count":20934653,"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":["cosmos","cosmos-sdk","prometheus"],"created_at":"2024-10-14T20:01:12.577Z","updated_at":"2025-04-05T23:05:49.540Z","avatar_url":"https://github.com/kilnfi.png","language":"Go","funding_links":[],"categories":["Go","Monitoring"],"sub_categories":[],"readme":"# Cosmos Validator Watcher\n\n[![License](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/MIT)\n\n**Cosmos Validator Watcher** is a Prometheus exporter to help you monitor missed blocks on\nany cosmos-based blockchains in real-time.\n\nFeatures:\n\n- Track when your validator **missed a block** (with solo option)\n- Check how many validators missed the signatures for each block\n- Track the current active set and check if your validator is **bonded** or **jailed**\n- Track the **staked amount** as well as the min seat price\n- Track **pending proposals** and check if your validator has voted (including proposal end time)\n- Expose **upgrade plan** to know when the next upgrade will happen (including pending proposals)\n- Trigger webhook when an upgrade happens\n\n![Cosmos Validator Watcher Screenshot](assets/cosmos-validator-watcher-screenshot.jpg)\n\n## ✨ Usage\n\nExample for cosmoshub using 2 public RPC nodes and tracking 4 validators (with custom aliases).\n\n### Via compiled binary\n\nCompiled binary can be found on the [Releases page](https://github.com/kilnfi/cosmos-validator-watcher/releases).\n\n```bash\ncosmos-validator-watcher \\\n  --node https://cosmos-rpc.publicnode.com:443 \\\n  --node https://cosmos-rpc.polkachu.com:443 \\\n  --validator 3DC4DD610817606AD4A8F9D762A068A81E8741E2:kiln \\\n  --validator 25445D0EB353E9050AB11EC6197D5DCB611986DB:allnodes \\\n  --validator 9DF8E338C85E879BC84B0AAA28A08B431BD5B548:9df8e338 \\\n  --validator ABC1239871ABDEBCDE761D718978169BCD019739:random-name\n```\n\n### Via Docker\n\nLatest Docker image can be found on the [Packages page](https://github.com/kilnfi/cosmos-validator-watcher/pkgs/container/cosmos-validator-watcher).\n\n```bash\ndocker run --rm ghcr.io/kilnfi/cosmos-validator-watcher:latest \\\n  --node https://cosmos-rpc.publicnode.com:443 \\\n  --node https://cosmos-rpc.polkachu.com:443 \\\n  --validator 3DC4DD610817606AD4A8F9D762A068A81E8741E2:kiln \\\n  --validator 25445D0EB353E9050AB11EC6197D5DCB611986DB:allnodes \\\n  --validator 9DF8E338C85E879BC84B0AAA28A08B431BD5B548:9df8e338 \\\n  --validator ABC1239871ABDEBCDE761D718978169BCD019739:random-name\n```\n\n### Available options\n\n```\ncosmos-validator-watcher --help\n\nNAME:\n   cosmos-validator-watcher - Real-time Cosmos-based chains monitoring tool\n\nUSAGE:\n   cosmos-validator-watcher [global options] command [command options] [arguments...]\n\nCOMMANDS:\n   help, h  Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --babylon                                                      enable babylon watcher (checkpoint votes \u0026 finality providers) (default: false)\n   --chain-id value                                               to ensure all nodes matches the specific network (dismiss to auto-detected)\n   --debug                                                        shortcut for --log-level=debug (default: false)\n   --denom value                                                  denom used in metrics label (eg. atom or uatom)\n   --denom-exponent value                                         denom exponent (eg. 6 for atom, 1 for uatom) (default: 0)\n   --finality-provider value [ --finality-provider value ]        list of finality providers to watch (requires --babylon)\n   --http-addr value                                              http server address (default: \":8080\")\n   --log-level value                                              log level (debug, info, warn, error) (default: \"info\")\n   --namespace value                                              namespace for Prometheus metrics (default: \"cosmos_validator_watcher\")\n   --no-color                                                     disable colored output (default: false)\n   --no-commission                                                disable calls to get validator commission (useful for chains without distribution module) (default: false)\n   --no-gov                                                       disable calls to gov module (useful for consumer chains) (default: false)\n   --no-slashing                                                  disable calls to slashing module (default: false)\n   --no-staking                                                   disable calls to staking module (useful for consumer chains) (default: false)\n   --no-upgrade                                                   disable calls to upgrade module (for chains created without the upgrade module) (default: false)\n   --node value [ --node value ]                                  rpc node endpoint to connect to (specify multiple for high availability) (default: \"http://localhost:26657\")\n   --start-timeout value                                          timeout to wait on startup for one node to be ready (default: 10s)\n   --stop-timeout value                                           timeout to wait on stop (default: 10s)\n   --validator value [ --validator value ]                        validator address(es) to track (use :my-label to add a custom label in metrics \u0026 output)\n   --webhook-custom-block value [ --webhook-custom-block value ]  trigger a custom webhook at a given block number (experimental)\n   --webhook-url value                                            endpoint where to send upgrade webhooks (experimental)\n   --x-gov value                                                  version of the gov module to use (v1|v1beta1) (default: \"v1\")\n   --help, -h                                                     show help\n   --version, -v                                                  print the version\n```\n\n\n## ❇️ Endpoints\n\n- `/metrics` exposed Prometheus metrics (see next section)\n- `/ready` responds OK when at least one of the nodes is synced (ie. `.SyncInfo.catching_up` is `false`)\n- `/live` responds OK as soon as server is up \u0026 running correctly\n\n\n## 📊 Prometheus metrics\n\nAll metrics are by default prefixed by `cosmos_validator_watcher` but this can be changed through options.\n\nMetrics (without prefix)        | Description\n--------------------------------|-------------------------------------------------------------------------\n`active_set`                    | Number of validators in the active set\n`block_height`                  | Latest known block height (all nodes mixed up)\n`commission`                    | Earned validator commission\n`consecutive_missed_blocks`     | Number of consecutive missed blocks per validator (for a bonded validator)\n`downtime_jail_duration`        | Duration of the jail period for a validator in seconds\n`empty_blocks`                  | Number of empty blocks (blocks with zero transactions) proposed by validator\n`is_bonded`                     | Set to 1 if the validator is bonded\n`is_jailed`                     | Set to 1 if the validator is jailed\n`min_signed_blocks_per_window`  | Minimum number of blocks required to be signed per signing window\n`missed_blocks_window`          | Number of missed blocks per validator for the current signing window (for a bonded validator)\n`missed_blocks`                 | Number of missed blocks per validator (for a bonded validator)\n`node_block_height`             | Latest fetched block height for each node\n`node_synced`                   | Set to 1 is the node is synced (ie. not catching-up)\n`proposal_end_time`             | Timestamp of the voting end time of a proposal\n`proposed_blocks`               | Number of proposed blocks per validator (for a bonded validator)\n`rank`                          | Rank of the validator\n`seat_price`                    | Min seat price to be in the active set (ie. bonded tokens of the latest validator)\n`signed_blocks_window`          | Number of blocks per signing window\n`skipped_blocks`                | Number of blocks skipped (ie. not tracked) since start\n`slash_fraction_double_sign`    | Slash penaltiy for double-signing\n`slash_fraction_downtime`       | Slash penaltiy for downtime\n`solo_missed_blocks`            | Number of missed blocks per validator, unless the block is missed by many other validators\n`tokens`                        | Number of staked tokens per validator\n`tracked_blocks`                | Number of blocks tracked since start\n`transactions`                  | Number of transactions since start\n`upgrade_plan`                  | Block height of the upcoming upgrade (hard fork)\n`validated_blocks`              | Number of validated blocks per validator (for a bonded validator)\n`vote`                          | Set to 1 if the validator has voted on a proposal\n\n\n### Chain specific metrics\n\n**Babylon** (requires the `--babylon` flag).\n\nMetrics (without prefix)                      | Description\n----------------------------------------------|-------------------------------------------------------------------------\n`babylon_epoch`                               | Babylon epoch\n`babylon_checkpoint_vote`                     | Count of checkpoint votes since start (equal to number of epochs)\n`babylon_committed_checkpoint_vote`           | Number of committed checkpoint votes for a validator\n`babylon_missed_checkpoint_vote`              | Number of missed checkpoint votes for a validator\n`babylon_consecutive_missed_checkpoint_vote`  | Number of consecutive missed checkpoint votes for a validator\n`babylon_finality_votes`                      | Count of total finality provider slots since start\n`babylon_committed_finality_votes`            | Number of votes for a finality provider\n`babylon_missed_finality_votes`               | Number of missed votes for a finality provider\n`babylon_consecutive_missed_finality_votes`   | Number of consecutive missed votes for a finality provider\n\n\n### Grafana dashboard\n\nFor an example of a Prometheus and Grafana dashboard setup using Docker Compose, you can refer to [21state/cosmos-watcher-stack](https://github.com/21state/cosmos-watcher-stack/).\n\n\n## ❓FAQ\n\n### Which blockchains are compatible?\n\nAny blockchains based on the cosmos-sdk should work:\n\n- cosmoshub\n- celestia\n- cronos\n- dydx\n- evmos\n- injective\n- kava\n- osmosis\n- persistence\n- dymension\n- zetachain\n- ...\n\nThis app is using the [CometBFT library](https://github.com/cometbft/cometbft/) (successor of Tendermint) as well as the `x/staking` module from the [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk).\n\n### How to get your validator pubkey address?\n\n**Option 1**: use `tendermint show-validator` to get the pubkey and `debug pubkey` to convert to hex format.\n\n```bash\nCLI_NAME=gaiad\nADDRESS=\"$($CLI_NAME debug pubkey \"$($CLI_NAME tendermint show-validator)\" 2\u003e\u00261 | grep \"Address\")\"\nADDRESS=\"${ADDRESS##* 0x}\"\nADDRESS=\"${ADDRESS##* }\"\necho \"${ADDRESS^^}\"\n```\n\n(replace `gaiad` by the binary name or the desired chain, eg. `evmosd`, `strided`, `injectived`, …).\n\n**Option 2**: use the `cosmos-validator-watcher debug consensus-key` sub command:\n\n```bash\ncosmos-validator-watcher debug validator \\\n  --node https://cosmos-rpc.publicnode.com:443 \\\n  cosmosvaloper1uxlf7mvr8nep3gm7udf2u9remms2jyjqvwdul2\n```\n\nNotes:\n- the `--node` flag must be placed before the validator address)\n- this doesns't work for consumer chains (neutron, stride) since they don't rely on the `staking` module\n\n\n## 📃 License\n\n[MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilnfi%2Fcosmos-validator-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkilnfi%2Fcosmos-validator-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilnfi%2Fcosmos-validator-watcher/lists"}