Skip to main content
You're viewing v3 documentation

This is the v3 HyperIndex documentation. Still on an older version? Open the v2 documentation and consider migrating to v3.

Configuration File (config.yaml)

The config.yaml file defines your indexer's behavior, including which blockchain events to index, contract addresses, which chains 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)"

chains:
  - 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.

note

Addresses can be provided in checksum format or in lowercase. Envio accepts both and normalizes them internally.

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

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

Per-Contract Start Block Override​

By default, contracts use the chain start_block. You can also set a per-contract start_block to override it. Handy when:

  • Contracts were deployed at different blocks
  • You only need data from a contract starting at a specific block
  • You want to skip unnecessary historical data for some contracts
  • Works nicely with Dynamic Contract Registration

Example with optional per-contract start_block override:

chains:
  - id: 1 # ethereum-mainnet
    start_block: 18000000 # Default start block for all contracts on this chain
    contracts:
      - name: ERC20Token
        address:
          - "0x1111111111111111111111111111111111111111"
          - "0x2222222222222222222222222222222222222222"
        start_block: 18500000 # Override for this contract
      - name: Greeter
        address: "0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c"
        # Uses chain default (18000000)

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.

Custom Event Names​

You can assign custom names to events in config.yaml. This is handy when two events share the same name but have different signatures, or when you want a more descriptive name in your Envio project.

events:
  - event: Assigned(address indexed recipientId, uint256 amount, address token)
  - event: Assigned(address indexed recipientId, uint256 amount, address token, address sender)
    name: AssignedWithSender

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 events 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 Config File Reference 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.

Multichain Mode​

In V3, multichain indexing always runs in unordered mode — events from different chains are processed in parallel without strictly maintaining cross-chain event ordering, which minimizes indexing latency at the head. The V2 unordered_multichain_mode option and the multichain: ordered opt-in have been removed.

Learn more about multichain indexing here.

Address Format​

Use address_format to control how every address surfaced by the indexer (event fields like event.srcAddress / event.transaction.from, chain.<Contract>.addresses, addresses embedded in entity ids, etc.) is formatted.

address_format: lowercase # default: checksum
  • checksum (default) – EIP-55 checksummed mixed-case addresses.
  • lowercase – every address is lowercased globally. Useful when joining against another data source that stores addresses in lowercase, or when you want byte-for-byte deterministic ids without per-handler .toLowerCase() calls.

You can still call .toLowerCase() ad-hoc inside a handler when you only need a single value lowercased.

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.

Preload Optimization​

Preload Optimization is always enabled in V3. There is no preload_handlers flag — the previous opt-in is now the only behavior.

Be aware of:

Environment Variables​

Environment variable interpolation is supported for flexibility and security:

chains:
  - id: ${ENVIO_CHAIN_ID:-ethereum-mainnet}
    contracts:
      - name: Greeter
        address: ${ENVIO_GREETER_ADDRESS}

Run your indexer with custom environment variables:

ENVIO_CHAIN_ID=optimism ENVIO_GREETER_ADDRESS=0xYourContractAddress pnpm dev

Interpolation syntax:

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

For more detailed information about environment variables, see our Environment Variables Guide.

Schema File Path​

You can customize the path to the schema file using the schema option:

schema: ./path/to/schema.graphql

By default, the schema.graphql is expected to be in the root directory of your project.

Memory and Resource Considerations​

  • RPC rate limits: If using RPC sync, your provider's rate limits will cap throughput. Use HyperSync where supported for significantly faster data retrieval.
  • Handler complexity: Expensive operations in handlers (e.g., many eth_call via the Effect API) slow down processing. Use caching and batching to mitigate.
  • Database size: Large entity tables slow down both writes and queries. Add database indices for frequently queried fields.

For detailed performance optimization strategies, see the Performance guide.

Full config file example​

This example indexes events from multiple contracts across multiple networks.

name: envio-indexer
contracts:
  - name: PoolManager
    events:
      - event: Swap(bytes32 indexed id, address indexed sender, int128 amount0, int128 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick, uint24 fee)
  - name: PositionManager
    events:
      - event: Transfer(address indexed from, address indexed to, uint256 indexed id)
chains:
  - id: 1
    # Keep it 0 and HyperSync will automatically find the first block for your contracts
    start_block: 0
    contracts:
      - name: PositionManager
        address:
          - "0xbD216513d74C8cf14cf4747E6AaA6420FF64ee9e"
        start_block: 18500000 # OPTIONAL: Override for contract deployed later
      - 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"

Configuration Schema Reference​

Explore detailed configuration schema parameters here:

For AI/LLM Systems

Recommended: Use the Config Schema Reference for programmatic access to schema information. The interactive viewer below is optimized for human users.

📋 Hierarchical Interactive Schema Explorer (Click to expand - For human reference only)
Loading ....

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