Skip to content

docs: Update v3.0.0-alpha.15 release notes and features #851

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 10 commits into from
Apr 6, 2026
+70 −5
Merged

docs: Update v3.0.0-alpha.15 release notes and features #851

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
2cecfeb
Add v3.0.0-alpha.15 release notes to migration guide
claude Apr 3, 2026
8dcaa83
Move getWhere operators into existing getWhere API section
claude Apr 3, 2026
08b3693
Make block lag description more concise with advanced use case note
claude Apr 3, 2026
67fe16d
Add back env var replacement note to block lag description
claude Apr 3, 2026
cfb3b26
Add v3.0.0-alpha.16 release notes to migration guide
claude Apr 3, 2026
702c9ac
Clarify ENVIO_PG_PUBLIC_SCHEMA backward compat until v4
claude Apr 6, 2026
7261616
Add v3.0.0-alpha.18 release notes to migration guide
claude Apr 6, 2026
2bf44ea
Merge Metrics Changes into Official /metrics section, revert LLM file
claude Apr 6, 2026
93df311
Remove chain_block_height rename from metrics breaking changes
claude Apr 6, 2026
cab9345
Add v3.0.0-alpha.20 release notes to migration guide
claude Apr 6, 2026
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
75 changes: 70 additions & 5 deletions docs/HyperIndex/migrate-to-v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,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.14 init svm
pnpx envio@3.0.0-alpha.20 init svm
```

See the [Solana documentation](/docs/HyperIndex/solana) for more details.
Expand Down Expand Up @@ -232,7 +232,7 @@ We gave our TUI some love, making it look more beautiful and compact. It also co

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

### New Testing Framework (Experimental)
### New Testing Framework

We introduced a new testing framework that allows you to test handlers' logic using real blockchain data and programmatically debug code without repetitive local runs. Key capabilities include:

Expand Down Expand Up @@ -362,10 +362,63 @@ const transfers = await context.Transfer.getWhere.from.eq("0x123...");
const transfers = await context.Transfer.getWhere({ from: { _eq: "0x123..." } });
```

Additionally, three new filter operators are available following Hasura-style conventions:

```typescript
context.Entity.getWhere({ amount: { _gte: 100n } })
context.Entity.getWhere({ amount: { _lte: 500n } })
context.Entity.getWhere({ status: { _in: ["active", "pending"] } })
```

### Direct RPC Client

Replaced Ethers.js with a direct RPC client implementation, reducing dependencies and improving performance.

### Block Lag Configuration

A per-chain `block_lag` option to index behind the chain head by a specified number of blocks. Replaces the global `ENVIO_INDEXING_BLOCK_LAG` environment variable. Defaults to 0. This is for advanced use cases — only use it if you know what you're doing.

Comment on lines +379 to +380
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 3, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Missing migration guidance for ENVIO_INDEXING_BLOCK_LAG removal

Line 379 says block_lag replaces ENVIO_INDEXING_BLOCK_LAG, but the “Environment Variable Changes” list (Lines 442-447) does not include that variable. Please add it there (and ideally in the checklist) so migration steps are consistent and actionable.

Suggested doc fix 
 ### Environment Variable Changes
 
 - Removed `UNSTABLE__TEMP_UNORDERED_HEAD_MODE` environment variable
 - Removed `UNORDERED_MULTICHAIN_MODE` environment variable
+- Removed `ENVIO_INDEXING_BLOCK_LAG` environment variable (use per-chain `block_lag` in `config.yaml`)
 - Removed `MAX_BATCH_SIZE` environment variable (use `full_batch_size` in config.yaml instead)

Also applies to: 442-447

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/HyperIndex/migrate-to-v3.md` around lines 379 - 380, Add a migration
note that ENVIO_INDEXING_BLOCK_LAG is removed and replaced by the per-chain
config option block_lag: update the “Environment Variable Changes” list to
include ENVIO_INDEXING_BLOCK_LAG (indicate it’s removed and replaced by
block_lag, default 0), and add a checklist item instructing users to move any
ENVIO_INDEXING_BLOCK_LAG settings into the appropriate chain’s block_lag entry
in their config; reference the symbols block_lag and ENVIO_INDEXING_BLOCK_LAG so
readers can locate the relevant sections.

```yaml
chains:
- id: 1
block_lag: 5
```

### Official `/metrics` Endpoint

Prometheus metrics are now official. We cleaned up metric names, switched time units to seconds instead of milliseconds, and followed Prometheus naming conventions more closely. Metrics also cover data points previously available only via the `--bench` feature. A separate `/metrics/runtime` endpoint with a dedicated Prometheus registry is available for runtime metrics, isolated from the default `/metrics` endpoint.

Starting from the v3.0.0 release, Prometheus metrics will follow semver and be documented.

Breaking changes:

- Cleaned up metric names and switched time units from milliseconds to seconds
- Removed [`--bench`](/docs/HyperIndex/benchmarking) support — use the `/metrics` endpoint instead

### Double Handler Registration

It's now possible to register multiple handlers for the same event with similar filters:

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

ERC20.Transfer.handler(async ({ event, context }) => {
// Your logic here
});

ERC20.Transfer.handler(async ({ event, context }) => {
// And here
});
```
Comment on lines +400 to +412
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 3, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Example text and code don’t match on “similar filters”

