Chain Sight

Fetch and store blockchain data in PostgreSQL for analysis and monitoring

ChainTools

Overview

Chain Sight is a command-line tool designed for fetching blockchain data (validators and governance proposals) and storing it in a PostgreSQL database. It supports multiple blockchain networks and allows users to manage chain configurations and fetch data efficiently via the command line.

Chain Sight simplifies the process of collecting and organizing blockchain data for analysis, monitoring, and reporting. By storing the data in a structured PostgreSQL database, it becomes easier to run queries, generate insights, and build applications on top of the data.

The tool is particularly valuable for blockchain analysts, developers, and operators who need to track validator performance, governance activities, and other on-chain metrics across multiple networks. Its modular design allows for easy extension to support new blockchain networks and data types.

Key Features

  • Multi-Chain Support - Fetch data from multiple Cosmos SDK-based blockchains with a unified interface.
  • Validator Data Collection - Retrieve detailed validator information including voting power, commission rates, and status.
  • Governance Tracking - Collect governance proposal data including voting status, content, and outcomes.
  • PostgreSQL Storage - Store all blockchain data in a structured PostgreSQL database for easy querying and analysis.
  • Chain Configuration Management - Import and manage blockchain network configurations from a JSON file.
  • Command-Line Interface - Simple and intuitive CLI for all operations, making it easy to automate data collection.
  • Historical Data Support - Track changes over time with timestamped data collection and historical records.

Installation

Install Chain Sight from GitHub:

git clone https://github.com/ChainTools-Tech/chain_sight
cd chain_sight
pip install -e .

# Or install directly from GitHub
pip install git+https://github.com/ChainTools-Tech/chain_sight.git

Requirements

  • Python 3.8 or higher
  • PostgreSQL database
  • psycopg2 (PostgreSQL adapter for Python)
  • SQLAlchemy (ORM for database interaction)
  • Click (for CLI interface)
  • Access to RPC endpoints for target blockchains

Usage

First, configure your database connection and import chain configurations:

# Set up environment variables for database connection
export DB_CONNECTION="postgresql://username:password@localhost/chain_sight"

# Import chain configurations
chain-sight import-chain --file chains.json

# List configured chains
chain-sight list-chains

# Fetch validator data for a specific chain
chain-sight fetch-validators --chain juno

# Fetch all chains
chain-sight fetch-validators --all

# Fetch governance proposals
chain-sight fetch-proposals --chain cosmos

Configuration

Create a chains.json file to configure the blockchains you want to track:

[
  {
    "name": "juno",
    "display_name": "Juno Network",
    "rpc_endpoint": "https://rpc.juno.chaintools.tech",
    "rest_endpoint": "https://rest.juno.chaintools.tech",
    "chain_id": "juno-1",
    "prefix": "juno",
    "denom": "ujuno",
    "exponent": 6,
    "symbol": "JUNO"
  },
  {
    "name": "cosmos",
    "display_name": "Cosmos Hub",
    "rpc_endpoint": "https://rpc.cosmos.network",
    "rest_endpoint": "https://rest.cosmos.network",
    "chain_id": "cosmoshub-4",
    "prefix": "cosmos",
    "denom": "uatom",
    "exponent": 6,
    "symbol": "ATOM"
  }
]

Database Schema

Chain Sight stores blockchain data in a PostgreSQL database with the following schema:

Validators Table

CREATE TABLE validators (
  id SERIAL PRIMARY KEY,
  chain_id INTEGER REFERENCES chains(id),
  address VARCHAR(255) NOT NULL,
  moniker VARCHAR(255),
  identity VARCHAR(255),
  website VARCHAR(255),
  details TEXT,
  security_contact VARCHAR(255),
  commission_rate DECIMAL,
  commission_max_rate DECIMAL,
  commission_max_change_rate DECIMAL,
  min_self_delegation BIGINT,
  tokens BIGINT,
  delegator_shares DECIMAL,
  status VARCHAR(50),
  jailed BOOLEAN,
  unbonding_height BIGINT,
  unbonding_time TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(chain_id, address, created_at)
);

Governance Proposals Table

CREATE TABLE proposals (
  id SERIAL PRIMARY KEY,
  chain_id INTEGER REFERENCES chains(id),
  proposal_id INTEGER,
  title VARCHAR(255),
  description TEXT,
  proposal_type VARCHAR(100),
  status VARCHAR(50),
  submit_time TIMESTAMP,
  deposit_end_time TIMESTAMP,
  voting_start_time TIMESTAMP,
  voting_end_time TIMESTAMP,
  total_deposit JSONB,
  final_tally_result JSONB,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(chain_id, proposal_id)
);

CLI Commands

Chain Sight provides a comprehensive command-line interface for managing blockchain data collection:

Import Chain Configuration

chain-sight import-chain --file chains.json

Imports chain configurations from a JSON file to the database.

List Configured Chains

chain-sight list-chains

Lists all configured chains in the database.

Fetch Validators

chain-sight fetch-validators --chain juno

Fetches validator data for a specific chain.

Fetch Governance Proposals

chain-sight fetch-proposals --chain cosmos

Fetches governance proposal data for a specific chain.

Related Resources