ADR-0015: Deprecate Hyperliquid testnet; mainnet is the only live target

• Status: accepted, refines ADR-0001
• Date: 2026-06-02
• Affects: packages/brokers/hyperliquid-testnet/ (removed), packages/shared/src/broker.ts (BrokerKind union), apps/live-runner, packages/data-ingest, deployment UX, docs

Context

ADR-0001 set Hyperliquid as the MVP exchange and made testnet the default for live deployments, with mainnet gated behind explicit per-deployment confirmation. The intent was conservative: traders could prove out a Skill against a real exchange surface before risking capital.

In practice, Hyperliquid testnet does not earn its keep as a safety layer for this platform:

1. Liquidity and order flow on testnet don't reflect mainnet. Spreads, slippage, fill behavior, and funding rates on testnet are not representative. A strategy that "works on testnet" gives little information about whether it'll work on mainnet — the paper broker with realistic fee/slippage modeling already covers the "does my strategy run end-to-end without crashing" check, and does it deterministically with full historical context.
2. Testnet adds an integration to maintain. A separate adapter, separate API base, separate credentials, separate config flag throughout the stack. Each piece is a small thing; together they're a thicket the next contributor has to navigate to do anything live-shaped.
3. The "ramp" from sim to live happens at paper → mainnet anyway. No matter how thorough testnet was, a trader is still going to look at their first mainnet tick with the same anxiety. The presence of testnet as an intermediate stop pretends to add a safety layer it doesn't actually deliver. Better to be honest: sim is comprehensive (and now cross-margin per ADR-0014), then mainnet is the real thing.
4. Pre-MVP scope. We have no users running on testnet right now; the testnet adapter is a stub. The cost of removing it is near zero; the cost of carrying it forward is small-but-permanent.

Decision

Remove Hyperliquid testnet from the platform surface entirely. Mainnet is the only live target.

Concretely:

• Delete packages/brokers/hyperliquid-testnet/ (stub package; no implementation to migrate).
• Remove 'hyperliquid-testnet' from BrokerKind in packages/shared/src/broker.ts. Final union: 'paper' | 'hyperliquid-mainnet'.
• Drop the package from apps/live-runner deps and tsconfig project references; update apps/live-runner/src/types.ts broker_kind type union.
• Drop --env testnet from packages/data-ingest/src/cli.ts. Always hit api.hyperliquid.xyz/info. The HyperliquidEnv type and the env→URL map go away; ingest reads from mainnet only.
• Update the DB-schema check constraint in docs/architecture/data-model.md so broker_kind allows only 'paper' and 'hyperliquid-mainnet'. The actual migration is part of the database scaffolding phase; pre-MVP rows do not exist.
• Update the UI deploy flow (PRD bullet, roadmap) to drop the testnet picker option. Live deployment is paper or mainnet.
• ADR-0001's "testnet is the default" clause is refined by this ADR; ADR-0001 is otherwise still in force (Hyperliquid as MVP exchange).

What replaces testnet as a safety layer

The path from idea to live trading becomes:

strategy authoring (Skill editor)
    │
    ▼
backtest in simulator
    (cross-margin paper broker, real historical bars/news/funding,
     ADR-0014 accounting)
    │
    ▼
mainnet deployment
    (explicit per-deployment confirmation, mainnet-prod env-var fence,
     small initial position sizes via risk caps)

The safety net stack — L1–L7 in security/risk-controls.md — is unchanged. In particular:

• Engine-imposed risk caps still apply on mainnet exactly as in sim.
• The mainnet broker still requires an explicit per-deployment confirmation step (this is a UI gate, not a testnet gate).
• The mainnet env variable + secrets path stays distinct from dev/preview; nothing about that fence shifts.
• The "kill switch" infrastructure (L7) is independent of broker kind.

The thing we are losing: the comforting feeling of having pushed bytes at a Hyperliquid API and seen them come back. That's a real loss, but a small one — the integration code paths exercise the SDK; the difference between testnet and mainnet at that layer is the API base URL.

Alternatives considered

Alt A — Keep testnet as opt-in dev-only mode

• Leave the stub broker; remove from the UI dropdown but keep the code paths.
• Net effect: dead code that one developer might rediscover and re-enable inconsistently. Worse than full removal. Not picked.

Alt B — Replace testnet with a mainnet "dry-run" mode (orders simulated locally but read state from real mainnet)

• Reads real mainnet market state through Hyperliquid; doesn't place real orders.
• Interesting idea but it's basically the paper broker with extra steps. We already model real bars + funding + news. The marginal value is being on the live order-book at proposal time, which we don't actually need before deploying — risk caps + small initial sizing achieve the same protection.
• Deferred. If the paper broker's sim-to-live divergence ever becomes a problem we can revisit.

Alt C — Keep testnet, finish the adapter implementation properly

• Earlier project plan.
• Builds an integration we don't use. The cost is ongoing — Hyperliquid's testnet API can drift independently of mainnet, and we'd be tracking both.
• Not picked.

Consequences

Positive

• One less broker adapter to build, test, and maintain. Single Hyperliquid integration target.
• Honest mental model. Traders see the same surfaces sim → live. No false sense of safety from a testnet stop.
• Simpler config. One HYPERLIQUID_API_* set of env vars, no env switch flag through the stack.
• Smaller surface area for the deploy flow UI. Two broker choices in the dropdown instead of three.

Negative / trade-offs

• No exchange-side smoke test. Any change to the live broker adapter goes directly to mainnet for confirmation that the integration works. Mitigated by paper-broker integration tests for the engine path, by reading mainnet state in dry-run paths during development, and by small initial position sizes (10% of equity cap by default).
• ADR-0001's "testnet first" framing is gone. Anyone reading 0001 needs to know it's been refined here. Marked accordingly.
• Lost a debugging tool. If something looks weird on mainnet, having testnet as a comparison environment can be useful. We accept this; in practice, comparison would more often be vs the paper broker simulation anyway.

Things we'll need to revisit

• If the mainnet integration code grows substantially, build an integration-test rig that exercises the SDK against a Hyperliquid sandbox endpoint (if one exists in the future) or against recorded API fixtures. Don't reintroduce a testnet adapter just to have a place to point integration tests.
• If users start asking for testnet support back (unlikely — most want to trade real money), reconsider. The decision is reversible; the integration code can be reintroduced under the same BrokerKind extension point.

References

• ADR-0001 — Hyperliquid as MVP exchange; this ADR refines the testnet-default clause
• ADR-0014 — cross-margin paper broker; the sim layer that now substitutes for what testnet was supposed to provide
• security/risk-controls.md — the L1–L7 safety stack, unchanged by this decision
• packages/shared/src/broker.ts — BrokerKind union after the change