Skip to main content
Version: v2

Setting up Configuration File

The config.yaml outlines the specifications for the indexer, including network and contract details, as well as event information to be used in the indexing process. For a full specification, view the explorer below.

Example Configuration

Here is an example config.yaml from the TypeScript Greeter template:

# yaml-language-server: $schema=./node_modules/envio/evm.schema.json
name: Greeter
description: Greeter indexer
#Global contract definitions that must contain all definitions except
#addresses. Now you can share a single handler/abi/event definitions
#for contracts across multiple chains
contracts:
- name: Greeter
abi_file_path: ./abis/greeter-abi.json
handler: ./src/EventHandlers.ts
events:
- event: NewGreeting
- event: ClearGreeting
networks:
- id: 137 # Polygon
start_block: 45336336
contracts:
- name: Greeter #A reference to the global contract definition
address: 0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c
- id: 59144 # Linea
start_block: 367801
contracts:
- name: Greeter #A reference to the global contract definition
address: 0xdEe21B97AB77a16B4b236F952e586cf8408CF32A

Once you have set up your config file and the schema, you are ready to generate the indexing code required to write the event handlers.

Run the following command:

pnpm codegen

Contract Addresses

For the address field in the configuration file, use the address that emits the events.

  • Transparent Proxy Pattern: Use the address of the proxy contract, as this is the contract that emits the events. Retrieve the ABI from the implementation contract.
  • No Proxy Contract: Use the same address from which the ABI was obtained.

If multiple contract addresses need to be indexed, they can be entered as an array like ["0xAddress1", "0xAddress2"] or in a dash-denominated list as seen in this example repo.

You can also choose to omit the address field for use cases like a factory contract where addresses will be dynamically registered during the indexing process.

Human-Readable ABI Format

In the configuration, you can optionally pass the file path to the ABI for a contract in the abi_file_path field, or you can specify the event signature in the event field.

Here is an example from the above configuration:

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

More information on Human Readable ABI parsing is available here.

Dev note: An error in the ABI or the event signature will result in the events not matching, and they may not reflect in the raw_events_table or propagate correctly into the event handler logic.

Custom Event Names

This is useful when you want to have a different name on the Envio side; or index events with the same name but different signatures:

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

Field Selection

Field selection allows you to add specific data points to each event that gets passed to your handlers. For a complete list of available fields, refer to the explorer below.

By default, the block_fields include number, hash, and timestamp without requiring additional configuration.

In the Fuel version, these default to the height, id, and time fields for blocks, along with the id field for transactions. Note that custom field selection is not supported for Fuel.

Note: For indexing from RPC in versions below envio@2.10.0, only hash and transactionIndex are supported in transaction_fields. If you encounter this limitation, consider upgrading to a more recent version to access improved functionality.

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

Field Selection per Event

Starting with envio@2.11.0, you can specify field selection for individual events. This feature is useful for optimizing RPC and HyperSync calls by fetching only the data relevant to specific events, avoiding over-fetching.

Per-event field selection overrides any global field selection, ensuring precise data handling for each event.

events:
- event: "Transfer(address indexed from, address indexed to, uint256 value)"
field_selection:
transaction_fields:
- "to"
- "from"

Environment Variables Interpolation

Starting from envio@2.9.0 the config file can use Environment Variables to offer more flexibility. If you want to switch between different configurations quickly, you don't need to edit the config file each time; you can just set Environment Variables at run time.

Below is a simple example:

networks:
- id: ${ENVIO_CHAIN_ID:-137}
start_block: ${ENVIO_START_BLOCK:-45336336}
contracts:
- name: Greeter
address: ${ENVIO_GREETER_ADDRESSES}

Then you can run ENVIO_GREETER_ADDRESSES=0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c pnpm dev, or set the values via the .env or the indexer settings page on the Hosted Service.

Interpolation syntax

For the interpolation to be applied, the Environment Variable name should be placed in braces after a dollar sign (${VAR}).

For braced expressions, the following formats are supported:

Direct substitution

  • ${VAR} -> value of VAR

Default value

  • ${VAR:-default} -> value of VAR if set and non-empty, otherwise default
  • ${VAR-default} -> value of VAR if set, otherwise default

Ways to set variables with interpolation

Envio can interpolate variables into your config file from multiple sources.

Note that when the same variable is declared by multiple sources, precedence applies:

  1. Variables from your shell environment
  2. Variables set via Hosted Service
  3. Variables set by a .env file in the root indexer directory

Additional Guidelines

  • The contract name field (Greeter in the example above) should contain a single word, as it is used to create a namespace for functions in the indexer.
  • The address field should contain the address of the proxy contract, which emits the events on the specified blockchain.
  • If the human-readable ABI format is not used, the ABI referenced in the config file needs to be copied from the implementation contract into the specified ABI directory.

Explorer

Loading ....