@liberfi.io/ui-perpetuals 0.2.0 → 0.2.2

package/README.md

@@ -51,6 +51,12 @@ Required peer dependencies:
 - `TradeHistorySkeleton()`
 - `TradeHistoryEmpty()`
 - `PerpetualsProvider(props: PerpetualsProviderProps)`
+- `DepositFormUI(props: DepositFormUIProps)` — pure deposit form (amount + recipient)
+- `DepositConfirmUI(props: DepositConfirmUIProps)` — quote confirmation modal with expiry countdown
+- `DepositStatusUI(props: DepositStatusUIProps)` — terminal status modal (settled / refunded / failed)
+- `DepositFlowWidget(props: DepositFlowWidgetProps)` — orchestrates form + confirm + status with hooks
+- `HyperliquidInitUI(props: HyperliquidInitUIProps)` — first-run setup checklist (builder fee / referrer / leverage)
+- `HyperliquidInitWidget(props: HyperliquidInitWidgetProps)` — wires the checklist to `useHyperliquidSetup`
 
 ### Hooks
 
@@ -67,6 +73,13 @@ Required peer dependencies:
 - Component script hooks:
   - `useCoinInfo`, `useSearchCoinsScript`, `useOrderBookScript`, `useTradesScript`
   - `usePlaceOrderFormScript`, `usePositionsScript`, `useOpenOrdersScript`, `useTradeHistoryScript`
+- Deposit hooks (Solana → Hyperliquid USDC):
+  - `usePerpDepositClient` — accessor for the deposit REST client from `PerpetualsProvider`
+  - `usePerpDepositQuote` — TanStack Query wrapper around `POST /v1/deposits/quote`
+  - `usePerpDepositExecute` — orchestrates `quote → sign → broadcast → submit` via the `DepositState` FSM
+  - `usePerpDepositStatus` — long-poll `GET /v1/deposits/{id}` until terminal
+- Hyperliquid first-run setup:
+  - `useHyperliquidSetup` — runs `approveBuilderFee`, `setReferrer`, and `updateLeverage` idempotently against an injected `IHyperliquidSetupAdapter`
 - Also exported helpers from hook modules:
   - Query keys and fetchers such as `coinsQueryKey`/`fetchCoins`, `marketQueryKey`/`fetchMarket`, `ordersQueryKey`/`fetchOrders`, etc.
   - Trade operation helpers: `createOrder`, `cancelOrder`.
@@ -75,12 +88,30 @@ Required peer dependencies:
 
 - `HyperliquidPerpetualsClient` class implementing `IPerpetualsClient`.
 - `usePerpetualsClient()` as the context accessor utility.
+- `LiberFiHttpTransport` — shared HTTP layer (used by every LiberFi REST client; injectable for testing).
+- `LiberFiPerpetualsClient` — REST client over LiberFi-managed perpetuals (talks to perpetuals-server).
+- `LiberFiPerpDepositClient` — REST client over `/v1/deposits/*` (quote / submit / status / refresh).
+- Deposit state machine (pure functions) — `reduceDepositState`, `initialDepositState`, `isDepositTerminal`, `isDepositPolling`, `currentDepositStatus`, `currentDepositBreakdown`, `isTerminalDepositLifecycle`.
+- Hyperliquid setup state machine (pure functions) — `reduceSetupState`, `initialSetupState`, `classifyStep`, `nextRunnableStep`.
 
 ### Types & Enums
 
 - Client-related:
   - `IPerpetualsClient`, `HyperliquidClientConfig`, `HyperliquidEnvironment`, `HyperliquidApiError`
   - `PerpetualsContextValue`, `PerpetualsProviderProps`
+  - `LiberFiHttpTransportConfig`, `LiberFiHttpMethod`, `LiberFiHttpRequestOptions`, `LiberFiApiError`
+  - `LiberFiPerpetualsClientConfig`, `SignTypedDataFn`
+  - `IPerpDepositClient`, `LiberFiPerpDepositClientConfig`
+- Deposit (Solana → Hyperliquid):
+  - `DepositSource`, `DepositStatus`, `DepositErrorInfo`, `DepositStatusTransition`, `DepositBreakdown`
+  - `DepositQuoteRequest`, `DepositQuoteResponse`, `DepositSubmitRequest`, `DepositSubmitResponse`, `DepositStatusResponse`
+  - `DepositPhase`, `DepositState`, `DepositEvent`
+  - `TERMINAL_DEPOSIT_STATUSES`
+- Hyperliquid setup:
+  - `IHyperliquidSetupAdapter`, `HyperliquidAccountState`, `HyperliquidSetupActionResult`
+  - `ApproveBuilderFeeParams`, `SetReferrerParams`, `UpdateLeverageParams`
+  - `SetupStep`, `SetupStepId`, `StepRecord`, `StepStatus`, `SetupPhase`, `SetupState`, `SetupAction`
+  - `UseHyperliquidSetupOptions`, `UseHyperliquidSetupResult`
 - Domain enums/types:
   - `Symbol`, `TradingProvider`, `OrderSide`, `OrderType`, `OrderStatus`, `KlineInterval`, `TradeSide`
 - Domain entities:
@@ -139,8 +170,102 @@ const methods = useForm<PlaceOrderFormData>({
 // Pass methods directly to PlaceOrderFormUI if you build your own container.
 ```
 
+### Deposit (Solana → Hyperliquid USDC)
+
+The deposit flow is a single end-to-end widget plus three presentational
+components for callers that want a custom layout. The widget consumes
+the deposit client via `PerpetualsProvider` and delegates wallet signing
+to the host application.
+
+```tsx
+import {
+  DepositFlowWidget,
+  HyperliquidPerpetualsClient,
+  LiberFiHttpTransport,
+  LiberFiPerpDepositClient,
+  PerpetualsProvider,
+} from "@liberfi.io/ui-perpetuals";
+
+const transport = new LiberFiHttpTransport({
+  baseUrl: process.env.NEXT_PUBLIC_PERPETUALS_API!,
+});
+
+const perpetualsClient = new HyperliquidPerpetualsClient({
+  environment: "mainnet",
+});
+const depositClient = new LiberFiPerpDepositClient({ transport });
+
+export function DepositPanel({ wallet }: { wallet: SolanaWalletAdapter }) {
+  return (
+    <PerpetualsProvider client={perpetualsClient} depositClient={depositClient}>
+      <DepositFlowWidget
+        userSolanaAddress={wallet.publicKey.toBase58()}
+        userId={user.id}
+        source="dex"
+        defaultRecipient={user.evmAddress}
+        signAndBroadcast={async (txBase64) => wallet.signAndSend(txBase64)}
+        buildSolanaExplorerUrl={(h) => `https://solscan.io/tx/${h}`}
+        buildHyperliquidExplorerUrl={(h) =>
+          `https://app.hyperliquid.xyz/explorer/tx/${h}`
+        }
+        onSettled={(intentId) => console.log("settled", intentId)}
+      />
+    </PerpetualsProvider>
+  );
+}
+```
+
+For a fully custom layout, drive the lower-level UI components with
+`usePerpDepositQuote`, `usePerpDepositExecute`, and `usePerpDepositStatus`
+directly. The state-machine pure functions (`reduceDepositState`, etc.)
+are also exported for tooling and tests.
+
+### Hyperliquid first-run setup
+
+`HyperliquidInitWidget` orchestrates the three idempotent setup actions
+Hyperliquid expects on a fresh account: approve a builder fee, set a
+referrer, and pin a default leverage. Wallet signing is delegated to a
+consumer-supplied adapter so this SDK does not pin a specific Hyperliquid
+client library.
+
+```tsx
+import {
+  HyperliquidInitWidget,
+  type IHyperliquidSetupAdapter,
+} from "@liberfi.io/ui-perpetuals";
+
+const adapter: IHyperliquidSetupAdapter = buildPrivyAdapter(/* … */);
+
+export function FirstRunSetup({ user }: { user: { evmAddress: string } }) {
+  return (
+    <HyperliquidInitWidget
+      adapter={adapter}
+      userAddress={user.evmAddress}
+      steps={[
+        {
+          id: "approveBuilderFee",
+          params: { builder: BUILDER_ADDRESS, maxFeeRate: 45 },
+        },
+        { id: "setReferrer", params: { code: "LIBERFI" } },
+        {
+          id: "updateLeverage",
+          params: { asset: "BTC", leverage: 5, isCross: true },
+        },
+      ]}
+      onComplete={() => router.push("/perpetuals")}
+    />
+  );
+}
+```
+
+The pure state machine (`reduceSetupState`, `classifyStep`,
+`nextRunnableStep`) is exported separately so apps can build their own
+checklist UI without reimplementing the transition rules.
+
 ## Future Improvements
 
 - Add integration tests for order submit/cancel and subscription lifecycle.
 - Add i18n wiring for all user-facing strings in `ui-perpetuals` components.
 - Replace placeholder account/margin values in place-order script with real account sources.
+- Surface deposit status updates over a push channel (SSE/WebSocket) once the perpetuals-server exposes one — today the client polls.
+- Ship a first-party `HyperliquidSetupAdapter` implementation via a dedicated `@liberfi.io/wallet-connector-hyperliquid` package so consumers don’t need to write their own.