diff --git a/docs/roadmap.md b/docs/roadmap.md index 35ef726..628c0e9 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,7 +1,9 @@ # Roadmap -> Status: living plan. Track 1 spot discovery has landed; Track 2 outcome reads -> are under review as an experimental read-only follow-up. +> Status: living plan. Tracks 1-4 have landed. Track 5 HyperEVM direct swap is +> paused as a later spike until liquidity, routing, allowance, and failure modes +> are validated. Release remains intentionally gated until live testnet/IRL +> validation and generated release output are reviewed. > Direction: keep `usdh-kit` centered on USDH, but expand from "obtain USDH via > USDC" to "interact cleanly with USDH surfaces on Hyperliquid". @@ -26,11 +28,21 @@ What already works: - HyperCore balance reads and route/preflight helpers - `bridgeAndSwap()` for route -> optional bridge -> swap - USDH spot discovery with `listPairs`, `getPair`, `getBook`, and `getMids` -- `InfoClient` reads for `spotMeta`, `spotClearinghouseState`, and `l2Book` +- experimental read-only outcome discovery with `listOutcomeMarkets`, + `getOutcomeMarket`, `getOutcomeBook`, and `getOutcomeMids` +- USDH-only spot orders with `placeOrder`, `cancelOrder`, `getOpenOrders`, and + `getOrderStatus` +- `InfoClient` reads for `spotMeta`, `outcomeMeta`, + `spotClearinghouseState`, `l2Book`, `allMids`, `frontendOpenOrders`, and + `orderStatus` - typed lifecycle errors, including `BridgeAndSwapError` and `isBridgeAndSwapError()` - React widget on top of the SDK +- `USDH -> USDC` HyperCore reverse swaps +- `bridgeFromCore()` for linked USDC/USDH spot assets moving from HyperCore to + HyperEVM + This remains the core retail path. New roadmap items should preserve that simple path instead of forcing integrators into a broader trading abstraction. @@ -85,7 +97,8 @@ type UsdhPair = { - testnet/mainnet token-index handling behind existing network config - Watchlist: - HIP-3 USDH-denominated markets - - outcome metadata, once Track 2 confirms the exact API shape + - outcome write support, only after denomination/settlement behavior is + verified - Out of scope: - generic pair discovery for all assets - generic perps SDK @@ -95,9 +108,9 @@ type UsdhPair = { Owner: @sumfxn -Status: in review as PR #51. The proposed API is read-only and experimental: -metadata, side encoding helpers, books, and mids only. It does not add outcome -orders, cancellations, or settlement/denomination claims. +Status: landed as PR #51. The API is read-only and experimental: metadata, side +encoding helpers, books, and mids only. It does not add outcome orders, +cancellations, or settlement/denomination claims. Prioritize this if outcomes are natively denominated in USDH. This is a stronger USDH use case than generic perps because it creates direct demand for USDH as the @@ -114,9 +127,10 @@ settlement/quote asset. ### Proposed API ```ts -kit.listOutcomeMarkets({ quote?: 'USDH' }): Promise -kit.getOutcomeMarket(id: string): Promise -kit.getOutcomeBook(id: string, opts?: { nSigFigs?: NSigFigs }): Promise +kit.listOutcomeMarkets(): Promise +kit.getOutcomeMarket({ outcome }): Promise +kit.getOutcomeBook({ outcome, side, nSigFigs? }): Promise +kit.getOutcomeMids(): Promise> ``` Possible later write path: @@ -142,6 +156,12 @@ kit.placeOutcomeOrder({ ## Track 3 - Targeted USDH trading +Owner: @Yaugourt + +Status: landed as PR #54. The final API stays USDH-scoped while accepting both +live Hyperliquid pair names such as `@230` and ergonomic token aliases such as +`USDH/USDC`. + Build only the trading primitives needed for USDH markets: ```ts @@ -177,6 +197,10 @@ lower-level order API in docs. ## Track 4 - Useful USDH flows +Status: landed in PR #56. Reverse swap and bridge-out are implemented in the SDK +with conservative constraints. No live write-path bridge/swap test has been run +yet, so release remains gated on IRL validation. + Keep the UX simple: - `USDC -> USDH` remains the core path @@ -188,9 +212,21 @@ Keep the UX simple: ```ts kit.swap({ from: 'USDH', to: 'USDC', amount, ... }) -kit.bridgeFromCore({ asset: 'USDC' | 'USDH', amount, recipient? }) +kit.bridgeFromCore({ asset: 'USDC' | 'USDH', amount }) ``` +Implementation notes from PR #56: + +- `USDH -> USDC` is HyperCore-only. HyperEVM direct swap stays a separate + Track 5 spike. +- `bridgeFromCore()` uses Hyperliquid `sendAsset` to the token system address. +- The HyperEVM recipient is the Core action sender, so v1 does not expose an + arbitrary `recipient`. +- Approved agent wallets cannot bridge funds out for a master account; + `signer.address` must match `accountAddress`. +- Live validation for #56 is read-only only: mainnet/testnet `spotMeta`, + `l2Book`, SDK `getQuote()`, and SDK `getRoute()`. + Multi-hop via arbitrary intermediate assets should stay out of scope until there is a clear product need and enough tests to make route selection safe. @@ -214,11 +250,11 @@ kit.evmQuote({ from, to, amount }): Promise kit.evmSwap({ from, to, amount, minOut?, recipient?, deadline? }): Promise ``` -Do not block Tracks 1 and 2 on this. +Do not block shipped tracks on this. -## Initial split +## Landed Split -Start with two parallel PRs: +The initial SDK expansion landed as four focused PRs: 1. @Yaugourt: Track 1, Discovery USDH - spot USDH market discovery first @@ -232,7 +268,17 @@ Start with two parallel PRs: - land a read-only experimental API if the shape is stable enough - document any unknowns before write support -After both land, revisit Track 3 with actual market metadata in hand. +3. @Yaugourt: Track 3, Targeted USDH trading + - spot order placement and cancellation for USDH-bearing pairs + - USDH-filtered open orders and order status reads + - live pair names plus token-pair aliases + - no generic Hyperliquid account/order surface + +4. @sumfxn: Track 4, Useful USDH flows + - `USDH -> USDC` reverse swap on HyperCore + - `bridgeFromCore()` for linked USDC/USDH spot assets + - no arbitrary bridge-out recipient + - no HyperEVM direct swap or arbitrary multi-hop routing ## Non-goals @@ -242,14 +288,19 @@ After both land, revisit Track 3 with actual market metadata in hand. - HyperEVM direct swap before liquidity and router validation - Broad agent/vault support before the USDH-specific API is settled -## Open questions +## Decisions And Open Questions + +Resolved decisions: + +1. `listPairs()` is spot-only and USDH-scoped. +2. Outcomes use separate `listOutcomeMarkets()` style APIs. +3. Track 3 supports only USDH-bearing spot pairs, not generic Hyperliquid + trading. +4. `bridgeFromCore()` v1 is sender-owned only; no arbitrary recipient. + +Open questions: -1. Should `listPairs()` default to spot-only USDH markets? Proposed: yes. -2. Should outcomes live under `listPairs({ kind: 'outcome' })` or separate - `listOutcomeMarkets()`? Proposed: separate API until the metadata shape is - proven. -3. Should Track 3 support only USDH pairs, or any pair returned by - `listPairs()`? Proposed: only USDH pairs for this package. -4. Which API should expose HIP-3 USDH markets, if any? Proposed: experimental +1. Which API should expose HIP-3 USDH markets, if any? Proposed: experimental watchlist after spot/outcomes. -5. What is the minimum useful `bridgeFromCore` API for integrators? +2. Which examples should become first-class maintained demos before the next + release?