subgraph-development-guide
Skill8 starsChanged 9 months agoMITView on GitHub
Guide to building blockchain data indexes with The Graph — subgraph architecture, schema design, mapping handlers, deployment, and querying. Covers GraphQL APIs for DEX data, token transfers, and DeFi protocol events. Use when explaining blockchain indexing or building custom data pipelines.
- Installs packages
In this repository45 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- llms-full.txtllms.txt
- llms.txtllms.txt
- sperax-skillsSkill
- agent-wallet-securitySkill
- ai-agent-defi-guideSkill
- airdrop-hunting-guideSkill
- arbitrum-defi-guideSkill
- chainlink-oracle-guideSkill
- cross-chain-bridge-guideSkill
- crypto-governance-guideSkill
- crypto-market-sentimentSkill
- crypto-news-aggregationSkill
- crypto-portfolio-managementSkill
- crypto-price-data-guideSkill
- crypto-tax-basicsSkill
- dca-strategy-guideSkill
- defi-dashboard-buildingSkill
- defi-lending-guideSkill
- defillama-analytics-guideSkill
- defi-risk-assessmentSkill
- defi-yield-strategiesSkill
- erc8004-agent-identitySkill
- gas-optimization-guideSkill
- impermanent-loss-explainedSkill
- mev-protection-guideSkill
- nft-analytics-guideSkill
- onchain-analytics-guideSkill
- plutus-plsassets-guideSkill
- plutus-protocol-overviewSkill
- plutus-vaults-guideSkill
- restaking-explainedSkill
- smart-contract-reading-guideSkill
- sperax-ecosystem-overviewSkill
- sperax-farms-guideSkill
- sperax-spa-stakingSkill
- sperax-usds-guideSkill
- stablecoin-mechanicsSkill
- token-approval-safetySkill
- token-discovery-guideSkill
- token-swap-best-practicesSkill
- web3-glossarySkill
- whale-watching-guideSkill
- yield-vault-guideSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
No aggregation (can't query "total volume last 7 days")
- Distinctive: line 18
No relationships (can't join swaps with token metadata)
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Subgraph Development Guide
The Graph is the indexing protocol for blockchain data. Subgraphs turn raw blockchain events into queryable GraphQL APIs. This guide covers how they work and how to build them.
Why Subgraphs?
The Problem
Reading blockchain data directly is painful:
- RPC calls are slow and sequential
- No aggregation (can't query "total volume last 7 days")
- No relationships (can't join swaps with token metadata)
- Rate limits on public RPCs
The Solution
Subgraphs listen to blockchain events, process them, and store structured data:
Blockchain Events → Subgraph Indexer → GraphQL API
(Swap, Transfer, (Processes, (Fast queries,
Mint, Burn) aggregates) relationships)Architecture
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 1. Schema │ │ 2. Mappings │ │ 3. Manifest │
│ (GraphQL types) │ │ (Event handlers)│ │ (subgraph.yaml) │
│ │ │ │ │ │
│ type Token { │ │ handleSwap(e) { │ │ dataSources: │
│ id: ID! │ │ // process │ │ - name: Pool │
│ symbol: String│ │ // and save │ │ source: │
│ volume: BigInt│ │ } │ │ abi: Pool │
│ } │ │ │ │ address: │
└─────────────────┘ └─────────────────┘ └─────────────────┘Three Core Files
| File | Purpose |
schema.graphql | Define your data model (entities) |
src/mapping.ts | Event handler functions (AssemblyScript) |
subgraph.yaml | Manifest — which contracts, events, and chains to index |
Building a Token Transfer Tracker
Step 1: Schema (schema.graphql)
type Token @entity {
id: ID! # Contract address
symbol: String!
name: String!
decimals: Int!
totalSupply: BigInt!
transferCount: BigInt!
holderCount: BigInt!
}
type Transfer @entity {
id: ID! # tx hash + log index
token: Token!
from: Bytes!
to: Bytes!
value: BigDecimal!
timestamp: BigInt!
blockNumber: BigInt!
}
type Account @entity {
id: ID! # Wallet address
balances: [AccountBalance!]! @derivedFrom(field: "account")
}
type AccountBalance @entity {
id: ID! # account-token
account: Account!
token: Token!
balance: BigDecimal!
}Step 2: Manifest (subgraph.yaml)
specVersion: 0.0.5
schema:
file: ./schema.graphql
dataSources:
- kind: ethereum
name: USDC
network: arbitrum-one
source:
address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
abi: ERC20
startBlock: 100000000
mapping:
kind: ethereum/events
apiVersion: 0.0.7
language: wasm/assemblyscript
entities:
- Token
- Transfer
- Account
abis:
- name: ERC20
file: ./abis/ERC20.json
eventHandlers:
- event: Transfer(indexed address,indexed address,uint256)
handler: handleTransfer
file: ./src/mapping.tsStep 3: Mapping (src/mapping.ts)
import { Transfer as TransferEvent } from "../generated/USDC/ERC20"
import { Token, Transfer, Account, AccountBalance } from "../generated/schema"
import { BigInt, BigDecimal } from "@graphprotocol/graph-ts"
export function handleTransfer(event: TransferEvent): void {
// Load or create token
let token = Token.load(event.address.toHexString())
if (token == null) {
token = new Token(event.address.toHexString())
token.symbol = "USDC"
token.name = "USD Coin"
token.decimals = 6
token.totalSupply = BigInt.fromI32(0)
token.transferCount = BigInt.fromI32(0)
token.holderCount = BigInt.fromI32(0)
}
token.transferCount = token.transferCount.plus(BigInt.fromI32(1))
token.save()
// Create transfer entity
let transfer = new Transfer(
event.transaction.hash.toHexString() + "-" + event.logIndex.toString()
)
transfer.token = token.id
transfer.from = event.params.from
transfer.to = event.params.to
transfer.value = event.params.value.toBigDecimal().div(
BigDecimal.fromString("1000000") // 6 decimals
)
transfer.timestamp = event.block.timestamp
transfer.blockNumber = event.block.number
transfer.save()
}Querying Subgraphs
GraphQL Query Examples
Top tokens by transfer volume:
{
tokens(first: 10, orderBy: transferCount, orderDirection: desc) {
id
symbol
transferCount
}
}Recent large transfers:
{
transfers(
first: 20
orderBy: timestamp
orderDirection: desc
where: { value_gt: "100000" }
) {
from
to
value
timestamp
token { symbol }
}
}Account balances:
{
account(id: "0x1234...") {
balances {
token { symbol }
balance
}
}
}Query Endpoints
| Network | Hosted Service | Decentralized |
| Ethereum | api.thegraph.com/subgraphs/name/... | gateway.thegraph.com/api/... |
| Arbitrum | Same pattern | Same pattern |
| Base/Optimism | Same pattern | Same pattern |
Popular Existing Subgraphs
| Subgraph | What It Indexes | Useful For |
| Uniswap V3 | Pools, swaps, liquidity positions | DEX price data, volume |
| Aave V3 | Deposits, borrows, liquidations | Lending market data |
| Balancer V2 | Pools, swaps, BPT balances | Multi-asset pool data |
| ENS | Domain registrations, transfers | Name resolution |
| Sperax | USDs transfers, SPA staking | Sperax ecosystem data |
Deployment
The Graph Studio (Decentralized)
# Install CLI
npm install -g @graphprotocol/graph-cli
# Initialize
graph init --studio my-subgraph
# Authenticate
graph auth --studio YOUR_DEPLOY_KEY
# Build + Deploy
graph codegen
graph build
graph deploy --studio my-subgraphSelf-Hosted Graph Node
For full control:
# Docker Compose
docker-compose up graph-node postgres ipfs
# Deploy to local
graph create --node http://localhost:8020/ my-subgraph
graph deploy --node http://localhost:8020/ my-subgraphPerformance Tips
| Tip | Why |
Use startBlock wisely | Don't index from block 0 — start from contract deployment |
Avoid call handlers | They're 10x slower than event handlers |
Use BigDecimal for prices | Avoid precision loss with BigInt division |
| Batch entity loading | Use store.get() sparingly in hot paths |
| Index only what you need | More entities = slower indexing |
Alternative Indexing Solutions
| Tool | Approach | Best For |
| The Graph | Decentralized, GraphQL | Production DeFi data |
| Goldsky | Managed subgraph hosting + streaming | High-performance queries |
| Envio | HyperIndex — fast parallel indexing | Speed-critical applications |
| Ponder | TypeScript framework for indexing | Developer-friendly, type-safe |
| Dune Analytics | SQL on decoded blockchain data | Analytics and dashboards |
Agent Tips
- Use existing subgraphs first — don't build one if Uniswap/Aave already has what you need
- Decentralized network is production — hosted service is being sunset
- Start with events, not calls — event handlers are much faster
- Schema design matters — think about what queries you need before designing entities
- Multi-chain — deploy the same subgraph to multiple networks for cross-chain data
- Sperax data: USDs transfer volumes, SPA staking events, and veSPA locking can all be indexed with subgraphs on Arbitrum
Links
- The Graph: https://thegraph.com
- Graph Explorer: https://thegraph.com/explorer
- Graph Docs: https://thegraph.com/docs
- GitHub: https://github.com/graphprotocol/graph-node
- Arbiscan (for ABI/contract data): https://arbiscan.io
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

