Subgraph

The manifest (subgraph.yaml) is the configuration blueprint. It defines the smart contracts to index, the specific blockchain events to listen for, and the handlers that process them. This declarative setup allows developers to specify their data sources without writing complex indexing logic from scratch.

Mappings are the core transformation logic, written in AssemblyScript or TypeScript. They contain event handlers (e.g., handleTransfer) that are automatically triggered when a specified on-chain event is detected. These handlers decode event data and save structured entities to the store.

The GraphQL schema (schema.graphql) defines the shape of the indexed data. Developers declare entity types (like User, Transaction) with their fields and relationships. The subgraph runtime automatically generates corresponding database tables and a complete GraphQL API from this schema.

A subgraph processes blockchain data deterministically, meaning that given the same chain data and manifest, it will always produce an identical database. This ensures data integrity and allows for trustless verification of the indexed results by network nodes.

The primary output of a subgraph is a GraphQL endpoint. Applications query this API using GraphQL's flexible syntax to fetch precisely the data they need—filtering, sorting, and paginating entities—without requiring complex backend infrastructure or direct RPC calls.

A Subgraph defines the smart contracts of interest, the events to index, and how to map event data into queryable entities. Indexers on The Graph network run this code, processing blockchain data in real-time to create a structured, high-performance database. This eliminates the need for developers to run their own complex indexing infrastructure.

Once deployed, a Subgraph exposes a GraphQL endpoint. Developers can query this API using GraphQL's declarative syntax to fetch precisely the data they need—such as user balances, transaction histories, or protocol metrics—without writing complex database queries or parsing raw logs. This is the primary interface for dApps to consume indexed data.

A Subgraph is built from three core files:

• Subgraph Manifest (subgraph.yaml): Defines the smart contracts, events, and handlers.
• GraphQL Schema (schema.graphql): Defines the data entities and relationships.
• Mapping Scripts (AssemblyScript): Contains the logic to translate blockchain events into the entities defined in the schema.

Subgraphs are foundational for data-rich applications:

• DeFi Dashboards: Querying real-time Total Value Locked (TVL), liquidity pool stats, and user positions from protocols like Uniswap or Aave.
• NFT Marketplaces: Indexing collections, tracking ownership history, and aggregating traits for discovery.
• Analytics Platforms: Providing historical data on transactions, fees, and user growth for on-chain analysis.

Subgraphs can be deployed to The Graph Network, a decentralized marketplace for data. Here, Indexers stake GRT to provide indexing and query processing services, Curators signal on high-quality subgraphs, and Delegators secure the network by delegating GRT. Users pay for queries with GRT tokens, creating a sustainable ecosystem.

The Graph offers two main deployment environments:

• Hosted Service: A free, managed service run by The Graph team, ideal for development and testing. It is being sunset in favor of the decentralized network.
• Decentralized Network (Mainnet): The production-ready, permissionless network where subgraphs are indexed by a decentralized set of node operators, ensuring reliability and censorship resistance.

A network node operator in The Graph protocol that runs the hardware required to index and serve queries for specific Subgraphs. Indexers stake GRT and earn query fees and indexing rewards for their service. They are responsible for:

• Processing blockchain events
• Storing indexed data
• Responding to GraphQL queries

The configuration files that define a Subgraph. The subgraph manifest (subgraph.yaml) specifies the smart contracts, events, and handlers to index. The GraphQL schema (schema.graphql) defines the shape of the queryable data, including entities, fields, and their relationships.

The transformation logic written in AssemblyScript that processes blockchain events into the queryable entities defined in the schema. Mappings run in a WASM (WebAssembly) environment and are triggered by event handlers. They are responsible for:

• Decoding event/log data
• Creating or updating entity instances
• Storing these entities in the indexer's database

The end-user application that consumes data from a Subgraph. Instead of running its own node or making complex RPC calls, a dApp's frontend sends GraphQL queries to a public or private GraphQL endpoint powered by The Graph network. This architecture enables efficient, serverless data access for blockchain applications.

The core configuration files that define a subgraph's behavior.

• Manifest (subgraph.yaml): Specifies the smart contract to index, the events to listen for, and the mapping file.
• Mapping (mapping.ts): Contains the AssemblyScript code that translates blockchain events into the entities defined in the schema. This is where the logic for processing and storing data lives.

The Graph offers two main deployment options.

• Hosted Service: A free, managed service run by The Graph Foundation. It's easier for prototyping but is being phased out in favor of the decentralized network.
• Decentralized Network (Mainnet): The production-ready, permissionless network where subgraphs are published, indexed, and queried in a decentralized manner, with costs paid in GRT.

Subgraphs power data for major DeFi and NFT applications.

• Uniswap: Tracks pools, swaps, liquidity, and token data.
• Decentraland: Indexes LAND parcels, wearables, and marketplace sales.
• Aave: Monitors lending pools, user positions, and interest rates. These dApps query their subgraphs to populate dashboards, calculate metrics, and drive user interfaces.

To fetch data, applications send a POST request to a subgraph's GraphQL endpoint. A typical query might request the last 10 transactions for a specific pool, including amounts, users, and timestamps. Queries can be filtered, sorted, and paginated. Tools like the Graph Explorer provide an interactive playground for testing queries before integrating them into code.