StellarHyperion / stellarhyperion-backend

# Hyperion backend
The off-chain half. It answers one question and performs one job.
The question is "where is my transfer". A cross-chain transfer is two transactions on two chains
with a rail in between, and for some of its life it exists only as an attestation sitting in
somebody else's API. Nothing on either chain can tell you about that middle part, so something has
to watch both ends and the rail, and keep a record that outlives the seven days of history a
Soroban RPC node retains.
The job is moving a stuck one along. Rails get stuck for boring reasons: a destination gas market
moved between the quote and the execution, a recipient was frozen when the delivery arrived, a
second leg needs somebody to submit it and nobody did. Every one of those has a permissionless fix
on chain, and a keeper that notices and pays is worth more than a support inbox.
This process holds no keys that can move user funds. Everything it calls is either a read or a
permissionless call that anybody could make, which is a deliberate limit on how much damage it can
do if it is compromised.
## State of play
Built and verified:
| Subsystem | Scope |
| ------------ | ----------------------------------------------------------------- |
| Config | Declarative spec table, accumulating reader, strict validation |
| HTTP | Fastify 5, `/health` and `/ready` probes, REST API endpoints |
| Runtime | Poller loop, backoff, readiness registry, graceful shutdown |
| Database | Schema, SQL migrations, connection pool, row mappers |
| Stellar | Soroban event watcher, cursor safe across bounded ledger windows |
| EVM | Per-chain viem log watcher, confirmation-aware, reorg-detecting |
| Rail Pollers | Circle Iris attestation poller, Axelar GMP status poller |
| Keeper | BullMQ workers for TTL bumps, claim settlement, second-step calls |
| REST API | Transfer status, parked claims, route health, prometheus metrics |
| CI/CD | GitHub Actions workflow, PR template, CODEOWNERS, security docs |
158 tests passing across unit and integration suites against real PostgreSQL 16 and Redis 7. Both watchers are verified against live chains and testnet router contracts.
### Organization links
This service connects on-chain contracts with the web interface across the StellarHyperion organization:
- Contracts: stellarhyperion-contracts
- Frontend: stellarhyperion-frontend
## Why the config layer is the longest file here
Because a process that boots with half a configuration and discovers the rest on the first inbound
transfer discovers it at the worst possible moment.
Every variable goes through a spec that says what it is, whether it is required, what it is for,
and whether its value may ever appear in an error message. The reader accumulates faults instead of
throwing on the first one, so a bad deploy names every variable that needs attention in a single
message rather than one per restart. Nothing logs a value: `DATABASE_URL` and `REDIS_URL` carry
passwords, and a configuration dump at info level is