Configuration Schema Reference

Static, deep-linkable reference for the config.yaml JSON Schema.

Tip: Use the Table of Contents to jump to a field or definition.

Top-level Properties

description

Description of the project

type: string | null

Example (config.yaml):

description: Greeter indexer

name

Name of the project

type: string

Example (config.yaml):

name: MyIndexer

ecosystem

Ecosystem of the project.

type: anyOf(unknown | null)

Variants:

1: EcosystemTag
2: null

Example (config.yaml):

ecosystem: evm

schema

Custom path to schema.graphql file

type: string | null

Example (config.yaml):

schema: ./schema.graphql

output

Path where the generated directory will be placed. By default it's 'generated' relative to the current working directory. If set, it'll be a path relative to the config file location.

type: string | null

Example (config.yaml):

output: ./generated

contracts

Global contract definitions that must contain all definitions except addresses. You can share a single handler/abi/event definitions for contracts across multiple chains.

type: array | null

Example (config.yaml):

contracts:
  - name: Greeter
    handler: src/EventHandlers.ts
    events:
      - event: "NewGreeting(address user, string greeting)"

networks

Configuration of the blockchain networks that the project is deployed on.

type: array<unknown>
items: unknown
items ref: Network

Example (config.yaml):

networks:
  - id: 1
    start_block: 0
    contracts:
      - name: Greeter
        address: 0x9D02A17dE4E68545d3a58D3a20BbBE0399E05c9c

unordered_multichain_mode

A flag to indicate if the indexer should use a single queue for all chains or a queue per chain (default: false)

type: boolean | null

Example (config.yaml):

unordered_multichain_mode: true

event_decoder

The event decoder to use for the indexer (default: hypersync-client)

type: anyOf(unknown | null)

Variants:

1: EventDecoder
2: null

Example (config.yaml):

event_decoder: hypersync-client

rollback_on_reorg

A flag to indicate if the indexer should rollback to the last known valid block on a reorg. This currently incurs a performance hit on historical sync and is recommended to turn this off while developing (default: true)

type: boolean | null

Example (config.yaml):

rollback_on_reorg: true

save_full_history

A flag to indicate if the indexer should save the full history of events. This is useful for debugging but will increase the size of the database (default: false)

type: boolean | null

Example (config.yaml):

save_full_history: false

field_selection

Select the block and transaction fields to include in all events globally

type: anyOf(unknown | null)

Variants:

1: FieldSelection
2: null

Example (config.yaml):

field_selection:
  transaction_fields:
    - hash
  block_fields:
    - timestamp

raw_events

If true, the indexer will store the raw event data in the database. This is useful for debugging, but will increase the size of the database and the amount of time it takes to process events (default: false)

type: boolean | null

Example (config.yaml):

raw_events: true

Definitions

EcosystemTag

type: enum (1 values)
allowed: evm

Example (config.yaml):

ecosystem: evm

GlobalContract_for_ContractConfig

type: object
required: name, handler, events

Properties:

name: string – A unique project-wide name for this contract (no spaces)
abi_file_path: string | null – Relative path (from config) to a json abi. If this is used then each configured event should simply be referenced by its name
handler: string – The relative path to a file where handlers are registered for the given contract
events: array<unknown> – A list of events that should be indexed on this contract

Example (config.yaml):

contracts:
  - name: Greeter
    handler: src/EventHandlers.ts
    events:
      - event: "NewGreeting(address user, string greeting)"

EventConfig

type: object
required: event

Properties:

event: string – The human readable signature of an event 'eg. Transfer(address indexed from, address indexed to, uint256 value)' OR a reference to the name of an event in a json ABI file defined in your contract config. A provided signature will take precedence over what is defined in the json ABI
name: string | null – Name of the event in the HyperIndex generated code. When ommitted, the event field will be used. Should be unique per contract
field_selection: anyOf(unknown | null) – Select the block and transaction fields to include in the specific event

Example (config.yaml):

contracts:
  - name: Greeter
    handler: src/EventHandlers.ts
    events:
      - event: "Assigned(address indexed recipientId, uint256 amount, address token)"
        name: Assigned
        field_selection:
          transaction_fields:
            - transactionIndex

FieldSelection

type: object

Properties:

transaction_fields: array | null – The transaction fields to include in the event, or in all events if applied globally
block_fields: array | null – The block fields to include in the event, or in all events if applied globally

Example (config.yaml):

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

TransactionField

type: enum (33 values)
allowed: transactionIndex, hash, from, to, gas, gasPrice, maxPriorityFeePerGas, maxFeePerGas, cumulativeGasUsed, effectiveGasPrice, gasUsed, input, nonce, value, v, r, s, contractAddress, logsBloom, root, status, yParity, chainId, accessList, maxFeePerBlobGas, blobVersionedHashes, kind, l1Fee, l1GasPrice, l1GasUsed, l1FeeScalar, gasUsedForL1, authorizationList

BlockField

type: enum (24 values)
allowed: parentHash, nonce, sha3Uncles, logsBloom, transactionsRoot, stateRoot, receiptsRoot, miner, difficulty, totalDifficulty, extraData, size, gasLimit, gasUsed, uncles, baseFeePerGas, blobGasUsed, excessBlobGas, parentBeaconBlockRoot, withdrawalsRoot, l1BlockNumber, sendCount, sendRoot, mixHash

Network

type: object
required: id, start_block, contracts

Properties:

