Skip to content

Update and improvements to the config-schema reference #710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JasoonS merged 2 commits into from
Oct 2, 2025
Merged

Update and improvements to the config-schema reference #710

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d3cd848
Update and improvements to the config-schema reference
JasoonS Oct 2, 2025
55557f1
Readd the example under 'events' for FieldSelection
JasoonS Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 70 additions & 49 deletions docs/HyperIndex/Advanced/config-schema-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ Static, deep-linkable reference for the `config.yaml` JSON Schema.
- [save_full_history](#savefullhistory)
- [field_selection](#fieldselection)
- [raw_events](#rawevents)
- [preload_handlers](#preloadhandlers)
- [address_format](#addressformat)
Comment on lines +28 to +29
Copy link
Contributor Author

@JasoonS JasoonS Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New features


### description {#description}

Expand Down Expand Up @@ -56,10 +58,10 @@ name: MyIndexer

Ecosystem of the project.

- **type**: `anyOf(unknown | null)`
- **type**: `anyOf(object<EcosystemTag> | null)`
Copy link
Contributor Author

@JasoonS JasoonS Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These 'unknown' fields were annoying, since we did actually have the type.


Variants:
- `1`: [EcosystemTag](#ecosystemtag)
- `1`: [EcosystemTag](#def-ecosystemtag)
Copy link
Contributor Author

@JasoonS JasoonS Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There were clashes, eg on the old site there was no way to link to this part of the page (since they both had the same link: https://docs.envio.dev/docs/HyperIndex/config-schema-reference#fieldselection)

image

unavailable via link since overshadowed:
Uploading image.png…

- `2`: `null`


Expand Down Expand Up @@ -116,9 +118,9 @@ contracts:

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

- **type**: `array&lt;unknown&gt;`
- **items**: `unknown`
- **items ref**: [Network](#network)
- **type**: `array<object<Network>>`
- **items**: `object<Network>`
- **items ref**: [Network](#def-network)


Example (config.yaml):
Expand Down Expand Up @@ -149,10 +151,10 @@ unordered_multichain_mode: true

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

- **type**: `anyOf(unknown | null)`
- **type**: `anyOf(object<EventDecoder> | null)`

Variants:
- `1`: [EventDecoder](#eventdecoder)
- `1`: [EventDecoder](#def-eventdecoder)
- `2`: `null`


Expand Down Expand Up @@ -192,10 +194,10 @@ save_full_history: false

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

- **type**: `anyOf(unknown | null)`
- **type**: `anyOf(object<FieldSelection> | null)`

Variants:
- `1`: [FieldSelection](#fieldselection)
- `1`: [FieldSelection](#def-fieldselection)
- `2`: `null`


Expand All @@ -206,7 +208,7 @@ field_selection:
transaction_fields:
- hash
block_fields:
- timestamp
- miner
Copy link
Contributor Author

@JasoonS JasoonS Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was just wrong, Timestamp is always included on the block and if you add this here the codegen will not allow it (and fail with error)

```

### raw_events {#rawevents}
Expand All @@ -222,9 +224,27 @@ Example (config.yaml):
raw_events: true
```

### preload_handlers {#preloadhandlers}

Makes handlers run twice to enable preload optimisations. Removes handlerWithLoader API, since it's not needed. (recommended, default: false)

- **type**: `boolean | null`


### address_format {#addressformat}

Address format for Ethereum addresses: 'checksum' or 'lowercase' (default: checksum)

- **type**: `anyOf(object<AddressFormat> | null)`

Variants:
- `1`: [AddressFormat](#def-addressformat)
- `2`: `null`


## Definitions

### EcosystemTag {#ecosystemtag}
### EcosystemTag {#def-ecosystemtag}

- **type**: `enum (1 values)`
- **allowed**: `evm`
Expand All @@ -235,7 +255,7 @@ Example (config.yaml):
ecosystem: evm
```

### GlobalContract_for_ContractConfig {#globalcontractforcontractconfig}
### GlobalContract_for_ContractConfig {#def-globalcontractforcontractconfig}

- **type**: `object`
- **required**: `name`, `handler`, `events`
Expand All @@ -244,7 +264,7 @@ 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&lt;unknown&gt;` – A list of events that should be indexed on this contract
- `events`: `array<object<EventConfig>>` – A list of events that should be indexed on this contract

Example (config.yaml):

Expand All @@ -256,15 +276,15 @@ contracts:
- event: "NewGreeting(address user, string greeting)"
```

### EventConfig {#eventconfig}
### EventConfig {#def-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
- `field_selection`: `anyOf(object<FieldSelection> | null)` – Select the block and transaction fields to include in the specific event

Example (config.yaml):

Expand All @@ -280,50 +300,45 @@ contracts:
- transactionIndex
```

### FieldSelection {#fieldselection}
### FieldSelection {#def-fieldselection}

- **type**: `object`

Properties:
- `transaction_fields`: `array | null` – The transaction fields to include in the event, or in all events if applied globally
- Available values:
`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`
- `block_fields`: `array | null` – The block fields to include in the event, or in all events if applied globally
- Available values:
`parentHash`, `nonce`, `sha3Uncles`, `logsBloom`, `transactionsRoot`, `stateRoot`, `receiptsRoot`, `miner`, `difficulty`, `totalDifficulty`, `extraData`, `size`, `gasLimit`, `gasUsed`, `uncles`, `baseFeePerGas`, `blobGasUsed`, `excessBlobGas`, `parentBeaconBlockRoot`, `withdrawalsRoot`, `l1BlockNumber`, `sendCount`, `sendRoot`, `mixHash`

Example (config.yaml):

```yaml
events:
- event: "Assigned(address indexed user, uint256 amount)"
# can be within an event as shown here, or globally for all events
field_selection:
transaction_fields:
- transactionIndex
block_fields:
- timestamp
- miner
```

### TransactionField {#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 {#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 {#network}
### Network {#def-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
- `rpc_config`: `anyOf(object<RpcConfig> | 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(object<NetworkRpc> | 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(object<HypersyncConfig> | 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&lt;unknown&gt;` – All the contracts that should be indexed on the given network
Copy link
Contributor Author

@JasoonS JasoonS Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was just a bug, it was overwriting it for some reason.

- `contracts`: `array<object<NetworkContract_for_ContractConfig>>` – All the contracts that should be indexed on the given network

Example (config.yaml):

Expand All @@ -337,13 +352,13 @@ networks:
address: 0x1111111111111111111111111111111111111111
```

### RpcConfig {#rpcconfig}
### RpcConfig {#def-rpcconfig}

- **type**: `object`
- **required**: `url`

Properties:
- `url`: `anyOf(string | array&lt;string&gt;)` – 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.
- `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
Expand All @@ -362,14 +377,14 @@ networks:
initial_block_interval: 1000
```

### NetworkRpc {#networkrpc}
### NetworkRpc {#def-networkrpc}

- **type**: `anyOf(string | unknown | array&lt;unknown&gt;)`
- **type**: `anyOf(string | object<Rpc> | array<object<Rpc>>)`

Variants:
- `1`: `string`
- `2`: [Rpc](#rpc)
- `3`: `array&lt;unknown&gt;`
- `2`: [Rpc](#def-rpc)
- `3`: `array<object<Rpc>>`

Example (config.yaml):

Expand All @@ -379,14 +394,14 @@ networks:
rpc: https://eth.llamarpc.com
```

### Rpc {#rpc}
### Rpc {#def-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.
- `for`: `object<For>` – 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
Expand All @@ -405,15 +420,15 @@ networks:
for: sync
```

### For {#for}
### For {#def-for}

- **type**: `oneOf(const sync | const fallback)`

Variants:
- `1`: `const sync`
- `2`: `const fallback`

### HypersyncConfig {#hypersyncconfig}
### HypersyncConfig {#def-hypersyncconfig}

- **type**: `object`
- **required**: `url`
Expand All @@ -430,17 +445,18 @@ networks:
url: https://eth.hypersync.xyz
```

### NetworkContract_for_ContractConfig {#networkcontractforcontractconfig}
### NetworkContract_for_ContractConfig {#def-networkcontractforcontractconfig}

- **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.
- `address`: `object<Addresses>` – 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.
- `start_block`: `integer | null` – The block at which the indexer should start ingesting data for this specific contract. If not specified, uses the network start_block. Can be greater than the network start_block for more specific indexing.
- `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&lt;unknown&gt;` – A list of events that should be indexed on this contract
- `events`: `array<object<EventConfig>>` – A list of events that should be indexed on this contract

Example (config.yaml):

Expand All @@ -457,13 +473,13 @@ networks:
- event: Transfer(address indexed from, address indexed to, uint256 value)
```

### Addresses {#addresses}
### Addresses {#def-addresses}

- **type**: `anyOf(anyOf(string | integer) | array&lt;anyOf(string | integer)&gt;)`
- **type**: `anyOf(anyOf(string | integer) | array<anyOf(string | integer)>)`

Variants:
- `1`: `anyOf(string | integer)`
- `2`: `array&lt;anyOf(string | integer)&gt;`
- `2`: `array<anyOf(string | integer)>`

Example (config.yaml):

Expand All @@ -477,7 +493,7 @@ networks:
- 0x2222222222222222222222222222222222222222
```

### EventDecoder {#eventdecoder}
### EventDecoder {#def-eventdecoder}

- **type**: `enum (2 values)`
- **allowed**: `viem`, `hypersync-client`
Expand All @@ -488,3 +504,8 @@ Example (config.yaml):
event_decoder: hypersync-client
```

### AddressFormat {#def-addressformat}

- **type**: `enum (2 values)`
- **allowed**: `checksum`, `lowercase`

1 change: 1 addition & 0 deletions docs/HyperRPC/hyperrpc-supported-networks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ Here is a table of the currently supported networks on HyperRPC and their respec
| Bsc Testnet | 97 | https://bsc-testnet.rpc.hypersync.xyz or https://97.rpc.hypersync.xyz | |
| Celo | 42220 | https://celo.rpc.hypersync.xyz or https://42220.rpc.hypersync.xyz | |
| Chainweb Testnet 20 | 5920 | https://chainweb-testnet-20.rpc.hypersync.xyz or https://5920.rpc.hypersync.xyz | |
| Chainweb Testnet 21 | 5921 | https://chainweb-testnet-21.rpc.hypersync.xyz or https://5921.rpc.hypersync.xyz | |
| Chainweb Testnet 22 | 5922 | https://chainweb-testnet-22.rpc.hypersync.xyz or https://5922.rpc.hypersync.xyz | |
| Chainweb Testnet 23 | 5923 | https://chainweb-testnet-23.rpc.hypersync.xyz or https://5923.rpc.hypersync.xyz | |
| Chainweb Testnet 24 | 5924 | https://chainweb-testnet-24.rpc.hypersync.xyz or https://5924.rpc.hypersync.xyz | |
Expand Down
1 change: 1 addition & 0 deletions docs/HyperSync/hypersync-supported-networks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ If you are a network operator or user and would like improved service support or
| Bsc Testnet | 97 | https://bsc-testnet.hypersync.xyz or https://97.hypersync.xyz | 🎒 | |
| Celo | 42220 | https://celo.hypersync.xyz or https://42220.hypersync.xyz | 🪨 | |
| Chainweb Testnet 20 | 5920 | https://chainweb-testnet-20.hypersync.xyz or https://5920.hypersync.xyz | 🪨 | |
| Chainweb Testnet 21 | 5921 | https://chainweb-testnet-21.hypersync.xyz or https://5921.hypersync.xyz | 🪨 | |
| Chainweb Testnet 22 | 5922 | https://chainweb-testnet-22.hypersync.xyz or https://5922.hypersync.xyz | 🪨 | |
Comment on lines +51 to 52
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify Chainweb Testnet 21 before advertising support

We previously removed this row after confirming the HyperSync endpoint returned HTTP 404; unless the service is now live, re-adding it gives users a broken URL. Please confirm the endpoint is operational (e.g. simple curl -I https://chainweb-testnet-21.hypersync.xyz) before keeping it here.
Based on learnings

🏁 Script executed:

#!/bin/bash
curl -s -o /dev/null -w "%{http_code}\n" https://chainweb-testnet-21.hypersync.xyz
curl -s -o /dev/null -w "%{http_code}\n" https://5921.hypersync.xyz

Length of output: 7

Remove Chainweb Testnet 21 Both endpoints return HTTP 404; remove this row until support is restored.

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

51-51: Bare URL used

(MD034, no-bare-urls)

51-51: Bare URL used

(MD034, no-bare-urls)

52-52: Bare URL used

(MD034, no-bare-urls)

52-52: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
docs/HyperSync/hypersync-supported-networks.md around lines 51 to 52: remove the
entire table row for "Chainweb Testnet 21" (the row containing port 5921 and the
two endpoints) so the table no longer lists that network; ensure the table
remains syntactically valid (remove the line only, do not alter other rows or
table headers) and save the file.

| Chainweb Testnet 23 | 5923 | https://chainweb-testnet-23.hypersync.xyz or https://5923.hypersync.xyz | 🪨 | |
| Chainweb Testnet 24 | 5924 | https://chainweb-testnet-24.hypersync.xyz or https://5924.hypersync.xyz | 🪨 | |
Expand Down
Loading