> ## 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 specification for the subgraph manifest file

## Overview

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

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.

<Note>
  **Spec Version**: v.0.0.4
</Note>

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

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

  <Expandable title="Example">
    ```yaml theme={null}
    specVersion: 0.0.4
    ```
  </Expandable>
</ParamField>

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

  <Expandable title="Example">
    ```yaml theme={null}
    schema:
      file: ./schema.graphql
    ```
  </Expandable>
</ParamField>

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

  <Expandable title="Example">
    ```yaml theme={null}
    description: "Uniswap V2 subgraph for tracking liquidity pools"
    ```
  </Expandable>
</ParamField>

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

  <Expandable title="Example">
    ```yaml theme={null}
    repository: "https://github.com/example/my-subgraph"
    ```
  </Expandable>
</ParamField>

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

  <Expandable title="Example">
    ```yaml theme={null}
    graft:
      base: QmQwXy...
      block: 12345678
    ```
  </Expandable>
</ParamField>

<ParamField path="dataSources" type="Array<Data Source Spec>" 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.

  See [Data Sources](/api/data-sources) for complete documentation.
</ParamField>

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

  See [Data Source Templates](/api/data-sources#data-source-templates) for complete documentation.
</ParamField>

<ParamField path="features" type="Array<String>">
  A list of feature names used by the subgraph. Required for `specVersion` >= 0.0.4.

  See [Features](#features) for available feature names.

  <Expandable title="Example">
    ```yaml theme={null}
    features:
      - nonFatalErrors
      - fullTextSearch
    ```
  </Expandable>
</ParamField>

## Schema

The schema defines the GraphQL types that will be generated for your subgraph.

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

  See [Path](#path) for format details.
</ParamField>

### Example

```yaml theme={null}
schema:
  file: ./schema.graphql
```

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

  <Tabs>
    <Tab title="Local Path">
      ```yaml theme={null}
      file: ./schema.graphql
      ```
    </Tab>

    <Tab title="IPLD Link">
      ```yaml theme={null}
      file: /ipfs/QmTXzATwNfgGVukV1fX2T6xw9f6LAYRVWpsdXyRWzUR2H9
      ```
    </Tab>
  </Tabs>
</ParamField>

## Graft Base

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.

<Warning>
  Grafting requires the `grafting` feature to be declared in the `features` list for `specVersion` >= 0.0.4.
</Warning>

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

  This is the IPFS hash of the deployed subgraph.
</ParamField>

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

  Indexing will resume from this block number.
</ParamField>

### Example

```yaml theme={null}
graft:
  base: QmQwXy8dhDzFfJHT4KJVXcGqTSQhvVuqN2G9rMpWLZ8VWP
  block: 12345678
```

## Features

Starting from `specVersion` `0.0.4`, a subgraph must declare all *feature* names it uses to be considered valid.

<Warning>
  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.
</Warning>

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

### Available Features

<ParamField path="nonFatalErrors" type="Feature">
  Enables non-fatal error handling in mappings. When enabled, errors in handlers won't stop the subgraph from syncing.
</ParamField>

<ParamField path="fullTextSearch" type="Feature">
  Enables full-text search capabilities on entities. Requires special field annotations in the schema.
</ParamField>

<ParamField path="grafting" type="Feature">
  Enables grafting functionality. Required when using the `graft` field in the manifest.
</ParamField>

<ParamField path="ipfsOnEthereumContracts" type="Feature">
  Enables IPFS data fetching from Ethereum contract events and calls.
</ParamField>

### Example

```yaml theme={null}
specVersion: 0.0.4
features:
  - nonFatalErrors
  - fullTextSearch
  - ipfsOnEthereumContracts
```

## Complete Manifest Example

<Tabs>
  <Tab title="Basic Subgraph">
    ```yaml theme={null}
    specVersion: 0.0.4
    description: My Ethereum Subgraph
    repository: https://github.com/example/my-subgraph
    schema:
      file: ./schema.graphql
    features:
      - nonFatalErrors
    dataSources:
      - kind: ethereum/contract
        name: MyContract
        network: mainnet
        source:
          address: "0x1234567890123456789012345678901234567890"
          abi: MyContract
          startBlock: 10000000
        mapping:
          kind: ethereum/events
          apiVersion: 0.0.7
          language: wasm/assemblyscript
          entities:
            - User
            - Transaction
          abis:
            - name: MyContract
              file: ./abis/MyContract.json
          eventHandlers:
            - event: Transfer(address,address,uint256)
              handler: handleTransfer
          file: ./src/mapping.ts
    ```
  </Tab>

  <Tab title="With Templates">
    ```yaml theme={null}
    specVersion: 0.0.4
    description: DEX Subgraph with Dynamic Pairs
    schema:
      file: ./schema.graphql
    features:
      - nonFatalErrors
    dataSources:
      - kind: ethereum/contract
        name: Factory
        network: mainnet
        source:
          address: "0xFactory..."
          abi: Factory
          startBlock: 10000000
        mapping:
          kind: ethereum/events
          apiVersion: 0.0.7
          language: wasm/assemblyscript
          entities:
            - Factory
            - Pair
          abis:
            - name: Factory
              file: ./abis/Factory.json
            - name: Pair
              file: ./abis/Pair.json
          eventHandlers:
            - event: PairCreated(address,address,address,uint256)
              handler: handlePairCreated
          file: ./src/factory.ts
    templates:
      - kind: ethereum/contract
        name: Pair
        network: mainnet
        source:
          abi: Pair
        mapping:
          kind: ethereum/events
          apiVersion: 0.0.7
          language: wasm/assemblyscript
          entities:
            - Pair
            - Token
            - Swap
          abis:
            - name: Pair
              file: ./abis/Pair.json
          eventHandlers:
            - event: Swap(address,uint256,uint256,uint256,uint256,address)
              handler: handleSwap
          file: ./src/pair.ts
    ```
  </Tab>

  <Tab title="With Grafting">
    ```yaml theme={null}
    specVersion: 0.0.4
    description: Grafted Subgraph
    schema:
      file: ./schema.graphql
    features:
      - grafting
    graft:
      base: QmQwXy8dhDzFfJHT4KJVXcGqTSQhvVuqN2G9rMpWLZ8VWP
      block: 15000000
    dataSources:
      - kind: ethereum/contract
        name: MyContract
        network: mainnet
        source:
          address: "0x1234567890123456789012345678901234567890"
          abi: MyContract
          startBlock: 15000000
        mapping:
          kind: ethereum/events
          apiVersion: 0.0.7
          language: wasm/assemblyscript
          entities:
            - Entity
          abis:
            - name: MyContract
              file: ./abis/MyContract.json
          eventHandlers:
            - event: Event(address,uint256)
              handler: handleEvent
          file: ./src/mapping.ts
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Sources" icon="database" href="/api/data-sources">
    Learn about configuring data sources
  </Card>

  <Card title="Mappings" icon="code" href="/api/mappings">
    Configure handlers and mapping logic
  </Card>
</CardGroup>