Data Source Configuration

Complete guide to configuring data sources and templates

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

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

Factory Mapping

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

Multiple Related Contracts

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

Next Steps

Mappings

Configure event handlers and mapping logic

Manifest Spec

View complete manifest specification