Data Source Configuration

Overview

Data sources define what blockchain data will be ingested and how it will be transformed. Each data source specifies:

The type of blockchain (e.g., Ethereum)
The smart contract to index
Which network the contract is on
When to start indexing
How to transform the data (mappings)

Data Source Fields

kind

String

required

The type of data source.Possible values:

ethereum/contract - Ethereum smart contract data source

Show Example

kind: ethereum/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.Must be unique across all data sources in the manifest.

Show Example

name: MyContract

network

String

required

For blockchains, this describes which network the subgraph targets.Supported Ethereum networks:

mainnet - Ethereum Mainnet
goerli - Goerli testnet
sepolia - Sepolia testnet
matic - Polygon Mainnet
mumbai - Polygon Mumbai testnet
arbitrum-one - Arbitrum One
optimism - Optimism Mainnet
bsc - BNB Smart Chain
gnosis - Gnosis Chain (formerly xDai)
fantom - Fantom Opera
avalanche - Avalanche C-Chain
celo - Celo Mainnet

For an up-to-date list, see the graph-cli code.

Show Example

network: mainnet

source

EthereumContractSource

required

The source data on a blockchain such as Ethereum.See Ethereum Contract Source for details.

mapping

Mapping

required

The transformation logic applied to the data prior to being indexed.See Mappings for complete documentation.

Ethereum Contract Source

The source field for Ethereum data sources specifies which contract to index and from which block to start.

address

String

required

The address of the smart contract on the blockchain.Must be a valid Ethereum address (0x-prefixed hex string).

Show Example

address: "0x1234567890123456789012345678901234567890"

abi

String

required

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

Show Example

abi: MyContract

startBlock

BigInt

The block number to start indexing this data source from.Recommended: Set this to the block where your contract was deployed to improve sync performance.

Show Example

startBlock: 10000000

Example

source:
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  abi: USDC
  startBlock: 6082465

Data Source Templates

Data source templates allow you to create data sources dynamically at runtime. This is useful when:

New contracts are created by a factory contract
You need to index multiple instances of the same contract type
Contract addresses aren’t known at deployment time

Template Structure

A data source template has all the same fields as a normal data source, except:

No address field under source (address is provided when creating the template instance)
Must be defined in the templates array at the top level of the manifest

name

String

required

Unique name for the template. Used when creating template instances in mapping code.

kind

String

required

Must be ethereum/contract for Ethereum templates.

network

String

required

The network this template targets.

source

Object

required

Source configuration without an address field.

Show Properties

abi (String, required) - Name of the ABI for contracts created from this template
startBlock (BigInt, optional) - Block to start indexing from

mapping

Mapping

required

The mapping configuration for this template. Same structure as regular data sources.See Mappings for details.

Creating Template Instances

In your mapping code, create a new data source from a template using:

import { DataSourceTemplate } from '@graphprotocol/graph-ts'

// Create a new data source from a template
DataSourceTemplate.create('TemplateName', [contractAddress])

Template Example

Factory Pattern
Factory Mapping

dataSources:
  - kind: ethereum/contract
    name: Factory
    network: mainnet
    source:
      address: "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f"
      abi: UniswapV2Factory
      startBlock: 10000835
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Factory
        - Pair
      abis:
        - name: UniswapV2Factory
          file: ./abis/UniswapV2Factory.json
        - name: UniswapV2Pair
          file: ./abis/UniswapV2Pair.json
      eventHandlers:
        - event: PairCreated(indexed address,indexed address,address,uint256)
          handler: handlePairCreated
      file: ./src/factory.ts

templates:
  - kind: ethereum/contract
    name: Pair
    network: mainnet
    source:
      abi: UniswapV2Pair
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Pair
        - Token
        - Swap
      abis:
        - name: UniswapV2Pair
          file: ./abis/UniswapV2Pair.json
      eventHandlers:
        - event: Swap(indexed address,uint256,uint256,uint256,uint256,indexed address)
          handler: handleSwap
        - event: Sync(uint112,uint112)
          handler: handleSync
      file: ./src/pair.ts

import { PairCreated } from '../generated/Factory/UniswapV2Factory'
import { Pair as PairTemplate } from '../generated/templates'
import { Pair } from '../generated/schema'

