Delegator Tracker

Track validator delegators and stake amounts across Cosmos-based blockchains

ChainTools

Overview

Delegator Tracker is a Python-based tool designed to help validators monitor their delegators and stake amounts across various Cosmos SDK-based blockchains. It provides valuable insights into delegation patterns, helps identify changes in staking behavior, and enables validators to better understand their delegator base.

For validators operating in the Cosmos ecosystem, understanding delegation patterns is crucial for maintaining a competitive edge and providing better service to delegators. The Delegator Tracker tool automates the collection and analysis of delegation data, providing validators with actionable insights.

The tool can track delegations across multiple chains, generate reports and visualizations, and help validators identify trends or changes that might require attention. This data can inform validator decisions about commission rates, services offered, and communication strategies.

Key Features

  • Multi-Chain Support - Track delegations across multiple Cosmos SDK-based blockchains simultaneously.
  • Historical Data Tracking - Store and analyze delegation history to identify trends and changes over time.
  • Delegator Analysis - Identify top delegators, new delegations, and withdrawals with detailed metrics.
  • Customizable Reporting - Generate reports in various formats including CSV, JSON, and console output.
  • Delegation Change Alerts - Receive notifications about significant changes in delegation patterns.
  • Address Labeling - Add custom labels to delegator addresses for easier identification and analysis.

Installation

Install Delegator Tracker from GitHub:

git clone https://github.com/ChainTools-Tech/delegator_tracker
cd delegator_tracker
pip install -r requirements.txt

Requirements

  • Python 3.8 or higher
  • pip package manager
  • Access to RPC endpoints for your target blockchains
  • Optional: PostgreSQL database for historical data storage

Usage

Configure your validators and run the tracker to monitor delegations:

# Run the tracker with the default configuration
python3 delegator_tracker.py

# Specify a custom configuration file
python3 delegator_tracker.py --config my_config.yaml

# Track only specific chains
python3 delegator_tracker.py --chains juno,osmosis,cosmos

# Generate a report for a specific time period
python3 delegator_tracker.py --start-date 2025-01-01 --end-date 2025-04-01

# Export data to CSV
python3 delegator_tracker.py --export csv --output delegations.csv

Configuration

Create a YAML configuration file to specify validators and chains to track:

chains:
  juno:
    rpc_endpoint: "https://rpc.juno.chaintools.tech"
    validator_address: "junovaloper1dru5985k4n5q369rxeqfdsjl8ezutch8mc6nx9"
    validator_name: "ChainTools"
  osmosis:
    rpc_endpoint: "https://rpc.osmosis.chaintools.tech"
    validator_address: "osmovaloper1clpqr4nrk4khgkxj78fcwwh6dl3uw4epasmvn6"
    validator_name: "ChainTools"

settings:
  update_frequency: 24 # hours
  store_history: true
  db_connection: "postgresql://user:password@localhost/delegator_tracker"
  notification:
    enabled: true
    threshold_change: 5 # percentage
    email: "alerts@example.com"

Data Analysis and Insights

Delegator Tracker provides rich analytics to help validators understand their delegator base:

Sample Output

Chain: Juno
Validator: ChainTools (junovaloper1dru5985k4n5q369rxeqfdsjl8ezutch8mc6nx9)
Total Delegators: 324
Total Stake: 1,532,456 JUNO

Top 5 Delegators:
1. juno1abcdef... (Label: CEX-Binance) - 250,000 JUNO (16.3%)
2. juno1ghijkl... (Label: Foundation) - 150,000 JUNO (9.8%)
3. juno1mnopqr... - 75,000 JUNO (4.9%)
4. juno1stuvwx... (Label: Whale-1) - 62,500 JUNO (4.1%)
5. juno1yzabcd... - 45,000 JUNO (2.9%)

Recent Changes (Last 7 days):
- New Delegations: 12 (Total: +85,000 JUNO)
- Withdrawals: 3 (Total: -22,500 JUNO)
- Net Change: +62,500 JUNO (+4.2%)

Distribution Analysis:
- Top 10 delegators control 48.2% of stake
- Median delegation size: 1,250 JUNO
- Delegator retention rate: 97.3% (monthly)

Data Visualization

The tool can generate visualizations to help understand delegation distribution, historical trends, and comparative analysis across chains. These visualizations make it easier to identify patterns and communicate insights to stakeholders.

Sample Delegator Distribution Chart

Related Resources