Chain Sight

Chain Sight collects validators, their delegators and governance proposals from Cosmos SDK chains and stores them in a SQL database — PostgreSQL or SQLite — for querying and reporting.

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

Requirements

• Python 3 (3.8 or newer recommended)
• A REST (LCD) endpoint for each chain
• PostgreSQL, or nothing extra for SQLite

Install

git clone https://github.com/ChainTools-Tech/chain_sight.git && cd chain_sight
python3 -m venv .venv && . .venv/bin/activate
pip install .
pip install psycopg2-binary   # only for PostgreSQL

Database

Set DATABASE_URL in the environment or in a .env file in the folder you run Chain Sight from:

DATABASE_URL=postgresql://<USER>:<PASSWORD>@localhost/chain_sight

Without DATABASE_URL, Chain Sight uses a SQLite file, chainsight.db, in the current folder. Tables are created on the first run: chain_config, validators, delegators and governance_proposals.

Chain list

Chains are imported from a JSON file into the database:

{
  "chains": [
    {
      "name": "BitSong",
      "chain_id": "bitsong-2b",
      "prefix": "bitsong",
      "rpc_endpoint": "https://rpc.bitsong.chaintools.tech",
      "api_endpoint": "https://api.bitsong.chaintools.tech",
      "grpc_endpoint": "grpc.bitsong.chaintools.tech:443"
    }
  ]
}

name, chain_id, prefix, rpc_endpoint and api_endpoint are required; grpc_endpoint is optional. Data is fetched over the REST endpoint. Importing again updates changed fields of chains with the same chain_id.

Usage

chain_sight --config import --config-path chains.json   # import or update the chain list
chain_sight --config display                             # print the stored chain list as JSON
chain_sight --fetch validators --chain bitsong-2b        # validators and their delegators
chain_sight --fetch governance --chain bitsong-2b        # governance proposals

Option	Default	Meaning
--config import|display	—	Manage the chain list (use either --config or --fetch)
--config-path	—	JSON file, required with --config import
--fetch validators|governance	—	What to fetch
--chain	—	Chain ID from the chain list, required with --fetch
--log-file	chain_sight.log	Log file
--log-level	INFO	DEBUG, INFO, WARNING, ERROR or CRITICAL

What gets stored:

• validators — all validators of the chain, then every delegation of each validator; delegators that have left are removed.
• governance — all proposals, from cosmos/gov/v1 or, on older chains, v1beta1; existing proposals are updated.

Run the fetch commands from cron to keep the data current.

WARNING

Chain Sight requests to the REST endpoints are made without TLS certificate verification.