Skip to content

Latest commit

 

History

History
187 lines (144 loc) · 9.51 KB

README.md

File metadata and controls

187 lines (144 loc) · 9.51 KB
Raw

Cosmos Validator Watcher

License

Cosmos Validator Watcher is a Prometheus exporter to help you monitor missed blocks on any cosmos-based blockchains in real-time.

Features:

  • Track when your validator missed a block (with solo option)
  • Check how many validators missed the signatures for each block
  • Track the current active set and check if your validator is bonded or jailed
  • Track the staked amount as well as the min seat price
  • Track pending proposals and check if your validator has voted (including proposal end time)
  • Expose upgrade plan to know when the next upgrade will happen (including pending proposals)
  • Trigger webhook when an upgrade happens

Cosmos Validator Watcher Screenshot

✨ Usage

Example for cosmoshub using 2 public RPC nodes and tracking 4 validators (with custom aliases).

Via compiled binary

Compiled binary can be found on the Releases page.

cosmos-validator-watcher \
  --node https://cosmos-rpc.publicnode.com:443 \
  --node https://cosmos-rpc.polkachu.com:443 \
  --validator 3DC4DD610817606AD4A8F9D762A068A81E8741E2:kiln \
  --validator 25445D0EB353E9050AB11EC6197D5DCB611986DB:allnodes \
  --validator 9DF8E338C85E879BC84B0AAA28A08B431BD5B548:9df8e338 \
  --validator ABC1239871ABDEBCDE761D718978169BCD019739:random-name

Via Docker

Latest Docker image can be found on the Packages page.

docker run --rm ghcr.io/kilnfi/cosmos-validator-watcher:latest \
  --node https://cosmos-rpc.publicnode.com:443 \
  --node https://cosmos-rpc.polkachu.com:443 \
  --validator 3DC4DD610817606AD4A8F9D762A068A81E8741E2:kiln \
  --validator 25445D0EB353E9050AB11EC6197D5DCB611986DB:allnodes \
  --validator 9DF8E338C85E879BC84B0AAA28A08B431BD5B548:9df8e338 \
  --validator ABC1239871ABDEBCDE761D718978169BCD019739:random-name

Available options

cosmos-validator-watcher --help

NAME:
   cosmos-validator-watcher - Real-time Cosmos-based chains monitoring tool

USAGE:
   cosmos-validator-watcher [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --chain-id value                                               to ensure all nodes matches the specific network (dismiss to auto-detected)
   --http-addr value                                              http server address (default: ":8080")
   --log-level value                                              log level (debug, info, warn, error) (default: "info")
   --debug                                                        shortcut for --log-level=debug (default: false)
   --namespace value                                              namespace for Prometheus metrics (default: "cosmos_validator_watcher")
   --no-color                                                     disable colored output (default: false)
   --node value [ --node value ]                                  rpc node endpoint to connect to (specify multiple for high availability) (default: "http://localhost:26657")
   --no-gov                                                       disable calls to gov module (useful for consumer chains) (default: false)
   --no-staking                                                   disable calls to staking module (useful for consumer chains) (default: false)
   --no-slashing                                                  disable calls to slashing module (default: false)
   --no-commission                                                disable calls to get validator commission (useful for chains without distribution module) (default: false)
   --no-upgrade                                                   disable calls to upgrade module (for chains created without the upgrade module) (default: false)
   --denom value                                                  denom used in metrics label (eg. atom or uatom)
   --denom-exponent value                                         denom exponent (eg. 6 for atom, 1 for uatom) (default: 0)
   --start-timeout value                                          timeout to wait on startup for one node to be ready (default: 10s)
   --stop-timeout value                                           timeout to wait on stop (default: 10s)
   --validator value [ --validator value ]                        validator address(es) to track (use :my-label to add a custom label in metrics & ouput)
   --webhook-url value                                            endpoint where to send upgrade webhooks (experimental)
   --webhook-custom-block value [ --webhook-custom-block value ]  trigger a custom webhook at a given block number (experimental)
   --x-gov value                                                  version of the gov module to use (v1|v1beta1) (default: "v1")
   --help, -h                                                     show help
   --version, -v                                                  print the version

❇️ Endpoints

  • /metrics exposed Prometheus metrics (see next section)
  • /ready responds OK when at least one of the nodes is synced (ie. .SyncInfo.catching_up is false)
  • /live responds OK as soon as server is up & running correctly

📊 Prometheus metrics

All metrics are by default prefixed by cosmos_validator_watcher but this can be changed through options.

Metrics (without prefix) Description
active_set Number of validators in the active set
block_height Latest known block height (all nodes mixed up)
commission Earned validator commission
consecutive_missed_blocks Number of consecutive missed blocks per validator (for a bonded validator)
downtime_jail_duration Duration of the jail period for a validator in seconds
empty_blocks Number of empty blocks (blocks with zero transactions) proposed by validator
is_bonded Set to 1 if the validator is bonded
is_jailed Set to 1 if the validator is jailed
min_signed_blocks_per_window Minimum number of blocks required to be signed per signing window
missed_blocks_window Number of missed blocks per validator for the current signing window (for a bonded validator)
missed_blocks Number of missed blocks per validator (for a bonded validator)
node_block_height Latest fetched block height for each node
node_synced Set to 1 is the node is synced (ie. not catching-up)
proposal_end_time Timestamp of the voting end time of a proposal
proposed_blocks Number of proposed blocks per validator (for a bonded validator)
rank Rank of the validator
seat_price Min seat price to be in the active set (ie. bonded tokens of the latest validator)
signed_blocks_window Number of blocks per signing window
skipped_blocks Number of blocks skipped (ie. not tracked) since start
slash_fraction_double_sign Slash penaltiy for double-signing
slash_fraction_downtime Slash penaltiy for downtime
solo_missed_blocks Number of missed blocks per validator, unless the block is missed by many other validators
tokens Number of staked tokens per validator
tracked_blocks Number of blocks tracked since start
transactions Number of transactions since start
upgrade_plan Block height of the upcoming upgrade (hard fork)
validated_blocks Number of validated blocks per validator (for a bonded validator)
vote Set to 1 if the validator has voted on a proposal

For an example of a Prometheus and Grafana dashboard setup using Docker Compose, you can refer to 21state/cosmos-watcher-stack.

❓FAQ

Which blockchains are compatible?

Any blockchains based on the cosmos-sdk should work:

  • cosmoshub
  • celestia
  • cronos
  • dydx
  • evmos
  • injective
  • kava
  • osmosis
  • persistence
  • dymension
  • zetachain
  • ...

This app is using the CometBFT library (successor of Tendermint) as well as the x/staking module from the Cosmos-SDK.

How to get your validator pubkey address?

Option 1: use tendermint show-validator to get the pubkey and debug pubkey to convert to hex format.

CLI_NAME=gaiad
ADDRESS="$($CLI_NAME debug pubkey "$($CLI_NAME tendermint show-validator)" 2>&1 | grep "Address")"
ADDRESS="${ADDRESS##* 0x}"
ADDRESS="${ADDRESS##* }"
echo "${ADDRESS^^}"

(replace gaiad by the binary name or the desired chain, eg. evmosd, strided, injectived, …).

Option 2: use the cosmos-validator-watcher debug consensus-key sub command:

cosmos-validator-watcher debug validator \
  --node https://cosmos-rpc.publicnode.com:443 \
  cosmosvaloper1uxlf7mvr8nep3gm7udf2u9remms2jyjqvwdul2

Notes:

  • the --node flag must be placed before the validator address)
  • this doesns't work for consumer chains (neutron, stride) since they don't rely on the staking module

📃 License

MIT License.