StellarHyperion / stellarhyperion-contracts

# Hyperion contracts
The on-chain half of Hyperion: a router on Stellar, a router on the EVM side, and one adapter per
rail they route over.
Hyperion is not a bridge. It never decides for itself that a cross-chain message is real. It hands
transfers to rails that already made that decision and were audited for it, and it keeps the
bookkeeping, the limits, the fee and the claims. `bridge_in` only ever acts on a call from the
underlying rail's own verifier, and there is no path in this repository by which Hyperion attests
anything.
That is a smaller promise than most bridges make, and it is the reason the code looks the way it
does. There is no validator set here, no multisig signing messages, no light client. What there is
instead is a lot of arithmetic that has to be exactly right, four rails that each behave slightly
differently, and three implementations of the same wire formats that have to agree.
## Organization overview
The StellarHyperion organization divides cross-chain routing across three dedicated repositories:
| Repository | Purpose | Core Technologies |
|---|---|---|
| `stellarhyperion-contracts` | On-chain routers, adapters, and shared protocol SDK | Soroban (Rust), EVM (Solidity, Foundry), TypeScript |
| `stellarhyperion-backend` | Event indexer, rail pollers, keeper upkeep, and REST API | Fastify, Postgres, Redis, BullMQ, viem, stellar-sdk |
| `stellarhyperion-frontend` | User interface, live switchyard, and transfer tracker | Next.js 16, React 19, CSS modules, wagmi, Stellar Wallets Kit |
Each repository maintains independent continuous integration, dependency definitions, and issue governance while sharing protocol constants and wire codecs from `@hyperion/protocol`.
## What is in the box
 [code] 
## The test suites
| Tree | Tests | Run it with |
|---|---|---|
| Soroban | 380 | `cd soroban && cargo test --workspace` |
| EVM | 365 | `cd evm && FOUNDRY_PROFILE=ci forge test` |
| Protocol package | 300 | `cd packages/protocol && npm run check` |
All 1,045 pass. The EVM suite includes fuzz tests at twenty thousand runs each, which is why it
takes a minute and a half.
The number worth more than the total is in the protocol package: `test/parity.test.ts` reads the
Rust and the Solidity off disk and fails if the error numbering, the route tags, the address kinds,
the quote blockers, the CCTP offsets, the SEP-23 version bytes, the note layout or the fee and
decimal ceilings have drifted apart. Three implementations of one wire format is the actual risk in
this design, and that test is what turns drift into a red branch rather than a transfer that
arrives somewhere unexpected.
## Things that are easy to get wrong, and what was done about them
**A Stellar address is not a 32 byte key.** It is a string with a CRC16 over its own contents, and
a bridge is the one place where an undetected flipped bit means funds delivered to an address
nobody on earth holds a secret for. So the string travels all the way to the contract and the
checksum is ve