Cross-Chain Indexing with The Graph: A Complete Tutorial

• The Graph is a decentralized indexing protocol that lets developers query blockchain data using GraphQL — no custom node infrastructure required.
• A subgraph is the open API you build and deploy to define exactly what on-chain data gets indexed and how it is structured.
• The three core files you edit are subgraph.yaml (manifest), schema.graphql (data shape), and mapping.ts (transformation logic).
• The Graph supports 60+ blockchains including Ethereum, Solana, Arbitrum, Avalanche, Base, and BNB Chain — making it the go-to tool for cross-chain data indexing.
• Miners transitioning to development will recognize the parallel: just as Chia’s Chialisp puzzles define spending logic in a declarative way, subgraph mappings declaratively define how raw chain events become queryable data.

The Graph indexing tutorial covers how to define, build, and deploy a subgraph — a custom open API that extracts blockchain events, transforms them into structured entities, and serves them through a fast GraphQL endpoint. Once deployed, your subgraph is maintained by a decentralized network of indexers, meaning you get reliable blockchain data access without running your own archive node.¹

What Is The Graph and Why Does It Matter?

Think about trying to look up every sale of a specific NFT on Ethereum. To do that directly, you would have to scan every single block, one by one, looking for the right contract events. That could mean processing hundreds of millions of blocks. It is incredibly slow and expensive. The Graph was created specifically to solve this problem.

The Graph is a decentralized indexing protocol that processes raw blockchain data and makes it searchable through a standard GraphQL API. It was founded in 2018 by Yaniv Tal, Brandon Ramirez, and Jannis Pohlmann to address what they described as the “lack of tooling and mature protocols on Ethereum.”⁶ Often called the “Google of blockchains,” The Graph has grown to process over 195 billion queries per month as of 2024.⁵

“The Graph lifts stability up one level to where any developer can reliably find and consume organized data directly into their dApps.”— Yaniv Tal, Co-founder of The Graph and CEO of Edge & Node⁸

The Problem The Graph Solves

Reading data directly from Ethereum through JSON-RPC is functional, but it falls short fast. You can only retrieve one piece of data at a time, you cannot filter or sort results on the chain’s side, and querying historical states means replaying the entire chain. For a simple dApp showing a user’s portfolio history or a DeFi protocol displaying liquidity events, this approach is unworkable at scale.³

Before The Graph existed, developer teams solved this by building centralized indexing servers — essentially private databases that scraped chain data. This works, but it reintroduces the centralization that blockchains are designed to remove. The Graph replaces that private database with a shared, decentralized network of indexer nodes that anyone can query and anyone with the right staked GRT tokens can contribute to.

How The Graph Compares to Traditional APIs

Traditional REST APIs fetch data from a centralized database controlled by a single company. If that company goes down, your data access disappears. GraphQL APIs built on The Graph are different: they are powered by a decentralized network of indexers staking GRT tokens to serve queries correctly. If one indexer goes offline, others continue to serve the data. The economic incentives in The Graph’s protocol — where indexers earn rewards for accurate queries and lose stake for incorrect ones — are what make decentralized data access trustworthy at production scale.²

The Graph Network: Roles and Economics

Before diving into the tutorial, it helps to understand who does what inside The Graph’s ecosystem. There are four key roles, each with economic skin in the game.

Indexers: The Node Operators

Indexers are node operators who run Graph Nodes — open-source software that links the blockchain, a PostgreSQL database, and IPFS together.⁷ They must stake a minimum of 100,000 GRT to participate, and they earn both query fee revenue and indexing rewards (funded by a 3% annual protocol inflation rate) in return.² If an indexer serves incorrect data, their stake can be slashed. This makes the system self-enforcing. For miners transitioning to Web3 development, the indexer role is the most directly analogous to running a full node — except it comes with structured earning incentives rather than just network contribution.

Curators, Delegators, and Developers