Line 393 says handlers can be registered “with similar filters,” but both examples on Lines 398-404 have no filters. Either add filter args to the examples or drop “with similar filters” from the sentence.

Suggested doc wording fix 
-It's now possible to register multiple handlers for the same event with similar filters:
+It's now possible to register multiple handlers for the same event:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
It's now possible to register multiple handlers for the same event with similar filters:
```typescript
import { ERC20 } from "generated";
ERC20.Transfer.handler(async ({ event, context }) => {
// Your logic here
});
ERC20.Transfer.handler(async ({ event, context }) => {
// And here
});
```
It's now possible to register multiple handlers for the same event:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/HyperIndex/migrate-to-v3.md` around lines 393 - 405, The sentence claims
handlers can be registered "with similar filters" but the example using
ERC20.Transfer.handler has no filter arguments; either remove "with similar
filters" from the sentence or update the two ERC20.Transfer.handler examples to
include example filter params (e.g., a filter object or predicate passed to
handler) to demonstrate registering multiple handlers with similar filters;
reference the ERC20.Transfer.handler calls and update the surrounding text and
examples so they match.


### Improved Multiple Data-Sources Support

After switching to a fallback source, HyperIndex now attempts to recover to the primary source 60 seconds later. Previously, it would stay on the fallback until the fallback was down or the indexer was restarted. The source selection logic has also been improved for better indexing resilience and stricter enforcement of the `live` mode configuration.

### Updated Dev Docker Flow

`envio dev` no longer uses a generated Docker Compose file and manages containers, network, and volumes directly for greater flexibility. For example, disabling Hasura with `ENVIO_HASURA` now prevents `envio dev` from pulling the Hasura image. Use `envio dev --restart` (or `-r`) to forcefully clear the database even if there are no config changes detected.

## Breaking Changes

### Node.js & Runtime
Expand Down Expand Up @@ -406,6 +459,7 @@ export ENVIO_API_TOKEN=your_token_here
- Removed `UNSTABLE__TEMP_UNORDERED_HEAD_MODE` environment variable
- Removed `UNORDERED_MULTICHAIN_MODE` environment variable
- Removed `MAX_BATCH_SIZE` environment variable (use `full_batch_size` in config.yaml instead)
- Renamed `ENVIO_PG_PUBLIC_SCHEMA` to `ENVIO_PG_SCHEMA` (the old name is still supported until v4)

### Generated Code Changes

Expand All @@ -415,16 +469,21 @@ export ENVIO_API_TOKEN=your_token_here
- **Lowercased entity types removed**: Generated code no longer exports lowercased entity types (e.g., `transfer`). Use capitalized names instead (e.g., `Transfer`)
- Entity array field values are now typed as `readonly` — update any code that directly mutates array fields

### Metrics Changes
### Postgres Column Updates

- Renamed `chain_block_height` Prometheus metric to `envio_indexing_known_height`
- `raw_events.event_id`: `NUMERIC` → `BIGINT`
- `raw_events.serial`: `SERIAL` → `BIGSERIAL`
- `envio_chains.events_processed`: `INTEGER` → `BIGINT`
- `envio_checkpoints.id`: `INTEGER` → `BIGINT`
- Deprecated `envio_chains._num_batches_fetched` — always returns 0 for backward compatibility

## Fixes

- Fixed an issue where the indexer stops progressing without any error (PostgreSQL client update)
- Fixed checksum for addresses returned by RPC in lowercase
- Fixed incorrect validation of transactions `to` field returned by RPC
- Fixed OOM error on RPC request crashing loop
- Fixed an edge case where a multichain indexer could freeze during a rollback on reorg (also backported to v2.32.10)

## Migration Guide

Expand Down Expand Up @@ -462,7 +521,7 @@ Update your `package.json` with the following changes:
"node": ">=22.0.0"
},
"dependencies": {
"envio": "3.0.0-alpha.14"
"envio": "3.0.0-alpha.20"
},
"devDependencies": {
"typescript": "^5.7.3"
Expand Down Expand Up @@ -769,6 +828,12 @@ If you encounter any issues during migration, join our [Discord community](https

For detailed release notes, see:

- [v3.0.0-alpha.20](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.20)
- [v3.0.0-alpha.19](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.19)
- [v3.0.0-alpha.18](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.18)
- [v3.0.0-alpha.17](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.17)
- [v3.0.0-alpha.16](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.16)
- [v3.0.0-alpha.15](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.15)
- [v3.0.0-alpha.14](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.14)
- [v3.0.0-alpha.13](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.13)
- [v3.0.0-alpha.12](https://github.com/enviodev/hyperindex/releases/tag/v3.0.0-alpha.12)
Expand Down