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
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 ofVAR
${VAR:-default}
– UseVAR
if set, otherwise usedefault
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:
Now your configuration file is set, you're ready to start indexing with HyperIndex!