hyperliquid-deposit 1.0.0

package/README.md

@@ -0,0 +1,215 @@
+# @aspect-build/hyperliquid-deposit
+
+One-click deposit to HyperLiquid trading account from any chain. Automatically bridges tokens to Arbitrum USDC and deposits to HyperLiquid.
+
+[![npm version](https://img.shields.io/npm/v/@aspect-build/hyperliquid-deposit.svg)](https://www.npmjs.com/package/@aspect-build/hyperliquid-deposit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 **One-Click Deposits** - Deposit to HyperLiquid from any supported chain
+- 🌉 **Auto-Bridging** - Automatically bridges tokens to Arbitrum USDC via LI.FI
+- 💰 **Multi-Chain Support** - Supports 60+ chains including Ethereum, Arbitrum, Base, Monad, etc.
+- 🎯 **Smart Routing** - Finds optimal routes considering fees, speed, and gas
+- ⚛️ **React Component** - Drop-in React component with TypeScript support
+- 🎨 **Customizable** - Custom button rendering, styles, and callbacks
+- 📱 **Responsive** - Works on desktop and mobile
+
+## Installation
+
+```bash
+# npm
+npm install @aspect-build/hyperliquid-deposit
+
+# yarn
+yarn add @aspect-build/hyperliquid-deposit
+
+# bun
+bun add @aspect-build/hyperliquid-deposit
+
+# pnpm
+pnpm add @aspect-build/hyperliquid-deposit
+```
+
+## Quick Start
+
+### Basic Usage
+
+```tsx
+import { HyperliquidDeposit } from '@aspect-build/hyperliquid-deposit';
+
+function App() {
+  return (
+    <HyperliquidDeposit
+      walletAddress="0x..." // Connected wallet address
+      onDepositComplete={(txHash, amount) => {
+        console.log(`Deposited $${amount} USDC! Tx: ${txHash}`);
+      }}
+    />
+  );
+}
+```
+
+### With Custom Button
+
+```tsx
+import { HyperliquidDeposit } from '@aspect-build/hyperliquid-deposit';
+
+function App() {
+  return (
+    <HyperliquidDeposit
+      walletAddress={address}
+      renderButton={({ onClick, disabled }) => (
+        <button 
+          onClick={onClick} 
+          disabled={disabled}
+          className="my-custom-button"
+        >
+          💰 Fund Trading Account
+        </button>
+      )}
+    />
+  );
+}
+```
+
+### Using the Hook
+
+```tsx
+import { useHyperliquidDeposit } from '@aspect-build/hyperliquid-deposit';
+
+function App() {
+  const { openDeposit, DepositModal } = useHyperliquidDeposit({
+    walletAddress: '0x...',
+  });
+
+  return (
+    <>
+      <button onClick={openDeposit}>
+        Open Deposit Modal
+      </button>
+      <DepositModal />
+    </>
+  );
+}
+```
+
+### Standalone Modal
+
+```tsx
+import { DepositModal } from '@aspect-build/hyperliquid-deposit';
+
+function App() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Deposit</button>
+      
+      {isOpen && (
+        <DepositModal
+          chains={chains}
+          walletAddress="0x..."
+          onClose={() => setIsOpen(false)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+## API Reference
+
+### `<HyperliquidDeposit />`
+
+Main component that renders a deposit button and modal.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `walletAddress` | `string` | ✅ | Connected wallet address |
+| `chains` | `ChainInfo[]` | ❌ | Custom chains (auto-fetched if not provided) |
+| `onDepositComplete` | `(txHash: string, amount: number) => void` | ❌ | Callback on successful deposit |
+| `onDepositError` | `(error: string) => void` | ❌ | Callback on deposit error |
+| `renderButton` | `(props: { onClick, disabled }) => ReactNode` | ❌ | Custom button renderer |
+| `buttonText` | `string` | ❌ | Button text (default: "Deposit to HyperLiquid") |
+| `buttonStyle` | `CSSProperties` | ❌ | Custom button styles |
+| `buttonClassName` | `string` | ❌ | Custom button class name |
+| `disabled` | `boolean` | ❌ | Disable the button |
+| `modalStyles` | `{ modal?, overlay? }` | ❌ | Custom modal styles |
+
+### `useHyperliquidDeposit()`
+
+Hook for programmatic control.
+
+```tsx
+const {
+  isOpen,        // boolean - modal open state
+  openDeposit,   // () => void - open the modal
+  closeDeposit,  // () => void - close the modal
+  DepositModal,  // React component - the modal
+} = useHyperliquidDeposit(props);
+```
+
+### Constants
+
+```tsx
+import { 
+  HYPERLIQUID_BRIDGE_ADDRESS,  // HyperLiquid bridge contract on Arbitrum
+  MIN_HYPERLIQUID_DEPOSIT_USD  // Minimum deposit ($5)
+} from '@aspect-build/hyperliquid-deposit';
+```
+
+## How It Works
+
+1. **User enters amount** - e.g., $50 USDC
+2. **Scans balances** - Checks all chains for available tokens
+3. **Calculates optimal route** - Finds best bridges considering fees & speed
+4. **Executes bridges** - Bridges tokens to Arbitrum USDC
+5. **Deposits to HyperLiquid** - Transfers USDC to HyperLiquid bridge contract
+
+```
+Your Wallet (any chain)
+        ↓
+   [LI.FI Bridge]
+        ↓
+  Arbitrum USDC
+        ↓
+ HyperLiquid Bridge Contract
+        ↓
+ HyperLiquid Trading Account
+```
+
+## Supported Chains
+
+The component automatically fetches supported chains from LI.FI, including:
+
+- Ethereum, Arbitrum, Base, Optimism, Polygon
+- BSC, Avalanche, Fantom, Gnosis
+- Monad, HyperEVM, Linea, zkSync, Scroll
+- And 50+ more...
+
+## Requirements
+
+- React 18+
+- MetaMask or compatible Web3 wallet
+- Tokens on any supported chain
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Watch mode
+bun run build:watch
+
+# Run example
+bun run dev:example
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,321 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { CSSProperties } from 'react';
+import { LiFiStep } from '@lifi/sdk';
+
+interface ChainInfo {
+    id: number;
+    name: string;
+    key: string;
+    chainType: string;
+    logoURI?: string;
+    nativeToken: {
+        symbol: string;
+        decimals: number;
+        address: string;
+    };
+}
+interface TokenInfo {
+    address: string;
+    symbol: string;
+    decimals: number;
+    chainId: number;
+    name: string;
+    logoURI?: string;
+}
+interface WalletState {
+    address: string | null;
+    chainId: number | null;
+    isConnected: boolean;
+}
+interface TokenBalance {
+    chainId: number;
+    chainName: string;
+    balance: string;
+    formattedBalance: string;
+    symbol: string;
+    tokenAddress: string;
+}
+interface ChainBalance extends TokenBalance {
+    chain: ChainInfo;
+}
+
+interface HyperliquidDepositProps {
+    /**
+     * Wallet address to deposit from
+     */
+    walletAddress: string;
+    /**
+     * Optional: Custom chains to support. If not provided, uses LI.FI supported chains.
+     */
+    chains?: ChainInfo[];
+    /**
+     * Optional: Callback when deposit is completed
+     */
+    onDepositComplete?: (txHash: string, amountUSDC: number) => void;
+    /**
+     * Optional: Callback when deposit fails
+     */
+    onDepositError?: (error: string) => void;
+    /**
+     * Optional: Custom button render function. If not provided, uses default button.
+     */
+    renderButton?: (props: {
+        onClick: () => void;
+        disabled: boolean;
+    }) => React.ReactNode;
+    /**
+     * Optional: Button text (only used with default button)
+     */
+    buttonText?: string;
+    /**
+     * Optional: Custom styles for the button (only used with default button)
+     */
+    buttonStyle?: React.CSSProperties;
+    /**
+     * Optional: Custom class name for the button (only used with default button)
+     */
+    buttonClassName?: string;
+    /**
+     * Optional: Disable the button
+     */
+    disabled?: boolean;
+    /**
+     * Optional: Custom modal styles
+     */
+    modalStyles?: {
+        modal?: React.CSSProperties;
+        overlay?: React.CSSProperties;
+    };
+}
+/**
+ * HyperliquidDeposit - A one-click deposit button for HyperLiquid
+ *
+ * This component provides a button that opens a modal to deposit funds
+ * from any supported chain to your HyperLiquid trading account.
+ *
+ * @example
+ * ```tsx
+ * import { HyperliquidDeposit } from '@aspect-build/hyperliquid-deposit';
+ *
+ * function App() {
+ *   return (
+ *     <HyperliquidDeposit
+ *       walletAddress="0x..."
+ *       onDepositComplete={(txHash, amount) => {
+ *         console.log(`Deposited $${amount} USDC. Tx: ${txHash}`);
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare const HyperliquidDeposit: React.FC<HyperliquidDepositProps>;
+/**
+ * useHyperliquidDeposit - Hook for programmatic control
+ *
+ * @example
+ * ```tsx
+ * const { openDeposit, DepositModal } = useHyperliquidDeposit({
+ *   walletAddress: '0x...',
+ * });
+ *
+ * return (
+ *   <>
+ *     <button onClick={openDeposit}>Custom Button</button>
+ *     <DepositModal />
+ *   </>
+ * );
+ * ```
+ */
+declare const useHyperliquidDeposit: (props: Omit<HyperliquidDepositProps, "renderButton" | "buttonText" | "buttonStyle" | "buttonClassName">) => {
+    isOpen: boolean;
+    openDeposit: () => void;
+    closeDeposit: () => void;
+    DepositModal: () => react_jsx_runtime.JSX.Element | null;
+};
+
+interface DepositModalProps {
+    chains: ChainInfo[];
+    walletAddress: string;
+    onClose: () => void;
+    embedded?: boolean;
+    styles?: {
+        modal?: React.CSSProperties;
+        overlay?: React.CSSProperties;
+    };
+}
+declare const DepositModal: React.FC<DepositModalProps>;
+
+declare const HYPERLIQUID_BRIDGE_ADDRESS = "0x2df1c51e09aecf9cacb7bc98cb1742757f163df7";
+declare const MIN_HYPERLIQUID_DEPOSIT_USD = 5;
+
+interface BridgeWidgetStyles {
+    container?: CSSProperties;
+    connectButton?: CSSProperties;
+    bridgeButton?: CSSProperties;
+    walletInfo?: CSSProperties;
+    modal?: {
+        overlay?: CSSProperties;
+        content?: CSSProperties;
+        header?: CSSProperties;
+        closeButton?: CSSProperties;
+        body?: CSSProperties;
+    };
+    balanceItem?: CSSProperties;
+    chainInfo?: CSSProperties;
+    bridgeFromButton?: CSSProperties;
+    infoBox?: CSSProperties;
+}
+
+interface HyprBridgeWidgetProps {
+    styles?: BridgeWidgetStyles;
+}
+declare const HyprBridgeWidget: React.FC<HyprBridgeWidgetProps>;
+
+interface SearchableToken {
+    symbol: string;
+    name: string;
+    address: string;
+    chainId: number;
+    decimals: number;
+    logoURI?: string;
+    priceUSD?: string;
+}
+declare class TokenSearchService {
+    private tokenCache;
+    private cacheTimestamp;
+    private readonly CACHE_DURATION;
+    /**
+     * Get all tradeable tokens for a specific chain
+     */
+    getTokensForChain(chainId: number): Promise<SearchableToken[]>;
+    /**
+     * Get only popular/whitelisted tokens for a chain (for default display)
+     * These are the top 200 tokens by market cap that exist on this chain
+     * Tokens with logos appear first, sorted by market cap rank
+     * Tokens without logos appear at the end
+     */
+    getPopularTokensForChain(chainId: number): Promise<SearchableToken[]>;
+    /**
+     * Search tokens by name or symbol on a specific chain
+     * This searches ALL tokens, not just popular ones
+     */
+    searchTokens(chainId: number, query: string): Promise<SearchableToken[]>;
+    /**
+     * Get token by exact address on a specific chain
+     */
+    getTokenByAddress(chainId: number, address: string): Promise<SearchableToken | null>;
+    /**
+     * Get token by symbol on a specific chain
+     */
+    getTokenBySymbol(chainId: number, symbol: string): Promise<SearchableToken | null>;
+    /**
+     * Get popular tokens for a chain (USDC, USDT, ETH, WBTC, etc.)
+     */
+    getPopularTokens(chainId: number): Promise<SearchableToken[]>;
+    /**
+     * Clear cache for a specific chain or all chains
+     */
+    clearCache(chainId?: number): void;
+    private mapToSearchableToken;
+}
+
+interface ChainTokenSelectorProps {
+    chains: ChainInfo[];
+    onSelect: (chain: ChainInfo, token: SearchableToken) => void;
+    onClose: () => void;
+    initialChainId?: number;
+    walletAddress?: string;
+    styles?: {
+        modal?: React.CSSProperties;
+        overlay?: React.CSSProperties;
+    };
+}
+declare const ChainTokenSelector: React.FC<ChainTokenSelectorProps>;
+
+declare global {
+    interface Window {
+        ethereum?: any;
+    }
+}
+interface BridgeProgress {
+    status: 'idle' | 'approving' | 'pending' | 'completed' | 'failed';
+    message: string;
+    txHash?: string;
+    txLink?: string;
+}
+interface StepInfo {
+    id: string;
+    tool: string;
+    toolName: string;
+    toolLogo: string;
+    type: string;
+    status: 'waiting' | 'action_required' | 'pending' | 'done' | 'failed';
+    progress: number;
+    txHash?: string;
+    txLink?: string;
+}
+interface DetailedBridgeProgress {
+    overallStatus: 'idle' | 'approving' | 'pending' | 'completed' | 'failed';
+    message: string;
+    steps: StepInfo[];
+    txHash?: string;
+    txLink?: string;
+}
+declare class LiFiBridgeService {
+    private chains;
+    constructor();
+    private initializeLiFi;
+    getAllChains(): Promise<ChainInfo[]>;
+    getTokenInfo(chainId: number, tokenSymbol?: string): Promise<TokenInfo | null>;
+    getBridgeRoute(fromChainId: number, toChainId: number, tokenAmount: string, userAddress: string, tokenSymbol?: string): Promise<LiFiStep>;
+    /**
+     * Get bridge route with specific token addresses (for dynamic source/destination)
+     */
+    getBridgeRouteWithTokens(fromChainId: number, toChainId: number, fromTokenAddress: string, toTokenAddress: string, tokenAmount: string, userAddress: string): Promise<LiFiStep>;
+    executeBridge(quote: LiFiStep, onProgress: (progress: BridgeProgress) => void): Promise<void>;
+    private getStatusMessage;
+    /**
+     * Execute bridge with detailed step-by-step progress for status page
+     */
+    executeBridgeWithDetailedProgress(quote: LiFiStep, onDetailedProgress: (progress: DetailedBridgeProgress) => void): Promise<void>;
+    /**
+     * Get token price in USD
+     * Returns the current USD price for a token on a specific chain
+     */
+    getTokenPrice(chainId: number, tokenAddress: string): Promise<number | null>;
+}
+
+interface BridgeParams {
+    fromChainId: number;
+    toChainId: number;
+    fromToken: SearchableToken;
+    toToken: SearchableToken;
+    amount: string;
+}
+
+/**
+ * Top 200 tokens by market cap (CoinGecko ranking as of 2024)
+ * These tokens are shown by default when a user selects a chain.
+ * The list is ordered by market cap rank.
+ *
+ * Format: Symbol -> Rank (lower = higher market cap)
+ */
+declare const TOP_TOKENS_BY_MARKETCAP: Map<string, number>;
+/**
+ * Check if a token is in the top tokens list
+ */
+declare function isTopToken(symbol: string): boolean;
+/**
+ * Get the market cap rank of a token (lower = higher market cap)
+ * Returns Infinity if not in the list
+ */
+declare function getTokenRank(symbol: string): number;
+/**
+ * Sort tokens by market cap rank
+ */
+declare function sortByMarketCap<T extends {
+    symbol: string;
+}>(tokens: T[]): T[];
+
+export { type BridgeParams, type BridgeProgress, type BridgeWidgetStyles, type ChainBalance, type ChainInfo, ChainTokenSelector, DepositModal, type DetailedBridgeProgress, HYPERLIQUID_BRIDGE_ADDRESS, HyperliquidDeposit, type HyperliquidDepositProps, HyprBridgeWidget, type HyprBridgeWidgetProps, LiFiBridgeService, MIN_HYPERLIQUID_DEPOSIT_USD, type SearchableToken, type StepInfo, TOP_TOKENS_BY_MARKETCAP, TokenSearchService, type WalletState, getTokenRank, isTopToken, sortByMarketCap, useHyperliquidDeposit };