Curators signal which subgraphs are high quality by staking GRT on them, directing indexer attention toward the most useful APIs. Delegators support indexers by lending their GRT stake without running their own node, earning a share of the indexer’s rewards. Developers build and publish the subgraphs themselves, defining the indexing logic and deploying it to the network.⁴ You get 100,000 free queries per month when you publish a subgraph on The Graph Network.¹

The Graph Indexing Tutorial: Three Core Files

Every subgraph is built from exactly three files. Understanding what each one does is the most important step in this the graph indexing tutorial — everything else is just filling in the details.

The Subgraph Manifest (subgraph.yaml)

The manifest is the configuration file that tells The Graph what to watch. It specifies which blockchain network your subgraph targets, which smart contract address to listen to, which ABI (Application Binary Interface) describes that contract, which events the contract emits that you care about, and which handler function in your mapping code should respond to each event.¹ If you think of a subgraph like a smart alarm system, the manifest is the list of triggers — what to watch for and what to do when it happens.

When initializing with the Graph CLI, you will be prompted to enter the contract address, choose the network (for example, Ethereum Mainnet or Arbitrum), and specify whether to automatically index contract events as entities. Setting that last option to true will pre-populate your manifest with event handlers based on the contract ABI, saving significant setup time.

The Schema (schema.graphql)

The schema defines the shape of the data you want to store and query. You declare “entities” — think of them as database tables — with typed fields. For example, a simple token transfer entity might include fields for id, from, to, value, and blockTimestamp. Once you deploy your subgraph, these entities become the rows in your queryable database, and the field names become what you filter and sort by in GraphQL.⁹

Relationships between entities are defined directly in the schema too. If you want to link a Transfer entity to a Token entity, you add a field referencing the token’s ID. Unlike traditional SQL databases, there are no native joins in GraphQL — all relationships must be explicitly modeled in the schema and maintained through entity linking in your mappings.

AssemblyScript Mappings (mapping.ts)

Mappings are the transformation layer — the code that takes raw blockchain event data and writes it into the entities you defined in your schema. They are written in AssemblyScript, which is a strict subset of TypeScript. When The Graph’s indexer sees one of the events you declared in your manifest, it runs the corresponding handler function in your mappings file, which reads the event data, creates or updates an entity, and saves it to the index.⁹ Mappings are sandboxed: they cannot make external API calls, perform async operations, or read contract state beyond what is emitted in the event itself. This constraint keeps indexing deterministic and reproducible across all nodes in the network.

Step-by-Step The Graph Indexing Tutorial: Build Your First Subgraph

This tutorial walks you through building a subgraph from scratch. You will need Node.js installed and a free account at Subgraph Studio.

Step 1 — Install the Graph CLI

The Graph CLI is the command-line tool you use to initialize, build, and deploy subgraphs. Install it globally using npm or yarn:

npm install -g @graphprotocol/graph-cli
# or
yarn global add @graphprotocol/graph-cli

Once installed, you can access the CLI from any directory. Verify it is working by running graph --version. You should see the current version number printed to your terminal.

Step 2 — Initialize Your Subgraph

Create a new directory for your project and run the init command. The Graph CLI will open an interactive setup in your terminal:

graph init

You will be asked to choose your protocol (Ethereum or another supported chain), enter the smart contract address you want to index, and provide the contract’s ABI if it is not auto-detected from Etherscan. Set the “Index contract events as entities” option to true — this scaffolds your manifest and mappings automatically based on the contract’s events, which saves a lot of manual setup.¹

Step 3 — Define Your Schema

Open schema.graphql and define the entities that represent the data you want to query. Here is a minimal example for tracking ERC-20 token transfers:

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

Every entity must have an id field. The ! mark means the field is required. After editing the schema, run graph codegen — this auto-generates TypeScript classes based on your schema, which your mappings file will use to create and save entities in a type-safe way.

Step 4 — Write Your Mappings

Open src/mapping.ts and write your handler functions. Each function corresponds to a contract event you declared in subgraph.yaml. The function receives the raw event data, uses the generated classes from graph codegen, and saves entities to the store:

