Cosmos Validator Monitoring Service(CVMS) 🌌 🔭

✅ Validators in Cosmos-SDK-based chains sometimes have additional responsibilities beyond block production. In this document, we refer to these responsibilities as duties.

Background About CVMS

The Cosmos ecosystem comprises app chains built on Cosmos-SDK, which, despite having similar system architectures, often require validators to perform a wider range of customized duties (like oracle or EVM bridging services) in addition to maintaining standard consensus security.

For example, a duty might have different names or applications across Chain A and Chain B.

As a result, validators use different custom paths designated by each app chain to check their current status and prevent penalties, such as slashing, when performing specific duties. Moreover, for duties outside the consensus, it’s challenging to quickly verify the state of the network and ensure each validator is compliant.

To alleviate the burden of checking various conditions unique to the Cosmos ecosystem, Cosmostation has developed the Cosmos Validator Monitoring System (CVMS), an integrated monitoring system for validators and network maintainers in the Cosmos ecosystem.

Through CVMS, we aim to provide validators, blockchain network maintainers, and other developers in the Cosmos ecosystem with a straightforward way to monitor and overview the consensus, duties, and other unique characteristics of each Cosmos app chain as integrated metrics without additional effort.

Description

The Cosmos Validator Monitoring Service (CVMS) is an integrated monitoring system for validators within the Cosmos app chain ecosystem.

CVMS consolidates key metrics essential to validators and the network, such as slashing uptime, oracle status, and bridge status, into a single metric view for each chain.

CVMS supports two modes: validator mode(for monitoring whitelisted validator) and network mode(for monitoring all validators in the network), determined by the moniker setup in the configuration. For instance, specifying moniker=['Cosmostation1', 'Cosmostation2'] enables monitoring of specific validators, representing validator mode, while moniker=['all'] monitors all validators, representing network mode.

Depending on the mode, CVMS provides different overviews.

🚀 Validator Mode

In validator mode, CVMS offers an overview that makes it easy to check the essential elements required for validators.

• Example of an integrated dashboard for a solo validator

🛰️ Network Mode

In network mode, CVMS provides an overview that allows users to check the status of the network alongside the state of distributed validators concerning elements essential to a specific chain.

• Example Network Mode Dashboard For Oracle Duty

• Example Network Mode Dashbord For Vote Extension

Supported Packages

The packages currently supported by CVMS are as follows:

Run CVMS

We recommend running the CVMS application in Docker by default. If there are components in the default Docker Compose setup that you find unnecessary, you can disable them with a Docker override.

Initially, we could not account for all app chains within the Cosmos ecosystem. Therefore, by default, this application operates based on the chains listed in support_chains.yaml

If the chain you want to monitor is not in the support chain list, you can add it to the custom_chains.yaml list or update the support chains list through a PR.

If you want to know more details how to setup CVMS from scratch, Click here👇

# 1. Create a config file from example config
# case1) for validator mode
cp .resource/example-validator-config.yaml config.yaml
# case2) for network mode
cp .resource/example-network-config.yaml config.yaml

# 2. Modify config yaml
vi config.yaml

# 3. Custom the enviroments to suit your needs
# This is not necessary, but if you want to make custom config for prometheus, alertmanger or cvms's log level
cp .resource/.env.example .env

# 4. Run cvms
docker compose up --build -d

Additional Information

Alerting Rule Samples

We provide alerting rules for easy use by developers. 👉 Check here!

Grafana Dashboards Samples

We provide basic dashboards for easy use by developers. 👉 Check here!

Prometheus Metrics Description

All metrics are prefixed with cvms as the namespace, with the package name as a subspace.

• Metric name format: cvms_<package-name>_<metric-name>
• For example: cvms_block_timestamp

Block Package Metrics

• cvms_block_height (by node): This value represents the latest block's height from the connected endpoint.

• Default labels: chain, chain_id, mainnet, package

• Package-specific labels: endpoint

• cvms_block_timestamp (by node): This value represents the latest block's timestamp from the connected endpoint.

• Default labels: chain, chain_id, mainnet, package
• Package-specific labels: endpoint

Uptime Package Metrics

• cvms_uptime_min_signed_per_window (by network): This value represents the minimum signed blocks per window to prevent slashing as a validator.

• Default labels: chain, chain_id, mainnet, package

• cvms_uptime_signed_blocks_window (by network): This value represents the number of blocks per window for evaluation.

• Default labels: chain, chain_id, mainnet, package

• cvms_uptime_missed_blocks_counter (by validator): This value represents the count of missed blocks in the current slashing info.

• Default labels: chain, chain_id, mainnet, package
• Package-specific labels: proposer address, validator_operator_address, validator_consensus_address

Balance Package Metrics

• cvms_balance_remaining_amount (by config): This value represents the remaining balance amount being monitored.
• Default labels: chain, chain_id, mainnet, package
• Package-specific labels: balance_address

Upgrade Package Metrics

• cvms_upgrade_remaining_time (by network): This value represents the remaining seconds for an on-chain upgrade.
• Default labels: chain, chain_id, mainnet, package
• Package-specific labels: upgrade_name

Eventnonce Package Metrics

• cvms_eventnonce_highest_nonce (by network): This value represents the highest event nonce value in the network.

• Default labels: chain, chain_id, mainnet, package

• cvms_eventnonce_nonce (by validator): This value represents the current event nonce value for a validator.

• Default labels: chain, chain_id, mainnet, package
• Package-specific labels: moniker, validator_operator_address, orchestrator_address