Repository: subquery/subql
Stars: 18817
CLAUDE.md
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Plan and Reivew
Before Starting work
- Always in planning mode, to make a plan
- After the plan is made, make sure to write the plan to ./.claude/tasks/TASK_NAME.md
- The plan should be a detailed implementation and the reasoning behind them as well as the tasks broken down
- If the task requires external knowledge or certain dependencies, also research to get the latest knowledge. (Use the Task tool for research)
- Don't over plan it, always design an MVP
- Once you make the plan, firstly ask me to review it . Do not continue until I approve the plan
While implementing
- The plan should be updated as you work
- After completing tasks in the plan you should append a detailed description of the channges you made, so the following tasks can be handed over to other engineers
Development Commands
Building
-
yarn build - Build all packages in the workspace using TypeScript- Individual package builds use
tsc -b and copy necessary files (e.g., CLI templates)Testing
-
yarn test - Run Jest tests with coverage in UTC timezone-
yarn test:ci - Run tests in CI mode with specific patterns-
yarn test:docker - Run tests in Docker containersLinting and Code Quality
-
yarn lint - Run ESLint across all TypeScript files in packages- Uses ESLint with TypeScript support, Prettier, and various plugins
- Configured with husky pre-commit hooks and lint-staged
CLI-Specific Commands (packages/cli)
-
yarn build - Builds CLI and copies templates to lib/-
yarn format - Format code using Prettier-
yarn codegen - Generate GraphQL and API client code-
yarn codegen:graphql - Generate GraphQL types-
yarn codegen:chs - Generate consumer host service API clientProject Architecture
Monorepo Structure
This is a Yarn workspace monorepo containing multiple packages:
- @subql/cli - Command-line interface for SubQuery projects (OCLIF-based)
- @subql/node - Substrate-specific SubQuery indexer implementation
- @subql/node-core - Core chain-agnostic indexing functionality
- @subql/query - GraphQL query service
- @subql/common - Shared utilities and types
- @subql/common-substrate - Substrate-specific common utilities
- @subql/types-core - Core type definitions
- @subql/utils - General utility functions
CLI Commands Architecture
The CLI uses OCLIF framework with commands organized by functionality:
- Core project lifecycle: init, build, publish
- Code generation: codegen (GraphQL types, ABI imports)
- Multi-chain support: multi-chain add
- Network operations: Commands for SubQuery Network (deployments, projects, API keys, boosts)
- OnFinality hosting: Project and deployment management
- Migration tools: Project upgrade utilities
- MCP integration: Model Context Protocol support for AI tools
Key Technologies
- TypeScript throughout with strict configuration
- OCLIF for CLI framework
- Jest for testing with custom module mapping for workspace packages
- ESBuild and Webpack for bundling
- GraphQL code generation
- Zod for schema validation
- Ethers.js for Ethereum integration
- WalletConnect for wallet interactions
Development Patterns
#### Package Dependencies
Uses Yarn workspace protocol (workspace:~) for internal package dependencies to ensure proper linking during development.
#### Testing Setup
- Custom Jest configuration with module name mapping for workspace packages
- UTC timezone enforcement for consistent test behavior
- Coverage collection across multiple packages
- Special handling for Polkadot packages in transform ignore patterns
#### CLI Command Structure
Commands follow a consistent pattern:
- Input validation using Zod schemas
- Adapter functions for shared logic between CLI and MCP modes
- Structured logging and error handling
- Progress indication using ora spinner
#### MCP Integration
The CLI supports Model Context Protocol for AI tool integration, allowing commands to be executed through AI interfaces like Cursor.
Build System
- TypeScript compilation with project references
- Template copying for CLI (EJS templates in src/template → lib/template)
- OCLIF manifest generation for command discovery
- Automatic README generation from command help
Network Support
SubQuery supports multiple blockchain networks:
- Polkadot/Substrate (primary)
- Ethereum and EVM-compatible chains
- Cosmos/CosmWasm
- Algorand, NEAR, Stellar, Solana, Starknet, Concordium
Each network has its own implementation repository, with this repo containing the core Substrate implementation and shared components.
README.md
Welcome to SubQuery!
Flexible, reliable, and decentralised APIs for your web3 project
SubQuery is an Open, Flexible, Fast and Universal data indexing framework for web3. Our mission is to help developers create the decentralised products of the future.
SubQuery allows teams across multiple blockchain architectures to process and query their data. The project is inspired by the growth of data protocols serving the application layer and its aim is to help web3 projects build better dApps by allowing anyone to reliably find and consume data faster. Today, anyone can query and extract blockchain data from various supported networks in only minutes and at no cost.
The future is multi-chain - SubQuery is no different. SubQuery is well on our way to support all leading blockchain networks with support for the following:
- Polkadot (and all Substrate networks)
- Ethereum (and all EVM-compatible networks)
- Cosmos (and all CosmWasm and Ethermint networks)
- Algorand
- NEAR
- Stellar (including Soroban)
- Solana (Beta)
- Starknet
- Concordium
You can also use SubQuery to index data from multiple networks in any combination of the above SDKs. See our Multi-Chain Indexing Quickstart for more details.
Get Started
Create a SubQuery project
You can follow our Quick Start Guide to learn how to create, initialize, build, and publish a new SubQuery Project using the @subql/cli tool.
Learn and improve with our comprehensive documentation
Dig into every term, usecases, and best-practices that help you build a dApp which your users love. Take a look at our detailed technical documentation.
Publish your SubQuery Project to the SubQuery Network
Take advantage of the decentralized SubQuery Network to host your project without managing any infrastructure. By publishing to the SubQuery Network, you'll benefit from a reliable, scalable, cost-optimised, and censorship-resistant indexing service. Follow our comprehensive publishing guide to learn how to upload your project to the network and start leveraging its distributed infrastructure today.
Publish to managed hosting providers
If you prefer a managed hosting option for your indexer deployment, contact our managed hosting partners.
Learn more.
Run your own Indexer and Query Service
Follow our guide to run your own SubQuery local node that you can use to debug, test, and run you own GraphQL server.
You're going to need to a Postgres database, a node to extract chain data, and a moderately powerful computer to run the indexer in the background.
You'll also use our custom-built GraphQL query service @subql/query to interact with your SubQuery project.
MCP (Beta)
You can also create, build and deploy SubQuery projects using MCP (Model Context Protocol). Our MCP integration provides all the same functionality as the CLI but works well with LLMs and AI IDEs such as Cursor.
Manual configuration
For adding SubQuery MCP into other tools, the following command needs be run by the client.
npx -y @subql/cli mcpAn example manual configuration:
"subquery": {
"command": "npx",
"args": ["-y", "@subql/cli", "mcp"]
}Components
This repository contains all the core components of the SubQuery SDK as well as the Substrate implementation. It includes the following packages:
* @subql/cli - The command line interface for SubQuery, used to create, build, and publish SubQuery projects
* @subql/node - The Substrate SubQuery SDK, which provides the indexing functionality for Substrate-based chains
* @subql/node-core - Core indexing functionality that is chain agnostic
* @subql/query - The GraphQL query service for SubQuery projects, allowing you to interact with your indexed data.
* @subql/common - Common utilities and types used across SubQuery packages
* @subql/common-substrate - Common utilities and types specifically for Substrate-based chains
* @subql/types - Type definitions for Substrate-based chains and SubQuery projects, including the project manifest and data models
For more detail on the specific network implementations please see their respective repositories:
* @subql/node-ethereum
* @subql/node-cosmos
* @subql/node-algorand
* @subql/node-near
* @subql/node-stellar
* @subql/node-solana
* @subql/node-starknet
* @subql/node-concordium
Other Components:
* @subql/query-subgraph - A Subgraph compatible query service for SubQuery projects.
Support
We have a vibrant community of developers and users who are always ready to help. If you have any questions, issues, or need assistance, please reach out to us through the following channels:
- Discord - The best place to get help and discuss with the community
- X
- Telegram
- YouTube
Contribute
We love contributions and feedback from the community. To contribute the code, we suggest starting by creating an issue in our main repository so we can give you support.
Copyright
SubQuery is a project built with love from the team at SubQuery all the way from New Zealand
Copyright © 2025 SubQuery Pte Ltd authors & contributors