import { Transfer as TransferEvent } from "../generated/MyToken/MyToken";
import { Transfer } from "../generated/schema";

export function handleTransfer(event: TransferEvent): void {
  let entity = new Transfer(event.transaction.hash.concatI32(event.logIndex.toI32()));
  entity.from = event.params.from;
  entity.to = event.params.to;
  entity.value = event.params.value;
  entity.blockNumber = event.block.number;
  entity.blockTimestamp = event.block.timestamp;
  entity.transactionHash = event.transaction.hash;
  entity.save();
}

This handler is called every time a Transfer event fires on your target contract. It creates a new entity, populates the fields with event data, and saves it — making it instantly queryable via GraphQL.⁹

Step 5 — Build and Deploy

Build your subgraph to check for compilation errors, then deploy it to Subgraph Studio:

graph codegen && graph build
graph auth --studio YOUR_DEPLOY_KEY
graph deploy --studio your-subgraph-name

Once deployed, your subgraph enters the indexing stage. It will begin processing historical blocks from the start block you specified in your manifest. Depending on how many blocks it needs to process, this can take anywhere from a few minutes to several hours. You can monitor indexing progress in the Subgraph Studio dashboard.¹ After indexing is complete, your GraphQL endpoint is live and you can query it directly from any frontend or API client.

Cross-Chain Indexing: How The Graph Handles Multiple Blockchains

One of The Graph’s most powerful features for developers working across ecosystems is its native cross-chain support. A single Subgraph Studio account can manage subgraphs for Ethereum, Arbitrum, Optimism, Base, Avalanche, Polygon, BNB Chain, Solana, NEAR, Arweave, and 50+ other networks.⁵ This means you do not need to learn different indexing tools or set up different infrastructure for each chain you build on.

Networks Supported by The Graph

The Graph supports both EVM-compatible chains (where your AssemblyScript mappings work the same way) and non-EVM chains. For non-EVM chains like Solana, The Graph introduced fast no-code indexing in 2024, allowing developers to access on-chain data in hours rather than weeks without writing any Rust code.⁵ Base has seen particularly strong adoption — in Q3 2025, it surpassed Ethereum Mainnet in query fees for the first time, generating $21,982 in fees, up 39.7% quarter-over-quarter.¹⁰

Substreams: The Fast Lane for Cross-Chain Data

For high-throughput use cases, The Graph introduced Substreams — a modular, streaming-first indexing layer that processes data in parallel and can reduce full-chain sync times from days to hours.¹⁰ Unlike standard subgraph mappings that process events sequentially, Substreams uses Rust modules that execute in parallel across blocks, making it dramatically faster for chains with high transaction volume. If you are building analytics infrastructure, a real-time cross-chain dashboard, or anything requiring tracking complex balance changes including flash loans and DeFi position shifts, Substreams is worth learning after you have mastered basic subgraphs.

The Chia Network Parallel: Declarative Logic for On-Chain Data

If you have been working with Chialisp, The Graph’s architecture will feel philosophically familiar. In Chialisp, a puzzle defines the conditions under which a coin can be spent — it does not execute transactions, it defines the logic that evaluates transaction validity. In a very similar way, a subgraph manifest and mappings do not write to the blockchain — they define the logic that transforms on-chain events into queryable data. Both are declarative: you describe the rules and let the network execute them.

Just as Chialisp puzzles are evaluated by every full node running the Chia consensus, subgraph mappings are executed identically across every indexer node running the Graph Node software — producing the same deterministic output from the same input blocks. This is what allows the protocol to generate cryptographic Proofs of Indexing (POI): a verifiable record that an indexer processed specific blocks correctly.² For Chia miners exploring multi-chain development, this architectural parallel is not just a curiosity — it is a genuine mental model that can accelerate your understanding of how The Graph actually works. You can explore more about Chialisp’s approach to decentralized logic in our guide to Chialisp transforming blockchain smart contracts.

