Multi-chain blockchain indexer with SOLID principles and Clean Architecture
blockchain-indexer is a scalable multi-chain blockchain indexer that indexes block and transaction data from various blockchains including EVM, Solana, Cosmos, Polkadot, Avalanche, and Ripple, and provides access through GraphQL, gRPC, and REST APIs.
- EVM Chains: Ethereum, BSC, Polygon, Arbitrum, Optimism, etc.
- Solana: Solana mainnet, devnet, testnet
- Cosmos: Cosmos Hub, Osmosis, and other Cosmos SDK chains
- Polkadot: Polkadot, Kusama, and Substrate-based chains
- Avalanche: C-Chain, X-Chain, P-Chain
- Ripple: XRPL (XRP Ledger)
- SOLID Architecture: Follows SOLID principles for maintainability
- Clean Architecture: Separated layers (Domain, Application, Infrastructure, Presentation)
- Pluggable Adapters: Easy to add new blockchain support
- Efficient Storage: PebbleDB for high-performance embedded storage
- High-Performance Event Bus: 100M+ events/sec delivery
- Flexible Querying: GraphQL, gRPC, and REST API support
- Real-time Statistics: Live indexing metrics and chain statistics
- Gap Detection & Recovery: Automatic detection and filling of missing blocks
- Performance Optimization: LRU caching, batch operations, configurable profiles
- Health Monitoring: Comprehensive health checks and observability
- GraphQL API: Flexible querying with filtering and pagination
- gRPC API: High-performance RPC with TLS 1.2+
- REST API: Standard HTTP API with TLS 1.2+
- TLS 1.2+ Support: Secure communication for all APIs
- Authentication: JWT-based authentication support
┌─────────────────────────────────────────────────────┐
│ Presentation Layer (APIs) │
│ GraphQL │ gRPC │ REST API │
└──────────────┴─────────────┴────────────────────────┘
│
┌─────────────────────▼─────────────────────────────┐
│ Application Layer (Use Cases) │
│ Indexer │ Block Processor │ Query Handler │
└──────────────┬────────────────────────────────────┘
│
┌──────────────▼────────────────────────────────────┐
│ Domain Layer (Business Logic) │
│ Models │ Repositories │ Services │
└──────────────┬────────────────────────────────────┘
│
┌──────────────▼────────────────────────────────────┐
│ Infrastructure Layer (External) │
│ Chain Adapters │ Storage │ Event Bus │
│ EVM │ Solana │ Cosmos │ Polkadot │ ... │
└───────────────────────────────────────────────────┘
For detailed architecture, see ARCHITECTURE.md
- Architecture - System architecture and design principles
- Directory Structure - Project layout and organization
- Deployment Guide - Docker, systemd, and production deployment
- CI/CD Guide - GitHub Actions workflows and automation
- API Reference - Complete API documentation (GraphQL, gRPC, REST)
- GraphQL Schema - GraphQL schema definition
- gRPC Protocol Buffers - Protocol Buffer definitions
- Chain Adapter Guide - How to use and add new blockchain support
- Performance Guide - Optimization strategies and configuration
- Monitoring Guide - Health checks, metrics, and troubleshooting
- Go 1.21 or higher
- Git
# Clone repository
git clone https://github.com/sage-x-project/blockchain-indexer.git
cd blockchain-indexer
# Install dependencies
go mod download
# Copy example config and customize
cp config/config.example.yaml config/config.yaml
# OR use chain-specific configs:
# For Solana: cp config/config-solana.example.yaml config/config.yaml
# For Cosmos: cp config/config-cosmos.example.yaml config/config.yaml
# For Polkadot: cp config/config-polkadot.example.yaml config/config.yaml
# For Avalanche: cp config/config-avalanche.example.yaml config/config.yaml
# For Ripple: cp config/config-ripple.example.yaml config/config.yaml
# Build the indexer
go build -o bin/indexer ./cmd/indexer# Start the API server with your configuration
./bin/indexer server --config config/config.yaml
# The server will start with the following endpoints:
# - REST API: http://localhost:8080/api
# - GraphQL: http://localhost:8080/graphql
# - gRPC: localhost:50051
# - Health: http://localhost:8080/health
# - Metrics: http://localhost:9091/metrics# Test health endpoint
curl http://localhost:8080/health
# Test REST API
curl http://localhost:8080/api/
# Test GraphQL (access GraphQL Playground)
open http://localhost:8080/graphql
# Run integration tests
go test -v ./test/integration/...# Show all available commands
./bin/indexer --help
# Start API server
./bin/indexer server --config config/config.yaml
# Start blockchain indexing
./bin/indexer index --config config/config.yaml
# Show version information
./bin/indexer version
# Manage configuration
./bin/indexer config --help# Build and run with Docker Compose (includes Prometheus & Grafana)
docker-compose up -d
# Access services:
# - Indexer API: http://localhost:8080
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3000 (admin/admin)
# View logs
docker-compose logs -f indexer
# Stop services
docker-compose downFor detailed deployment instructions, see DEPLOYMENT.md
The blockchain indexer has been developed through a phased approach, with all core phases now complete:
The project includes:
- Foundation layer with clean architecture and SOLID principles
- Multi-chain support for EVM, Solana, Cosmos, Polkadot, Avalanche, and Ripple
- Complete API layer with GraphQL, gRPC, and REST endpoints
- Production deployment with Docker and CI/CD automation
- Advanced features including real-time statistics, gap detection, and monitoring
Current Version: 1.0.0-rc1
This project is licensed under the MIT License - see the LICENSE file for details.
Current Version: 1.0.0-rc1
Last Updated: 2025-10-31