Subgraph Manifest

A Subgraph Manifest is a YAML or JSON file, typically named subgraph.yaml, that serves as the complete blueprint for a subgraph on The Graph protocol. It explicitly defines the smart contracts to index, the specific blockchain events to listen for, and the precise mapping functions that translate raw blockchain data into queryable entities. This manifest is the single source of truth for the subgraph's data pipeline, instructing the Graph Node on how to process historical and real-time data from a specified network.

The manifest's structure is organized into several key sections. The dataSources block specifies the smart contract ABI, address, and start block. The most critical component is the eventHandlers list, which links specific contract events to handler functions written in AssemblyScript. These handlers, defined in a separate mapping file, contain the logic for creating, updating, or deleting entities in the subgraph's database. Additional sections configure the network (e.g., Ethereum mainnet, Arbitrum), the schema of the resulting data, and templates for dynamically adding data sources.

When a developer deploys a subgraph, the Graph Node ingests this manifest to begin the indexing process. It scans the blockchain from the defined start block, executes the mapping logic for each matching event, and populates a PostgreSQL database with the structured entities. Consequently, any change to the subgraph's behavior—such as indexing a new event or modifying an entity field—requires an update to the manifest and a redeployment. This declarative approach separates the data indexing logic from the query layer, enabling powerful and efficient GraphQL APIs for decentralized applications.

A subgraph manifest is a YAML or JSON file, typically named subgraph.yaml, that acts as the complete blueprint for a subgraph. It specifies the smart contract to index, the blockchain network it resides on, the events to listen for, and the mapping logic that translates raw blockchain data into the structured GraphQL schema. This file is the single source of truth for The Graph's indexing node, telling it exactly what to index and how to process it. Without a properly configured manifest, a subgraph cannot be deployed or begin indexing data.

The manifest is structured into several key sections. The dataSources section defines the smart contract address, the blockchain network (e.g., mainnet, arbitrum-one), and the contract ABI. The templates section allows for dynamic data source creation. Crucially, the eventHandlers within each data source link specific contract events to handler functions in the mapping script. Finally, the manifest references the schema.graphql file, ensuring the mapping's output conforms to the defined data model. This declarative approach separates the what (the manifest) from the how (the mapping code).

During deployment, The Graph's tooling, like the Graph CLI, validates and processes the manifest. It compiles the mapping code (written in AssemblyScript or other supported languages), ensures the schema is syntactically correct, and registers the subgraph's intent with the network. Once deployed, the indexing node reads the manifest to understand its starting block, begins scanning the chain for the specified events, and executes the corresponding handler functions to populate the database. Any change to the subgraph's logic or data sources requires an update to the manifest and a new deployment.

For developers, working with the manifest involves careful configuration of startBlock to optimize indexing speed, defining efficient eventHandlers to capture only necessary data, and managing dataSource templates for factory contracts that deploy new instances. A well-crafted manifest is essential for subgraph performance and accuracy, as errors here can lead to missed events or incorrect data transformations. It is the foundational document that bridges the on-chain world with the queryable off-chain database.

A Subgraph Manifest is a YAML or JSON configuration file (typically subgraph.yaml) that serves as the complete blueprint for a subgraph, defining the smart contracts to index, the events to track, and the logic for transforming blockchain data into queryable entities. It is the single source of truth for The Graph's indexing node, instructing it on precisely what data to ingest and how to process it. This declarative file is the first artifact created when developing a subgraph and is essential for its deployment to a decentralized network or a hosted service.

The manifest's core sections define the data sources. Each data source specifies a smart contract address, its Application Binary Interface (ABI), the blockchain network, and the starting block for indexing. Crucially, it lists the specific contract events and function calls that the subgraph will monitor. The mapping section then links this data to the transformation logic, pointing to the handler functions written in AssemblyScript that will process these events and populate the subgraph's GraphQL schema. This separation of configuration and logic allows for clear, maintainable subgraph definitions.

Beyond core indexing rules, the manifest includes important metadata like the subgraph's name and version, and it can define templates for dynamically created data sources. For instance, a factory contract that deploys new trading pairs can be configured to automatically spawn a new data source for each new contract, without manual updates. Advanced features like call handlers for tracking specific function executions and block handlers for processing every new block are also configured here, making the manifest a powerful tool for capturing complex blockchain state.

Mapping logic is the executable code that processes blockchain events and function calls, translating raw transaction data into structured entities within a subgraph's data store. This logic is defined in a mapping file, typically written in AssemblyScript, and is triggered by event handlers and call handlers specified in the subgraph manifest. Each handler is a function that receives the decoded blockchain data as an input parameter, allowing developers to write custom business logic for creating, updating, or deleting entities in response to on-chain activity.

An event handler is the most common mapping trigger, invoked when a specific smart contract event, or log, is emitted on-chain. The handler function receives the event's indexed and non-indexed parameters as typed objects. For example, a Transfer(address indexed from, address indexed to, uint256 value) event would trigger a handler that could create a TransferEntity or update User entity balances. The precision of these handlers is what allows subgraphs to maintain a precise, real-time reflection of contract state.

A call handler provides an alternative mapping trigger, executing logic in response to specific smart contract function calls, even if they do not emit an event. This is crucial for indexing state-changing calls to functions marked as external or public. Block handlers run once per new block, enabling the indexing of block-level data like miner rewards or difficulty, while transaction handlers run for every transaction, useful for tracking gas prices or transaction origins. The choice of handler depends on the specific data sourcing requirement.

Within the mapping function, developers interact with the store via the Entity API. The core operations are entity.save() to persist a new or updated entity and entity.load() to retrieve an existing entity for modification. This is where the logic applies the business rules: calculating derived statistics, updating aggregate balances, or establishing relationships between entity types. All changes made within a handler are atomically committed to the store, ensuring data consistency.

Effective mapping design is critical for subgraph performance and correctness. Best practices include minimizing state lookups, avoiding unnecessary computations, and ensuring handler logic is deterministic—it must produce the same entity changes for the same on-chain inputs every time. Since mappings process every relevant event from the start block onward, efficient logic ensures the subgraph can sync quickly and remain cost-effective to host and query.

A GraphQL Schema is a declarative contract written in the GraphQL Schema Definition Language (SDL) that defines the data types, fields, and relationships that a subgraph will expose. It serves as the blueprint for the subgraph's API, specifying exactly what queries can be made and what data structures will be returned. Every entity, scalar, enum, and interface used by the subgraph must be explicitly defined in this schema file, which is typically named schema.graphql. This schema is the single source of truth for the subgraph's data model.

The schema's primary components are entity types, which represent indexed objects like User or Transaction. Each entity is defined with fields that have specific GraphQL scalar types (String, Int, BigInt, Bytes, etc.) or references to other entities, establishing relationships. The @entity directive marks a type for indexing, while the @derivedFrom directive creates a reverse lookup on a relationship. This schema directly informs the generation of the underlying database tables and the structure of the GraphQL API endpoint.

Beyond static definitions, the schema supports enums for predefined value sets, interfaces for shared fields across entities, and union types for flexible return values. Crucially, the schema is tightly coupled with the subgraph's mapping logic written in AssemblyScript; the mappings are responsible for populating the entities defined here with data sourced from blockchain events. Any change to the schema necessitates a redeployment of the subgraph, as it alters the fundamental data structure.