export function handlePairCreated(event: PairCreated): void {
  // Create entity
  let pair = new Pair(event.params.pair.toHexString())
  pair.token0 = event.params.token0
  pair.token1 = event.params.token1
  pair.save()
  
  // Create dynamic data source from template
  PairTemplate.create(event.params.pair)
}

Multiple Data Sources

You can define multiple data sources to index multiple contracts:

dataSources:
  - kind: ethereum/contract
    name: TokenA
    network: mainnet
    source:
      address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
      abi: ERC20
      startBlock: 6082465
    mapping:
      # ... mapping configuration
  
  - kind: ethereum/contract
    name: TokenB
    network: mainnet
    source:
      address: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
      abi: ERC20
      startBlock: 4634748
    mapping:
      # ... mapping configuration

Best Practices

Set startBlock Appropriately

Always set startBlock to the block where your contract was deployed. This significantly improves indexing performance by avoiding unnecessary block processing.You can find the deployment block on block explorers like Etherscan.

Use Descriptive Names

Choose clear, descriptive names for your data sources. These names:

Appear in generated code
Help with debugging
Make your manifest self-documenting

Good: UniswapV2Factory, USDC Bad: Contract1, Token

Template Naming

For templates, use names that indicate they are templates and what they create:

Good: PairTemplate, ERC20Token
Avoid: Pair (ambiguous if you also have a Pair entity)

Network Consistency

Ensure all data sources and templates in your manifest target the same network. Mixing networks in a single subgraph is not supported.

ABI References

The abi field in source must match a name in the mapping.abis array. Double-check that:

Names match exactly (case-sensitive)
The ABI file exists at the specified path
The ABI contains all events/functions you’re handling

Common Patterns

Single Contract

Indexing a single deployed contract:

dataSources:
  - kind: ethereum/contract
    name: MyContract
    network: mainnet
    source:
      address: "0x1234..."
      abi: MyContract
      startBlock: 12000000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - MyEntity
      abis:
        - name: MyContract
          file: ./abis/MyContract.json
      eventHandlers:
        - event: MyEvent(address,uint256)
          handler: handleMyEvent
      file: ./src/mapping.ts

Factory + Template

Indexing a factory that creates multiple contract instances:

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
      abis:
        - name: Factory
          file: ./abis/Factory.json
      eventHandlers:
        - event: Created(address)
          handler: handleCreated
      file: ./src/factory.ts

templates:
  - kind: ethereum/contract
    name: Instance
    network: mainnet
    source:
      abi: Instance
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Instance
      abis:
        - name: Instance
          file: ./abis/Instance.json
      eventHandlers:
        - event: Action(address,uint256)
          handler: handleAction
      file: ./src/instance.ts

Indexing several contracts that interact:

dataSources:
  - kind: ethereum/contract
    name: Router
    network: mainnet
    source:
      address: "0xRouter..."
      abi: Router
      startBlock: 10000000
    mapping:
      # ... router mapping
  
  - kind: ethereum/contract
    name: Registry
    network: mainnet
    source:
      address: "0xRegistry..."
      abi: Registry
      startBlock: 10000000
    mapping:
      # ... registry mapping

GraphQL API

Graphman CLI

Subgraph Manifest

Data Source Configuration

Overview

Data Source Fields

Ethereum Contract Source

Example

Data Source Templates

Template Structure

Creating Template Instances

Template Example

Multiple Data Sources

Best Practices

Common Patterns

Single Contract

Factory + Template

Next Steps

Mappings

Manifest Spec

Build docs developers (and LLMs) love

GraphQL API

Graphman CLI

Subgraph Manifest

​Overview

​Data Source Fields

​Ethereum Contract Source

​Example

​Data Source Templates

​Template Structure

​Creating Template Instances

​Template Example

​Multiple Data Sources

​Best Practices

​Common Patterns

​Single Contract

​Factory + Template

​Multiple Related Contracts

​Next Steps

Mappings

Manifest Spec

Build docs developers (and LLMs) love

Overview

Data Source Fields

Ethereum Contract Source

Example

Data Source Templates

Template Structure

Creating Template Instances

Template Example

Multiple Data Sources

Best Practices

Common Patterns

Single Contract

Factory + Template

Multiple Related Contracts

Next Steps