built by Citizen Web3 for ValidatorInfo

• Cosmos Hub - Development 🚧
• Aztec Protocol - Production ✅

• Overview
• Supported Networks
• Features
• Architecture
• Requirements
• Installation
• Quick Start
• Configuration
• Usage
• Makefile Shortcuts
• Troubleshooting
• Development Notes
• Contributing
• License

Chain Data Indexer (CDI) is a high-performance, modular blockchain data indexer designed for powering block explorers, analytics platforms, DeFi dashboards, compliance tools, and research projects.
It extracts, processes, and stores blockchain data from various networks into a PostgreSQL database, enabling fast and flexible querying.

• 🧭 Primary Use Case: Powering block explorers with rich, searchable blockchain data.
• 🌌 Extensible: Suitable for analytics, compliance, DeFi, R&D, and more.
• 🌐 Multi-Network: This is a monorepo with indexers for multiple blockchain networks.

CDI supports multiple blockchain networks. Each network has its own dedicated branch with specialized implementation:

To work with a specific network indexer, switch to the corresponding branch:

# For Cosmos Hub indexer (this branch)
git checkout main

# For Aztec Protocol indexer
git checkout aztec

💡 Note: Each branch contains network-specific configuration, schemas, and documentation. Make sure to read the branch-specific README for detailed setup instructions.

Note: The features below are specific to the Cosmos Hub indexer. For other networks, please refer to the respective branch documentation.

• 🚀 High Performance: Efficiently processes large volumes of blocks and transactions.
• 🔄 Resumable Indexing: Smart resumption from the last indexed block to prevent data loss.
• 🐳 Dockerized: Simple deployment with Docker Compose.
• 🗄️ PostgreSQL Integration: Robust, scalable storage with partitioning and indexing.
• 📊 Advanced Decoding: Supports rich message/transaction type extraction.
• ⚡ Real-time Capable: Block-by-block processing with adjustable concurrency.
• 🔌 Modular Branches: Each supported network can be developed and maintained independently.

• RPC Client: Interfaces with blockchain RPC endpoints.
• Message Decoder: Dynamically generates message type definitions for supported chains.
• Database Layer: Optimized PostgreSQL schema with automatic partitioning.
• Configuration System: Environment-based, validated configuration.

• Node.js (v22+ recommended or v22.18.0 LTS for the best experience)
• yarn
• Docker & docker-compose

git clone https://github.com/citizenweb3/indexer.git
cd indexer

yarn install --frozen-lockfile

1. Copy and configure your environment:

   cp .env.example .env
   # Edit .env as needed

2. Build and start all services:

   docker compose --env-file .env up --build -d

3. View indexer logs:

   docker compose logs -f indexer

By default, the indexer will resume from the last processed block (RESUME=true) and use Postgres as the sink.

docker compose down -v

docker compose --env-file .env up -d db

All configuration is managed through environment variables.
See .env.example for a complete list.

1. Install dependencies:

   yarn install --frozen-lockfile

2. Create a .env file:

   cp .env.example .env
   # Edit as necessary

3. Generate runtime artifacts:

   npx tsx scripts/gen-known-msgs.ts

4. Run Postgres (via Docker):

   make up

5. Start the indexer:

   npm run start

Need more memory?
export NODE_OPTIONS=--max-old-space-size=24576

• make up — Start db via docker-compose
• make down — Stop services
• make reset — Remove volumes and re-init DB
• make logs — Show DB logs (docker compose --env-file .env logs -f db)
• make psql — Exec psql inside the Postgres container
• make psql-file FILE=path/to/script.sql — Copy and run a SQL file inside the DB container

• Indexer fails due to memory? Increase NODE_OPTIONS.
• Check your .env for correct DB and RPC settings.
• Use make reset to reinitialize your database if needed.

• Runs TypeScript directly via tsx during development.
• No tests by default; please add smoke tests for core logic changes.
• See Makefile and Docker Compose files for advanced operations.

Contributions are welcome!
Open issues/PRs for improvements, bug fixes, or new features.

For significant changes, please open an issue to discuss your ideas first.

BE GOOD License for details.