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

# 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

<ParamField path="kind" type="String" required>
  The type of data source.

  **Possible values:**

  * `ethereum/contract` - Ethereum smart contract data source

  <Expandable title="Example">
    ```yaml theme={null}
    kind: ethereum/contract
    ```
  </Expandable>
</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.

  Must be unique across all data sources in the manifest.

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

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

  <Note>
    For an up-to-date list, see the [graph-cli code](https://github.com/graphprotocol/graph-tooling/blob/main/packages/cli/src/protocols/index.ts#L76-L117).
  </Note>

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

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

  See [Ethereum Contract Source](#ethereum-contract-source) for details.
</ParamField>

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

  See [Mappings](/api/mappings) for complete documentation.
</ParamField>

## Ethereum Contract Source

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

<ParamField path="address" type="String" required>
  The address of the smart contract on the blockchain.

  Must be a valid Ethereum address (0x-prefixed hex string).

  <Expandable title="Example">
    ```yaml theme={null}
    address: "0x1234567890123456789012345678901234567890"
    ```
  </Expandable>
</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.

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

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

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

### Example

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

<ParamField path="name" type="String" required>
  Unique name for the template. Used when creating template instances in mapping code.
</ParamField>

<ParamField path="kind" type="String" required>
  Must be `ethereum/contract` for Ethereum templates.
</ParamField>

<ParamField path="network" type="String" required>
  The network this template targets.
</ParamField>

<ParamField path="source" type="Object" required>
  Source configuration without an address field.

  <Expandable title="Properties">
    * `abi` (String, required) - Name of the ABI for contracts created from this template
    * `startBlock` (BigInt, optional) - Block to start indexing from
  </Expandable>
</ParamField>

<ParamField path="mapping" type="Mapping" required>
  The mapping configuration for this template. Same structure as regular data sources.

  See [Mappings](/api/mappings) for details.
</ParamField>

### Creating Template Instances

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

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

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

### Template Example

<Tabs>
  <Tab title="Factory Pattern">
    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="Factory Mapping">
    ```typescript theme={null}
    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)
    }
    ```
  </Tab>
</Tabs>

## Multiple Data Sources

You can define multiple data sources to index multiple contracts:

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="Network Consistency">
    Ensure all data sources and templates in your manifest target the same network. Mixing networks in a single subgraph is not supported.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Common Patterns

### Single Contract

Indexing a single deployed contract:

```yaml theme={null}
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:

```yaml theme={null}
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:

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

<CardGroup cols={2}>
  <Card title="Mappings" icon="code" href="/api/mappings">
    Configure event handlers and mapping logic
  </Card>

  <Card title="Manifest Spec" icon="file-code" href="/api/manifest-spec">
    View complete manifest specification
  </Card>
</CardGroup>