Delegator Tracker

Delegator Tracker counts the delegators and totals the stake of Cosmos SDK validators, optionally with a USD value from CoinMarketCap. It shows the result as a terminal table, a small web page or Prometheus metrics.

Source on GitHub · Summary on chaintools.tech · MIT licence

Requirements

• Python 3.8 or newer
• A REST (LCD) endpoint for each chain
• Optional: a CoinMarketCap API key for USD values

Install

git clone https://github.com/ChainTools-Tech/delegator_tracker.git && cd delegator_tracker
python3 -m venv .venv && . .venv/bin/activate
pip install .

Configuration

Default location: ~/.chaintools/delegator_tracker.yaml (override with --config).

nodes:
  - name: BitSong
    api_url: https://api.bitsong.chaintools.tech
    cmc_api_id: "<COINMARKETCAP_ID>"
    base_denom: ubtsg
    display_denom: BTSG
    exponent: 6
    validators:
      - validator_id: bitsongvaloper1...

Key	Meaning
name	Chain name shown in the output
api_url	REST endpoint of the chain
cmc_api_id	CoinMarketCap ID of the coin — required key; the price is only fetched when an API key is set
base_denom	Base denom (informational)
display_denom	Symbol shown in the output
exponent	Decimals between base and display denom (default 6)
validators[]	validator_id: the validator operator address

For USD values, put the API key in a .env file in the folder you run the tool from:

COINMARKETCAP_API_KEY=<YOUR_KEY>
# optional, this is the default:
COINMARKETCAP_API_URL=https://pro-api.coinmarketcap.com/v2/cryptocurrency/quotes/latest

Without a key, USD values are reported as 0.

Usage

--mode and --chain are required in every mode. All chains in the configuration are processed regardless of --chain, so pass --chain all.

Table in the terminal

delegator-tracker --mode cli --chain all --config config.yaml

Prometheus exporter

delegator-tracker --mode exporter --chain all --config config.yaml --interval 60

Web page

# run from the repository folder: the page template is loaded from ./templates
delegator-tracker --mode web --chain all --config config.yaml

Option	Default	Meaning
--mode	— (required)	cli, exporter or web
--chain	— (required)	See above; use all
--config	~/.chaintools/delegator_tracker.yaml	Configuration file
--interval	60	Exporter refresh interval in seconds
--log-level	INFO	DEBUG, INFO or WARNING

The exporter and the web page both listen on port 8000 (the web page on all interfaces). Orbit Metrics also uses port 8000, so the two can't run on the same host; Cert Expiry Checker can be moved to another port.

Output

The table and web page show, per validator: chain, validator address, number of delegators, total stake in the display denom, total stake in USD, and the denom.

Prometheus metrics:

Metric	Labels	Value
delegator_tracker_delegator_count	validator	Number of delegators
delegator_tracker_total_stake	validator, denom	Total stake in the display denom
delegator_tracker_total_stake_usd	validator	Total stake in USD (0 without an API key)

Total stake is the sum of all delegations' shares, divided by 10^exponent.