Skip to content

Docs for V3 alpha 5 #773

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
DZakh merged 1 commit into from
Jan 6, 2026
Merged

Docs for V3 alpha 5 #773

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
123 changes: 98 additions & 25 deletions docs/HyperIndex/migrate-to-v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,19 +75,95 @@ rpc:

In this case, the RPC won't be used for historical sync but will join the source selection logic when entering live indexing.

### Chain Info on Context
### Chain State on Context

The Handler Context object provides a nice way to get chain info via `chains` and `chain` properties:
The Handler Context object provides chain state via the `chain` property:

```typescript
ERC20.Approval.handler(async ({ context }) => {
console.log(context.chain.id); // 1 - The chain id of the event
console.log(context.chain.isLive); // true - Whether the event chain is indexing at the head

console.log(context.chains); // { 1: {id: 1, isLive: true}, 8453: {id: 8453, isLive: false} }
});
```

### Indexer State & Config

As a replacement for the deprecated and removed `getGeneratedByChainId`, we introduce the `indexer` value. It provides nicely typed chains and contract data from your config, as well as the current indexing state, such as `isLive` and `addresses`. Use `indexer` either at the top level of the file or directly from handlers. It returns the latest indexer state.

With this change, we also introduce new official types: `Indexer`, `EvmChainId`, `FuelChainId`, and `SvmChainId`.

```typescript
import { indexer } from "generated";

indexer.name; // "uniswap-v4-indexer"
indexer.description; // "Uniswap v4 indexer"
indexer.chainIds; // [1, 42161, 10, 8453, 137, 56]
indexer.chains[1].id; // 1
indexer.chains[1].startBlock; // 0
indexer.chains[1].endBlock; // undefined
indexer.chains[1].isLive; // false
indexer.chains[1].PoolManager.name; // "PoolManager"
indexer.chains[1].PoolManager.abi; // unknown[]
indexer.chains[1].PoolManager.addresses; // ["0x000000000004444c5dc75cB358380D2e3dE08A90"]
```

### Conditional Event Handlers

Now it's possible to return a boolean value from the `eventFilters` function to disable or enable the handler conditionally.

```typescript
ERC20.Transfer.handler(
async ({ event, context }) => {
// ... your handler logic
},
{
wildcard: true,
eventFilters: ({ chainId }) => {
// Skip all ERC20 on Polygon
if (chainId === 137) {
return false;
}

// Track all ERC20 on Ethereum Mainnet
if (chainId === 1) {
return true;
}

// Track only whitelisted addresses on other chains
return [
{ from: ZERO_ADDRESS, to: WHITELISTED_ADDRESSES[chainId] },
{ from: WHITELISTED_ADDRESSES[chainId], to: ZERO_ADDRESS },
];
},
}
);
```

### Automatic Contract Configuration

Started automatically configuring all globally defined contracts. This fixes an issue where `addContract` crashed because the contract was defined globally but not linked for a specific chain. Now it's done automatically:

```yaml
contracts:
- name: UniswapV3Factory
events: # ...
- name: UniswapV3Pool
events: # ...
chains:
- id: 1
start_block: 0
contracts:
- name: UniswapV3Factory
address: 0x1F98431c8aD98523631AE4a59f267346ea31F984
# UniswapV3Pool no longer needed here - auto-configured from global contracts
- id: 10
start_block: 0
contracts:
- name: UniswapV3Factory
address: 0x1F98431c8aD98523631AE4a59f267346ea31F984
# UniswapV3Pool no longer needed here - auto-configured from global contracts
```

### ClickHouse Sink (Experimental)

We added experimental support for a ClickHouse Sink. Postgres still serves as the primary database, and you can additionally sink the entities to a ClickHouse database that is restart- and reorg-resistant.
Expand Down Expand Up @@ -117,7 +193,7 @@ HyperIndex now supports Solana with RPC as a source. This feature is experimenta
To initialize a Solana project:

```bash
pnpx envio@3.0.0-alpha.4 init svm
pnpx envio@3.0.0-alpha.5 init svm
```

