Skip to main content

Configuration File (config.yaml)

The config.yaml file defines your indexer's behavior, including which blockchain events to index, contract addresses, which networks to index, and various advanced indexing options. It is a crucial step in configuring your HyperIndex setup.

After any changes to your config.yaml and the schema, run:

pnpm codegen

This command generates necessary types and code for your event handlers.

Configuration Structure​

Here's an example config.yaml file:

# yaml-language: $schema=./node_modules/envio/evm.schema.json
name: Greeter
description: Greeter Indexer Example

contracts:
  - name: Greeter
    abi:
      - event: "NewGreeting(address user, string greeting)"
      - event: "ClearGreeting(address user)"

networks:
  - id: 1 # ethereum-mainnet
    start_block: 12345678
    contracts:
      - name: Greeter
        address: 0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c

Key Configuration Options​

Contract Addresses​

Set the address of the smart contract you're indexing.

Single address:

address: 0xContractAddress

Multiple addresses for the same contract:

contracts:
  - name: MyContract
    address:
      - 0xAddress1
      - 0xAddress2
tip

If using a proxy contract, always use the proxy address, not the implementation address.

Global definitions:
You can also avoid repeating addresses by using global contract definitions:

contracts:
  - name: Greeter
    abi: greeter.json

networks:
  - id: ethereum-mainnet
    contracts:
      - name: Greeter
        address: 0xProxyAddressHere

Events Selection​

Define specific events to index in a human-readable format:

events:
  - event: "NewGreeting(address user, string greeting)"
  - event: "ClearGreeting(address user)"

By default, all events defined in the contract are indexed, but you can selectively disable them by removing them from this list.

Raw Events Storage​

By default, HyperIndex doesn't store raw event data in the database to optimize performance and reduce storage requirements. However, you can enable this feature for debugging purposes or if you need to access the original event data.

To enable storage of raw events, add the following to your config.yaml:

raw_events: true

When enabled, all indexed events will be stored in the raw_events table in the database, which you can view through the Hasura interface. This is particularly useful for:

  • Debugging event processing issues
  • Verifying that events are being captured correctly
  • Creating custom queries against raw blockchain data

Note that enabling this option will increase database storage requirements and may slightly impact indexing performance.

Field Selection​

To improve indexing performance and reduce credits usage the block and transaction fields on event contain only a subset of the fields available on the blockchain.

To access fields that are not provided by default, specify them using the field_selection option for your event:

events:
  - event: "Assigned(address indexed user, uint256 amount)"
    field_selection:
      transaction_fields:
        - transactionIndex
      block_fields:
        - timestamp

See all possible options in the Interactive Schema Explorer or use IDE autocomplete for your help.

Global Field Selection​

You can also specify fields globally for all events in the root of the config file:

field_selection:
  transaction_fields:
    - hash
    - gasUsed
  block_fields:
    - parentHash

Try to use this option sparingly as it can cause redundant Data Source calls and increased credits usage.

note

Field Selection per Event is available from envio@2.11.0 and above. Please, upgrade your indexer to access this feature.

Unordered Multichain Mode​

To improve indexing performance when indexing multiple blockchains, you can enable Unordered Multichain Mode. This setting allows parallel processing of events from different networks without strictly maintaining cross-chain event ordering. Useful for minimizing indexing latency when indexing at the head.

Activate this by adding to your config.yaml:

unordered_multichain_mode: true

Learn more about when and how to use this feature here.

Rollback on Reorg​

HyperIndex automatically handles blockchain reorganizations by default. To disable or customize this behavior, set the rollback_on_reorg flag in your config.yaml:

rollback_on_reorg: true # default is true

See detailed configuration options here.

Environment Variables​

Since envio@2.9.0, environment variable interpolation is supported for flexibility and security:

networks:
  - id: ${CHAIN_ID:-ethereum-mainnet}
    contracts:
      - name: Greeter
        address: ${GREETER_ADDRESS}

Run your indexer with custom environment variables:

CHAIN_ID=optimism ENVIO_ADDRESS=0xYourContractAddress pnpm dev

Interpolation syntax:

  • ${VAR} – Use the value of VAR
  • ${VAR:-default} – Use VAR if set, otherwise use default

Full config file example​

This example indexes events from multiple contracts across multiple networks.

name: envio-indexer
unordered_multichain_mode: true
rollback_on_reorg: false
contracts:
  - name: PoolManager
    handler: src/EventHandlers.ts
    events:
      - event: Swap(bytes32 indexed id, address indexed sender, int128 amount0, int128 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick, uint24 fee)
  - name: PositionManager
    handler: src/EventHandlers.ts
    events:
      - event: Transfer(address indexed from, address indexed to, uint256 indexed id)
networks:
  - id: 1
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - 0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e
      - name: PoolManager
        address:
          - "0x000000000004444c5dc75cB358380D2e3dE08A90"
  - id: 10
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - 0x3C3Ea4B57a46241e54610e5f022e5c45859A1017
      - name: PoolManager
        address:
          - 0x9a13F98Cb987694C9F086b1F5eB990EeA8264Ec3
  - id: 42161
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - 0xd88f38f930b7952f2db2432cb002e7abbf3dd869
      - name: PoolManager
        address:
          - 0x360e68faccca8ca495c1b759fd9eee466db9fb32

Interactive Schema Explorer​

Explore detailed configuration schema parameters here:

Loading ....

Now your configuration file is set, you're ready to start indexing with HyperIndex!