> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# Subgraph Manifest Specification

> Complete reference for the 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](https://github.com/ipld/specs/) may be used to define a subgraph manifest. This includes YAML and JSON. Examples in this document are in YAML.

## Top-Level API

<ParamField path="specVersion" type="String" required>
  A Semver version indicating which version of this API is being used.
</ParamField>

<ParamField path="schema" type="Schema" required>
  The GraphQL schema of this subgraph. See [Schema](#schema) for details.
</ParamField>

<ParamField path="description" type="String">
  An optional description of the subgraph's purpose.
</ParamField>

<ParamField path="repository" type="String">
  An optional link to where the subgraph lives.
</ParamField>

<ParamField path="graft" type="Graft Base">
  An optional base to graft onto. See [Grafting](#grafting) for details.
</ParamField>

<ParamField path="dataSources" type="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.
</ParamField>

<ParamField path="templates" type="Data Source Template[]">
  Each data source template defines a data source that can be created dynamically from the mappings.
</ParamField>

<ParamField path="features" type="String[]">
  A list of feature names used by the subgraph. Required when `specVersion` is `0.0.4` or higher.
</ParamField>

## Schema

<ParamField path="file" type="Path" required>
  The path of the GraphQL IDL file, either local or on IPFS.
</ParamField>

## Data Source

<ParamField path="kind" type="String" required>
  The type of data source. Possible values: `ethereum/contract`, `near/account`, `cosmos/contract`, `arweave`, `starknet/contract`.
</ParamField>

<ParamField path="name" type="String" required>
  The name of the source data. Will be used to generate APIs in the mapping and also for self-documentation purposes.
</ParamField>

<ParamField path="network" type="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](https://github.com/graphprotocol/graph-tooling/blob/main/packages/cli/src/protocols/index.ts) for the most up-to-date list.
</ParamField>

<ParamField path="source" type="EthereumContractSource" required>
  The source data on a blockchain such as Ethereum.
</ParamField>

<ParamField path="mapping" type="Mapping" required>
  The transformation logic applied to the data prior to being indexed.
</ParamField>

### EthereumContractSource

<ParamField path="address" type="String">
  The address of the source data in its respective blockchain. Optional for templates.
</ParamField>

<ParamField path="abi" type="String" required>
  The name of the ABI for this Ethereum contract. Must reference an ABI defined in the `mapping.abis` section.
</ParamField>

<ParamField path="startBlock" type="BigInt">
  The block to start indexing this data source from. Defaults to genesis block (0).
</ParamField>

## Mapping

### Ethereum Mapping

<ParamField path="kind" type="String" required>
  Must be `ethereum/events` for Ethereum Events Mapping.
</ParamField>

<ParamField path="apiVersion" type="String" required>
  Semver string of the version of the Mappings API that will be used by the mapping script.
</ParamField>

<ParamField path="language" type="String" required>
  The language of the runtime for the Mapping API. Possible values: `wasm/assemblyscript`.
</ParamField>

<ParamField path="entities" type="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.
</ParamField>

<ParamField path="abis" type="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.
</ParamField>

<ParamField path="eventHandlers" type="EventHandler[]">
  Handlers for specific events, which will be defined in the mapping script.
</ParamField>

<ParamField path="callHandlers" type="CallHandler[]">
  A list of functions that will trigger a handler and the name of the corresponding handlers in the mapping.
</ParamField>

<ParamField path="blockHandlers" type="BlockHandler[]">
  Defines block filters and handlers to process matching blocks.
</ParamField>

<ParamField path="file" type="Path" required>
  The path of the mapping script.
</ParamField>

<Note>
  Each mapping is required to supply one or more handler type: `eventHandlers`, `callHandlers`, or `blockHandlers`.
</Note>

## Handler Types

### EventHandler

<ParamField path="event" type="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.
</ParamField>

<ParamField path="handler" type="String" required>
  The name of an exported function in the mapping script that should handle the specified event.
</ParamField>

<ParamField path="topic0" type="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.
</ParamField>

<ParamField path="calls" type="CallDecl[]">
  A list of predeclared `eth_calls` that will be made before running the handler. Available from spec version 1.2.0.
</ParamField>

### CallHandler

<ParamField path="function" type="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.
</ParamField>

<ParamField path="handler" type="String" required>
  The name of an exported function in the mapping script that should handle the specified event.
</ParamField>

### BlockHandler

<ParamField path="handler" type="String" required>
  The name of an exported function in the mapping script that should handle the specified event.
</ParamField>

<ParamField path="filter" type="BlockHandlerFilter">
  Definition of the filter to apply. If none is supplied, the handler will be called on every block.
</ParamField>

#### BlockHandlerFilter

<ParamField path="kind" type="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
</ParamField>

<ParamField path="every" type="Number">
  For `polling` filters, specifies how many blocks between handler invocations.
</ParamField>

## Declaring Calls

<Note>
  Available from spec version 1.2.0. Struct field access available from spec version 1.4.0.
</Note>

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>)`:

<ParamField path="label" type="String" required>
  A label for the call for error messages.
</ParamField>

<ParamField path="call" type="String" required>
  The call specification string.
</ParamField>

<ParamField path="ABI" type="String" required>
  The name of an ABI from the `abis` section.
</ParamField>

<ParamField path="address" type="Expr" required>
  The address of a contract that follows the ABI.
</ParamField>

<ParamField path="function" type="String" required>
  The name of a view function in the contract.
</ParamField>

<ParamField path="args" type="Expr[]" required>
  The arguments to pass to the function.
</ParamField>

### 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](https://github.com/ipld/specs/).

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.

<ParamField path="path" type="String | IPLD Link" required>
  A path to a local file or IPLD link.
</ParamField>

## 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.

<CodeGroup>
  ```yaml Example Template theme={null}
  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
  ```

  ```typescript Creating Dynamic Data Sources theme={null}
  import { DataSourceTemplate } from '@graphprotocol/graph-ts'

  // In your event handler
  export function handleNewExchange(event: NewExchange): void {
    // Create a new data source from the template
    DataSourceTemplate.create('Exchange', [event.params.exchange.toHex()])
  }
  ```
</CodeGroup>

## 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.

<ParamField path="base" type="String" required>
  The subgraph ID of the base subgraph.
</ParamField>

<ParamField path="block" type="BigInt" required>
  The block number up to which to use data from the base subgraph.
</ParamField>

<CodeGroup>
  ```yaml Grafting Example theme={null}
  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
  ```
</CodeGroup>

## 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` |

<CodeGroup>
  ```yaml Using Features theme={null}
  specVersion: 0.0.4
  schema:
    file: ./schema.graphql
  features:
    - nonFatalErrors
    - fullTextSearch
  dataSources:
    # ... your data sources
  ```
</CodeGroup>

## Complete Example

<CodeGroup>
  ```yaml Full Manifest Example theme={null}
  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
  ```
</CodeGroup>

## Best Practices

<Tabs>
  <Tab title="Performance">
    * 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
  </Tab>

  <Tab title="Reliability">
    * 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
  </Tab>

  <Tab title="Maintainability">
    * 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
  </Tab>
</Tabs>