Skip to content

a5c-ai/babysitter / library/specializations/cryptography-blockchain/skills/subgraph-indexing

subgraph-indexing

Verified

Subgraph development for The Graph protocol. Includes manifest configuration, GraphQL schema design, AssemblyScript handlers, entity relationships, and deployment to hosted and decentralized networks.

Subgraph Indexing Skill

Subgraph development for The Graph protocol, enabling efficient blockchain data indexing and querying.

Capabilities

  • Manifest Configuration: Write subgraph.yaml files
  • Schema Design: Define GraphQL schemas for entities
  • Event Handlers: Implement AssemblyScript handlers
  • Entity Relationships: Handle derived fields and relations
  • Local Testing: Test with Graph Node locally
  • Deployment: Deploy to hosted and decentralized networks
  • Performance: Optimize indexing performance
  • Reorg Handling: Handle chain reorganizations

Installation

# Install Graph CLI
npm install -g @graphprotocol/graph-cli

# Verify
graph --version

Project Setup

Initialize Subgraph

# Initialize from existing contract
graph init --product subgraph-studio \
  --from-contract 0x... \
  --network mainnet \
  --abi ./abi.json \
  my-subgraph

cd my-subgraph

Project Structure

my-subgraph/
├── subgraph.yaml          # Manifest
├── schema.graphql         # GraphQL schema
├── src/
│   └── mapping.ts         # Event handlers
├── abis/
│   └── Contract.json      # Contract ABIs
├── tests/
│   └── contract.test.ts   # Unit tests
└── package.json

Manifest (subgraph.yaml)

specVersion: 0.0.5
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: Token
    network: mainnet
    source:
      address: "0x..."
      abi: Token
      startBlock: 18000000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Transfer
        - Account
      abis:
        - name: Token
          file: ./abis/Token.json
      eventHandlers:
        - event: Transfer(indexed address,indexed address,uint256)
          handler: handleTransfer
        - event: Approval(indexed address,indexed address,uint256)
          handler: handleApproval
      callHandlers:
        - function: transfer(address,uint256)
          handler: handleTransferCall
      blockHandlers:
        - handler: handleBlock
      file: ./src/mapping.ts

GraphQL Schema

# schema.graphql

type Token @entity {
  id: ID!
  name: String!
  symbol: String!
  decimals: Int!
  totalSupply: BigInt!
  holders: [Account!]! @derivedFrom(field: "token")
}

type Account @entity {
  id: ID!
  token: Token!
  balance: BigInt!
  transfersFrom: [Transfer!]! @derivedFrom(field: "from")
  transfersTo: [Transfer!]! @derivedFrom(field: "to")
}

type Transfer @entity {
  id: ID!
  from: Account!
  to: Account!
  value: BigInt!
  timestamp: BigInt!
  blockNumber: BigInt!
  transactionHash: Bytes!
}

# For aggregations
type DailyVolume @entity {
  id: ID!  # date string
  date: BigInt!
  volume: BigInt!
  txCount: Int!
}

AssemblyScript Handlers

// src/mapping.ts
import { Transfer as TransferEvent } from "../generated/Token/Token";
import { Token, Account, Transfer, DailyVolume } from "../generated/schema";
import { BigInt, Bytes, Address } from "@graphprotocol/graph-ts";

export function handleTransfer(event: TransferEvent): void {
  // Create Transfer entity
  let transfer = new Transfer(
    event.transaction.hash.toHex() + "-" + event.logIndex.toString()
  );
  transfer.from = getOrCreateAccount(event.params.from).id;
  transfer.to = getOrCreateAccount(event.params.to).id;
  transfer.value = event.params.value;
  transfer.timestamp = event.block.timestamp;
  transfer.blockNumber = event.block.number;
  transfer.transactionHash = event.transaction.hash;
  transfer.save();

  // Update account balances
  updateAccountBalance(event.params.from, event.params.value.neg());
  updateAccountBalance(event.params.to, event.params.value);

  // Update daily volume
  updateDailyVolume(event.block.timestamp, event.params.value);
}

function getOrCreateAccount(address: Address): Account {
  let id = address.toHex();
  let account = Account.load(id);

  if (account == null) {
    account = new Account(id);
    account.token = "token-id";
    account.balance = BigInt.fromI32(0);
    account.save();
  }

  return account;
}

function updateAccountBalance(address: Address, delta: BigInt): void {
  let account = getOrCreateAccount(address);
  account.balance = account.balance.plus(delta);
  account.save();
}

function updateDailyVolume(timestamp: BigInt, value: BigInt): void {
  let dayId = timestamp.toI32() / 86400;
  let id = dayId.toString();

  let volume = DailyVolume.load(id);
  if (volume == null) {
    volume = new DailyVolume(id);
    volume.date = BigInt.fromI32(dayId * 86400);
    volume.volume = BigInt.fromI32(0);
    volume.txCount = 0;
  }

  volume.volume = volume.volume.plus(value);
  volume.txCount = volume.txCount + 1;
  volume.save();
}

Data Source Templates

# subgraph.yaml - for factory patterns
templates:
  - kind: ethereum
    name: Pool
    network: mainnet
    source:
      abi: Pool
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Pool
        - Swap
      abis:
        - name: Pool
          file: ./abis/Pool.json
      eventHandlers:
        - event: Swap(indexed address,uint256,uint256)
          handler: handleSwap
      file: ./src/pool.ts
// src/factory.ts
import { Pool as PoolTemplate } from "../generated/templates";

export function handlePoolCreated(event: PoolCreated): void {
  // Create data source for new pool
  PoolTemplate.create(event.params.pool);

  // Create Pool entity
  let pool = new Pool(event.params.pool.toHex());
  pool.save();
}

Build and Deploy

# Generate code from schema
graph codegen

# Build subgraph
graph build

# Authenticate
graph auth --studio <deploy-key>

# Deploy to Subgraph Studio
graph deploy --studio my-subgraph

# Deploy to hosted service (deprecated)
graph deploy --node https://api.thegraph.com/deploy/ \
  --ipfs https://api.thegraph.com/ipfs/ \
  username/my-subgraph

Querying

# Example queries
query RecentTransfers {
  transfers(first: 10, orderBy: timestamp, orderDirection: desc) {
    id
    from {
      id
      balance
    }
    to {
      id
      balance
    }
    value
    timestamp
  }
}

query TopHolders {
  accounts(first: 10, orderBy: balance, orderDirection: desc) {
    id
    balance
  }
}

query DailyVolumes {
  dailyVolumes(first: 30, orderBy: date, orderDirection: desc) {
    date
    volume
    txCount
  }
}

Testing

// tests/token.test.ts
import { assert, test, clearStore } from "matchstick-as";
import { handleTransfer } from "../src/mapping";
import { createTransferEvent } from "./utils";

test("Creates Transfer entity", () => {
  let event = createTransferEvent(
    "0x1234...",
    "0x5678...",
    "1000000000000000000"
  );

  handleTransfer(event);

  assert.entityCount("Transfer", 1);
  clearStore();
});

Process Integration

ProcessPurpose
subgraph-development.jsSubgraph development
blockchain-indexer-development.jsIndexing pipelines
dapp-frontend-development.jsData integration

Best Practices

  1. Use appropriate startBlock to avoid reindexing
  2. Implement efficient entity updates
  3. Handle reorgs with immutable entities
  4. Use derived fields for relations
  5. Test with Matchstick
  6. Monitor indexing performance

See Also

  • skills/wallet-integration/SKILL.md - dApp integration
  • agents/web3-frontend/AGENT.md - Frontend expert
  • The Graph Documentation
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall