Subgraph Manifest Specification

The subgraph manifest specifies all the information required to index and query a specific subgraph. This is the entry point to your subgraph.

Overview

The subgraph manifest, and all the files linked from it, is what is deployed to IPFS and hashed to produce a subgraph ID that can be referenced and used to retrieve your subgraph in The Graph.

Format

Any data format that has a well-defined 1:1 mapping with the IPLD Canonical Format may be used to define a subgraph manifest. This includes YAML and JSON. Examples in this document are in YAML.

Top-Level API

specVersion

String

required

A Semver version indicating which version of this API is being used.

schema

Schema

required

The GraphQL schema of this subgraph. See Schema for details.

description

String

An optional description of the subgraph’s purpose.

repository

String

An optional link to where the subgraph lives.

graft

Graft Base

An optional base to graft onto. See Grafting for details.

dataSources

Data Source[]

required

Each data source spec defines the data that will be ingested as well as the transformation logic to derive the state of the subgraph’s entities based on the source data.

templates

Data Source Template[]

Each data source template defines a data source that can be created dynamically from the mappings.

features

String[]

A list of feature names used by the subgraph. Required when specVersion is 0.0.4 or higher.

Schema

file

Path

required

The path of the GraphQL IDL file, either local or on IPFS.

Data Source

kind

String

required

The type of data source. Possible values: ethereum/contract, near/account, cosmos/contract, arweave, starknet/contract.

name

String

required

The name of the source data. Will be used to generate APIs in the mapping and also for self-documentation purposes.

network

String

required

For blockchains, this describes which network the subgraph targets.For Ethereum, this can be any of: mainnet, sepolia, goerli, polygon, mumbai, arbitrum-one, arbitrum-sepolia, optimism, base, bsc, fantom, gnosis, avalanche, and others.Check the graph-cli code for the most up-to-date list.

source

EthereumContractSource

required

The source data on a blockchain such as Ethereum.

mapping

Mapping

required

The transformation logic applied to the data prior to being indexed.

EthereumContractSource

address

String

The address of the source data in its respective blockchain. Optional for templates.

abi

String

required

The name of the ABI for this Ethereum contract. Must reference an ABI defined in the mapping.abis section.

startBlock

BigInt

The block to start indexing this data source from. Defaults to genesis block (0).

Mapping

Ethereum Mapping

kind

String

required

Must be ethereum/events for Ethereum Events Mapping.

apiVersion

String

required

Semver string of the version of the Mappings API that will be used by the mapping script.

language

String

required

The language of the runtime for the Mapping API. Possible values: wasm/assemblyscript.

entities

String[]

required

A list of entities that will be ingested as part of this mapping. Must correspond to names of entities in the GraphQL IDL.

abis

ABI[]

required

ABIs for the contract classes that should be generated in the Mapping ABI. Name is also used to reference the ABI elsewhere in the manifest.

eventHandlers

EventHandler[]

Handlers for specific events, which will be defined in the mapping script.

callHandlers

CallHandler[]

A list of functions that will trigger a handler and the name of the corresponding handlers in the mapping.

blockHandlers

BlockHandler[]

Defines block filters and handlers to process matching blocks.

file

Path

required

The path of the mapping script.

Each mapping is required to supply one or more handler type: eventHandlers, callHandlers, or blockHandlers.

Handler Types

EventHandler

event

String

required

An identifier for an event that will be handled in the mapping script. For Ethereum contracts, this must be the full event signature to distinguish from events that may share the same name.No alias types can be used. For example, uint will not work, uint256 must be used.

handler

String

required

The name of an exported function in the mapping script that should handle the specified event.

topic0

String

A 0x prefixed hex string. If provided, events whose topic0 is equal to this value will be processed by the given handler.When topic0 is provided, only the topic0 value will be matched, and not the hash of the event signature. This is useful for processing anonymous events in Solidity.

calls

CallDecl[]

A list of predeclared eth_calls that will be made before running the handler. Available from spec version 1.2.0.

CallHandler

function

String

required

An identifier for a function that will be handled in the mapping script. For Ethereum contracts, this is the normalized function signature to filter calls by.

handler

String

required

The name of an exported function in the mapping script that should handle the specified event.

BlockHandler

handler

String

required

The name of an exported function in the mapping script that should handle the specified event.

filter

BlockHandlerFilter

Definition of the filter to apply. If none is supplied, the handler will be called on every block.

BlockHandlerFilter

kind

String

required

The selected block handler filter. Options:

call: Only run the handler if the block contains at least one call to the data source contract
polling: Run the handler every N blocks (use with every field)
once: Run the handler once at initialization

every

Number

For polling filters, specifies how many blocks between handler invocations.

Declaring Calls

Available from spec version 1.2.0. Struct field access available from spec version 1.4.0.

Declared calls are performed in parallel before the handler is run and can greatly speed up syncing. Mappings access the call results simply by using ethereum.call from the mappings.

Call Format

Each call is of the form <ABI>[<address>].<function>(<args>):

label

String

required

A label for the call for error messages.

call

String

required

The call specification string.

ABI

String

required

The name of an ABI from the abis section.

address

Expr

required

The address of a contract that follows the ABI.

function

String

required

The name of a view function in the contract.

args

Expr[]

required

The arguments to pass to the function.

Expression Types

The Expr can be one of the following:

Expression	Description
`event.address`	The address of the contract that emitted the event
`event.params.<name>`	A simple parameter from the event
`event.params.<name>.<index>`	A field from a struct parameter by numeric index
`event.params.<name>.<fieldName>`	A field from a struct parameter by field name (spec version 1.4.0+)

Path

