Web3 Indexing: Subgraphs & The Graph Studio

Learning Goal: Building High-Performance Web3 Data Indexers: Designing Custom Subgraphs with The Graph and Subgraph Studio.

---

Prerequisites

• Basic understanding of blockchain concepts (smart contracts, transaction logs, and events).
• Familiarity with JavaScript or TypeScript syntax.
• Comfortable using a command-line interface (CLI).

Estimated Total Study Time: 18 Hours

---

Module 1: Introduction to Web3 and the Indexing Problem

Module Overview

To build user-friendly decentralized applications (dApps), fast and flexible data access is mandatory. However, blockchain designs prioritize consensus and security over search efficiency. This module explores the structural limitations of querying raw blockchain data (the "haystack problem"), why direct RPC querying fails to scale, and how decentralized indexing protocols like The Graph serve as the query engine for Web3.

Recommended Videos

Why this video

This video paints a vivid picture of the "haystack problem" developers face when dealing with raw blockchain logs. It explains why running a proprietary indexer on a custom server creates a centralized single point of failure and details the trade-offs of building self-hosted architectures compared to utilizing decentralized options.

---

Why this video

This animated guide acts as an accessible entry point to the entire ecosystem of The Graph. It explains how indexers, curators, delegators, and subgraphs interact under the hood to organize and serve decentralized API data reliably.

---

Why this video

Presented by Nader Dabit, a prominent Web3 developer advocate, this video connects conceptual problems directly to the Web3 developer stack. It reviews why Web2 database patterns cannot be directly applied to blockchains and provides a high-level walkthrough of how subgraphs resolve these limitations.

---

Why this video

This short segment provides immediate proof of why relying solely on front-end event querying is impractical for scaling applications. It details the performance degradation and user experience limitations that happen when dApps attempt to scan historical events directly using front-end provider nodes.

---

Knowledge Checkpoint

• Understand the architectural difference between a standard Web2 database and a Web3 peer-to-peer ledger from a data retrieval perspective.
• Identify why direct RPC node queries (like scanning logs via getPastEvents) fail as dApp transaction volumes grow.
• Define the roles of Indexers, Curators, and Delegators in The Graph’s decentralized economy.
• Explain the "haystack problem" in Web3 data fetching.

---

Module 2: GraphQL Foundation & Schema Design

Module Overview

The standard query interface for subgraphs is GraphQL. To build high-performance data pipelines, you must understand how GraphQL works, how to write schema definition files (schema.graphql), and how to construct flexible entity models that avoid over-fetching while allowing nested relationships.

Recommended Videos

Why this video

This crash course introduces GraphQL from first principles. It compares GraphQL with standard RESTful APIs, demonstrating how a single-endpoint schema architecture solves the classic REST problems of over-fetching and under-fetching.

---

Why this video

This video explains how to write schemas using strongly typed objects. Understanding how custom types, scalar types, and query layers interact in standard GraphQL is essential for creating your subgraph's entity structure.

---

Why this video

A comprehensive deep-dive into advanced query concepts, variables, and arguments. It provides practical foundation-building knowledge on writing complex queries that filters, sorts, and structures nested relation queries cleanly.

---

Knowledge Checkpoint

• Understand the differences between GraphQL query syntax and REST payloads.
• Define custom object types using basic GraphQL scalar types (e.g., String, Int, Boolean, ID).
• Write GraphQL queries containing variables to retrieve specific fields from a nested dataset.
• Understand how schemas act as a reliable structural contract between backend storage and client UI.

---

Module 3: The Graph Architecture and Subgraph Anatomy

Module Overview

This module explores the inner anatomy of a subgraph. You will examine its three core components: the Manifest (subgraph.yaml) which configures data sources, the Schema (schema.graphql) which defines relational data models, and Mappings (mapping.ts) which serve as event handling code.

Recommended Videos

Why this video

Led by Marcus Rein, this video acts as a complete visual mapping of subgraph anatomy. It traces the lifecycle of an event from emission to database ingestion, showing exactly how the manifest, schema, and mappings fit together.

---

Why this video

This concise guide walks through the physical structure of the manifest file. You will learn how to declare network configurations, target addresses, specific ABI events, and configure the mapping handlers that process block events.

---

Why this video

This session explains how the Graph Node engine monitors blocks in parallel, matches event logs, runs mapping modules, and updates its internal state store. It illustrates how developers build and maintain database integrity in an asynchronous environment.

---

Knowledge Checkpoint

• Identify and describe the purpose of the three main files in any standard subgraph project.
• Map out how a smart contract event declaration translates into a data source handler within the subgraph.yaml manifest.
• Draft a simple schema.graphql entity annotated with the @entity directive.
• Understand how Graph CLI compiles these configurations to prepare code generation bindings.

---

Module 4: Writing Mappings in AssemblyScript

Module Overview

AssemblyScript compiles a subset of TypeScript to optimized WebAssembly (Wasm) bytecode, allowing Graph Nodes to run mapping code at near-native speeds. In this module, you will learn the basics of AssemblyScript and how to map contract events using Web3-specific libraries like @graphprotocol/graph-ts.

Recommended Videos

Why this video

This deep dive explores WebAssembly runtimes and why AssemblyScript is preferred over standard JavaScript. It explains how AssemblyScript balances TypeScript syntax familiarity with predictable, low-level execution characteristics.

---

Why this video

This video provides a practical configuration introduction to the AssemblyScript compiler. It outlines essential syntax variations from standard JavaScript/TypeScript, focusing on strict static typing, explicit type casting, and pointer mechanics.

---

Why this video

This short conceptual video explains low-level type mechanics in AssemblyScript. It clarifies why you must work with precise types (e.g., i32, u64) instead of standard JavaScript dynamically cast generic floats.

---

⚠️ Curriculum Developer Note — Gap Acknowledgment: While general AssemblyScript resources are covered here, there is limited coverage on Web3 data type mappings (specifically using @graphprotocol/graph-ts types such as Address, Bytes, and BigInt).

Action Item: For independent study, search Google or YouTube for: "AssemblyScript mapping types The Graph tutorial" or consult the official Graph Protocol mapping documentation. Study how to initialize new entities, retrieve data from events using event.params.parameterName, and type-cast using .toHex() or .toBigDecimal().

---

Knowledge Checkpoint

• Explain why the Graph Protocol uses AssemblyScript instead of standard JavaScript for mapping execution.
• Correctly load, update, and save custom database entities within an AssemblyScript event handler function.
• Differentiate between standard AssemblyScript types and Graph-specific Web3 types (e.g., standard string vs. @graphprotocol/graph-ts Address, Bytes, and BigInt).
• Write logic that conditionally creates a new database record only if it does not already exist in storage.

---

Module 5: Building and Deploying with Subgraph Studio

Module Overview

With your schema, manifest, and mappings ready, you can deploy your project to Subgraph Studio. This module guides you through authenticating, building, deploying, running sandbox tests using Matchstick, and querying your deployed subgraph via the interactive playground interface.

Recommended Videos

Why this video

This official walkthrough shows how to build and deploy a subgraph using Subgraph Studio. It demonstrates using the Graph CLI to initialize projects, generate code bindings, and deploy code to the sandbox staging area.

---

Why this video

This video provides a deep-dive deployment tutorial using realistic ERC-20 smart contract events. It guides you through using deployment keys, monitoring progress on the dashboard, checking sync statuses, and testing with the Playground.

---

Why this video

Testing is essential for robust indexing. This tutorial covers the Matchstick framework, showing you how to build mock events in sandboxed environments, perform assertions on the simulated database state, and run quick automated tests before publishing to production.

---

Knowledge Checkpoint

• Install the Graph CLI globally and authenticate with Subgraph Studio via terminal commands.
• Run graph codegen and graph build without compilation errors.
• Build a basic Matchstick unit test with mock events that validates your entity mapping logic.
• Deploy a subgraph to Subgraph Studio and retrieve testing payloads using the integrated GraphQL Playground.

---

Module 6: Advanced Subgraph Optimization & Best Practices

Module Overview

As transactional scale increases, poorly written subgraphs can encounter indexing bottlenecks or require excessive storage. This module introduces performance-tuning techniques, including entity pruning, @derivedFrom fields, reducing direct contract read overhead, and deploying multi-chain subgraph architectures.

Recommended Videos

Why this video

This presentation covers four performance optimization patterns: using database indexer hints for automatic pruning, implementing the @derivedFrom directive for fast virtual relationships, avoiding contract reads inside mappings, and reducing storage footprints to speed up syncing.

---

Why this video

This session explains how to design multi-chain subgraphs. Core developers share strategies on deploying similar structures across multiple networks, designing multi-chain schema aggregation pipelines, and configuring optional management layers.

---

⚠️ Curriculum Developer Note — Gap Acknowledgment: While advanced optimizations are covered above, there is limited coverage on avoiding expensive blockchain RPC reads (commonly referred to as eth_calls or contract calls) in mapping code.

Action Item: For independent study, search Google or YouTube for: "How to avoid eth_calls in subgraphs". Learn how to design event logs that emit all required transaction state variables, eliminating the need to read state directly from the smart contract during block parsing.

---

Knowledge Checkpoint

• Explain how the @derivedFrom directive creates clean, non-persisted virtual relationships that reduce storage overhead.
• Describe how avoiding direct contract calls (e.g., calling balanceOf inside a transfer handler) speeds up subgraph indexing.
• Implement database pruning mechanisms to automatically clean up historic, unneeded entity states.
• Formulate a multi-chain subgraph strategy that aggregates indices from multiple networks.

---

Course Map

---

Key People Index

• Nader Dabit (@naderdabit)
  Context: Well-known Web3 developer advocate and technical educator. His video outlines the core architectural components of the modern decentralized developer stack.
• Marcus Rein (@ETHGlobal / @GraphProtocol)
  Context: Developer Educator at Edge & Node. He is a primary contributor to learning materials on subgraph development, unit testing with Matchstick, and database optimization.
• Simon Emanuel Schmid (@ETHGlobal)
  Context: Technical educator and engineer who provides comprehensive, step-by-step developer guides on subgraphs and multi-chain indexing architectures.

---

Final Self-Assessment

Complete this comprehensive self-assessment before publishing your subgraph to production:

• Explain the structural database indexing problem on blockchains and why decentralized subgraphs are preferred over centralized alternatives.
• Draft a clean schema.graphql file that uses appropriate type definitions, primary keys, and annotations.
• Implement one-to-many and many-to-many relationships in a schema using the @derivedFrom directive.
• Configure a subgraph.yaml manifest that targets correct networks, starting blocks, contract addresses, and event signatures.
• Write AssemblyScript mapping logic to process events, load/mutate records, and save state to the database.
• Implement strict type checks and conversions on Web3 primitives like BigInt, Address, and Bytes within your code.
• Use the Graph CLI to initialize, compile, build, and deploy a subgraph to Subgraph Studio.
• Write automated unit tests for mappings using the Matchstick test runner.
• Explain the performance implications of making direct contract calls during indexing and detail how to minimize them.
• Construct custom GraphQL queries in the Playground sandbox using variables, sorting parameters, and filters.