a5c-ai/babysitter / library/specializations/cryptography-blockchain/skills/subgraph-indexing
subgraph-indexing
VerifiedSubgraph 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
| Process | Purpose |
|---|---|
subgraph-development.js | Subgraph development |
blockchain-indexer-development.js | Indexing pipelines |
dapp-frontend-development.js | Data integration |
Best Practices
- Use appropriate startBlock to avoid reindexing
- Implement efficient entity updates
- Handle reorgs with immutable entities
- Use derived fields for relations
- Test with Matchstick
- Monitor indexing performance
See Also
skills/wallet-integration/SKILL.md- dApp integrationagents/web3-frontend/AGENT.md- Frontend expert- The Graph Documentation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |