-
-## Use cases
+## Archive Contents
-A few real flows the SDK is shaped for today. Runnable examples are still on the roadmap; until they land, treat these as the integration targets to copy into your own app.
+The repo also preserves the original USDH work:
-- **End-to-end CLI** — bridge + quote + swap from a private key on the command line. Smallest possible integration.
-- **Discord bot** — slash command that quotes `USDC → USDH`, confirms the route, then calls `bridgeAndSwap()` with progress updates.
-- **Subscription billing** — collect or rebalance USDC into USDH from a merchant wallet after a payment webhook.
-- **Treasury rebalance** — scheduled job that converts a fraction of HyperCore USDC above a floor into USDH. Designed for cron.
+- HyperCore/HyperEVM balance and bridge helpers;
+- USDH spot pair discovery;
+- Hyperliquid agent-wallet signing;
+- legacy `USDC -> USDH` swap and bridge flows;
+- experimental read-only HIP-4/outcome helpers;
+- a demo registry for migration and historical component references.
-## Features (V1)
-
-- `USDC → USDH` quote and swap via the canonical HL spot pair
-- `USDH → USDC` reverse swap on HyperCore
-- HyperEVM → HyperCore bridge with credit polling (`bridgeToCore`)
-- HyperCore → HyperEVM bridge-out for linked USDC/USDH spot assets (`bridgeFromCore`)
-- HyperCore balance, route/preflight helpers plus `bridgeAndSwap()` orchestration
-- Experimental read-only outcome market metadata, books, and mids
-- USDH-only spot order helpers for placing, cancelling, and reading USDH-pair orders
-- Wallet-agnostic `Signer` interface (works with viem, ethers, Privy, Turnkey, raw private key)
-- Approved Hyperliquid agent wallet flow for browser apps (`approveAgent`, `accountAddress`)
-- Read-only `InfoClient` (spotMeta, outcomeMeta, spot clearinghouse state, L2 book, allMids) for consumers building custom UIs
-- Typed error hierarchy rooted at `UsdhKitError`, including `BridgeAndSwapError` phase/cause context and `isBridgeAndSwapError()` for orchestration failures
-- `friendlyError()` helper to map SDK errors to short, copy-safe strings
-- React widget (`@usdh-kit/widget`) with light, dark and auto theming (WCAG AA defaults, CSS variables for integrator overrides)
-- npm provenance on every release
-- Mainnet and testnet support, no signing on read paths
+Those surfaces are kept for compatibility and reference. They are not a roadmap
+for turning `usdh-kit` into a USDC, generic spot, or HIP-4 SDK.
## Docs
-- [docs/architecture.md](./docs/architecture.md) — what the SDK does under the hood, in the order it does it (msgpack, signing, bridge polling, error model).
-- [docs/agent-wallets.md](./docs/agent-wallets.md) — secure signing patterns for builders: backend agent, browser trading session, externally managed signer.
-- [docs/bridge-and-swap.md](./docs/bridge-and-swap.md) — the full USDC HyperEVM → USDH HyperCore flow, including wallet prompts and recovery.
-- [docs/glossary.md](./docs/glossary.md) — Hyperliquid terms used across the SDK and widget (HyperEVM vs HyperCore, IOC, system address, weiDecimals, …).
-- [docs/theming.md](./docs/theming.md) — widget CSS variable list, override patterns, SSR-flash mitigation, Tailwind setup.
-- [docs/troubleshooting.md](./docs/troubleshooting.md) — common errors with concrete fixes (`MissingEvmWalletError`, `BridgeTimeoutError`, "borders render bright white", …).
+- [docs/README.md](./docs/README.md) - docs index
+- [docs/architecture.md](./docs/architecture.md) - SDK internals and legacy architecture
+- [docs/agent-wallets.md](./docs/agent-wallets.md) - secure signing patterns
+- [docs/bridge-and-swap.md](./docs/bridge-and-swap.md) - legacy acquisition flow and migration notes
+- [docs/glossary.md](./docs/glossary.md) - Hyperliquid terms used in the repo
+- [docs/roadmap.md](./docs/roadmap.md) - sunset roadmap and non-goals
+- [docs/theming.md](./docs/theming.md) - widget CSS variables and theming
+- [docs/troubleshooting.md](./docs/troubleshooting.md) - common errors and recovery notes
-## Runtime support
+## Runtime Support
-- Node.js >= 18.18 (native `fetch`, `AbortController`, `bigint`)
+- Node.js >= 18.18
- Bun >= 1.1
-- Modern evergreen browsers (Chrome >= 107, Safari >= 16, Firefox >= 104)
-- Edge runtimes (Cloudflare Workers, Vercel Edge)
-
-Consumers targeting older environments must downlevel via their bundler.
-
-## Why USDH
-
-Hyperliquid's primary stable was USDC, bridged from Arbitrum. USDH is native, fully reserved (cash plus US Treasuries), and routes 50% of reserve revenue to the Assistance Fund instead of an issuer. Apps that hold or pay out stables on Hyperliquid have a reason to prefer USDH; this SDK removes the friction.
+- Modern evergreen browsers
+- Edge runtimes with `fetch`, `AbortController`, and `bigint`
## Contributing
-See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Security disclosures: [`SECURITY.md`](./SECURITY.md).
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Security disclosures:
+[`SECURITY.md`](./SECURITY.md).
## License
diff --git a/apps/demo/next-env.d.ts b/apps/demo/next-env.d.ts
index 1b3be08..830fb59 100644
--- a/apps/demo/next-env.d.ts
+++ b/apps/demo/next-env.d.ts
@@ -1,5 +1,6 @@
/// - Swap stables into USDH on Hyperliquid. + Migrate remaining USDH back to USDC on Hyperliquid.
- Copyable USDH product patterns. + USDH sunset migration and legacy references.
- Copyable USDH and HIP-4 patterns with preview, code, contract, and examples. + A migration widget for remaining USDH balances, with the legacy swap kept only for + compatibility.
- Read-only context for a USDC to USDH quote. + Read-only context for a USDH to USDC migration quote.
- Packaged USDHSwap with read-only quote before connect. + Legacy USDHSwap preserved for historical integrations.
@@ -80,6 +80,48 @@ export function UsdhWidgetPreview({ ) } +export function UsdhMigrationPreview({ size }: { size: PreviewSize }) { + return ( ++ Packaged USDHMigration: convert a HyperCore USDH balance back to USDC. +
+{receiveUsdValue ?? ' '}
- Filled + {partialFill ? 'Partially filled' : 'Filled'}
Received
- {trimReceive(result.receivedUsdh, USDC_DECIMALS)} USDH + {trimReceive(result.receivedAmount, USDC_DECIMALS)} {receiveTicker}
+ {result.spentAmount !== undefined && ( ++ Spent{' '} + + {trimReceive(result.spentAmount, USDC_DECIMALS)} + {' '} + {spentTicker} +
+ )}@@ -36,6 +68,19 @@ export function ResultPanel(props: { result: SwapResultPayload; onReset: () => v )}
+ {partialFill && result.spentAmount !== undefined && result.requestedAmount !== undefined ? ( ++ Migrated{' '} + + {trimReceive(result.spentAmount, USDC_DECIMALS)} + {' '} + of{' '} + + {trimReceive(result.requestedAmount, USDC_DECIMALS)} + {' '} + {spentTicker}. The unfilled balance remains on HyperCore. +
+ ) : null}(null) + const [route, setRoute] = useState(null) + const [isQuoting, setIsQuoting] = useState(false) + const [readOnlyEstimate, setReadOnlyEstimate] = useState (null) + const [readOnlyQuoteUnavailable, setReadOnlyQuoteUnavailable] = useState(false) + const [isReadOnlyQuoting, setIsReadOnlyQuoting] = useState(false) + const [depthWarning, setDepthWarning] = useState (null) + const [knownDepthLimited, setKnownDepthLimited] = useState(false) + const [result, setResult] = useState (null) + const [error, setError] = useState (null) + + const quoteExpirySeconds = useCountdown(quote?.validUntil ?? null) + + const busy = phase === 'approving' || phase === 'swapping' + const showingResult = phase === 'done' && result !== null + const networkToggleLocked = busy + + useEffect(() => { + if (!networkToggleLocked) setNetwork(initialNetwork) + }, [initialNetwork, networkToggleLocked]) + + useEffect(() => { + if (quote && quoteExpirySeconds === 0) setQuote(null) + }, [quote, quoteExpirySeconds]) + + const parsedAmount = useMemo(() => { + try { + return parseUnits(amountStr || '0', USDH_DECIMALS) + } catch { + return null + } + }, [amountStr]) + const balanceRefreshKey = balances.hcUsdh?.toString() ?? '' + + const quoteRequestId = useRef(0) + + useEffect(() => { + // A USDH deposit crediting after mount can flip the route from blocked to + // coverable, so re-quote when the HyperCore USDH balance changes. + void balanceRefreshKey + const requestId = ++quoteRequestId.current + setQuote(null) + setRoute(null) + setDepthWarning(null) + setKnownDepthLimited(false) + if (!kit) { + setIsQuoting(false) + return + } + if (parsedAmount === null || parsedAmount <= 0n) { + setIsQuoting(false) + return + } + const timer = setTimeout(async () => { + setError(null) + setIsQuoting(true) + try { + // USDH -> USDC: sell side, HyperCore only. preflightSwap returns the + // quote plus the HyperCore balance coverage we gate the button on. + const nextRoute = await kit.preflightSwap({ + from: 'USDH', + to: 'USDC', + amount: parsedAmount, + slippageBps, + sourceChain: 'hypercore', + }) + if (requestId !== quoteRequestId.current) return + let nextQuote = nextRoute.quote + try { + const book = await kit.getBook(nextRoute.quote.pair) + if (requestId !== quoteRequestId.current) return + const depth = estimateUsdcFromBidDepth(book.levels[0], parsedAmount) + if (depth === null || depth.spentUsdh === 0n) { + setKnownDepthLimited(true) + setDepthWarning('No visible USDH/USDC bid depth for this amount.') + } else if (!depth.fullyCovered) { + setKnownDepthLimited(true) + setDepthWarning( + `Visible bid depth covers ${trimReceive(depth.spentUsdh, USDH_DECIMALS)} of ${trimReceive(parsedAmount, USDH_DECIMALS)} USDH. Reduce the amount or refresh before migrating.`, + ) + } else { + setKnownDepthLimited(false) + setDepthWarning(null) + nextQuote = { ...nextRoute.quote, estimatedReceived: depth.receivedUsdc } + } + } catch { + setKnownDepthLimited(true) + setDepthWarning('Unable to verify visible USDH/USDC bid depth. Refresh before migrating.') + } + setRoute({ ...nextRoute, quote: nextQuote }) + setQuote(nextQuote) + } catch (err) { + if (requestId !== quoteRequestId.current) return + setError(friendlyError(err)) + } finally { + if (requestId === quoteRequestId.current) setIsQuoting(false) + } + }, QUOTE_DEBOUNCE_MS) + return () => clearTimeout(timer) + }, [kit, parsedAmount, slippageBps, balanceRefreshKey]) + + useEffect(() => { + setReadOnlyEstimate(null) + setReadOnlyQuoteUnavailable(false) + setDepthWarning(null) + setKnownDepthLimited(false) + if (isConnected || parsedAmount === null || parsedAmount <= 0n) { + setIsReadOnlyQuoting(false) + return + } + + let cancelled = false + const timer = window.setTimeout(async () => { + setIsReadOnlyQuoting(true) + try { + const info = createInfoClient({ network, timeoutMs: READ_ONLY_QUOTE_TIMEOUT_MS }) + const pairs = listUsdhSpotPairs(await info.spotMeta()) + const pair = pairs.find( + (candidate) => candidate.base === 'USDH' && candidate.quote === 'USDC', + ) + if (!pair) { + if (!cancelled) setReadOnlyQuoteUnavailable(true) + return + } + const book = await info.l2Book(pair.name) + const depth = estimateUsdcFromBidDepth(book.levels[0], parsedAmount) + if (depth === null || depth.spentUsdh === 0n) { + if (!cancelled) setReadOnlyQuoteUnavailable(true) + return + } + if (!depth.fullyCovered) { + if (!cancelled) { + setReadOnlyQuoteUnavailable(true) + setDepthWarning( + `Visible bid depth covers ${trimReceive(depth.spentUsdh, USDH_DECIMALS)} of ${trimReceive(parsedAmount, USDH_DECIMALS)} USDH.`, + ) + } + return + } + if (!cancelled) { + setReadOnlyEstimate(depth.receivedUsdc) + setReadOnlyQuoteUnavailable(false) + setDepthWarning(null) + } + } catch { + if (!cancelled) { + setReadOnlyEstimate(null) + setReadOnlyQuoteUnavailable(true) + } + } finally { + if (!cancelled) setIsReadOnlyQuoting(false) + } + }, QUOTE_DEBOUNCE_MS) + + return () => { + cancelled = true + window.clearTimeout(timer) + } + }, [isConnected, network, parsedAmount]) + + const belowMinOrderValue = + parsedAmount !== null && parsedAmount > 0n && parsedAmount < MIN_SWAP_AMOUNT + const hcCovers = route?.canSwap ?? false + const insufficientForRoute = + parsedAmount !== null && parsedAmount > 0n && !belowMinOrderValue && route !== null && !hcCovers + const routeLoaded = route !== null + + function reset() { + setPhase('idle') + setResult(null) + setError(null) + } + + function applySlippagePreset(bps: number) { + setSlippageBps(bps) + setShowCustomSlippage(false) + setCustomSlippageStr('') + } + + function applyCustomSlippage(input: string) { + setCustomSlippageStr(input) + const trimmed = input.trim() + if (trimmed === '') return + const pct = Number(trimmed) + if (!Number.isFinite(pct) || pct < 0 || pct > 50) return + setSlippageBps(Math.round(pct * 100)) + } + + async function executeMigration() { + if (!kit || parsedAmount === null || parsedAmount <= 0n) return + // Hard guard against double-clicks: setPhase is async, so without this a + // synchronous double-tap can dispatch two tx requests before the button's + // disabled state commits. + if (phase !== 'idle') return + setError(null) + setResult(null) + + if (!sessionReady) { + setPhase('approving') + try { + await enableTradingSession() + } catch (err) { + setError(friendlyError(err)) + } finally { + setPhase('idle') + } + return + } + + setPhase('swapping') + try { + const next = await kit.swap({ + from: 'USDH', + to: 'USDC', + amount: parsedAmount, + slippageBps, + }) + const payload: USDHMigrationResultPayload = { + orderId: next.orderId, + spentUsdh: next.spent, + receivedUsdc: next.received, + price: next.price, + slippageBps: next.slippageBps, + } + setResult(payload) + setPhase('done') + setRoute(null) + setQuote(null) + balances.refetch() + window.setTimeout(() => balances.refetch(), 2_500) + onMigrationComplete?.(payload) + } catch (err) { + setError(friendlyError(err)) + setPhase('idle') + } + } + + const inputDisabled = busy || showingResult + const canSwap = + !busy && + !showingResult && + isConnected && + kit !== null && + !isApprovingSession && + parsedAmount !== null && + parsedAmount > 0n && + !belowMinOrderValue && + routeLoaded && + hcCovers && + !knownDepthLimited + + const receiveDisplay = quote + ? trimReceive(quote.estimatedReceived, USDH_DECIMALS) + : readOnlyEstimate !== null + ? trimReceive(readOnlyEstimate, USDH_DECIMALS) + : readOnlyQuoteUnavailable + ? 'Quote unavailable' + : '0' + + const payUsdValue = parsedAmount ? formatUsd(parsedAmount, USDH_DECIMALS) : null + const receiveBigint = quote + ? quote.estimatedReceived + : readOnlyEstimate !== null + ? readOnlyEstimate + : null + const receiveUsdValue = receiveBigint ? formatUsd(receiveBigint, USDH_DECIMALS) : null + + function setMaxAmount() { + if (balances.hcUsdh === undefined || balances.hcUsdhDecimals === undefined) return + // Inverse of scaleAmount: pull native units back to USDH display units. + const usdhAmount = scaleAmount(balances.hcUsdh, USDH_DECIMALS - balances.hcUsdhDecimals) + setAmountStr(formatUnits(usdhAmount, USDH_DECIMALS)) + } + + const hasMaxBalance = + balances.hcUsdh !== undefined && balances.hcUsdhDecimals !== undefined && balances.hcUsdh > 0n + + return ( + ++ ) +} + +function estimateUsdcFromBidDepth( + bids: Array<{ px: string; sz: string }>, + desiredUsdh: bigint, +): BidDepthEstimate | null { + if (desiredUsdh <= 0n) return null + let remainingUsdh = desiredUsdh + let spentUsdh = 0n + let receivedUsdc = 0n + + try { + for (const level of bids) { + if (remainingUsdh <= 0n) break + const levelSizeUsdh = parseUnits(level.sz, USDH_DECIMALS) + const bidPrice18 = parseUnits(level.px, PRICE_DECIMALS) + if (levelSizeUsdh <= 0n || bidPrice18 <= 0n) continue + const fillUsdh = levelSizeUsdh < remainingUsdh ? levelSizeUsdh : remainingUsdh + spentUsdh += fillUsdh + receivedUsdc += (fillUsdh * bidPrice18) / TEN_18 + remainingUsdh -= fillUsdh + } + } catch { + return null + } + + return { + receivedUsdc, + spentUsdh, + fullyCovered: remainingUsdh === 0n, + } +} diff --git a/packages/widget/src/usdh-swap.tsx b/packages/widget/src/usdh-swap.tsx index cc7bdd9..fd47348 100644 --- a/packages/widget/src/usdh-swap.tsx +++ b/packages/widget/src/usdh-swap.tsx @@ -478,7 +478,16 @@ export function USDHSwap(props: USDHSwapProps) { )} {error &&++ +Migrate USDH to USDC
+ {!hideNetworkToggle && ( ++ )} + + USDH is being sunset on Hyperliquid. This converts your HyperCore USDH balance back to USDC. +
+ {isConnected && ( ++ HyperCore USDH balance + + + {formatBalance(balances.hcUsdh, balances.hcUsdhDecimals)} + {' '} + USDH + ++ )} + +++ + {!showingResult && ( + <> + {depthWarning && ( ++ + + {depthWarning}
+ )} + {insufficientForRoute && ( ++ Exceeds your HyperCore USDH balance. +
+ )} + {belowMinOrderValue && ( ++ Hyperliquid spot orders need more than 10 USDH. Use {MIN_SWAP_DISPLAY}+ USDH. +
+ )} + +setShowCustomSlippage((v) => !v)} + customStr={customSlippageStr} + onCustomChange={applyCustomSlippage} + disabled={inputDisabled} + /> + + + + )} + {error && } + {result && ( + + )} + + {!hideAttribution && ( + ++ )} ++ } - {result && } + {result && ( + + )} {!hideAttribution && ( diff --git a/packages/widget/tailwind.config.cjs b/packages/widget/tailwind.config.cjs index 8e56a08..4b1435a 100644 --- a/packages/widget/tailwind.config.cjs +++ b/packages/widget/tailwind.config.cjs @@ -10,7 +10,7 @@ module.exports = { colors: { // Semantic tokens — resolved from CSS variables defined in // src/styles.css. Light mode is the default; the `dark` class - // (added on the widget root by USDHSwap when the effective theme + // (added on the widget root when the effective theme // is dark) overrides each token. Using rgb(var() /) // means consumers can still write `bg-usdh-surface/40`, etc. 'usdh-bg': 'rgb(var(--usdh-bg) / )', diff --git a/packages/widget/test/bundle-size.test.ts b/packages/widget/test/bundle-size.test.ts index 1da2a47..666b864 100644 --- a/packages/widget/test/bundle-size.test.ts +++ b/packages/widget/test/bundle-size.test.ts @@ -10,12 +10,13 @@ import { describe, expect, it } from 'vitest' * over-the-wire size to end users is gzipped and roughly 30 to 35 % of * this number. * - * Current actual: ~56.6 KB ESM after the browser agent-session flow, native - * USDC bridge support, and dual-token balance display. Budget leaves a small - * cushion while still catching dependency creep; viem/accounts remains - * external and is not bundled into the widget. + * Current actual: ~73.6 KB ESM after the browser agent-session flow, native + * USDC bridge support, dual-token balance display, the USDHMigration exit + * widget, depth-aware migration quotes, and partial-fill receipts. Budget + * leaves a small cushion while still catching dependency creep; viem/accounts + * remains external and is not bundled into the widget. */ -const BUDGET_KB = 58 +const BUDGET_KB = 75 describe('widget bundle size', () => { it('ESM bundle stays under budget', () => { diff --git a/packages/widget/test/usdh-migration.test.tsx b/packages/widget/test/usdh-migration.test.tsx new file mode 100644 index 0000000..39c9d8e --- /dev/null +++ b/packages/widget/test/usdh-migration.test.tsx @@ -0,0 +1,511 @@ +import { fireEvent, render, screen, waitFor } from '@testing-library/react' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { USDHMigration } from '../src/usdh-migration.js' + +const STUB_ADDRESS = '0x1234567890abcdef1234567890abcdef12345678' as const + +const mockUseAccount = vi.fn<() => { isConnected: boolean; address?: `0x${string}` }>() +const mockUseWalletClient = + vi.fn< + () => { + data: + | { + sendTransaction: () => Promise + signTypedData: () => Promise<`0x${string}`> + signMessage: () => Promise<`0x${string}`> + } + | undefined + } + >() +const mockUseChainId = vi.fn<() => number>() +const mockUseReadContract = + vi.fn<() => { data: unknown; isLoading: boolean; refetch: () => void }>() +const mockUsePublicClient = vi.fn() +const mockGeneratePrivateKey = vi.fn<() => `0x${string}`>() +const mockPrivateKeyToAccount = vi.fn() + +vi.mock('wagmi', () => ({ + useAccount: () => mockUseAccount(), + useWalletClient: () => mockUseWalletClient(), + useSignTypedData: () => ({ signTypedDataAsync: vi.fn() }), + useSignMessage: () => ({ signMessageAsync: vi.fn() }), + useChainId: () => mockUseChainId(), + useSwitchChain: () => ({ switchChain: vi.fn(), isPending: false }), + useReadContract: () => mockUseReadContract(), + usePublicClient: () => mockUsePublicClient(), +})) + +vi.mock('viem/accounts', () => ({ + generatePrivateKey: () => mockGeneratePrivateKey(), + privateKeyToAccount: (privateKey: `0x${string}`) => mockPrivateKeyToAccount(privateKey), +})) + +const mockHcQueryData = vi.fn<() => { usdc: bigint; usdh: bigint | undefined } | undefined>( + () => undefined, +) +const mockTokenQueryData = vi.fn<() => unknown>(() => ({ + usdc: { + evmAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f', + evmDecimals: 18, + hcWeiDecimals: 8, + hcTokenIndex: 0, + }, + usdh: { + evmAddress: '0x1111111111111111111111111111111111111111', + evmDecimals: 18, + hcWeiDecimals: 8, + hcTokenIndex: 1, + }, +})) + +vi.mock('@tanstack/react-query', () => ({ + useQuery: ({ queryKey }: { queryKey: unknown[] }) => { + if (queryKey.includes('stable-token-info')) { + return { data: mockTokenQueryData(), isLoading: false, refetch: vi.fn() } + } + return { data: mockHcQueryData(), isLoading: false, refetch: vi.fn() } + }, +})) + +const mockPreflightSwap = vi.fn() +const mockSwap = vi.fn() +const mockApproveAgent = vi.fn() +const mockKitGetBook = vi.fn() +const mockL2Book = vi.fn() +const mockListUsdhSpotPairs = vi.fn() + +const usdhUsdcPair = { + name: '@230', + label: 'USDH/USDC', + index: 230, + base: 'USDH', + quote: 'USDC', + usdhRole: 'base', +} + +function makeQuote(estimatedReceived = 11_000_000n) { + return { + from: 'USDH', + to: 'USDC', + pair: 'USDH/USDC', + midPrice: 1_000_000_000_000_000_000n, + estimatedReceived, + validUntil: Date.now() + 30_000, + } +} + +function makeRoute( + overrides: Partial<{ + amount: bigint + canSwap: boolean + estimatedReceived: bigint + hypercoreBalance: bigint + requiredHypercoreBalance: bigint + }> = {}, +) { + const hypercoreBalance = overrides.hypercoreBalance ?? 2_000_000_000n + return { + from: 'USDH', + to: 'USDC', + amount: overrides.amount ?? 11_000_000n, + sourceChain: 'hypercore', + requiresBridge: false, + canSwap: overrides.canSwap ?? true, + quote: makeQuote(overrides.estimatedReceived), + hypercoreBalance, + hypercoreTotal: hypercoreBalance, + hypercoreHold: 0n, + hypercoreDecimals: 8, + requiredHypercoreBalance: overrides.requiredHypercoreBalance ?? 11_000_000n, + } +} + +function makeSwapResult( + overrides: Partial<{ orderId: string; received: bigint; spent: bigint }> = {}, +) { + return { + orderId: overrides.orderId ?? 'order-42', + received: overrides.received ?? 11_000_000n, + spent: overrides.spent ?? 11_000_000n, + price: 1_000_000_000_000_000_000n, + slippageBps: 0, + } +} + +vi.mock('@usdh-kit/sdk', () => ({ + approveAgent: (...args: unknown[]) => mockApproveAgent(...args), + createUsdhKit: () => ({ + preflightSwap: mockPreflightSwap, + swap: mockSwap, + getBook: mockKitGetBook, + }), + createInfoClient: () => ({ + spotMeta: vi.fn(async () => ({})), + l2Book: (...args: unknown[]) => mockL2Book(...args), + spotClearinghouseState: vi.fn(), + }), + listUsdhSpotPairs: (...args: unknown[]) => mockListUsdhSpotPairs(...args), + getHyperEvmNativeUsdcAddress: () => '0xb88339cb7199b77e23db6e890353e22632ba630f', + BridgeAndSwapError: class extends Error {}, + isBridgeAndSwapError: () => false, + BridgeTimeoutError: class extends Error {}, + InsufficientBalanceError: class extends Error {}, + InvalidInputError: class extends Error {}, + MissingEvmWalletError: class extends Error {}, + NetworkError: class extends Error {}, + NotImplementedError: class extends Error {}, + SigningError: class extends Error {}, + UsdhKitError: class extends Error {}, +})) + +function setConnected({ withSession = true }: { withSession?: boolean } = {}) { + mockUseAccount.mockReturnValue({ isConnected: true, address: STUB_ADDRESS }) + mockUseWalletClient.mockReturnValue({ + data: { + sendTransaction: () => Promise.resolve('0xtx'), + signTypedData: () => Promise.resolve(`0x${'c'.repeat(130)}` as `0x${string}`), + signMessage: () => Promise.resolve('0x0'), + }, + }) + if (withSession) seedAgentSession() + mockUseChainId.mockReturnValue(999) + mockUseReadContract.mockReturnValue({ data: undefined, isLoading: false, refetch: vi.fn() }) + mockUsePublicClient.mockReturnValue({ + waitForTransactionReceipt: vi.fn(async () => undefined), + }) + // 20 USDH on HyperCore at 8 weiDecimals covers the 11 USDH default amount. + mockHcQueryData.mockReturnValue({ usdc: 0n, usdh: 2_000_000_000n }) +} + +function seedAgentSession(network: 'mainnet' | 'testnet' = 'mainnet') { + window.sessionStorage.setItem( + `usdh-kit:agent-session:${network}:${STUB_ADDRESS.toLowerCase()}`, + JSON.stringify({ + version: 1, + network, + accountAddress: STUB_ADDRESS.toLowerCase(), + agentAddress: '0x00000000000000000000000000000000000000aa', + agentName: `usdh-kit-${network}`, + privateKey: `0x${'1'.repeat(64)}`, + createdAt: Date.now(), + }), + ) +} + +describe('USDHMigration', () => { + beforeEach(() => { + vi.resetAllMocks() + window.sessionStorage.clear() + mockGeneratePrivateKey.mockReturnValue(`0x${'2'.repeat(64)}`) + mockPrivateKeyToAccount.mockReturnValue({ + address: '0x00000000000000000000000000000000000000aa', + signTypedData: () => Promise.resolve(`0x${'a'.repeat(64)}${'b'.repeat(64)}1c`), + signMessage: () => Promise.resolve('0x0'), + }) + mockApproveAgent.mockResolvedValue({ + agentAddress: '0x00000000000000000000000000000000000000aa', + }) + mockTokenQueryData.mockReturnValue({ + usdc: { + evmAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f', + evmDecimals: 18, + hcWeiDecimals: 8, + hcTokenIndex: 0, + }, + usdh: { + evmAddress: '0x1111111111111111111111111111111111111111', + evmDecimals: 18, + hcWeiDecimals: 8, + hcTokenIndex: 1, + }, + }) + mockHcQueryData.mockReturnValue(undefined) + mockPreflightSwap.mockResolvedValue(makeRoute()) + mockSwap.mockResolvedValue(makeSwapResult()) + mockKitGetBook.mockResolvedValue({ + coin: '@230', + levels: [[{ px: '0.9999', sz: '20', n: 1 }], [{ px: '1.0001', sz: '20', n: 1 }]], + }) + mockL2Book.mockResolvedValue({ + coin: '@230', + levels: [[{ px: '0.9999', sz: '20', n: 1 }], [{ px: '1.0001', sz: '20', n: 1 }]], + }) + mockListUsdhSpotPairs.mockReturnValue([usdhUsdcPair]) + mockUseReadContract.mockReturnValue({ data: undefined, isLoading: false, refetch: vi.fn() }) + }) + + it('renders the migration form with the sunset notice and USDH/USDC tickers', () => { + mockUseAccount.mockReturnValue({ isConnected: false }) + mockUseWalletClient.mockReturnValue({ data: undefined }) + mockUseChainId.mockReturnValue(0) + + render( ) + + expect(screen.getByText('Migrate USDH to USDC')).toBeInTheDocument() + expect(screen.getByText(/USDH is being sunset on Hyperliquid/)).toBeInTheDocument() + expect(screen.getByText('You pay')).toBeInTheDocument() + expect(screen.getByText('You receive')).toBeInTheDocument() + expect(screen.getByLabelText('Amount in USDH')).toBeInTheDocument() + expect(screen.getByRole('button', { name: 'Connect wallet to migrate' })).toBeDisabled() + }) + + it('shows a strict read-only USDH/USDC quote before wallet connect', async () => { + mockUseAccount.mockReturnValue({ isConnected: false }) + mockUseWalletClient.mockReturnValue({ data: undefined }) + mockUseChainId.mockReturnValue(0) + + render( ) + + await waitFor(() => { + expect(mockL2Book).toHaveBeenCalledWith('@230') + }) + expect(screen.getByText('10.9989')).toBeInTheDocument() + }) + + it('shows quote unavailable when the USDH/USDC pair is missing before connect', async () => { + mockUseAccount.mockReturnValue({ isConnected: false }) + mockUseWalletClient.mockReturnValue({ data: undefined }) + mockUseChainId.mockReturnValue(0) + mockListUsdhSpotPairs.mockReturnValue([{ ...usdhUsdcPair, base: 'HYPE', quote: 'USDH' }]) + + render( ) + + await waitFor(() => { + expect(screen.getByText('Quote unavailable')).toBeInTheDocument() + }) + expect(mockL2Book).not.toHaveBeenCalled() + }) + + it('shows quote unavailable when the USDH/USDC book has no bid before connect', async () => { + mockUseAccount.mockReturnValue({ isConnected: false }) + mockUseWalletClient.mockReturnValue({ data: undefined }) + mockUseChainId.mockReturnValue(0) + mockL2Book.mockResolvedValue({ coin: '@230', levels: [[], []] }) + + render( ) + + await waitFor(() => { + expect(screen.getByText('Quote unavailable')).toBeInTheDocument() + }) + }) + + it('shows quote unavailable when visible bid depth is below the amount before connect', async () => { + mockUseAccount.mockReturnValue({ isConnected: false }) + mockUseWalletClient.mockReturnValue({ data: undefined }) + mockUseChainId.mockReturnValue(0) + mockL2Book.mockResolvedValue({ + coin: '@230', + levels: [[{ px: '0.9999', sz: '5', n: 1 }], [{ px: '1.0001', sz: '20', n: 1 }]], + }) + + render( ) + + await waitFor(() => { + expect(screen.getByText('Quote unavailable')).toBeInTheDocument() + }) + expect(screen.getByText(/Visible bid depth covers 5 of 11 USDH/)).toBeInTheDocument() + }) + + it('auto-fetches a quote and renders the depth-aware USDC receive estimate', async () => { + setConnected() + mockPreflightSwap.mockResolvedValue(makeRoute({ estimatedReceived: 10_999_800n })) + + render( ) + + await waitFor( + () => { + expect(mockPreflightSwap).toHaveBeenCalledWith( + expect.objectContaining({ + from: 'USDH', + to: 'USDC', + amount: 11_000_000n, + sourceChain: 'hypercore', + }), + ) + }, + { timeout: 2_000 }, + ) + await waitFor(() => { + expect(mockKitGetBook).toHaveBeenCalledWith('USDH/USDC') + expect(screen.getByText('10.9989')).toBeInTheDocument() + }) + }) + + it('renders the connected HyperCore USDH balance', async () => { + setConnected() + mockPreflightSwap.mockImplementation(() => new Promise(() => {})) + + render( ) + + expect(screen.getByText('HyperCore USDH balance')).toBeInTheDocument() + expect(screen.getByText('20')).toBeInTheDocument() + }) + + it('disables migration when connected visible bid depth is below the amount', async () => { + setConnected() + mockKitGetBook.mockResolvedValue({ + coin: '@230', + levels: [[{ px: '0.9999', sz: '5', n: 1 }], [{ px: '1.0001', sz: '20', n: 1 }]], + }) + + render( ) + + await waitFor( + () => { + expect(screen.getByText(/Visible bid depth covers 5 of 11 USDH/)).toBeInTheDocument() + }, + { timeout: 2_000 }, + ) + expect(screen.getByRole('button', { name: 'Migrate' })).toBeDisabled() + }) + + it('disables migration when connected bid depth cannot be verified', async () => { + setConnected() + mockKitGetBook.mockRejectedValue(new Error('book unavailable')) + + render( ) + + await waitFor( + () => { + expect( + screen.getByText( + 'Unable to verify visible USDH/USDC bid depth. Refresh before migrating.', + ), + ).toBeInTheDocument() + }, + { timeout: 2_000 }, + ) + expect(screen.getByRole('button', { name: 'Migrate' })).toBeDisabled() + }) + + it('surfaces a friendly error when the auto-quote rejects', async () => { + setConnected() + mockPreflightSwap.mockRejectedValue(new Error('upstream down')) + + render( ) + + await waitFor( + () => { + expect(screen.getByRole('alert')).toHaveTextContent('upstream down') + }, + { timeout: 2_000 }, + ) + }) + + it('blocks amounts below the Hyperliquid minimum notional', () => { + setConnected() + mockPreflightSwap.mockImplementation(() => new Promise(() => {})) + + render( ) + + expect(screen.getByText(/Use 11\+ USDH/)).toBeInTheDocument() + const button = screen.getByRole('button', { name: 'Minimum 11 USDH' }) + expect(button).toBeDisabled() + fireEvent.click(button) + expect(mockSwap).not.toHaveBeenCalled() + }) + + it('disables the button and labels it Insufficient when amount exceeds the USDH balance', async () => { + setConnected() + mockPreflightSwap.mockResolvedValue(makeRoute({ canSwap: false })) + + render( ) + + await waitFor(() => { + expect(screen.getByText(/Exceeds your HyperCore USDH balance/)).toBeInTheDocument() + }) + expect(screen.getByRole('button', { name: 'Insufficient HyperCore USDH' })).toBeDisabled() + }) + + it('requires an explicit trading session before the first migration', async () => { + setConnected({ withSession: false }) + + render( ) + + await waitFor( + () => { + expect(screen.getByRole('button', { name: 'Enable trading session' })).not.toBeDisabled() + }, + { timeout: 2_000 }, + ) + fireEvent.click(screen.getByRole('button', { name: 'Enable trading session' })) + + await waitFor(() => { + expect(mockApproveAgent).toHaveBeenCalledWith( + expect.objectContaining({ + network: 'mainnet', + agentName: 'usdh-kit-mainnet', + }), + ) + }) + expect(mockSwap).not.toHaveBeenCalled() + }) + + it('submits the migration swap and shows the filled USDC receipt', async () => { + setConnected() + mockSwap.mockResolvedValue(makeSwapResult({ orderId: 'order-7', received: 10_998_000n })) + const onMigrationComplete = vi.fn() + + render( ) + + await waitFor(() => { + expect(screen.getByRole('button', { name: 'Migrate' })).not.toBeDisabled() + }) + fireEvent.click(screen.getByRole('button', { name: 'Migrate' })) + + await waitFor(() => { + expect(screen.getByText('Filled')).toBeInTheDocument() + }) + expect(screen.getByText(/10\.998 USDC/)).toBeInTheDocument() + expect(mockSwap).toHaveBeenCalledWith( + expect.objectContaining({ + from: 'USDH', + to: 'USDC', + amount: 11_000_000n, + slippageBps: 30, + }), + ) + expect(onMigrationComplete).toHaveBeenCalledWith({ + orderId: 'order-7', + spentUsdh: 11_000_000n, + receivedUsdc: 10_998_000n, + price: 1_000_000_000_000_000_000n, + slippageBps: 0, + }) + }) + + it('shows a partial-fill receipt when IOC liquidity only fills part of the amount', async () => { + setConnected() + mockSwap.mockResolvedValue( + makeSwapResult({ orderId: 'order-partial', spent: 6_000_000n, received: 5_998_000n }), + ) + + render( ) + + await waitFor(() => { + expect(screen.getByRole('button', { name: 'Migrate' })).not.toBeDisabled() + }) + fireEvent.click(screen.getByRole('button', { name: 'Migrate' })) + + await waitFor(() => { + expect(screen.getByText('Partially filled')).toBeInTheDocument() + }) + expect(screen.getByText(/5\.998 USDC/)).toBeInTheDocument() + expect(screen.getByText(/Migrated/)).toHaveTextContent( + 'Migrated 6 of 11 USDH. The unfilled balance remains on HyperCore.', + ) + }) + + it('renders the watermark by default and hides it when hideAttribution is true', () => { + mockUseAccount.mockReturnValue({ isConnected: false }) + mockUseWalletClient.mockReturnValue({ data: undefined }) + mockUseChainId.mockReturnValue(0) + + const { rerender } = render( ) + expect(screen.getByText(/Powered by/)).toBeInTheDocument() + + rerender( ) + expect(screen.queryByText(/Powered by/)).not.toBeInTheDocument() + }) +}) diff --git a/scripts/demo-browser-smoke.mjs b/scripts/demo-browser-smoke.mjs index 810a3e4..30b8847 100644 --- a/scripts/demo-browser-smoke.mjs +++ b/scripts/demo-browser-smoke.mjs @@ -9,6 +9,7 @@ const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..') const demoDir = join(repoRoot, 'apps', 'demo') const routes = [ '/components', + '/components/usdh-migration', '/components/usdh-widget', '/components/market-board', '/components/outcome-reads',