@metamask-previews/perps-controller 0.0.0-preview-e4aa1532 → 0.0.0-preview-6dfa4aeba

package/dist/providers/HyperLiquidProvider.d.cts

@@ -1,881 +0,0 @@
-import { CaipAccountId } from "@metamask/utils";
-import { WebSocketConnectionState } from "../platform-services/HyperLiquidClientService.cjs";
-import type { AccountState, AssetRoute, BatchCancelOrdersParams, CancelOrderParams, CancelOrderResult, CancelOrdersResult, ClosePositionParams, ClosePositionsParams, ClosePositionsResult, DepositParams, DisconnectResult, EditOrderParams, FeeCalculationParams, FeeCalculationResult, Funding, GetAccountStateParams, GetAvailableDexsParams, GetFundingParams, GetHistoricalPortfolioParams, GetMarketsParams, GetOrderFillsParams, GetOrdersParams, GetPositionsParams, GetSupportedPathsParams, HistoricalPortfolioResult, InitializeResult, PerpsPlatformDependencies, PerpsProvider, LiquidationPriceParams, LiveDataConfig, MaintenanceMarginParams, MarginResult, MarketInfo, Order, OrderFill, OrderParams, OrderResult, PerpsMarketData, Position, RawHyperLiquidLedgerUpdate, ReadyToTradeResult, SubscribeAccountParams, SubscribeCandlesParams, SubscribeOICapsParams, SubscribeOrderBookParams, SubscribeOrderFillsParams, SubscribeOrdersParams, SubscribePositionsParams, SubscribePricesParams, ToggleTestnetResult, TransferBetweenDexsParams, TransferBetweenDexsResult, UpdatePositionTPSLParams, UserHistoryItem, WithdrawParams, WithdrawResult } from "../types/index.cjs";
-/**
- * HyperLiquid provider implementation
- *
- * Implements the PerpsProvider interface for HyperLiquid protocol.
- * Uses the @nktkas/hyperliquid SDK for all operations.
- * Delegates to service classes for client management, wallet integration, and subscriptions.
- *
- * HIP-3 Balance Management:
- * Attempts to use HyperLiquid's native DEX abstraction for automatic collateral transfers.
- * If not supported, falls back to programmatic balance management using SDK's sendAsset.
- */
-export declare class HyperLiquidProvider implements PerpsProvider {
-    readonly protocolId = "hyperliquid";
-    private readonly deps;
-    private readonly clientService;
-    private readonly walletService;
-    private readonly subscriptionService;
-    private readonly symbolToAssetId;
-    private readonly userFeeCache;
-    private readonly maxLeverageCache;
-    private readonly cachedMetaByDex;
-    private perpDexsCache;
-    private readonly referralCheckCache;
-    private readonly builderFeeCheckCache;
-    private ensureReadyPromise;
-    private readonly pendingBuilderFeeApprovals;
-    private readonly compiledAllowlistPatterns;
-    private readonly compiledBlocklistPatterns;
-    private userFeeDiscountBips?;
-    private readonly hip3Enabled;
-    private readonly allowlistMarkets;
-    private readonly blocklistMarkets;
-    private useDexAbstraction;
-    private cachedValidatedDexs;
-    private cachedAllPerpDexs;
-    private pendingValidatedDexsPromise;
-    private cachedUsdcTokenId?;
-    private readonly errorMappings;
-    private clientsInitialized;
-    private initializationPromise;
-    constructor(options: {
-        isTestnet?: boolean;
-        hip3Enabled?: boolean;
-        allowlistMarkets?: string[];
-        blocklistMarkets?: string[];
-        useDexAbstraction?: boolean;
-        platformDependencies: PerpsPlatformDependencies;
-    });
-    /**
-     * Initialize HyperLiquid SDK clients (lazy initialization)
-     *
-     * This is called on first API operation to ensure Engine.context is ready.
-     * Creating the wallet adapter requires accessing Engine.context.AccountTreeController,
-     * which may not be available during early app initialization.
-     *
-     * IMPORTANT: This method awaits the WebSocket transport.ready() to ensure
-     * the connection is fully established before marking initialization complete.
-     */
-    private ensureClientsInitialized;
-    /**
-     * Attempt to enable HIP-3 native balance abstraction
-     *
-     * If successful, HyperLiquid automatically manages collateral transfers for HIP-3 orders.
-     * If not supported, disables the flag to trigger programmatic transfer fallback.
-     *
-     * @private
-     */
-    private ensureDexAbstractionEnabled;
-    /**
-     * Ensure clients are initialized and asset mapping is loaded
-     * Asset mapping is built once on first call and reused for the provider's lifetime
-     * since HIP-3 configuration is immutable after construction
-     */
-    private ensureReady;
-    /**
-     * Get all available DEXs without allowlist filtering
-     * Used when skipFilters=true in getMarkets()
-     *
-     * @returns Array of all DEX names (null for main DEX, strings for HIP-3 DEXs)
-     */
-    private getAllAvailableDexs;
-    /**
-     * Get validated list of DEXs to use based on feature flags and allowlist
-     * Implements Step 3b from HIP-3-IMPLEMENTATION.md (lines 108-134)
-     *
-     * Logic Flow:
-     * 1. If hip3Enabled === false → Return [null] (main DEX only)
-     * 2. Fetch available DEXs via SDK: infoClient.perpDexs()
-     * 3. If enabledDexs is empty [] → Return [null, ...allDiscoveredDexs] (auto-discover)
-     * 4. Else filter enabledDexs against available DEXs → Return [null, ...validatedDexs] (allowlist)
-     *
-     * Invalid DEX names are silently filtered with debugLogger warning.
-     *
-     * @returns Array of DEX names to use (null = main DEX, strings = HIP-3 DEXs)
-     */
-    private getValidatedDexs;
-    /**
-     * Internal method that performs the actual perpDexs fetch and caching
-     * Separated from getValidatedDexs to enable promise deduplication
-     */
-    private fetchValidatedDexsInternal;
-    /**
-     * Get cached meta response for a DEX, fetching from API if not cached
-     * This helper consolidates cache logic to avoid redundant API calls across the provider
-     *
-     * @param params.dexName - DEX name (null for main DEX)
-     * @param params.skipCache - If true, bypass cache and fetch fresh data
-     * @param params
-     * @returns MetaResponse with universe data
-     * @throws Error if API returns invalid data
-     */
-    private getCachedMeta;
-    /**
-     * Fetch perpDexs data with TTL-based caching
-     * Returns deployerFeeScale info needed for dynamic fee calculation
-     *
-     * @returns Array of ExtendedPerpDex objects (null entries represent main DEX)
-     */
-    private getCachedPerpDexs;
-    /**
-     * Calculate HIP-3 fee multiplier using HyperLiquid's official formula
-     * Fetches deployerFeeScale from perpDexs API and growthMode from meta API
-     *
-     * Formula from HyperLiquid docs:
-     * - scaleIfHip3 = deployerFeeScale < 1 ? deployerFeeScale + 1 : deployerFeeScale * 2
-     * - growthModeScale = growthMode ? 0.1 : 1
-     * - finalMultiplier = scaleIfHip3 * growthModeScale
-     *
-     * @param params
-     * @param params.dexName
-     * @param params.assetSymbol
-     * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees#fee-formula-for-developers
-     */
-    private calculateHip3FeeMultiplier;
-    /**
-     * Generate session cache key for user-specific caches
-     * Format: "network:userAddress" (address normalized to lowercase)
-     *
-     * @param network - 'mainnet' or 'testnet'
-     * @param userAddress - User's Ethereum address
-     * @returns Cache key for session-based caches
-     */
-    private getCacheKey;
-    /**
-     * Fetch markets for a specific DEX with optional filtering
-     * Uses session-based caching via getCachedMeta() - no TTL, cleared on disconnect
-     *
-     * @param params.dex - DEX name (null for main DEX)
-     * @param params.skipFilters - If true, skip HIP-3 filtering (return all markets)
-     * @param params.skipCache - If true, bypass cache and fetch fresh data
-     * @param params
-     * @returns Array of MarketInfo objects
-     */
-    private fetchMarketsForDex;
-    /**
-     * Get USDC token ID from spot metadata
-     * Returns format: "USDC:{hex_token_id}"
-     * Caches result to avoid repeated API calls
-     */
-    private getUsdcTokenId;
-    /**
-     * Check if a HIP-3 DEX uses USDH as collateral (vs USDC)
-     * Per HyperLiquid docs: USDH DEXs pull collateral from spot balance automatically
-     *
-     * @param dexName
-     */
-    private isUsdhCollateralDex;
-    /**
-     * Get user's USDH balance in spot wallet
-     */
-    private getSpotUsdhBalance;
-    /**
-     * Get user's USDC balance in spot wallet
-     * Required for USDH DEX orders - need USDC in spot to swap to USDH
-     */
-    private getSpotUsdcBalance;
-    /**
-     * Transfer USDC from main perps wallet to spot wallet
-     * Required before swapping USDC→USDH for USDH DEX orders
-     *
-     * @param amount
-     */
-    private transferUsdcToSpot;
-    /**
-     * Swap USDC to USDH on spot market
-     * Returns the result of the swap including filled size
-     *
-     * @param amount
-     */
-    private swapUsdcToUsdh;
-    /**
-     * Ensure sufficient USDH collateral in spot for HIP-3 DEX order
-     * If user lacks USDH, auto-swap from USDC
-     *
-     * @param dexName
-     * @param requiredMargin
-     */
-    private ensureUsdhCollateralForOrder;
-    /**
-     * Build asset ID mapping from market metadata
-     * Fetches metadata for feature-flag-enabled DEXs and builds a unified mapping
-     * with DEX-prefixed keys for HIP-3 assets (e.g., "xyz:XYZ100" → assetId)
-     *
-     * Per HIP-3-IMPLEMENTATION.md:
-     * - Main DEX: assetId = index (0, 1, 2, ...)
-     * - HIP-3 DEX: assetId = BASE_ASSET_ID + (perpDexIndex × DEX_MULTIPLIER) + index
-     *
-     * This enables proper order routing - when placeOrder({ symbol: "xyz:XYZ100" }) is called,
-     * the asset ID lookup succeeds and the order routes to the correct DEX.
-     */
-    private buildAssetMapping;
-    /**
-     * Set user fee discount context for next operations
-     * Used by PerpsController to apply MetaMask reward discounts
-     *
-     * @param discountBips - The discount in basis points (e.g., 550 = 5.5%)
-     */
-    setUserFeeDiscount(discountBips: number | undefined): void;
-    /**
-     * Query user data across all enabled DEXs in parallel
-     *
-     * DRY helper for multi-DEX user data queries. Handles feature flag logic
-     * and DEX iteration in one place. Uses cached getValidatedDexs() to avoid
-     * redundant perpDexs() API calls.
-     *
-     * @param baseParams - Base parameters (e.g., { user: '0x...' })
-     * @param queryFn - API method to call per DEX
-     * @returns Array of results per DEX with DEX identifier
-     *
-     * @example
-     * ```typescript
-     * const results = await this.queryUserDataAcrossDexs(
-     *   { user: userAddress },
-     *   (p) => infoClient.clearinghouseState(p)
-     * );
-     * ```
-     */
-    private queryUserDataAcrossDexs;
-    /**
-     * Map HyperLiquid API errors to standardized PERPS_ERROR_CODES
-     *
-     * @param error
-     */
-    private mapError;
-    /**
-     * Get error context for logging with searchable tags and context.
-     * Enables Sentry dashboard filtering by feature, provider, and network.
-     *
-     * @param method - The method name where the error occurred
-     * @param extra - Optional additional context fields (becomes searchable context data)
-     * @returns LoggerErrorOptions with tags (searchable) and context (searchable)
-     * @private
-     *
-     * @example
-     * this.deps.logger.error(error, this.getErrorContext('placeOrder', { symbol: 'BTC', orderType: 'limit' }));
-     * // Creates searchable tags: feature:perps, provider:hyperliquid, network:mainnet
-     * // Creates searchable context: perps_provider.method:placeOrder, perps_provider.symbol:BTC, perps_provider.orderType:limit
-     */
-    private getErrorContext;
-    /**
-     * Get supported deposit routes with complete asset and routing information
-     *
-     * @param params
-     */
-    getDepositRoutes(params?: GetSupportedPathsParams): AssetRoute[];
-    /**
-     * Get supported withdrawal routes with complete asset and routing information
-     *
-     * @param params
-     */
-    getWithdrawalRoutes(params?: GetSupportedPathsParams): AssetRoute[];
-    /**
-     * Check current builder fee approval for the user
-     *
-     * @param builder - Builder address to check approval for
-     * @returns Current max fee rate or null if not approved
-     */
-    private checkBuilderFeeApproval;
-    /**
-     * Ensure builder fee is approved for MetaMask
-     * Called once during initialization (ensureReady) to set up builder fee for the session
-     * Uses session cache to avoid redundant API calls until disconnect/reconnect
-     *
-     * Cache semantics: Only caches successful approvals (never caches "not approved" state)
-     * This allows detection of external approvals between retries while avoiding redundant checks
-     *
-     * Note: This is network-specific - testnet and mainnet have separate builder fee states
-     */
-    private ensureBuilderFeeApproval;
-    /**
-     * Check if builder fee is approved for the current user
-     *
-     * @returns Object with approval status and current rate
-     */
-    private checkBuilderFeeStatus;
-    /**
-     * Get available balance for a specific DEX
-     *
-     * @param params - Balance query parameters
-     * @param params.dex - DEX name (null = main, 'xyz' = HIP-3)
-     * @returns Available balance in USDC
-     * @private
-     */
-    private getBalanceForDex;
-    /**
-     * Find source DEX with sufficient balance for transfer
-     * Strategy: Prefer main DEX → other HIP-3 DEXs
-     *
-     * @param params - Source search parameters
-     * @param params.targetDex - Target DEX name
-     * @param params.requiredAmount - Required balance shortfall
-     * @returns Source DEX info or null if insufficient funds
-     * @private
-     */
-    private findSourceDexWithBalance;
-    /**
-     * Auto-transfer funds for HIP-3 orders when insufficient balance
-     * Only called for HIP-3 markets (not main DEX)
-     *
-     * @param params - Transfer parameters
-     * @param params.targetDex - HIP-3 DEX name (e.g., 'xyz')
-     * @param params.requiredMargin - Required margin with buffer
-     * @returns Transfer info for rollback, or null if no transfer needed
-     * @private
-     */
-    private autoTransferForHip3Order;
-    /**
-     * Auto-transfer freed margin back to main DEX after closing a HIP-3 position
-     *
-     * This method transfers the margin released from closing a position back to
-     * the main DEX to prevent balance fragmentation across HIP-3 DEXs.
-     *
-     * Design: Non-blocking operation - failures are logged but don't affect the
-     * position close operation. Extensible for future configuration options.
-     *
-     * @param params - Transfer configuration
-     * @param params.sourceDex - HIP-3 DEX name to transfer from
-     * @param params.freedMargin - Amount of margin released from position close
-     * @param params.transferAll - (Future) Transfer all available balance instead
-     * @param params.skipTransfer - (Future) Skip auto-transfer if disabled
-     * @returns Transfer info if successful, null if skipped/failed
-     * @private
-     */
-    private autoTransferBackAfterClose;
-    /**
-     * Calculate required margin for HIP-3 order based on existing position
-     * Handles three scenarios:
-     * 1. Increasing existing position - requires TOTAL margin (temporary over-funding)
-     * 2. Reducing/flipping position - requires margin for new order only
-     * 3. New position - requires margin for new order only
-     *
-     * @param params
-     * @param params.symbol
-     * @param params.dexName
-     * @param params.positionSize
-     * @param params.orderPrice
-     * @param params.leverage
-     * @param params.isBuy
-     * @private
-     */
-    private calculateHip3RequiredMargin;
-    /**
-     * Handle post-order balance check and auto-rebalance for HIP-3 orders
-     * After a successful order, checks available balance and transfers excess back to main DEX
-     * Does not throw errors - logs them for monitoring
-     *
-     * @param params
-     * @param params.dexName
-     * @param params.transferInfo
-     * @param params.transferInfo.amount
-     * @param params.transferInfo.sourceDex
-     * @private
-     */
-    private handleHip3PostOrderRebalance;
-    /**
-     * Handle rollback of HIP-3 transfer when order fails
-     * Attempts to return funds to source DEX
-     * Does not throw errors - logs them for monitoring
-     *
-     * @param params
-     * @param params.dexName
-     * @param params.transferInfo
-     * @param params.transferInfo.amount
-     * @param params.transferInfo.sourceDex
-     * @private
-     */
-    private handleHip3OrderRollback;
-    /**
-     * Validates order parameters before placement using provider-level validation
-     *
-     * @param params
-     * @throws Error if validation fails
-     */
-    private validateOrderBeforePlacement;
-    /**
-     * Gets asset info and current price from the correct DEX
-     *
-     * @param params
-     */
-    private getAssetInfo;
-    /**
-     * Prepares asset for trading by updating leverage if specified
-     *
-     * @param params
-     */
-    private prepareAssetForTrading;
-    /**
-     * Handles HIP-3 pre-order balance management
-     *
-     * @param params
-     */
-    private handleHip3PreOrder;
-    /**
-     * Submits order with atomic rollback for HIP-3 failures
-     *
-     * @param params
-     */
-    private submitOrderWithRollback;
-    /**
-     * Handles order errors with proper error mapping
-     *
-     * @param params
-     */
-    private handleOrderError;
-    /**
-     * Place an order using direct wallet signing
-     *
-     * Refactored to use helper methods for better maintainability and reduced complexity.
-     * Each helper method is focused on a single responsibility.
-     *
-     * @param params - Order parameters
-     * @param retryCount - Internal retry counter to prevent infinite loops (default: 0)
-     */
-    placeOrder(params: OrderParams, retryCount?: number): Promise<OrderResult>;
-    /**
-     * Edit an existing order (pending/unfilled order)
-     *
-     * Note: This modifies price/size of a pending order. It CANNOT add TP/SL to an existing order.
-     * For adding TP/SL to an existing position, use updatePositionTPSL instead.
-     *
-     * @param params.orderId - The order ID to modify
-     * @param params.newOrder - New order parameters (price, size, etc.)
-     * @param params
-     */
-    editOrder(params: EditOrderParams): Promise<OrderResult>;
-    /**
-     * Cancel an order
-     *
-     * @param params
-     */
-    cancelOrder(params: CancelOrderParams): Promise<CancelOrderResult>;
-    /**
-     * Cancel multiple orders in a single batch API call
-     * Optimized implementation that uses HyperLiquid's batch cancel endpoint
-     *
-     * @param params
-     */
-    cancelOrders(params: BatchCancelOrdersParams): Promise<CancelOrdersResult>;
-    closePositions(params: ClosePositionsParams): Promise<ClosePositionsResult>;
-    /**
-     * Update TP/SL for an existing position
-     *
-     * This creates new TP/SL orders for the position using 'positionTpsl' grouping.
-     * These are separate orders that will close the position when triggered.
-     *
-     * Key differences from editOrder:
-     * - editOrder: Modifies pending orders (before fill)
-     * - updatePositionTPSL: Creates TP/SL orders for filled positions
-     *
-     * HyperLiquid supports two TP/SL types:
-     * 1. 'normalTpsl' - Tied to a parent order (set when placing the order)
-     * 2. 'positionTpsl' - Tied to a position (can be set/modified after fill)
-     *
-     * @param params.symbol - Asset symbol of the position
-     * @param params.takeProfitPrice - TP price (undefined to remove)
-     * @param params.stopLossPrice - SL price (undefined to remove)
-     * @param params
-     */
-    updatePositionTPSL(params: UpdatePositionTPSLParams): Promise<OrderResult>;
-    /**
-     * Close a position
-     *
-     * For HIP-3 positions, this method automatically transfers freed margin
-     * back to the main DEX after successfully closing the position.
-     *
-     * @param params
-     */
-    closePosition(params: ClosePositionParams): Promise<OrderResult>;
-    /**
-     * Update margin for an existing position (add or remove)
-     *
-     * @param params - Margin adjustment parameters
-     * @param params.symbol - Asset symbol (e.g., 'BTC', 'ETH')
-     * @param params.amount - Amount to adjust as string (positive = add, negative = remove)
-     * @returns Promise resolving to margin adjustment result
-     *
-     * Note: HyperLiquid uses micro-units (multiply by 1e6) for the ntli parameter.
-     * The SDK's updateIsolatedMargin requires:
-     * - asset: Asset ID (number)
-     * - isBuy: Position direction (true for long, false for short)
-     * - ntli: Amount in micro-units (amount * 1e6)
-     */
-    updateMargin(params: {
-        symbol: string;
-        amount: string;
-    }): Promise<MarginResult>;
-    /**
-     * Get current positions with TP/SL prices
-     *
-     * Note on TP/SL orders:
-     * - normalTpsl: TP/SL tied to parent order, only placed after parent fills
-     * - positionTpsl: TP/SL tied to position, placed immediately
-     *
-     * This means TP/SL prices may not appear immediately after placing an order
-     * with TP/SL. They will only show up once the parent order is filled and
-     * the child TP/SL orders are actually placed on the order book.
-     *
-     * @param params
-     */
-    getPositions(params?: GetPositionsParams): Promise<Position[]>;
-    /**
-     * Get historical user fills (trade executions)
-     *
-     * @param params
-     */
-    getOrderFills(params?: GetOrderFillsParams): Promise<OrderFill[]>;
-    /**
-     * Get historical orders (order lifecycle)
-     *
-     * @param params
-     */
-    getOrders(params?: GetOrdersParams): Promise<Order[]>;
-    /**
-     * Get currently open orders (real-time status)
-     * Uses frontendOpenOrders API to get only currently active orders
-     * Aggregates orders from all enabled DEXs (main + HIP-3)
-     *
-     * @param params
-     */
-    getOpenOrders(params?: GetOrdersParams): Promise<Order[]>;
-    /**
-     * Get user funding history
-     *
-     * @param params
-     */
-    getFunding(params?: GetFundingParams): Promise<Funding[]>;
-    /**
-     * Get user non-funding ledger updates (deposits, transfers, withdrawals)
-     *
-     * @param params
-     * @param params.accountId
-     * @param params.startTime
-     * @param params.endTime
-     */
-    getUserNonFundingLedgerUpdates(params?: {
-        accountId?: string;
-        startTime?: number;
-        endTime?: number;
-    }): Promise<RawHyperLiquidLedgerUpdate[]>;
-    /**
-     * Get user history (deposits, withdrawals, transfers)
-     *
-     * @param params
-     * @param params.accountId
-     * @param params.startTime
-     * @param params.endTime
-     */
-    getUserHistory(params?: {
-        accountId?: CaipAccountId;
-        startTime?: number;
-        endTime?: number;
-    }): Promise<UserHistoryItem[]>;
-    getHistoricalPortfolio(params?: GetHistoricalPortfolioParams): Promise<HistoricalPortfolioResult>;
-    /**
-     * Get account state
-     * Aggregates balances across all enabled DEXs (main + HIP-3)
-     *
-     * @param params
-     */
-    getAccountState(params?: GetAccountStateParams): Promise<AccountState>;
-    /**
-     * Get available markets with multi-DEX aggregation support (HIP-3)
-     * Handles three query patterns:
-     * 1. Symbol filtering: Groups symbols by DEX, fetches in parallel
-     * 2. Multi-DEX aggregation: Fetches from all enabled DEXs when no specific DEX requested
-     * 3. Single DEX query: Fetches from main or specific DEX
-     *
-     * @param params - Optional parameters for filtering
-     */
-    getMarkets(params?: GetMarketsParams): Promise<MarketInfo[]>;
-    /**
-     * Get list of available HIP-3 DEXs that have markets
-     * Useful for debugging and manual DEX selection
-     *
-     * @returns Array of DEX names (excluding main DEX)
-     */
-    getAvailableHip3Dexs(): Promise<string[]>;
-    /**
-     * Get market data with prices, volumes, and 24h changes
-     * Aggregates data from all enabled DEXs (main + HIP-3) when equity is enabled
-     *
-     * Note: This is called once during initialization and cached by PerpsStreamManager.
-     * Real-time price updates come from WebSocket subscriptions, not this method.
-     */
-    getMarketDataWithPrices(): Promise<PerpsMarketData[]>;
-    /**
-     * Validate deposit parameters according to HyperLiquid-specific rules
-     * This method enforces protocol-specific requirements like minimum amounts
-     *
-     * @param params
-     */
-    validateDeposit(params: DepositParams): Promise<{
-        isValid: boolean;
-        error?: string;
-    }>;
-    /**
-     * Validate order parameters according to HyperLiquid-specific rules
-     * This includes minimum order sizes, leverage limits, and other protocol requirements
-     *
-     * @param params
-     */
-    validateOrder(params: OrderParams): Promise<{
-        isValid: boolean;
-        error?: string;
-    }>;
-    /**
-     * Validate close position parameters according to HyperLiquid-specific rules
-     * Note: Full validation including remaining position size requires position data
-     * which should be passed from the UI layer
-     *
-     * @param params
-     */
-    validateClosePosition(params: ClosePositionParams): Promise<{
-        isValid: boolean;
-        error?: string;
-    }>;
-    /**
-     * Validate withdrawal parameters - placeholder for future implementation
-     *
-     * @param _params
-     */
-    validateWithdrawal(_params: WithdrawParams): Promise<{
-        isValid: boolean;
-        error?: string;
-    }>;
-    /**
-     * Withdraw funds from HyperLiquid trading account
-     *
-     * This initiates a withdrawal request via HyperLiquid's API (withdraw3 endpoint).
-     *
-     * HyperLiquid Bridge Process:
-     * - Funds are immediately deducted from L1 balance on HyperLiquid
-     * - Validators sign the withdrawal (2/3 of staking power required)
-     * - Bridge contract on destination chain processes the withdrawal
-     * - After dispute period, USDC is sent to destination address
-     * - Total time: ~5 minutes
-     * - Fee: 1 USDC (covers Arbitrum gas costs)
-     * - No ETH required from user
-     *
-     * Note: Withdrawals won't appear as incoming transactions until the
-     * finalization phase completes (~5 minutes after initiation)
-     *
-     * @param params Withdrawal parameters
-     * @returns Result with txHash (HyperLiquid internal) and withdrawal ID
-     */
-    withdraw(params: WithdrawParams): Promise<WithdrawResult>;
-    /**
-     * Transfer USDC collateral between DEXs (main ↔ HIP-3)
-     *
-     * Verified working on mainnet via Phantom wallet testing (10/15/2025).
-     * See docs/perps/HIP-3-IMPLEMENTATION.md for complete transaction flow.
-     *
-     * @param params - Transfer parameters
-     * @param params.sourceDex - Source DEX name ('' = main, 'xyz' = HIP-3)
-     * @param params.destinationDex - Destination DEX name ('' = main, 'xyz' = HIP-3)
-     * @param params.amount - USDC amount to transfer
-     * @returns Transfer result with success status and transaction hash
-     *
-     * @example
-     * // Transfer 10 USDC from main DEX to xyz HIP-3 DEX
-     * await transferBetweenDexs({
-     *   sourceDex: '',
-     *   destinationDex: 'xyz',
-     *   amount: '10'
-     * });
-     */
-    transferBetweenDexs(params: TransferBetweenDexsParams): Promise<TransferBetweenDexsResult>;
-    /**
-     * Subscribe to live price updates
-     *
-     * @param params
-     */
-    subscribeToPrices(params: SubscribePricesParams): () => void;
-    /**
-     * Subscribe to live position updates
-     *
-     * @param params
-     */
-    subscribeToPositions(params: SubscribePositionsParams): () => void;
-    /**
-     * Subscribe to live order fill updates
-     *
-     * @param params
-     */
-    subscribeToOrderFills(params: SubscribeOrderFillsParams): () => void;
-    /**
-     * Subscribe to live order updates
-     *
-     * @param params
-     */
-    subscribeToOrders(params: SubscribeOrdersParams): () => void;
-    /**
-     * Subscribe to live account updates
-     *
-     * @param params
-     */
-    subscribeToAccount(params: SubscribeAccountParams): () => void;
-    /**
-     * Subscribe to open interest cap updates
-     * Zero additional overhead - data extracted from existing webData2 subscription
-     *
-     * @param params
-     */
-    subscribeToOICaps(params: SubscribeOICapsParams): () => void;
-    /**
-     * Subscribe to full order book updates with multiple depth levels
-     * Creates a dedicated L2Book subscription for real-time order book data
-     *
-     * @param params
-     */
-    subscribeToOrderBook(params: SubscribeOrderBookParams): () => void;
-    /**
-     * Subscribe to live candle updates
-     *
-     * @param params
-     */
-    subscribeToCandles(params: SubscribeCandlesParams): () => void;
-    /**
-     * Configure live data settings
-     *
-     * @param config
-     */
-    setLiveDataConfig(config: Partial<LiveDataConfig>): void;
-    /**
-     * Toggle testnet mode
-     */
-    toggleTestnet(): Promise<ToggleTestnetResult>;
-    /**
-     * Initialize provider (ensures clients are ready)
-     */
-    initialize(): Promise<InitializeResult>;
-    /**
-     * Check if ready to trade
-     */
-    isReadyToTrade(): Promise<ReadyToTradeResult>;
-    /**
-     * Calculate liquidation price using HyperLiquid's formula
-     * Formula: liq_price = price - side * margin_available / position_size / (1 - l * side)
-     * where l = 1 / MAINTENANCE_LEVERAGE = 1 / (2 * max_leverage)
-     *
-     * @param params
-     */
-    calculateLiquidationPrice(params: LiquidationPriceParams): Promise<string>;
-    /**
-     * Calculate maintenance margin for a specific asset
-     * According to HyperLiquid docs: maintenance_margin = 1 / (2 * max_leverage)
-     *
-     * @param params
-     */
-    calculateMaintenanceMargin(params: MaintenanceMarginParams): Promise<number>;
-    /**
-     * Get maximum leverage allowed for an asset
-     *
-     * @param asset
-     */
-    getMaxLeverage(asset: string): Promise<number>;
-    /**
-     * Calculate fees based on HyperLiquid's fee structure
-     * Returns fee rate as decimal (e.g., 0.00045 for 0.045%)
-     *
-     * Uses the SDK's userFees API to get actual discounted rates when available,
-     * falling back to base rates if the API is unavailable or user not connected.
-     *
-     * @param params
-     */
-    calculateFees(params: FeeCalculationParams): Promise<FeeCalculationResult>;
-    /**
-     * Check if the fee cache is valid for a user
-     *
-     * @param userAddress
-     * @private
-     */
-    private isFeeCacheValid;
-    /**
-     * Clear fee cache for a specific user or all users
-     *
-     * @param userAddress - Optional address to clear cache for
-     */
-    clearFeeCache(userAddress?: string): void;
-    /**
-     * Disconnect provider
-     */
-    disconnect(): Promise<DisconnectResult>;
-    /**
-     * Lightweight WebSocket health check using SDK's built-in ready() method
-     * Checks if WebSocket connection is open without making expensive API calls
-     *
-     * @param timeoutMs - Optional timeout in milliseconds (defaults to WEBSOCKET_PING_TIMEOUT_MS)
-     * @throws {Error} If WebSocket connection times out or fails
-     */
-    ping(timeoutMs?: number): Promise<void>;
-    /**
-     * Get the current WebSocket connection state from the client service.
-     * Used by the UI to monitor connection health and show notifications.
-     *
-     * @returns The current WebSocket connection state
-     */
-    getWebSocketConnectionState(): WebSocketConnectionState;
-    /**
-     * Subscribe to WebSocket connection state changes.
-     * The listener will be called immediately with the current state and whenever the state changes.
-     *
-     * @param listener - Callback function that receives the new connection state and reconnection attempt
-     * @returns Unsubscribe function to remove the listener
-     */
-    subscribeToConnectionState(listener: (state: WebSocketConnectionState, reconnectionAttempt: number) => void): () => void;
-    /**
-     * Manually trigger a WebSocket reconnection attempt.
-     * Used by the UI retry button when connection is lost.
-     */
-    reconnect(): Promise<void>;
-    /**
-     * Get list of available HIP-3 builder-deployed DEXs
-     *
-     * @param _params - Optional parameters (reserved for future filters/pagination)
-     * @returns Array of DEX names (empty string '' represents main DEX)
-     */
-    getAvailableDexs(_params?: GetAvailableDexsParams): Promise<string[]>;
-    /**
-     * Get block explorer URL for an address or just the base URL
-     *
-     * @param address - Optional address to append to the base URL
-     * @returns Block explorer URL
-     */
-    getBlockExplorerUrl(address?: string): string;
-    private getBuilderAddress;
-    private getReferralCode;
-    /**
-     * Ensure user has a MetaMask referral code set
-     * Called once during initialization (ensureReady) to set up referral for the session
-     * Uses session cache to avoid redundant API calls until disconnect/reconnect
-     *
-     * Cache semantics: Only caches successful referral sets (never caches "not set" state)
-     * This allows detection of external referral changes between retries while avoiding redundant checks
-     *
-     * Note: This is network-specific - testnet and mainnet have separate referral states
-     * Note: Non-blocking - failures are logged to Sentry but don't prevent trading
-     * Note: Will automatically retry on next session if failed (cache cleared on disconnect)
-     */
-    private ensureReferralSet;
-    /**
-     * Check if the referral code is ready to be used
-     *
-     * @returns Promise resolving to true if referral code is ready
-     */
-    private isReferralCodeReady;
-    /**
-     * Check if user has a referral code set with HyperLiquid
-     *
-     * @returns Promise resolving to true if referral is set, false otherwise
-     */
-    private checkReferralSet;
-    /**
-     * Set MetaMask as the user's referrer on HyperLiquid
-     */
-    private setReferralCode;
-}
-//# sourceMappingURL=HyperLiquidProvider.d.cts.map