A path has one field path, which either refers to a path of a file on the local dev machine or an IPLD link. When using the Graph-CLI, local paths may be used during development, and then, the tool will take care of deploying linked files to IPFS and replacing the local paths with IPLD links at deploy time.

path

String | IPLD Link

required

A path to a local file or IPLD link.

Data Source Templates

A data source template has all of the fields of a normal data source, except it does not include a contract address under source. The address is a parameter that can later be provided when creating a dynamic data source from the template.

templates:
  - name: Exchange
    kind: ethereum/contract
    network: mainnet
    source:
      abi: Exchange
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      file: ./src/mappings/exchange.ts
      entities:
        - Exchange
      abis:
        - name: Exchange
          file: ./abis/exchange.json
      eventHandlers:
        - event: TokenPurchase(address,uint256,uint256)
          handler: handleTokenPurchase

Grafting

A subgraph can be grafted on top of another subgraph, meaning that, rather than starting to index the subgraph from the genesis block, the subgraph is initialized with a copy of the given base subgraph, and indexing resumes from the given block.

base

String

required

The subgraph ID of the base subgraph.

block

BigInt

required

The block number up to which to use data from the base subgraph.

specVersion: 0.0.6
description: Grafted Subgraph
repository: https://github.com/graphprotocol/graph-node
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum/contract
    name: SimpleContract
    network: mainnet
    source:
      address: "0x5FbDB2315678afecb367f032d93F642f64180aa3"
      abi: SimpleContract
      startBlock: 1000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      entities:
        - GraftedData
      abis:
        - name: SimpleContract
          file: ./abis/Contract.abi
      blockHandlers:
        - handler: handleBlock
      file: ./src/mapping.ts
features:
  - grafting
graft:
  base: QmPreviousSubgraphHash
  block: 999

Features

Starting from specVersion 0.0.4, a subgraph must declare all feature names it uses to be considered valid. A Graph Node instance will reject a subgraph deployment if:

The specVersion is equal to or higher than 0.0.4 AND
It hasn’t explicitly declared a feature it uses

No validation errors will happen if a feature is declared but not used.

Available Features

Feature	Name
Non-fatal errors	`nonFatalErrors`
Full-text Search	`fullTextSearch`
Grafting	`grafting`
IPFS on Ethereum Contracts	`ipfsOnEthereumContracts`

specVersion: 0.0.4
schema:
  file: ./schema.graphql
features:
  - nonFatalErrors
  - fullTextSearch
dataSources:
  # ... your data sources

Complete Example

specVersion: 0.0.8
description: My Subgraph
repository: https://github.com/myorg/my-subgraph
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum/contract
    name: MyContract
    network: mainnet
    source:
      address: "0x1234567890123456789012345678901234567890"
      abi: MyContract
      startBlock: 12345678
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - User
        - Transaction
      abis:
        - name: MyContract
          file: ./abis/MyContract.json
        - name: ERC20
          file: ./abis/ERC20.json
      eventHandlers:
        - event: Transfer(indexed address,indexed address,uint256)
          handler: handleTransfer
        - event: Approval(indexed address,indexed address,uint256)
          handler: handleApproval
      callHandlers:
        - function: deposit(uint256)
          handler: handleDeposit
      blockHandlers:
        - handler: handleBlock
          filter:
            kind: call
      file: ./src/mapping.ts
templates:
  - kind: ethereum/contract
    name: DynamicContract
    network: mainnet
    source:
      abi: DynamicContract
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - DynamicData
      abis:
        - name: DynamicContract
          file: ./abis/DynamicContract.json
      eventHandlers:
        - event: DataUpdated(uint256)
          handler: handleDataUpdated
      file: ./src/mapping.ts

Best Practices

Performance
Reliability
Maintainability

Set appropriate startBlock values to avoid unnecessary indexing from genesis
Use declared calls (available from spec 1.2.0) to parallelize RPC calls
Limit the number of entities in your schema to what’s actually needed
Use block handlers sparingly as they run on every block

Always use full event signatures with explicit types (e.g., uint256 not uint)
Declare all required features when using specVersion 0.0.4+
Use the latest stable apiVersion for new subgraphs
Test thoroughly with a local Graph Node before deploying

Add meaningful description and repository fields
Use descriptive names for data sources and handlers
Keep mapping files organized and well-documented
Version control your manifest alongside your code

Get Started

Core Concepts

Running Graph Node

Deployment

Advanced Configuration

Operations

Subgraph Manifest Specification

Overview

Format

Top-Level API

Schema

Data Source

EthereumContractSource

Mapping

Ethereum Mapping

Handler Types

EventHandler

CallHandler

BlockHandler

BlockHandlerFilter

Declaring Calls

Call Format

Expression Types

Path

Data Source Templates

Grafting

Features

Available Features

Complete Example

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Running Graph Node

Deployment

Advanced Configuration

Operations

​Overview

​Format

​Top-Level API

​Schema

​Data Source

​EthereumContractSource

​Mapping

​Ethereum Mapping

​Handler Types

​EventHandler

​CallHandler

​BlockHandler

​BlockHandlerFilter

​Declaring Calls

​Call Format

​Expression Types

​Path

​Data Source Templates

​Grafting

​Features

​Available Features

​Complete Example

​Best Practices

Build docs developers (and LLMs) love

Overview

Format

Top-Level API

Schema

Data Source

EthereumContractSource

Mapping

Ethereum Mapping

Handler Types

EventHandler

CallHandler

BlockHandler

BlockHandlerFilter

Declaring Calls

Call Format

Expression Types

Path

Data Source Templates

Grafting

Features

Available Features

Complete Example

Best Practices