id: integer – The public blockchain network ID.
rpc_config: anyOf(unknown | null) – RPC configuration for utilizing as the network's data-source. Typically optional for chains with HyperSync support, which is highly recommended. HyperSync dramatically enhances performance, providing up to a 1000x speed boost over traditional RPC.
rpc: anyOf(unknown | null) – RPC configuration for your indexer. If not specified otherwise, for networks supported by HyperSync, RPC serves as a fallback for added reliability. For others, it acts as the primary data-source. HyperSync offers significant performance improvements, up to a 1000x faster than traditional RPC.
hypersync_config: anyOf(unknown | null) – Optional HyperSync Config for additional fine-tuning
confirmed_block_threshold: integer | null – The number of blocks from the head that the indexer should account for in case of reorgs.
start_block: integer – The block at which the indexer should start ingesting data
end_block: integer | null – The block at which the indexer should terminate.
contracts: array<unknown> – All the contracts that should be indexed on the given network

Example (config.yaml):

networks:
  - id: 1
    start_block: 0
    end_block: 19000000
    contracts:
      - name: Greeter
        address: 0x1111111111111111111111111111111111111111

RpcConfig

type: object
required: url

Properties:

url: anyOf(string | array<string>) – URL of the RPC endpoint. Can be a single URL or an array of URLs. If multiple URLs are provided, the first one will be used as the primary RPC endpoint and the rest will be used as fallbacks.
initial_block_interval: integer | null – The starting interval in range of blocks per query
backoff_multiplicative: number | null – After an RPC error, how much to scale back the number of blocks requested at once
acceleration_additive: integer | null – Without RPC errors or timeouts, how much to increase the number of blocks requested by for the next batch
interval_ceiling: integer | null – Do not further increase the block interval past this limit
backoff_millis: integer | null – After an error, how long to wait before retrying
fallback_stall_timeout: integer | null – If a fallback RPC is provided, the amount of time in ms to wait before kicking off the next provider
query_timeout_millis: integer | null – How long to wait before cancelling an RPC request

Example (config.yaml):

networks:
  - id: 1
    rpc_config:
      url: https://eth.llamarpc.com
      initial_block_interval: 1000

NetworkRpc

type: anyOf(string | unknown | array<unknown>)

Variants:

1: string
2: Rpc
3: array<unknown>

Example (config.yaml):

networks:
  - id: 1
    rpc: https://eth.llamarpc.com

Rpc

type: object
required: url, for

Properties:

url: string – The RPC endpoint URL.
for: unknown – Determines if this RPC is for historical sync, real-time chain indexing, or as a fallback.
initial_block_interval: integer | null – The starting interval in range of blocks per query
backoff_multiplicative: number | null – After an RPC error, how much to scale back the number of blocks requested at once
acceleration_additive: integer | null – Without RPC errors or timeouts, how much to increase the number of blocks requested by for the next batch
interval_ceiling: integer | null – Do not further increase the block interval past this limit
backoff_millis: integer | null – After an error, how long to wait before retrying
fallback_stall_timeout: integer | null – If a fallback RPC is provided, the amount of time in ms to wait before kicking off the next provider
query_timeout_millis: integer | null – How long to wait before cancelling an RPC request

Example (config.yaml):

networks:
  - id: 1
    rpc:
      - url: https://eth.llamarpc.com
        for: sync

For

type: oneOf(const sync | const fallback)

Variants:

1: const sync
2: const fallback

HypersyncConfig

type: object
required: url

Properties:

url: string – URL of the HyperSync endpoint (default: The most performant HyperSync endpoint for the network)

Example (config.yaml):

networks:
  - id: 1
    hypersync_config:
      url: https://eth.hypersync.xyz

NetworkContract_for_ContractConfig

type: object
required: name

Properties:

name: string – A unique project-wide name for this contract if events and handler are defined OR a reference to the name of contract defined globally at the top level
address: unknown – A single address or a list of addresses to be indexed. This can be left as null in the case where this contracts addresses will be registered dynamically.
abi_file_path: string | null – Relative path (from config) to a json abi. If this is used then each configured event should simply be referenced by its name
handler: string – The relative path to a file where handlers are registered for the given contract
events: array<unknown> – A list of events that should be indexed on this contract

Example (config.yaml):

networks:
  - id: 1
    start_block: 0
    contracts:
      - name: Greeter
        address:
          - 0x1111111111111111111111111111111111111111
        handler: src/EventHandlers.ts
        events:
          - event: Transfer(address indexed from, address indexed to, uint256 value)

Addresses

type: anyOf(anyOf(string | integer) | array<anyOf(string | integer)>)

Variants:

1: anyOf(string | integer)
2: array<anyOf(string | integer)>

Example (config.yaml):

networks:
  - id: 1
    contracts:
      - name: Greeter
        address:
          - 0x1111111111111111111111111111111111111111
          - 0x2222222222222222222222222222222222222222

EventDecoder

type: enum (2 values)
allowed: viem, hypersync-client

Example (config.yaml):

event_decoder: hypersync-client

Top-level Properties​

description​

name​

ecosystem​

schema​

output​

contracts​

networks​

unordered_multichain_mode​

event_decoder​

rollback_on_reorg​

save_full_history​

field_selection​

raw_events​

Definitions​

EcosystemTag​

GlobalContract_for_ContractConfig​

EventConfig​

FieldSelection​

TransactionField​

BlockField​

Network​

RpcConfig​

NetworkRpc​

Rpc​

For​

HypersyncConfig​

NetworkContract_for_ContractConfig​

Addresses​

EventDecoder​

Top-level Properties

description

name

ecosystem

schema

output

contracts

networks

unordered_multichain_mode

event_decoder

rollback_on_reorg

save_full_history

field_selection

raw_events

Definitions

EcosystemTag

GlobalContract_for_ContractConfig

EventConfig

FieldSelection

TransactionField

BlockField

Network

RpcConfig

NetworkRpc

Rpc

For

HypersyncConfig

NetworkContract_for_ContractConfig

Addresses

EventDecoder