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

You can optimize data retrieval by specifying exactly which fields to fetch (this is used to enhance performance, see Interactive Schema Explorer section):

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

Per-event Field Selection

Starting from envio@2.11.0, you can specify fields per event (see Interactive Schema Explorer for possibilities):

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

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!