subgraph-development-guide

name	subgraph-development-guide
description	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.
metadata	{"openclaw":{"emoji":"📊","homepage":"https://thegraph.com"}}

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.ts

Step 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-subgraph

Self-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-subgraph

Performance 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

1. Use existing subgraphs first — don't build one if Uniswap/Aave already has what you need
2. Decentralized network is production — hosted service is being sunset
3. Start with events, not calls — event handlers are much faster
4. Schema design matters — think about what queries you need before designing entities
5. Multi-chain — deploy the same subgraph to multiple networks for cross-chain data
6. 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