> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt). 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](./schema-file.md), run: ```bash pnpm codegen ``` This command generates necessary types and code for your event handlers. --- ## Configuration Structure Here's an example `config.yaml` file: ```yaml # 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. :::note Addresses can be provided in **checksum** format or in **lowercase**. Envio accepts both and normalizes them internally. ::: **Single address:** ```yaml address: 0xContractAddress ``` **Multiple addresses for the same contract:** ```yaml 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: ```yaml contracts: - name: Greeter abi: greeter.json networks: - id: ethereum-mainnet contracts: - name: Greeter address: 0xProxyAddressHere ``` --- ### Per-Contract Start Block Override By default, contracts use the network `start_block`. Starting from `envio@2.27`, you can 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](/docs/v2/HyperIndex/dynamic-contracts) **Example with optional per-contract start_block override:** ```yaml networks: - id: 1 # ethereum-mainnet start_block: 18000000 # Default start block for all contracts on this network contracts: - name: ERC20 address: - 0x1111111111111111111111111111111111111111 - 0x2222222222222222222222222222222222222222 start_block: 18500000 # Override for this contract - name: Greeter address: 0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c # Uses network default (18000000) ``` --- ### Events Selection Define specific events to index in a human-readable format: ```yaml 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. ```yaml 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`: ```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: ```yaml 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](/docs/v2/HyperIndex/config-schema-reference#fieldselection) 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: ```yaml 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`: ```yaml unordered_multichain_mode: true ``` Learn more about when and how to use this feature [here](./multichain-indexing#unordered-multichain-mode). --- ### 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`: ```yaml rollback_on_reorg: true # default is true ``` See detailed configuration options [here](./reorgs-support). --- ### Preload Optimization Enable [Preload Optimization](/docs/v2/HyperIndex/preload-optimization) for your handlers. This will make most indexers processing much faster without any additional code changes. ```yaml preload_handlers: true # default is false ``` Be aware of: - [Double-Run Footgun](/docs/v2/HyperIndex/preload-optimization#double-run-footgun) - [Effect API for External Calls](/docs/v2/HyperIndex/effect-api) - [Migrating from Loaders](/docs/v2/HyperIndex/preload-optimization#migrating-from-loaders) (recommended) --- ### Environment Variables Since `envio@2.9.0`, environment variable interpolation is supported for flexibility and security: ```yaml networks: - id: ${ENVIO_CHAIN_ID:-ethereum-mainnet} contracts: - name: Greeter address: ${ENVIO_GREETER_ADDRESS} ``` Run your indexer with custom environment variables: ```bash 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](./environment-variables). --- ### Schema File Path You can customize the path to the [schema file](./schema-file.md) using the `schema` option: ```yaml schema: ./path/to/schema.graphql ``` By default, the `schema.graphql` is expected to be in the root directory of your project. --- ### Output Directory Path You can customize the path where the generated directory will be placed using the `output` option: ```yaml output: ./custom/generated/path ``` By default, the generated directory is placed in `generated` relative to the current working directory. If set, it will be a path relative to the config file location. :::warning Advanced Configuration This is an advanced configuration option. When using a custom output directory, you'll need to manually adjust your `.gitignore` file and project structure to match the new configuration. ::: --- ### Memory and Resource Considerations - **RPC rate limits**: If using RPC sync, your provider's rate limits will cap throughput. Use [HyperSync](../Advanced/hypersync.md) where supported for significantly faster data retrieval. - **Handler complexity**: Expensive operations in handlers (e.g., many `eth_call` via the [Effect API](../Advanced/effect-api.md)) slow down processing. Use caching and batching to mitigate. - **Database size**: Large entity tables slow down both writes and queries. Add [database indices](../Advanced/performance/database-performance-optimization.md) for frequently queried fields. For detailed performance optimization strategies, see the [Performance guide](../Advanced/performance/index.md). --- ## Full config file example This example indexes events from multiple contracts across multiple networks. ```yaml name: envio-indexer unordered_multichain_mode: true preload_handlers: true 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 # 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: - See the full, deep-linkable reference: [Config Schema Reference](/docs/v2/HyperIndex/config-schema-reference) :::info For AI/LLM Systems **Recommended**: Use the [Config Schema Reference](/docs/v2/HyperIndex/config-schema-reference) for programmatic access to schema information. The interactive viewer below is optimized for human users. ::: import CodeBlock from "@theme/CodeBlock"; import Schema from "@site/static/schemas/config.evm.json"; import JSONSchemaViewer from "@theme/JSONSchemaViewer";
📋 Hierarchical Interactive Schema Explorer (Click to expand - For human reference only)
--- Now your configuration file is set, you're ready to start indexing with HyperIndex!