v4.1.0 — hot-tier query routing, stream replay hardening, asc range bounds

A performance-focused release: opt-in hot-tier routing keeps the most common history queries off old/cold shards, stream history replays are bounded by default, and sort=asc accepts sequence/block ranges as bounds.

New Features (opt-in, default off)

• Hot-first routing for get_actions account polls (#176, #177): with api.hot_first_actions: true, unbounded newest-first account polls (?account=X&limit=N, desc, no time bound) search only the newest api.hot_first_window (default 2) action partitions and widen to the full set only if the window returns fewer than limit hits — heavy pollers never fan out to old/warm shards. Responses served from the hot window carry hot_first: true. Also repairs ?hot_only=true, which previously targeted a non-existent alias.
• Recent-first routing for get_transaction (#180): with api.hot_first_transaction: true, a hint-less trx_id lookup probes the hot window first and widens to all partitions only on a miss. Since all of a transaction's documents share one partition, a hot-window hit is provably complete — recent lookups never touch the cold tier.
• get_transaction profiling (#181): api.hot_first_transaction_profiling: true logs per-request phase timings and parts_back so operators can size hot_first_window from measured lookup age distribution. Noisy — sample briefly, then disable.
• Row-deletion deltas restored (opt-in): features.index_deltas_deletions: true re-enables indexing of present=0 contract-row deltas as distinct deletion documents (lost in 4.0 when the delta-updater worker was removed), restoring deletion history in get_deltas. Requires a reindex of the affected range.

Fixes

• Stream history replay hardened against unbounded cold-tier walks (#178): replays are now capped at api.stream_max_concurrent_replays (default 4) per API process, stream_scroll_limit defaults to 50000 when unset (previously unlimited; -1 still means unlimited but warns past 100k docs), and scroll contexts are guaranteed released on every exit path (previously leaked on reject/timeout/NACK, pinning cold segments).
• get_transaction no longer masks Elasticsearch errors: non-404 ES errors propagate with the real cause instead of ending in a TypeError.

Improvements

• sort=asc accepts a global_sequence/block_num range as a valid bound on get_actions v2 (#182) — a range on the default sort field already bounds the scan, so it now satisfies the bound requirement without needing after/before. New api.require_bounded_asc (default true) lets self-hosted operators disable the asc bound guard entirely.

Upgrade note: if your config leaves stream_scroll_limit unset, history replays are now capped at 50000 docs per request; set -1 explicitly to keep unlimited scrolls (the new concurrency cap applies regardless).

Full details in CHANGELOG.md.

v4.0.8 — get_actions date/block bounds, ds_pool routing fix, ws security override

A quick maintenance release on top of 4.0.7 — API query fixes, an indexing routing fix, sync-accounts UX, and a security override for ws.

Fixes

• get_actions sort=asc accepts mixed date/block bounds (#174). A block-number bound combined with an ISO-date bound no longer returns 400 Invalid time value; each bound is classified independently (positive integer → block_num, else → @timestamp), in v1 and v2. Also hardened: strict integer classification (a date without T is no longer misread as a block number) and the sort=asc recency window now applies to any date after bound. Block-number bounds remain the supported way to query ranges older than max_asc_window_days.
• get_tokens missing balances (#170): sync accounts now resolves a contract's transfer struct via the action's declared type, so contracts using a non-transfer struct name are no longer skipped.
• ds_pool dropped traces for unassigned contracts (#169): an off-by-one routed unassigned contracts to a non-existent queue under ds_pool_size: 1; they now route to ds_pool:1.
• hyp-control indexer stop no longer fails with Invalid URL: ws://localhost:undefined/local on pre-4.0 configs missing control_port (now defaults to 7002).

Improvements

• Accurate sync accounts live progress (#171): continuously-moving "holders scanned" / "balances" counters and current-contract display instead of a stuck 0/1.

Security

• ws — Uninitialized memory disclosure (medium): pinned ws to 8.20.1 across the dependency tree via overrides (transitive deps still resolved < 8.20.1).

Maintenance

• nodemailer 8.0.7 → 8.0.10, ioredis 5.10.1 → 5.11.0, @types/node 25.5.0 → 25.9.1; CI now runs Build & Test on dev.

Upgrade note: after upgrading, re-run ./hyp-control sync accounts <chain> (or sync all) to backfill token contracts that the previous detection bug skipped.

Full details in CHANGELOG.md.

v4.0.7 — sync-all permissions, Redis/Sentinel resilience, optional pm2-independent deployment

Note: 4.0.6 was never tagged — that version sat on main and some operators deployed it directly before a release tag existed. To avoid ambiguity with those pre-tag production deployments, this work is released as 4.0.7. Functionally identical to what was briefly labeled 4.0.6.

⚠️ Before you upgrade

Hyperion now requires glibc ≥ 2.38 (Ubuntu 24.04+).

uWebSockets.js prebuilt binaries need GLIBC_2.38, so the API/stream server and indexer-controller will not start on Ubuntu 22.04 (glibc 2.35). Symptom:

Error: GLIBC_2.38 not found (required by .../uWebSockets.js/uws_linux_x64_*.node)

This is not new — every supported uWebSockets.js version needs glibc 2.38. It is simply documented now. Still on Ubuntu 22.04? Pick one:

• Upgrade the host to Ubuntu 24.04+, or run Hyperion in a glibc ≥ 2.38 container (e.g. node:22-trixie-slim).
• Pin the last glibc-2.35-compatible build — after each build/npm ci, force-install uWebSockets.js v20.52.0:

  npm install --no-save github:uNetworking/uWebSockets.js#v20.52.0
  

  (Trades newer uWS fixes for compatibility; re-apply after every rebuild.)
• Build uWebSockets.js from source on the host against its local glibc.

Highlights

🆕 Optional pm2-independent deployment — run Hyperion under systemd instead of pm2. New systemd/ unit templates (graceful controller stop for the indexer) plus an opt-in HYP_NO_PM2=1 mode for ./run / ./stop. pm2 stays the default and is unchanged when the variable is unset. Single-instance scope — pm2 cluster scaling (api.pm2_scaling) is intentionally not reproduced.

🐛 sync all no longer skips permissions — it previously synced voters/accounts/proposals/contract-state but silently skipped permissions, leaving the MongoDB permissions collection incomplete after a bootstrap or restore. It now runs with a proper indexer pause, and the standalone sync permissions race is closed. Re-run ./hyp-control sync all <chain> once after upgrading to backfill.

🐛 Redis replica / Sentinel resilience (#164, thanks @rwcii) — startup cache-invalidation DELs tolerate READONLY instead of crash-looping; RedisConfig now surfaces auth + Sentinel fields.

Other fixes

• Contract-state sync no longer aborts the run on a malformed/missing chain config — it reports a clear, actionable error instead.
• ./stop <chain>-api now actually stops the API (it was being treated as an indexer).
• Indexer status check is process-manager agnostic (no longer shells out to pm2 jlist; also fixes a latent always-false filter).
• Invalid query params return HTTP 400 (was 500); action regrouping handles notifications and inline actions correctly.

Maintenance

Dependency refresh — @wharfkit/antelope 1.2.0, amqplib 2.0.1, mongodb 7.2.0, fastify 5.8.5, undici 8.3.0, ws 8.20.1, zod 4.4.3, typescript 6.0.3, uWebSockets.js v20.67.0, plus Fastify plugin patches — and reconciled lockfiles.

Acknowledgements

Thanks to @eosusa for the field reports that drove several of these fixes — the launcher / process-management issues (./stop on the API, the glibc startup failure) and the sync all failures — and to @rwcii (#164) for the Redis replica/Sentinel resilience work.

---

Full details: CHANGELOG.md

v4.0.5 — Fix notification dedup regression

Fix: Notification Dedup Regression

Severity: High — impacts API response correctness for transaction queries

What was broken

A regression in v4.0.4 caused notification traces (e.g., eosio.token::transfer notifications to sender/receiver) to be stored as separate documents instead of being merged into a single action with multiple receipts. This caused get_transaction to return duplicate transfer actions, leading exchange integrations to triple-count deposits.

What this fixes

Indexer — Changed the dedup grouping key to use creator_action_ordinal, which correctly distinguishes notifications (merge with parent) from genuinely distinct duplicate actions (keep separate, per #148).

API (no re-index required) — Both v1 and v2 get_transaction handlers now re-group fragmented notification documents on read. This means:

• ✅ Data already indexed with v4.0.4 produces correct responses immediately after upgrading
• ✅ Newly indexed data is stored efficiently (merged at index time)
• ✅ v2 response now includes a notified field (comma-separated list of notified accounts)

What you need to do

1. Pull and rebuild from v4.0.5
2. Restart the API process
3. (Optional) Re-index from blocks to reclaim ~3x storage overhead from fragmented documents

Changed files

• src/indexer/helpers/action-dedup.ts — fixed grouping key
• src/api/helpers/regroup-actions.ts — new shared re-grouping helper
• src/api/routes/v2-history/get_transaction/get_transaction.ts — re-group on read + notified field
• src/api/routes/v1-history/get_transaction/get_transaction.ts — re-group on read
• tests/unit/action-dedup.test.ts — realistic Antelope ordinals
• tests/unit/regroup-actions.test.ts — new API re-grouping tests

v4.0.3 — Configurable Query Guards

Security

• Configurable Query Guards for sort=asc: Prevents unbounded ascending sort queries on get_actions (v1 & v2) that could overload Elasticsearch by forcing full reverse segment scans across all shards.

New Config Options

Two new optional fields in the api section of the chain config:

Option	Type	Default	Description
query_timeout	string	"10s"	Elasticsearch search timeout per query
max_asc_window_days	number	90	Maximum time range (in days) for sort=asc requests

Behavior Changes

• sort=asc on get_actions now requires a valid after or before parameter:
  • ISO date strings (must contain T, e.g., 2026-03-19T00:00:00Z)
  • Positive integer block numbers (e.g., 425000000)
• ISO date after values must be within max_asc_window_days of the current time.
• All get_actions queries (v1 + v2) now include a configurable Elasticsearch timeout.
• sort=desc (default) is unchanged — no new restrictions apply.

Testing

• 77/77 unit tests pass (17 new for query guard validation)
• Build: zero TypeScript errors

Upgrade

No configuration changes required — defaults apply automatically:

• query_timeout: "10s"
• max_asc_window_days: 90

To customize, add to your chain config under the api section:

{
  "api": {
    "query_timeout": "10s",
    "max_asc_window_days": 90
  }
}

v4.0.2

What's Changed

🧪 E2E Test Framework

• Added 8-phase high-fidelity end-to-end test suite with Docker-based infrastructure
• ChainManager, ContractDeployer, LoadGenerator, IndexerRunner, IntegrityChecker, ApiTests
• Docker Compose stack (ES 9.3.1, RabbitMQ, Redis) with port-isolated (+10000) networking

🔒 Security Fixes

• Bumped undici 7.22.0 → 7.24.4 (fixes CVE-2026-1528 and 5 other advisories)
• Updated all transitive dependencies — resolved 30 of 32 vulnerabilities

📦 Dependency Updates

• global-agent 4.1.2 → 4.1.3
• nodemailer 8.0.1 → 8.0.3
• @types/node 24.12.0 → 25.5.0

⚙️ CI

• Retargeted build workflow from release/4.0 to main
• Added unit test step (Bun) to CI pipeline

Full Changelog: v4.0.1...v4.0.2

v4.0.1

Hyperion History API v4.0.1

Dependency Upgrades (25 packages)

Major version bumps:

• @elastic/elasticsearch 9.3.4
• @fastify/mongodb 10.0.0 (mongodb driver 7.1.0)
• @fastify/static 9.0.0
• global-agent 4.1.2
• nodemailer 8.0.1
• uWebSockets.js v20.60.0
• @eosrio/node-abieos 4.1.0

Minor/patch updates:

• fastify 5.8.2, @fastify/cors 11.2.0, @fastify/http-proxy 11.4.1
• @fastify/redis 7.2.0, @fastify/swagger 9.7.0, @fastify/swagger-ui 5.2.5
• commander 14.0.3, dotenv 17.3.1, ioredis 5.10.0
• undici 7.22.0, ws 8.19.0, zod 4.3.6, lodash 4.17.23
• socket.io 4.8.3, socket.io-client 4.8.3

Unit Test Suite (new)

• 60 unit tests using bun test covering:
  • API helpers (query builders, meta merge, response schemas)
  • Indexer filter logic (checkMetaFilter — all 9 operators, @ meta expansion, asset filtering)
  • Configuration validation (Zod v4 schemas)
• Run with: bun test tests/unit

Code Cleanup

• Simplified plugins.ts FastifyInstance import (removed unnecessary http generic parameters)
• Dynamically load global-agent using createRequire

v4.0.0-beta.5

Full Changelog: v4.0.0-beta.4...v4.0.0-beta.5

v4.0.0-beta.4

• Update various dependencies including:
  • @elastic/elasticsearch to 9.1.1
  • @eosrio/node-abieos to 4.0.3-f7d5b45
  • @fastify/cors to 11.1.0
  • @fastify/swagger to 9.5.2
  • @wharfkit/antelope to 1.1.1
  • amqplib to 0.10.9
  • commander to 14.0.1
  • dotenv to 17.2.3
  • fastify to 5.6.1
  • ioredis to 5.8.0
  • mongodb to 6.20.0
  • nodemailer to 7.0.6
  • typescript to 5.9.2
  • undici to 7.16.0
  • zod to 4.1.11
• Update devDependencies including:
  • @types/async to 3.2.25
  • @types/node to 24.6.0
  • @types/nodemailer to 7.0.2

feat: add rabbit.sh for RabbitMQ installation

• Create a new script rabbit.sh to automate the installation of RabbitMQ and its dependencies on Ubuntu.

fix: update explorer metadata to include oracle configuration

• Modify the explorer metadata route to include oracle configuration from the manager and check for the existence of the oracle price histogram route.

fix: ensure MongoDB client is correctly typed

• Update the MongoDB client assignment in the server to use unknown as a workaround for type compatibility.

refactor: clean up plugin loading logic

• Remove unnecessary console error logs in the plugin loading process and improve type definition for plugin state.

v4.0.0-beta.3

What's Changed

Project Evolution & Ecosystem

• Full TypeScript Migration with ES Modules (Strict Mode):

  • The entire Hyperion History API codebase has been migrated to TypeScript.
  • The project now utilizes modern ES Modules and is compiled in strict mode, significantly enhancing code quality, maintainability, and the developer experience.

• Complete Migration from eosjs:

  • Replaced eosjs functionality with a combination of @wharfkit/antelope library and node-abieos
  • node-abieos continues to handle high-performance deserialization needs
  • @wharfkit/antelope provides modern TypeScript-first blockchain interaction APIs
  • New fastify-antelope plugin provides centralized chain API access
  • Enhanced serialization/deserialization with dual support and automatic fallback between both libraries

• Standalone Hyperion Explorer:

  • Compatibility with the new standalone Hyperion Explorer. The explorer application is now a separate project, available at https://github.com/eosrio/hyperion-explorer, and is no longer a Hyperion plugin.

• New Delphi Oracle Plugin & HPM:

  • Introduction of the hyperion-delphioracle-plugin. This new plugin allows Hyperion instances to track and serve data from on-chain price oracles, such as those powered by DelphiOracle.
  • The Hyperion Plugin Manager (hpm) remains fully functional for installing and managing this new plugin and existing ones.

Key Architectural Changes

• State Queries Overhauled: Hybrid MongoDB & Elasticsearch Architecture:

  • A fundamental re-architecture of state queries, with MongoDB handling contract state and Elasticsearch managing historical data. This major shift aims to significantly enhance performance, scalability, and query flexibility.
  • Introduces the Hyperion Account State Synchronizer (8ebf919) as the core engine for this new MongoDB-based state management.
  • New state-reader worker with advanced ABI caching and serialization strategies.
  • Fallback mechanisms between node-abieos and Antelope deserializers for maximum compatibility.
  • Provides robust support for custom contract indexing. Operators can now define how data from specific smart contracts is indexed and made available for queries, powered by a new custom_indexer_controller (c5711a5).

• Streaming SDK Rewrite:

  • The client-facing Streaming SDK has been completely rewritten (@eosrio/hyperion-stream-client v3.6+). This overhaul focuses on improved performance, expanded features, and better maintainability for developers building real-time applications on Hyperion.
  • Enhanced Developer Experience: New TypeScript-first API with full ES Modules support, AsyncIterator pattern for sequential data processing, and flexible event-driven architecture
  • Powerful Filtering & Data Consumption: Server-side filtering with dot-notation support, dual consumption patterns (event-driven and AsyncIterator), and automatic metadata processing
  • Robust Connection Management: Automatic reconnection with replay capabilities, connection timeout controls, and comprehensive error handling
  • Migration Note: The new streaming client (v3.6+) is only compatible with Hyperion servers v3.6 onwards

• Advanced Index Management (Elasticsearch):

  • Significant enhancements to Elasticsearch index lifecycle management. Hyperion now offers built-in capabilities for auto-pruning of aged data and implementing tiered storage allocation rules.
  • This advanced index management operates independently of Elastic's built-in policies, providing operators with more direct and granular control over their Hyperion data on Elasticsearch.

New Features & Major Enhancements

• Comprehensive State Synchronization Suite:

  • sync-accounts: Synchronizes complete account metadata including creation date, permissions, and resource limits
  • sync-permissions: Rebuilds permission hierarchies and tracks permission changes over time
  • sync-voters: Tracks voting power, delegations, and producer votes for governance analysis
  • sync-proposals: Indexes multisig proposals with their approval status and execution state
  • sync-contract-state: Enables custom indexing of smart contract tables and state changes

• Enhanced Repair CLI (hyp-repair):

  • New scan-actions feature for deep action data validation
  • Added monitor mode for real-time repair tracking
  • Improved interfaces for repair operations with better error recovery
  • New APIClient integration for direct chain queries during repairs

• Extensive CLI Tooling Updates:

  • This release brings numerous updates and enhancements across the suite of Command Line Interface (CLI) tools. These changes improve usability, add new functionalities, and resolve existing bugs.
  • Notable additions include a new Table Scanner Helper (cfb2188) for data diagnostics or management.
  • The hyp-repair tool has received fixes, including improved Elasticsearch library compatibility (9738d1f), and now includes a new scan-actions feature for more targeted diagnostics and repair of action data.

API & Endpoint Changes

• New Route: /v2/stats/get_trx_count: Adds a new endpoint to retrieve transaction counts, likely with various filtering options.
• New Route: /v2/history/get_block: Adds a new endpoint to fetch individual block details.

Breaking Changes

• MongoDB Now Required:

  • MongoDB is now a mandatory dependency for state queries and contract indexing
  • State table indices on Elasticsearch are deprecated and will stop receiving updates
  • All state-related data will be migrated to MongoDB for improved performance and most importantly, less disk wear

• Configuration File Location:

  • Configuration files must be moved to the new config directory
  • Legacy configuration locations are no longer supported

• API Response Format Changes:

  • Modified error response formats for better consistency

• Plugin Compatibility:

  • Existing plugins may need updates for TypeScript strict mode
  • Custom deserializers must handle new Antelope type system

Migration from 3.x

• Required Actions:

  1. Install MongoDB (now required for state queries)
  2. Move configuration files to the new config directory
  3. Review custom plugins for TypeScript compatibility
  4. Test streaming clients with new SDK

• For detailed migration instructions, see the official documentation at: https://hyperion.docs.eosrio.io/

• Deprecations:

  • Legacy streaming API protocol deprecated

Other Fixes & Improvements

• Type Safety for account_name (45e63da, 5d14196, 32c2530): Multiple commits ensure correct type handling for account names.
• Memory Usage Optimization (11cc4b9): Implements changes to reduce the memory footprint of Hyperion services.
• Monitoring Enhancements (da8025c, 8a448eb): Improvements to internal monitoring capabilities.
• Logging System Fixes (5b5fc88): General fixes and improvements to the logging infrastructure.
• Controller Connection Sequence (1d31968): Updates and refines the connection sequence for the Hyperion controller service.

Maintenance & Internal (Selected Commits from PR #157)

• Dependency Updates & Code Cleanup (a6ad50f, d2964aa, 522ece3).
• Log Output Refinements (7e90eaf, 4d596dd, 843b6b8, 60018a0).
• Repository Maintenance (145e1c0): Removal of ignored files.

Note: Commit SHAs in parentheses refer to commits within PR #157 that are indicative of the described changes. Some high-level changes reflect broader development efforts not captured by a single commit.

Full Changelog: v3.3.10-1...v4.0.0-beta.3