See the [Solana documentation](/docs/HyperIndex/solana) for more details.
Expand All @@ -144,11 +220,17 @@ Unordered multichain mode is now the default behavior. This provides better perf

Preload optimization is now enabled by default, replacing the previous `loaders` and `preload_handlers` options. This improves historical sync performance automatically.

### TUI Improvements

We gave our TUI some love, making it look more beautiful and compact. It also consumes fewer resources, shares a link to the Hasura playground, and dynamically adjusts to the terminal width.

![TUI](/img/sync.gif)

## Breaking Changes

### Node.js & Runtime

- **Node.js 22** is now the minimum required version
- **Node.js 22** is now the minimum required version, while 24 is the recommended version
- Changes in handler files don't trigger codegen on `pnpm dev`

### Handler API Changes
Expand Down Expand Up @@ -178,7 +260,7 @@ Preload optimization is now enabled by default, replacing the previous `loaders`

- Removed `chain` type in favor of `ChainId` (now a union type instead of a number)
- Removed internal `ContractType` enum (allows longer contract names)
- Removed `getGeneratedByChainId` (replacement coming in a future alpha version)
- Removed `getGeneratedByChainId` (use `indexer` value instead)

### Metrics Changes

Expand Down Expand Up @@ -220,7 +302,7 @@ Update your `package.json` with the following changes:
"node": ">=22.0.0"
},
"dependencies": {
"envio": "3.0.0-alpha.4"
"envio": "3.0.0-alpha.5"
},
"devDependencies": {
"typescript": "^5.7.3"
Expand Down Expand Up @@ -356,16 +438,6 @@ full_batch_size: 5000

Optionally move your handler files to `src/handlers/` and remove the explicit `handler` paths from `config.yaml`.

**RPC for Live Indexing (optional):**

If you want to use a dedicated RPC for live indexing:

```yaml
rpc:
- url: https://eth-mainnet.your-rpc-provider.com
for: live
```

### Step 4: Update Environment Variables

Remove these deprecated environment variables if present:
Expand All @@ -388,7 +460,7 @@ Remove these deprecated environment variables if present:

**Removed APIs:**

- `getGeneratedByChainId` — replacement coming in a future alpha version
- `getGeneratedByChainId` — use the `indexer.chains[chainId]` instead (see [Indexer State & Config](#indexer-state--config))

### Step 6: Test Your Migration

Expand All @@ -412,7 +484,7 @@ pnpm dev

- [ ] Update Node.js to >=22
- [ ] **Add `"type": "module"` to `package.json`** ← Required for V3!
- [ ] Update `envio` dependency to `3.0.0-alpha.4`
- [ ] Update `envio` dependency to `3.0.0-alpha.5`
- [ ] Update `engines.node` to `>=22.0.0` in `package.json`
- [ ] Update `tsconfig.json` for ESM support
- [ ] Replace `ts-mocha`/`ts-node` with `tsx` if using tests
Expand All @@ -437,7 +509,7 @@ pnpm dev
- [ ] Replace `block.chainId` with `context.chain.id` in block handlers
- [ ] Replace `transaction.kind` with `transaction.type`
- [ ] Update usage of `chain` type to `ChainId`
- [ ] Remove usage of `getGeneratedByChainId` (replacement coming soon)
- [ ] Replace `getGeneratedByChainId` with `indexer.chains[chainId]`
- [ ] Update code expecting `Address` type to be `string` (now `` `0x${string}` ``)
- [ ] Replace `transaction.chainId` with `context.chain.id` or `event.chainId`

Expand All @@ -453,8 +525,9 @@ If you encounter any issues during migration, join our [Discord community](https

For detailed release notes, see:

- [v3.0.0-alpha.0](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.0)
- [v3.0.0-alpha.1](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.1)
- [v3.0.0-alpha.2](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.2)
- [v3.0.0-alpha.3](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.3)
- [v3.0.0-alpha.5](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.5)
- [v3.0.0-alpha.4](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.4)
- [v3.0.0-alpha.3](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.3)
- [v3.0.0-alpha.2](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.2)
- [v3.0.0-alpha.1](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.1)
- [v3.0.0-alpha.0](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.0)
2 changes: 1 addition & 1 deletion docs/HyperIndex/solana/solana.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ description: Experimental Solana support in HyperIndex. Supports Block Handler,
## Quickstart

```bash
pnpx envio@3.0.0-alpha.4 init svm
pnpx envio@3.0.0-alpha.5 init svm
```

## Notes
Expand Down
7 changes: 6 additions & 1 deletion docs/HyperRPC/hyperrpc-supported-networks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ Here is a table of the currently supported networks on HyperRPC and their respec










Expand All @@ -56,7 +60,6 @@ Here is a table of the currently supported networks on HyperRPC and their respec
| Avalanche | 43114 | https://avalanche.rpc.hypersync.xyz or https://43114.rpc.hypersync.xyz |
| Base | 8453 | https://base.rpc.hypersync.xyz or https://8453.rpc.hypersync.xyz |
| Base Sepolia | 84532 | https://base-sepolia.rpc.hypersync.xyz or https://84532.rpc.hypersync.xyz |
| Base Traces | 8453 | https://base-traces.rpc.hypersync.xyz or https://8453-traces.rpc.hypersync.xyz |
| Berachain | 80094 | https://berachain.rpc.hypersync.xyz or https://80094.rpc.hypersync.xyz |
| Blast | 81457 | https://blast.rpc.hypersync.xyz or https://81457.rpc.hypersync.xyz |
| Blast Sepolia | 168587773 | https://blast-sepolia.rpc.hypersync.xyz or https://168587773.rpc.hypersync.xyz |
Expand All @@ -72,6 +75,7 @@ Here is a table of the currently supported networks on HyperRPC and their respec
| Ethereum Mainnet | 1 | https://eth.rpc.hypersync.xyz or https://1.rpc.hypersync.xyz |
| Fantom | 250 | https://fantom.rpc.hypersync.xyz or https://250.rpc.hypersync.xyz |
| Flare | 14 | https://flare.rpc.hypersync.xyz or https://14.rpc.hypersync.xyz |
| Fraxtal | 252 | https://fraxtal.rpc.hypersync.xyz or https://252.rpc.hypersync.xyz |
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 6, 2026

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

🏁 Script executed:

#!/bin/bash
# Verify that the HyperRPC endpoints for Fraxtal and Sei are accessible

echo "Testing Fraxtal endpoint (Network ID: 252)..."
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" --max-time 10 \
  https://fraxtal.rpc.hypersync.xyz || echo "Failed to connect"

echo ""
echo "Testing Fraxtal endpoint by ID (252)..."
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" --max-time 10 \
  https://252.rpc.hypersync.xyz || echo "Failed to connect"

echo ""
echo "Testing Sei endpoint (Network ID: 1329)..."
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" --max-time 10 \
  https://sei.rpc.hypersync.xyz || echo "Failed to connect"

echo ""
echo "Testing Sei endpoint by ID (1329)..."
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" --max-time 10 \
  https://1329.rpc.hypersync.xyz || echo "Failed to connect"

Repository: enviodev/docs

Length of output: 293

Remove or investigate Fraxtal and Sei entries - endpoints are not accessible.

Verification reveals all Fraxtal and Sei HyperRPC endpoints return HTTP 403 (Forbidden), indicating they are not accessible. Both the named endpoints (fraxtal.rpc.hypersync.xyz, sei.rpc.hypersync.xyz) and ID-based endpoints (252.rpc.hypersync.xyz, 1329.rpc.hypersync.xyz) are blocked. These entries should either be removed from the documentation or investigated to determine if access has been intentionally restricted or if the endpoints are no longer operational.

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

78-78: Bare URL used

(MD034, no-bare-urls)

78-78: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
In @docs/HyperRPC/hyperrpc-supported-networks.md at line 78, Documentation lists
Fraxtal and Sei RPC endpoints that return HTTP 403 and are inaccessible; update
the HyperRPC supported networks list by either removing the Fraxtal and Sei rows
or investigating and replacing the endpoints with working ones. Specifically,
check the entries for "Fraxtal" (network id 252, endpoints
fraxtal.rpc.hypersync.xyz and 252.rpc.hypersync.xyz) and "Sei" (network id 1329,
endpoints sei.rpc.hypersync.xyz and 1329.rpc.hypersync.xyz) and then either
delete those table rows or update them with validated, accessible endpoints and
a note about access restrictions if intentional.

| Fuji | 43113 | https://fuji.rpc.hypersync.xyz or https://43113.rpc.hypersync.xyz |
| Gnosis | 100 | https://gnosis.rpc.hypersync.xyz or https://100.rpc.hypersync.xyz |
| Gnosis Chiado | 10200 | https://gnosis-chiado.rpc.hypersync.xyz or https://10200.rpc.hypersync.xyz |
Expand Down Expand Up @@ -110,6 +114,7 @@ Here is a table of the currently supported networks on HyperRPC and their respec
| Rootstock | 30 | https://rootstock.rpc.hypersync.xyz or https://30.rpc.hypersync.xyz |
| Saakuru | 7225878 | https://saakuru.rpc.hypersync.xyz or https://7225878.rpc.hypersync.xyz |
| Scroll | 534352 | https://scroll.rpc.hypersync.xyz or https://534352.rpc.hypersync.xyz |
| Sei | 1329 | https://sei.rpc.hypersync.xyz or https://1329.rpc.hypersync.xyz |
| Sentient | 6767 | https://sentient.rpc.hypersync.xyz or https://6767.rpc.hypersync.xyz |
| Sentient Testnet | 1184075182 | https://sentient-testnet.rpc.hypersync.xyz or https://1184075182.rpc.hypersync.xyz |
| Sepolia | 11155111 | https://sepolia.rpc.hypersync.xyz or https://11155111.rpc.hypersync.xyz |
Expand Down
7 changes: 6 additions & 1 deletion docs/HyperSync/hypersync-supported-networks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ If you are a network operator or user and would like improved service support or










Expand All @@ -64,7 +68,6 @@ If you are a network operator or user and would like improved service support or
| Avalanche | 43114 | https://avalanche.hypersync.xyz or https://43114.hypersync.xyz | 🥉 |
| Base | 8453 | https://base.hypersync.xyz or https://8453.hypersync.xyz | 🏅 |
| Base Sepolia | 84532 | https://base-sepolia.hypersync.xyz or https://84532.hypersync.xyz | 🎒 |
| Base Traces | 8453 | https://base-traces.hypersync.xyz or https://8453-traces.hypersync.xyz | 🪨 |
| Berachain | 80094 | https://berachain.hypersync.xyz or https://80094.hypersync.xyz | 🥉 |
| Blast | 81457 | https://blast.hypersync.xyz or https://81457.hypersync.xyz | 🥉 |
| Blast Sepolia | 168587773 | https://blast-sepolia.hypersync.xyz or https://168587773.hypersync.xyz | 🎒 |
Expand All @@ -80,6 +83,7 @@ If you are a network operator or user and would like improved service support or
| Ethereum Mainnet | 1 | https://eth.hypersync.xyz or https://1.hypersync.xyz | 🏅 |
| Fantom | 250 | https://fantom.hypersync.xyz or https://250.hypersync.xyz | 🪨 |
| Flare | 14 | https://flare.hypersync.xyz or https://14.hypersync.xyz | 🪨 |
| Fraxtal | 252 | https://fraxtal.hypersync.xyz or https://252.hypersync.xyz | 🪨 |
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 6, 2026

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

🏁 Script executed:

#!/bin/bash
# Test Fraxtal and Sei HyperSync endpoints
echo "Testing Fraxtal HyperSync endpoint (Network ID: 252)..."
curl -s -o /dev/null -w "fraxtal.hypersync.xyz - HTTP Status: %{http_code}\n" --max-time 10 https://fraxtal.hypersync.xyz

echo "Testing Fraxtal HyperSync endpoint by ID (252)..."
curl -s -o /dev/null -w "252.hypersync.xyz - HTTP Status: %{http_code}\n" --max-time 10 https://252.hypersync.xyz

echo "Testing Sei HyperSync endpoint (Network ID: 1329)..."
curl -s -o /dev/null -w "sei.hypersync.xyz - HTTP Status: %{http_code}\n" --max-time 10 https://sei.hypersync.xyz

echo "Testing Sei HyperSync endpoint by ID (1329)..."
curl -s -o /dev/null -w "1329.hypersync.xyz - HTTP Status: %{http_code}\n" --max-time 10 https://1329.hypersync.xyz

Repository: enviodev/docs

Length of output: 415

🏁 Script executed:

# Find and examine the file context
fd "hypersync-supported-networks.md" -t f

# Get the file and show lines around 86 and 125
if git ls-files | grep -q "hypersync-supported-networks.md"; then
  echo "=== Context around line 86 ==="
  sed -n '80,92p' docs/HyperSync/hypersync-supported-networks.md
  echo ""
  echo "=== Context around line 125 ==="
  sed -n '119,131p' docs/HyperSync/hypersync-supported-networks.md
fi

Repository: enviodev/docs

Length of output: 3963

Remove or downgrade Fraxtal and Sei entries — HyperSync endpoints are non-functional (HTTP 403).

Both Fraxtal (252) and Sei (1329) endpoints return HTTP 403 Forbidden status, indicating they are inaccessible and non-functional. These should either be removed from the documentation or downgraded to a lower tier (🥉 or 🎒) to reflect their unavailability, consistent with how non-functional endpoints are handled in this guide.

🤖 Prompt for AI Agents 
In @docs/HyperSync/hypersync-supported-networks.md at line 86, The Fraxtal and
Sei entries in the networks table are reported non-functional (HTTP 403); update
the table rows for the networks labeled "Fraxtal" (ID 252) and "Sei" (ID 1329)
by either removing those rows entirely or downgrading their tier emojis to a
lower-tier indicator (e.g., 🥉 or 🎒) and adjust/remove their endpoint URLs
(https://fraxtal.hypersync.xyz / https://252.hypersync.xyz and the Sei URL) so
the documentation reflects their inaccessible status; ensure the changes target
the table rows containing the exact network names "Fraxtal" and "Sei" and IDs
252 and 1329.

| Fuji | 43113 | https://fuji.hypersync.xyz or https://43113.hypersync.xyz | 🎒 |
| Gnosis | 100 | https://gnosis.hypersync.xyz or https://100.hypersync.xyz | 🏅 |
| Gnosis Chiado | 10200 | https://gnosis-chiado.hypersync.xyz or https://10200.hypersync.xyz | 🎒 |
Expand Down Expand Up @@ -118,6 +122,7 @@ If you are a network operator or user and would like improved service support or
| Rootstock | 30 | https://rootstock.hypersync.xyz or https://30.hypersync.xyz | 🪨 |
| Saakuru | 7225878 | https://saakuru.hypersync.xyz or https://7225878.hypersync.xyz | 🪨 |
| Scroll | 534352 | https://scroll.hypersync.xyz or https://534352.hypersync.xyz | 🪨 |
| Sei | 1329 | https://sei.hypersync.xyz or https://1329.hypersync.xyz | 🪨 |
| Sentient | 6767 | https://sentient.hypersync.xyz or https://6767.hypersync.xyz | 🪨 |
| Sentient Testnet | 1184075182 | https://sentient-testnet.hypersync.xyz or https://1184075182.hypersync.xyz | 🪨 |
| Sepolia | 11155111 | https://sepolia.hypersync.xyz or https://11155111.hypersync.xyz | 🎒 |
Expand Down
Binary file modified static/img/sync.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 2 additions & 0 deletions supported-networks.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@
"supported-networks/flare-songbird",
"supported-networks/flow",
"supported-networks/flow-testnet",
"supported-networks/fraxtal",
"supported-networks/fuel-mainnet",
"supported-networks/fuel-testnet",
"supported-networks/fuji",
Expand Down Expand Up @@ -151,6 +152,7 @@
"supported-networks/satoshivm",
"supported-networks/scroll",
"supported-networks/scroll-sepolia",
"supported-networks/sei",
"supported-networks/sentient",
"supported-networks/sentient-testnet",
"supported-networks/sepolia",
Expand Down