Real-World Case Study: Uniswap and DeFi Data at Scale

Uniswap, the largest decentralized exchange by trading volume, uses The Graph as a core piece of its data infrastructure. Its public subgraph indexes every swap, liquidity addition, and pool creation event across Uniswap V2 and V3, powering the analytics dashboard at info.uniswap.org and feeding data to dozens of third-party DeFi aggregators and analytics tools.³ Without The Graph, reproducing that kind of historical data access would require maintaining a full Ethereum archive node — which costs thousands of dollars per month in infrastructure alone. Instead, any developer can query the Uniswap subgraph for free using GraphQL, building their own analytics, portfolio trackers, or trading tools on top of it.

Conclusion

The Graph turns the messiest part of blockchain development — getting organized, queryable data off a chain — into a standardized, decentralized workflow that any developer can follow. This the graph indexing tutorial has walked you through the full picture: why The Graph exists, how its network economics create trustworthy data, what the three core subgraph files do, and how to build and deploy your first subgraph step by step. Cross-chain development no longer requires building a different indexing pipeline for every network — one protocol, one query language, and a few YAML and TypeScript files cover 60+ chains. If you are coming from a mining background, the mental model is solid: The Graph’s node operators are the decentralized infrastructure layer, just as farmers are in Chia — and now, you know how to build on top of it. Start with the official Subgraph Studio, deploy your first subgraph on a testnet, and go from there.

the graph indexing tutorial FAQs

What is a subgraph in the graph indexing tutorial?

In a the graph indexing tutorial, a subgraph is an open API that defines how to extract, organize, and serve specific blockchain data through a GraphQL endpoint. It consists of three files — the manifest, schema, and mappings — and is deployed to The Graph’s decentralized network where indexer nodes process and serve it.

How do I run a the graph indexing tutorial for Ethereum?

To follow a the graph indexing tutorial for Ethereum, install the Graph CLI using npm, run graph init to scaffold your project with your target contract address, edit the schema and mappings to define what data you want, then deploy to Subgraph Studio using your deploy key. The entire process can be completed in under an hour for a simple ERC-20 or NFT contract.

How many blockchains does The Graph support for cross-chain indexing?

The Graph supports over 60 blockchain networks for cross-chain indexing as of 2025, including Ethereum, Arbitrum, Base, Avalanche, Polygon, Solana, BNB Chain, NEAR, and Arweave. EVM-compatible chains share the same AssemblyScript mapping format, while non-EVM chains like Solana use Substreams-based tooling for fast no-code indexing.

What is GRT and do I need it to deploy a subgraph?

GRT is The Graph’s native token used to pay for queries and to stake by indexers, curators, and delegators. You do not need GRT to deploy and test a subgraph in Subgraph Studio — deployed subgraphs are free to use with a rate limit of 100,000 queries per month. GRT is needed if you want to publish your subgraph to the fully decentralized network and attract indexers through curation signaling.

What is the difference between Substreams and a standard subgraph?

A standard subgraph processes blockchain events sequentially using AssemblyScript handler functions and is best for most dApp data needs. Substreams is a higher-performance streaming layer that uses parallel Rust modules, reducing full-chain sync from days to hours — making it ideal for analytics platforms and high-throughput cross-chain data pipelines.

the graph indexing tutorial Citations

1. The Graph — Quick Start: 5 Steps to Build a Subgraph
2. The Graph — Indexing Overview
3. QuickNode — How to Create a Custom Subgraph with The Graph
4. Chainstack — A Beginner’s Guide to Getting Started with The Graph
5. Wikipedia — The Graph (protocol)
6. Messari — What Is The Graph?
7. Chainstack — Avalanche Subnet Tutorial: Indexing with The Graph
8. CoinTelegraph — What Is The Graph and How Does It Work?
9. Hashtag Web3 — Your First Subgraph: Indexing Blockchain Data with The Graph
10. Messari — State of The Graph Q3 2025