Hyperion 4.0.5 — Operator reference

Source-cited operator documentation for Hyperion history-api 4.0.5. Every factual claim is backed by a file:line reference into the Hyperion source tree, so you can verify behavior against the code rather than trusting a doc.

These docs were produced while standing up a production Hyperion cluster and reverse-engineering behavior that wasn't covered by the official documentation (Redis topology, Sentinel passthrough, the ABI-scan → catchup → live transition machinery, queue sharding, etc.). Shared publicly for the benefit of other operators.

Contents

Doc	Scope	When to read
01-config-and-bootstrap.md	connections.json and chain .config.json field reference, startup sequence, common misconfigurations	Before first config edit; when an indexer won't start
02-indexer-control-plane.md	Master process, lifecycle phases (ABI scan → catchup → live), worker supervision, Redis keys, graceful shutdown, operator runbook	Before pm2 reload; when a replay stalls; when deciding whether to restart
03-indexer-data-plane.md	SHiP → RMQ → deserializer → ES/Mongo pipeline, queue topology, ABI caching, index templates, bottleneck diagnosis	When indexing is slow; when queues are backed up; when ES/Mongo writes fail
04-api-tier.md	Fastify API server, endpoint catalog, /v2/health contract, rate limiting, caching, streaming	Before touching API config; when CF LB sees a node unhealthy; when an endpoint is slow
05-cli-and-ops.md	Every CLI command (hyp-config, hyp-control, hyp-repair, hyp-es-config, hpm), common workflows, danger zone	Before running any hyp-* command; during incident response
06-redis-topology.md	All four Redis client sites, complete keyspace, producer/consumer map indexer↔API, deployment options (colocated vs. Sentinel), auth/Sentinel passthrough config	Before deciding where Redis lives; before rotating Redis creds; when /v2/health or get_transaction behaves oddly

Reading order

• New operator: 01 → 05 (workflows section) → 02 → 04 → 06 → 03 on demand
• Debugging a stuck indexer: 02 → 03 → 05
• Debugging a slow API: 04 → 06 → 03 → 05
• Planning a config change: 01 → 06 (if Redis/auth is involved) → 05 (safety matrix)
• Planning Redis topology or credential work: 06 → 01 → 05

Conventions

• File:line references in these docs are relative to the Hyperion source tree at src/ (i.e., master.ts:205 means src/indexer/modules/master.ts line 205 at the v4.0.5 tag). Paths should still be valid on main at the time of publication, but the line numbers may drift with upstream changes.
• When a doc says "TODO: verify X", the claim is informed-guess rather than confirmed. Treat as unverified until validated against the current code.
• Code snippets are verbatim quotes unless prefixed with "pseudocode" — do not paste pseudocode into production config.
• Example IP addresses in Sentinel configs etc. are illustrative. Substitute your own.

Verification history

These docs were originally produced by multiple subagents reading different sections of the codebase in parallel, then spot-checked against source. The spot-check caught three substantive errors in the first-draft output; all were corrected in the files here. Claims marked as verified below were re-read directly from the code.

Corrections applied during review

• 01: MongoDB enabled: false is respected at master.ts:1924 and in the API state routes; only a fully missing mongodb stanza triggers manager.class.ts:210. (Earlier draft said it was mandatory.)
• 02: All workers including parallel readers are auto-restarted by handleWorkerDisconnect (master.ts:1885) after 5s, except during mode_transition or shutdownStarted. (Earlier draft said readers were abandoned on crash.)
• 03: Queue-name table expanded with the correct sharding — index_blocks and the index_table_* queues are sharded by scaling.indexing_queues, not single-instance. index_abis is hardcoded to 1 queue (master.ts:1011–1012). The ds_pool queue family was missing and has been added.

Spot-checks that passed

• connections.json loader is plain JSON.parse (config.ts:129–144) — extra fields such as redis.username/redis.password/redis.sentinels DO pass through to ioredis, even though the TypeScript RedisConfig interface doesn't declare them.
• new Redis(this.manager.conn.redis) at master.ts:205, ds-pool.ts:100, api/server.ts:161.
• abieos.loadAbi('0', abiString) at state-history.ts:201 (the SHiP ABI error site).
• Master Redis writes: ${chain}:last_idx_block at master.ts:294 (LIVE branch only, not catchup); del ${chain}::fib at master.ts:1535 (startup); ${chain}::last_indexed_block at master.ts:1832 (graceful shutdown only).
• /v2/health Redis keys: ${chain}::ship_status 60s, hyperion-global::rabbit_status, ${chain}::es_status 1800s, ${chain}::fib no TTL (health.ts:88/99/218/240).
• TLS hardcoded rejectUnauthorized: false at manager.class.ts:116-118.

Known gaps

These topics are not covered and warrant follow-up if you hit them:

• MongoDB index strategy — Hyperion does not create Mongo indexes; the cluster operator must create them on the primary keys ({code, scope, symbol} for accounts, {voter}, {proposer, proposal_name}, etc.) or queries will table-scan.
• ES ILM policies — Hyperion creates time-partitioned indices but does not configure ILM. Long-running clusters need retention / rollover policies.
• Socket.io Redis adapter auth — The streaming pub/sub uses the same connections.json::redis object; if Redis is ACL-protected the operator must ensure the pub/sub channels are allowed for the configured user.
• Fork rollback in ES — master.ts:488–504 filters revBlockArray on fork but doesn't visibly delete ES documents. Fork handling on the write side wasn't fully traced.
• ARM64 support — @eosrio/node-abieos 4.1.0 ships only an x86_64 prebuilt binary. Graviton and other ARM64 deployments need a source rebuild (see docs/bootstrap in your own deployment repo for workaround).
• Non-eosio ABI namespace prefixes — abieos rejects any prefix that isn't eosio::abi/{1,2}.*. Forks of Antelope Spring that use a different namespace (e.g., core_net::abi/*) require an abieos patch.

Upstream contributions

Issues and PRs filed while producing these docs:

• eosrio/hyperion-history-api#164 — tolerate Redis READONLY on startup + declare Sentinel fields in RedisConfig
• AnvoIO/core#105 — Anvo Core should emit eosio::abi/* on eosio-bootstrapped chains

License

These docs are independent operator notes, not derived works of Hyperion itself. Shared under CC BY 4.0. Hyperion itself is MIT-licensed; see eosrio/hyperion-history-api for the source.