Subgraph Development Guide

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

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

Popular Existing Subgraphs

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

Alternative Indexing Solutions

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