From a179aace67fdb73d70bc4d1aaa63d0d580227579 Mon Sep 17 00:00:00 2001 From: sumfxn Date: Mon, 11 May 2026 12:07:56 +0200 Subject: [PATCH 1/3] docs(repo): update roadmap status --- docs/roadmap.md | 70 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 23 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 35ef726..eeb6b7b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,7 +1,8 @@ # 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-3 have landed; Track 4 useful USDH flows are +> the next SDK expansion. 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,7 +27,13 @@ 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 @@ -85,7 +92,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 +103,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 +122,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 +151,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 @@ -214,11 +229,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 three focused PRs: 1. @Yaugourt: Track 1, Discovery USDH - spot USDH market discovery first @@ -232,7 +247,11 @@ 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 ## Non-goals @@ -242,14 +261,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. + +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. What is the minimum useful `bridgeFromCore` API for integrators? +3. Which examples should become first-class maintained demos before the next + release? From e972fc282911a3372966722151af8292d493bd29 Mon Sep 17 00:00:00 2001 From: sumfxn Date: Mon, 11 May 2026 12:57:56 +0200 Subject: [PATCH 2/3] docs(repo): reflect track 4 draft status --- docs/roadmap.md | 42 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index eeb6b7b..7d0cc36 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,8 @@ # Roadmap -> Status: living plan. Tracks 1-3 have landed; Track 4 useful USDH flows are -> the next SDK expansion. Release remains intentionally gated until live -> testnet/IRL validation and generated release output are reviewed. +> Status: living plan. Tracks 1-3 have landed; Track 4 useful USDH flows are in +> draft PR #56. 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". @@ -38,6 +38,13 @@ What already works: `isBridgeAndSwapError()` - React widget on top of the SDK +In review: + +- Track 4 draft PR #56 adds `USDH -> USDC` HyperCore reverse swaps and + `bridgeFromCore()` for linked USDC/USDH spot assets. The PR has local and CI + validation, plus live read-only mainnet/testnet probes, but no live write-path + bridge/swap test yet. + This remains the core retail path. New roadmap items should preserve that simple path instead of forcing integrators into a broader trading abstraction. @@ -192,6 +199,9 @@ lower-level order API in docs. ## Track 4 - Useful USDH flows +Status: in draft PR #56. Reverse swap and bridge-out are implemented in the SDK +with conservative constraints, but should remain unmerged until review is done. + Keep the UX simple: - `USDC -> USDH` remains the core path @@ -203,9 +213,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. @@ -253,6 +275,14 @@ The initial SDK expansion landed as three focused PRs: - live pair names plus token-pair aliases - no generic Hyperliquid account/order surface +Track 4 is currently in review as PR #56: + +- @sumfxn: 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 - Becoming a generic Hyperliquid SDK @@ -269,11 +299,11 @@ Resolved decisions: 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. Which API should expose HIP-3 USDH markets, if any? Proposed: experimental watchlist after spot/outcomes. -2. What is the minimum useful `bridgeFromCore` API for integrators? -3. Which examples should become first-class maintained demos before the next +2. Which examples should become first-class maintained demos before the next release? From f9ce2910c25fd043daf447829fa1eca6a4aa39ff Mon Sep 17 00:00:00 2001 From: sumfxn Date: Mon, 11 May 2026 14:06:43 +0200 Subject: [PATCH 3/3] docs(repo): mark track 4 landed --- docs/roadmap.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 7d0cc36..628c0e9 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,7 +1,8 @@ # Roadmap -> Status: living plan. Tracks 1-3 have landed; Track 4 useful USDH flows are in -> draft PR #56. Release remains intentionally gated until live testnet/IRL +> 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". @@ -38,12 +39,9 @@ What already works: `isBridgeAndSwapError()` - React widget on top of the SDK -In review: - -- Track 4 draft PR #56 adds `USDH -> USDC` HyperCore reverse swaps and - `bridgeFromCore()` for linked USDC/USDH spot assets. The PR has local and CI - validation, plus live read-only mainnet/testnet probes, but no live write-path - bridge/swap test yet. +- `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. @@ -199,8 +197,9 @@ lower-level order API in docs. ## Track 4 - Useful USDH flows -Status: in draft PR #56. Reverse swap and bridge-out are implemented in the SDK -with conservative constraints, but should remain unmerged until review is done. +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: @@ -255,7 +254,7 @@ Do not block shipped tracks on this. ## Landed Split -The initial SDK expansion landed as three focused PRs: +The initial SDK expansion landed as four focused PRs: 1. @Yaugourt: Track 1, Discovery USDH - spot USDH market discovery first @@ -275,9 +274,7 @@ The initial SDK expansion landed as three focused PRs: - live pair names plus token-pair aliases - no generic Hyperliquid account/order surface -Track 4 is currently in review as PR #56: - -- @sumfxn: Useful USDH flows +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