@metamask-previews/perps-controller 0.0.0-preview-685dbf46b → 1.0.0-preview-bc00f2c

package/dist/PerpsController.d.cts

@@ -1,107 +1,994 @@
-import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
-import { BaseController } from "@metamask/base-controller";
+import { BaseController, ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
 import type { Messenger } from "@metamask/messenger";
+import type { Json } from "@metamask/utils";
+import { CandlePeriod } from "./constants/chartConfig.cjs";
+import type { SortOptionId } from "./constants/perpsConfig.cjs";
+import { WebSocketConnectionState } from "./types/index.cjs";
+import type { AccountState, AssetRoute, CancelOrderParams, CancelOrderResult, CancelOrdersParams, CancelOrdersResult, ClosePositionParams, ClosePositionsParams, ClosePositionsResult, DepositWithConfirmationParams, EditOrderParams, FeeCalculationParams, FeeCalculationResult, FlipPositionParams, Funding, GetAccountStateParams, GetAvailableDexsParams, GetFundingParams, GetMarketsParams, GetOrderFillsParams, GetOrdersParams, GetPositionsParams, PerpsProvider, LiquidationPriceParams, LiveDataConfig, MaintenanceMarginParams, MarginResult, MarketInfo, Order, OrderFill, OrderParams, OrderResult, PerpsControllerConfig, PerpsMarketData, Position, SubscribeAccountParams, SubscribeCandlesParams, SubscribeOICapsParams, SubscribeOrderBookParams, SubscribeOrderFillsParams, SubscribeOrdersParams, SubscribePositionsParams, SubscribePricesParams, SwitchProviderResult, ToggleTestnetResult, UpdateMarginParams, UpdatePositionTPSLParams, WithdrawParams, WithdrawResult, GetHistoricalPortfolioParams, HistoricalPortfolioResult, OrderType, PerpsPlatformDependencies, PerpsActiveProviderMode, PerpsProviderType, PerpsSelectedPaymentToken, PerpsRemoteFeatureFlagState } from "./types/index.cjs";
+import type { PerpsControllerAllowedActions, PerpsControllerAllowedEvents } from "./types/messenger.cjs";
+import type { CandleData } from "./types/perps-types.cjs";
+import { LastTransactionResult, TransactionStatus } from "./types/transactionTypes.cjs";
+import type { SortDirection } from "./utils/sortMarkets.cjs";
 /**
- * The name of the {@link PerpsController}, used to namespace the
- * controller's actions and events and to namespace the controller's state data
- * when composed with other controllers.
+ * Minimal payment token stored in PerpsController state.
+ * Only required fields for identification, Perps balance detection, and analytics.
  */
-export declare const controllerName = "PerpsController";
+export type SelectedPaymentTokenSnapshot = {
+    description?: string;
+    address: string;
+    chainId: string;
+    symbol?: string;
+};
+export { PERPS_ERROR_CODES, type PerpsErrorCode } from "./perpsErrorCodes.cjs";
 /**
- * Describes the shape of the state object for {@link PerpsController}.
+ * Initialization state enum for state machine tracking
  */
-export type PerpsControllerState = {};
-/**
- * Constructs the default {@link PerpsController} state. This allows
- * consumers to provide a partial state object when initializing the controller
- * and also helps in constructing complete state objects for this controller in
- * tests.
- *
- * @returns The default {@link PerpsController} state.
- */
-export declare function getDefaultPerpsControllerState(): PerpsControllerState;
-/**
- * Retrieves the state of the {@link PerpsController}.
- */
-export type PerpsControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PerpsControllerState>;
+export declare enum InitializationState {
+    Uninitialized = "uninitialized",
+    Initializing = "initializing",
+    Initialized = "initialized",
+    Failed = "failed"
+}
 /**
- * Actions that {@link PerpsControllerMessenger} exposes to other consumers.
+ * State shape for PerpsController
  */
-export type PerpsControllerActions = PerpsControllerGetStateAction;
+export type PerpsControllerState = {
+    activeProvider: PerpsActiveProviderMode;
+    isTestnet: boolean;
+    initializationState: InitializationState;
+    initializationError: string | null;
+    initializationAttempts: number;
+    accountState: AccountState | null;
+    perpsBalances: {
+        [provider: string]: {
+            totalBalance: string;
+            unrealizedPnl: string;
+            accountValue1dAgo: string;
+            lastUpdated: number;
+        };
+    };
+    depositInProgress: boolean;
+    lastDepositTransactionId: string | null;
+    lastDepositResult: LastTransactionResult | null;
+    withdrawInProgress: boolean;
+    lastWithdrawResult: LastTransactionResult | null;
+    withdrawalRequests: {
+        id: string;
+        amount: string;
+        asset: string;
+        accountAddress: string;
+        txHash?: string;
+        timestamp: number;
+        success: boolean;
+        status: TransactionStatus;
+        destination?: string;
+        source?: string;
+        transactionId?: string;
+        withdrawalId?: string;
+        depositId?: string;
+    }[];
+    withdrawalProgress: {
+        progress: number;
+        lastUpdated: number;
+        activeWithdrawalId: string | null;
+    };
+    depositRequests: {
+        id: string;
+        amount: string;
+        asset: string;
+        accountAddress: string;
+        txHash?: string;
+        timestamp: number;
+        success: boolean;
+        status: TransactionStatus;
+        destination?: string;
+        source?: string;
+        transactionId?: string;
+        withdrawalId?: string;
+        depositId?: string;
+    }[];
+    isEligible: boolean;
+    isFirstTimeUser: {
+        testnet: boolean;
+        mainnet: boolean;
+    };
+    hasPlacedFirstOrder: {
+        testnet: boolean;
+        mainnet: boolean;
+    };
+    watchlistMarkets: {
+        testnet: string[];
+        mainnet: string[];
+    };
+    tradeConfigurations: {
+        testnet: {
+            [marketSymbol: string]: {
+                leverage?: number;
+                orderBookGrouping?: number;
+                pendingConfig?: {
+                    amount?: string;
+                    leverage?: number;
+                    takeProfitPrice?: string;
+                    stopLossPrice?: string;
+                    limitPrice?: string;
+                    orderType?: OrderType;
+                    timestamp: number;
+                };
+            };
+        };
+        mainnet: {
+            [marketSymbol: string]: {
+                leverage?: number;
+                orderBookGrouping?: number;
+                pendingConfig?: {
+                    amount?: string;
+                    leverage?: number;
+                    takeProfitPrice?: string;
+                    stopLossPrice?: string;
+                    limitPrice?: string;
+                    orderType?: OrderType;
+                    timestamp: number;
+                };
+            };
+        };
+    };
+    marketFilterPreferences: {
+        optionId: SortOptionId;
+        direction: SortDirection;
+    };
+    lastError: string | null;
+    lastUpdateTimestamp: number;
+    hip3ConfigVersion: number;
+    selectedPaymentToken: Json | null;
+    cachedMarketData: PerpsMarketData[] | null;
+    cachedMarketDataTimestamp: number;
+    cachedPositions: Position[] | null;
+    cachedOrders: Order[] | null;
+    cachedAccountState: AccountState | null;
+    cachedUserDataTimestamp: number;
+    cachedUserDataAddress: string | null;
+};
 /**
- * Actions from other messengers that {@link PerpsControllerMessenger} calls.
+ * Get default PerpsController state
+ *
+ * To change the active provider, modify the `activeProvider` value below:
+ * - 'hyperliquid': HyperLiquid provider (default, production)
+ * - 'aggregated': Multi-provider aggregation mode
+ * - 'myx': MYX provider (future implementation)
+ *
+ * @returns The default perps controller state.
  */
-type AllowedActions = never;
+export declare const getDefaultPerpsControllerState: () => PerpsControllerState;
 /**
- * Published when the state of {@link PerpsController} changes.
+ * PerpsController events
  */
-export type PerpsControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PerpsControllerState>;
+export type PerpsControllerEvents = ControllerStateChangeEvent<'PerpsController', PerpsControllerState>;
 /**
- * Events that {@link PerpsControllerMessenger} exposes to other consumers.
+ * PerpsController actions
  */
-export type PerpsControllerEvents = PerpsControllerStateChangeEvent;
+export type PerpsControllerActions = ControllerGetStateAction<'PerpsController', PerpsControllerState> | {
+    type: 'PerpsController:placeOrder';
+    handler: PerpsController['placeOrder'];
+} | {
+    type: 'PerpsController:editOrder';
+    handler: PerpsController['editOrder'];
+} | {
+    type: 'PerpsController:cancelOrder';
+    handler: PerpsController['cancelOrder'];
+} | {
+    type: 'PerpsController:cancelOrders';
+    handler: PerpsController['cancelOrders'];
+} | {
+    type: 'PerpsController:closePosition';
+    handler: PerpsController['closePosition'];
+} | {
+    type: 'PerpsController:closePositions';
+    handler: PerpsController['closePositions'];
+} | {
+    type: 'PerpsController:withdraw';
+    handler: PerpsController['withdraw'];
+} | {
+    type: 'PerpsController:getPositions';
+    handler: PerpsController['getPositions'];
+} | {
+    type: 'PerpsController:getOrderFills';
+    handler: PerpsController['getOrderFills'];
+} | {
+    type: 'PerpsController:getOrders';
+    handler: PerpsController['getOrders'];
+} | {
+    type: 'PerpsController:getOpenOrders';
+    handler: PerpsController['getOpenOrders'];
+} | {
+    type: 'PerpsController:getFunding';
+    handler: PerpsController['getFunding'];
+} | {
+    type: 'PerpsController:getAccountState';
+    handler: PerpsController['getAccountState'];
+} | {
+    type: 'PerpsController:getMarkets';
+    handler: PerpsController['getMarkets'];
+} | {
+    type: 'PerpsController:refreshEligibility';
+    handler: PerpsController['refreshEligibility'];
+} | {
+    type: 'PerpsController:toggleTestnet';
+    handler: PerpsController['toggleTestnet'];
+} | {
+    type: 'PerpsController:disconnect';
+    handler: PerpsController['disconnect'];
+} | {
+    type: 'PerpsController:calculateFees';
+    handler: PerpsController['calculateFees'];
+} | {
+    type: 'PerpsController:markTutorialCompleted';
+    handler: PerpsController['markTutorialCompleted'];
+} | {
+    type: 'PerpsController:markFirstOrderCompleted';
+    handler: PerpsController['markFirstOrderCompleted'];
+} | {
+    type: 'PerpsController:getHistoricalPortfolio';
+    handler: PerpsController['getHistoricalPortfolio'];
+} | {
+    type: 'PerpsController:resetFirstTimeUserState';
+    handler: PerpsController['resetFirstTimeUserState'];
+} | {
+    type: 'PerpsController:clearPendingTransactionRequests';
+    handler: PerpsController['clearPendingTransactionRequests'];
+} | {
+    type: 'PerpsController:saveTradeConfiguration';
+    handler: PerpsController['saveTradeConfiguration'];
+} | {
+    type: 'PerpsController:getTradeConfiguration';
+    handler: PerpsController['getTradeConfiguration'];
+} | {
+    type: 'PerpsController:saveMarketFilterPreferences';
+    handler: PerpsController['saveMarketFilterPreferences'];
+} | {
+    type: 'PerpsController:getMarketFilterPreferences';
+    handler: PerpsController['getMarketFilterPreferences'];
+} | {
+    type: 'PerpsController:savePendingTradeConfiguration';
+    handler: PerpsController['savePendingTradeConfiguration'];
+} | {
+    type: 'PerpsController:getPendingTradeConfiguration';
+    handler: PerpsController['getPendingTradeConfiguration'];
+} | {
+    type: 'PerpsController:clearPendingTradeConfiguration';
+    handler: PerpsController['clearPendingTradeConfiguration'];
+} | {
+    type: 'PerpsController:getOrderBookGrouping';
+    handler: PerpsController['getOrderBookGrouping'];
+} | {
+    type: 'PerpsController:saveOrderBookGrouping';
+    handler: PerpsController['saveOrderBookGrouping'];
+} | {
+    type: 'PerpsController:setSelectedPaymentToken';
+    handler: PerpsController['setSelectedPaymentToken'];
+} | {
+    type: 'PerpsController:resetSelectedPaymentToken';
+    handler: PerpsController['resetSelectedPaymentToken'];
+};
 /**
- * Events from other messengers that {@link PerpsControllerMessenger} subscribes
- * to.
+ * PerpsController messenger constraints.
+ * Includes both PerpsController's own actions/events and
+ * allowed actions/events from external controllers.
  */
-type AllowedEvents = never;
+export type PerpsControllerMessenger = Messenger<'PerpsController', PerpsControllerActions | PerpsControllerAllowedActions, PerpsControllerEvents | PerpsControllerAllowedEvents>;
 /**
- * The messenger restricted to actions and events accessed by
- * {@link PerpsController}.
+ * PerpsController options
  */
-export type PerpsControllerMessenger = Messenger<typeof controllerName, PerpsControllerActions | AllowedActions, PerpsControllerEvents | AllowedEvents>;
+export type PerpsControllerOptions = {
+    messenger: PerpsControllerMessenger;
+    state?: Partial<PerpsControllerState>;
+    clientConfig?: PerpsControllerConfig;
+    /**
+     * Platform-specific dependencies (required)
+     * Provides logging, metrics, tracing, stream management, and rewards.
+     * Cross-controller communication uses the messenger pattern.
+     * Must be provided by the platform (mobile/extension) at instantiation time.
+     */
+    infrastructure: PerpsPlatformDependencies;
+};
+type BlockedRegionList = {
+    list: string[];
+    source: 'remote' | 'fallback';
+};
 /**
- * `PerpsController` manages perpetual trading functionality in MetaMask.
- *
- * This controller provides platform-agnostic perps trading capabilities.
- *
- * @example
+ * PerpsController - Protocol-agnostic perpetuals trading controller
  *
- * ``` ts
- * import { Messenger } from '@metamask/messenger';
- * import type {
- *   PerpsControllerActions,
- *   PerpsControllerEvents,
- * } from '@metamask/perps-controller';
- * import { PerpsController } from '@metamask/perps-controller';
- *
- * const rootMessenger = new Messenger<
- *   'Root',
- *   PerpsControllerActions,
- *   PerpsControllerEvents
- * >({ namespace: 'Root' });
- * const perpsControllerMessenger = new Messenger<
- *   'PerpsController',
- *   PerpsControllerActions,
- *   PerpsControllerEvents,
- *   typeof rootMessenger,
- * >({
- *   namespace: 'PerpsController',
- *   parent: rootMessenger,
- * });
- * // Instantiate the controller to register its actions on the messenger
- * new PerpsController({
- *   messenger: perpsControllerMessenger,
- * });
- *
- * const perpsControllerState = await rootMessenger.call(
- *   'PerpsController:getState',
- * );
- * ```
+ * Provides a unified interface for perpetual futures trading across multiple protocols.
+ * Features dual data flow architecture:
+ * - Trading actions use Redux for persistence and optimistic updates
+ * - Live data uses direct callbacks for maximum performance
  */
-export declare class PerpsController extends BaseController<typeof controllerName, PerpsControllerState, PerpsControllerMessenger> {
+export declare class PerpsController extends BaseController<'PerpsController', PerpsControllerState, PerpsControllerMessenger> {
+    #private;
+    protected providers: Map<PerpsProviderType, PerpsProvider>;
+    protected isInitialized: boolean;
+    protected blockedRegionList: BlockedRegionList;
+    /**
+     * Active provider instance for routing operations.
+     * When activeProvider is 'hyperliquid' or 'myx': points to specific provider directly
+     * When activeProvider is 'aggregated': points to AggregatedPerpsProvider wrapper
+     */
+    protected activeProviderInstance: PerpsProvider | null;
+    constructor({ messenger, state, clientConfig, infrastructure, }: PerpsControllerOptions);
+    /**
+     * Test-observable accessor for whether a standalone provider is cached.
+     *
+     * @returns True if a standalone provider instance exists.
+     */
+    protected hasStandaloneProvider(): boolean;
+    protected setBlockedRegionList(list: string[], source: 'remote' | 'fallback'): void;
+    /**
+     * Respond to RemoteFeatureFlagController state changes
+     * Refreshes user eligibility based on geo-blocked regions defined in remote feature flag.
+     * Uses fallback configuration when remote feature flag is undefined.
+     * Note: Initial eligibility is set in the constructor if fallback regions are provided.
+     *
+     * @param remoteFeatureFlagControllerState - State from RemoteFeatureFlagController.
+     */
+    protected refreshEligibilityOnFeatureFlagChange(remoteFeatureFlagControllerState: PerpsRemoteFeatureFlagState): void;
+    /**
+     * Initialize the PerpsController providers
+     * Must be called before using any other methods
+     * Prevents double initialization with promise caching
+     *
+     * @returns A promise that resolves when the operation completes.
+     */
+    init(): Promise<void>;
+    /**
+     * Get the currently active provider.
+     * In aggregated mode, returns AggregatedPerpsProvider which routes to underlying providers.
+     * In single provider mode, returns HyperLiquidProvider directly.
+     *
+     * @returns The active provider (aggregated wrapper or direct provider based on mode)
+     * @throws Error if provider is not initialized or reinitializing
+     */
+    getActiveProvider(): PerpsProvider;
+    /**
+     * Get the currently active provider, returning null if not available
+     * Use this method when the caller can gracefully handle a missing provider
+     * (e.g., UI components during initialization or reconnection)
+     *
+     * @returns The active provider, or null if not initialized/reinitializing
+     */
+    getActiveProviderOrNull(): PerpsProvider | null;
+    /**
+     * Place a new order
+     * Thin delegation to TradingService
+     *
+     * @param params - The operation parameters.
+     * @returns The order result with order ID and status.
+     */
+    placeOrder(params: OrderParams): Promise<OrderResult>;
+    /**
+     * Edit an existing order
+     * Thin delegation to TradingService
+     *
+     * @param params - The operation parameters.
+     * @returns The updated order result with order ID and status.
+     */
+    editOrder(params: EditOrderParams): Promise<OrderResult>;
+    /**
+     * Cancel an existing order
+     *
+     * @param params - The operation parameters.
+     * @returns The cancellation result with status.
+     */
+    cancelOrder(params: CancelOrderParams): Promise<CancelOrderResult>;
+    /**
+     * Cancel multiple orders in parallel
+     * Batch version of cancelOrder() that cancels multiple orders simultaneously
+     *
+     * @param params - The operation parameters.
+     * @returns The batch cancellation results for each order.
+     */
+    cancelOrders(params: CancelOrdersParams): Promise<CancelOrdersResult>;
+    /**
+     * Close a position (partial or full)
+     * Thin delegation to TradingService
+     *
+     * @param params - The operation parameters.
+     * @returns The order result from the close position request.
+     */
+    closePosition(params: ClosePositionParams): Promise<OrderResult>;
+    /**
+     * Close multiple positions in parallel
+     * Batch version of closePosition() that closes multiple positions simultaneously
+     *
+     * @param params - The operation parameters.
+     * @returns The batch close results for each position.
+     */
+    closePositions(params: ClosePositionsParams): Promise<ClosePositionsResult>;
+    /**
+     * Update TP/SL for an existing position
+     *
+     * @param params - The operation parameters.
+     * @returns The order result from the TP/SL update.
+     */
+    updatePositionTPSL(params: UpdatePositionTPSLParams): Promise<OrderResult>;
+    /**
+     * Update margin for an existing position (add or remove)
+     *
+     * @param params - The operation parameters.
+     * @returns The margin update result.
+     */
+    updateMargin(params: UpdateMarginParams): Promise<MarginResult>;
+    /**
+     * Flip position (reverse direction while keeping size and leverage)
+     *
+     * @param params - The operation parameters.
+     * @returns The order result from the position flip.
+     */
+    flipPosition(params: FlipPositionParams): Promise<OrderResult>;
+    /**
+     * Simplified deposit method that prepares transaction for confirmation screen
+     * No complex state tracking - just sets a loading flag
+     *
+     * @param params - Parameters for the deposit flow
+     * @param params.amount - Optional deposit amount
+     * @param params.placeOrder - If true, uses addTransaction instead of submit to avoid navigation
+     * @returns An object containing a promise that resolves to the transaction hash.
+     */
+    depositWithConfirmation(params?: DepositWithConfirmationParams): Promise<{
+        result: Promise<string>;
+    }>;
+    /**
+     * Same as depositWithConfirmation - prepares transaction for confirmation screen.
+     *
+     * @returns A promise that resolves to the string result.
+     */
+    depositWithOrder(): Promise<{
+        result: Promise<string>;
+    }>;
+    /**
+     * Clear the last deposit result after it has been shown to the user
+     */
+    clearDepositResult(): void;
+    clearWithdrawResult(): void;
+    /**
+     * Update withdrawal request status when it completes
+     * This is called when a withdrawal is matched with a completed withdrawal from the API
+     *
+     * @param withdrawalId - The withdrawal transaction ID.
+     * @param status - The current status.
+     * @param txHash - The transaction hash.
+     */
+    updateWithdrawalStatus(withdrawalId: string, status: 'completed' | 'failed', txHash?: string): void;
+    /**
+     * Update withdrawal progress (persistent across navigation)
+     *
+     * @param progress - The progress indicator.
+     * @param activeWithdrawalId - The active withdrawal ID.
+     */
+    updateWithdrawalProgress(progress: number, activeWithdrawalId?: string | null): void;
+    /**
+     * Get current withdrawal progress
+     *
+     * @returns The withdrawal progress, last update timestamp, and active withdrawal ID.
+     */
+    getWithdrawalProgress(): {
+        progress: number;
+        lastUpdated: number;
+        activeWithdrawalId: string | null;
+    };
+    /**
+     * Withdraw funds from trading account
+     *
+     * The withdrawal process varies by provider and may involve:
+     * - Direct on-chain transfers
+     * - Bridge operations
+     * - Multi-step validation processes
+     *
+     * Check the specific provider documentation for detailed withdrawal flows.
+     *
+     * @param params Withdrawal parameters
+     * @returns WithdrawResult with withdrawal ID and tracking info
+     */
+    withdraw(params: WithdrawParams): Promise<WithdrawResult>;
+    /**
+     * Get current positions
+     * Thin delegation to MarketDataService
+     *
+     * For standalone mode, bypasses getActiveProvider() to allow position queries
+     * without full perps initialization (e.g., for showing positions on token details page)
+     *
+     * @param params - The operation parameters.
+     * @returns Array of open positions for the active provider.
+     */
+    getPositions(params?: GetPositionsParams): Promise<Position[]>;
+    /**
+     * Get historical user fills (trade executions)
+     * Thin delegation to MarketDataService
+     *
+     * @param params - The operation parameters.
+     * @returns Array of historical trade executions (fills).
+     */
+    getOrderFills(params?: GetOrderFillsParams): Promise<OrderFill[]>;
+    /**
+     * Get historical user orders (order lifecycle)
+     * Thin delegation to MarketDataService
+     *
+     * @param params - The operation parameters.
+     * @returns Array of historical orders.
+     */
+    getOrders(params?: GetOrdersParams): Promise<Order[]>;
+    /**
+     * Get currently open orders (real-time status)
+     * Thin delegation to MarketDataService
+     *
+     * For standalone mode, bypasses getActiveProvider() to allow open order queries
+     * without full perps initialization (e.g., for background preloading)
+     *
+     * @param params - The operation parameters.
+     * @returns A promise that resolves to the result.
+     */
+    getOpenOrders(params?: GetOrdersParams): Promise<Order[]>;
+    /**
+     * Get historical user funding history (funding payments)
+     * Thin delegation to MarketDataService
+     *
+     * @param params - The operation parameters.
+     * @returns Array of historical funding payments.
+     */
+    getFunding(params?: GetFundingParams): Promise<Funding[]>;
+    /**
+     * Get account state (balances, etc.)
+     * Thin delegation to MarketDataService
+     *
+     * For standalone mode, bypasses getActiveProvider() to allow account state queries
+     * without full perps initialization (e.g., for checking if user has perps funds)
+     *
+     * @param params - The operation parameters.
+     * @returns A promise that resolves to the result.
+     */
+    getAccountState(params?: GetAccountStateParams): Promise<AccountState>;
+    /**
+     * Get historical portfolio data
+     * Thin delegation to MarketDataService
+     *
+     * @param params - The operation parameters.
+     * @returns The historical portfolio data points.
+     */
+    getHistoricalPortfolio(params?: GetHistoricalPortfolioParams): Promise<HistoricalPortfolioResult>;
+    /**
+     * Get available markets with optional filtering
+     * Thin delegation to MarketDataService
+     *
+     * For standalone mode, bypasses getActiveProvider() to allow market discovery
+     * without full perps initialization (e.g., for discovery banners on spot screens)
+     *
+     * @param params - The operation parameters.
+     * @returns Array of available markets matching the filter criteria.
+     */
+    getMarkets(params?: GetMarketsParams): Promise<MarketInfo[]>;
+    /**
+     * Get market data with prices (includes price, volume, 24h change)
+     *
+     * For standalone mode, bypasses getActiveProvider() to allow market data queries
+     * without full perps initialization (e.g., for background preloading on app start)
+     *
+     * @param params - The operation parameters.
+     * @param params.standalone - Whether to use standalone mode.
+     * @returns A promise that resolves to the market data.
+     */
+    getMarketDataWithPrices(params?: {
+        standalone?: boolean;
+    }): Promise<PerpsMarketData[]>;
+    /**
+     * Start background market data preloading.
+     * Fetches market data immediately and refreshes every 5 minutes.
+     * Watches for isTestnet and hip3ConfigVersion changes to re-preload.
+     */
+    startMarketDataPreload(): void;
+    /**
+     * Stop background market data preloading.
+     */
+    stopMarketDataPreload(): void;
+    /**
+     * Get list of available HIP-3 builder-deployed DEXs
+     *
+     * @param params - Optional parameters for filtering
+     * @returns Array of DEX names
+     */
+    getAvailableDexs(params?: GetAvailableDexsParams): Promise<string[]>;
+    /**
+     * Fetch historical candle data
+     * Thin delegation to MarketDataService
+     *
+     * @param options - The configuration options.
+     * @param options.symbol - The trading pair symbol.
+     * @param options.interval - The candle interval period.
+     * @param options.limit - Maximum number of items to fetch.
+     * @param options.endTime - End timestamp in milliseconds.
+     * @returns The historical candle data for the requested symbol and interval.
+     */
+    fetchHistoricalCandles(options: {
+        symbol: string;
+        interval: CandlePeriod;
+        limit?: number;
+        endTime?: number;
+    }): Promise<CandleData>;
+    /**
+     * Calculate liquidation price for a position
+     * Uses provider-specific formulas based on protocol rules
+     *
+     * @param params - The operation parameters.
+     * @returns A promise that resolves to the string result.
+     */
+    calculateLiquidationPrice(params: LiquidationPriceParams): Promise<string>;
+    /**
+     * Calculate maintenance margin for a specific asset
+     * Returns a percentage (e.g., 0.0125 for 1.25%)
+     *
+     * @param params - The operation parameters.
+     * @returns A promise that resolves to the numeric result.
+     */
+    calculateMaintenanceMargin(params: MaintenanceMarginParams): Promise<number>;
+    /**
+     * Get maximum leverage allowed for an asset
+     *
+     * @param asset - The asset identifier.
+     * @returns A promise that resolves to the numeric result.
+     */
+    getMaxLeverage(asset: string): Promise<number>;
+    /**
+     * Validate order parameters according to protocol-specific rules
+     *
+     * @param params - The operation parameters.
+     * @returns True if the condition is met.
+     */
+    validateOrder(params: OrderParams): Promise<{
+        isValid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Validate close position parameters according to protocol-specific rules
+     *
+     * @param params - The operation parameters.
+     * @returns A promise that resolves to the result.
+     */
+    validateClosePosition(params: ClosePositionParams): Promise<{
+        isValid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Validate withdrawal parameters according to protocol-specific rules
+     *
+     * @param params - The operation parameters.
+     * @returns True if the condition is met.
+     */
+    validateWithdrawal(params: WithdrawParams): Promise<{
+        isValid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get supported withdrawal routes - returns complete asset and routing information
+     *
+     * @returns Array of supported asset routes for withdrawals.
+     */
+    getWithdrawalRoutes(): AssetRoute[];
+    /**
+     * Toggle between testnet and mainnet
+     *
+     * @returns The toggle result with success status and current network mode.
+     */
+    toggleTestnet(): Promise<ToggleTestnetResult>;
+    /**
+     * Switch to a different provider
+     * Uses a full reinit approach: disconnect() → update state → init()
+     * This ensures complete state reset including WebSocket connections and caches.
+     *
+     * @param providerId - The provider identifier.
+     * @returns The switch result with success status and active provider.
+     */
+    switchProvider(providerId: PerpsActiveProviderMode): Promise<SwitchProviderResult>;
+    /**
+     * Get current network (mainnet/testnet)
+     *
+     * @returns Either 'mainnet' or 'testnet' based on the current configuration.
+     */
+    getCurrentNetwork(): 'mainnet' | 'testnet';
+    /**
+     * Get the current WebSocket connection state from the active provider.
+     * Used by the UI to monitor connection health and show notifications.
+     *
+     * @returns The current WebSocket connection state, or DISCONNECTED if not supported
+     */
+    getWebSocketConnectionState(): WebSocketConnectionState;
+    /**
+     * Subscribe to WebSocket connection state changes from the active provider.
+     * 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, or no-op if not supported
+     */
+    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>;
+    /**
+     * Subscribe to live price updates
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToPrices(params: SubscribePricesParams): () => void;
+    /**
+     * Subscribe to live position updates
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToPositions(params: SubscribePositionsParams): () => void;
+    /**
+     * Subscribe to live order fill updates
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToOrderFills(params: SubscribeOrderFillsParams): () => void;
+    /**
+     * Subscribe to live order updates
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToOrders(params: SubscribeOrdersParams): () => void;
+    /**
+     * Subscribe to live account updates.
+     * Updates controller state (Redux) when new account data arrives so consumers
+     * like usePerpsBalanceTokenFilter (PayWithModal) see the latest balance.
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToAccount(params: SubscribeAccountParams): () => void;
+    /**
+     * Subscribe to full order book updates with multiple depth levels
+     * Creates a dedicated L2Book subscription for real-time order book data
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToOrderBook(params: SubscribeOrderBookParams): () => void;
+    /**
+     * Subscribe to live candle updates
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToCandles(params: SubscribeCandlesParams): () => void;
+    /**
+     * Subscribe to open interest cap updates
+     * Zero additional network overhead - data comes from existing webData3 subscription
+     *
+     * @param params - The operation parameters.
+     * @returns A cleanup function to remove the subscription.
+     */
+    subscribeToOICaps(params: SubscribeOICapsParams): () => void;
+    /**
+     * Configure live data throttling
+     *
+     * @param config - The configuration object.
+     */
+    setLiveDataConfig(config: Partial<LiveDataConfig>): void;
+    /**
+     * Calculate trading fees for the active provider
+     * Each provider implements its own fee structure
+     *
+     * @param params - The operation parameters.
+     * @returns The fee calculation result for the trade.
+     */
+    calculateFees(params: FeeCalculationParams): Promise<FeeCalculationResult>;
+    /**
+     * Disconnect provider and cleanup subscriptions
+     * Call this when navigating away from Perps screens to prevent battery drain
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Eligibility (Geo-Blocking)
+     */
+    /**
+     * Fetch geo location
+     *
+     * Returned in Country or Country-Region format
+     * Example: FR, DE, US-MI, CA-ON
+     */
+    /**
+     * Refresh eligibility status
+     */
+    refreshEligibility(): Promise<void>;
+    /**
+     * 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;
+    /**
+     * Check if user is first-time for the current network
+     *
+     * @returns True if the condition is met.
+     */
+    isFirstTimeUserOnCurrentNetwork(): boolean;
+    /**
+     * Mark that the user has completed the tutorial/onboarding
+     * This prevents the tutorial from showing again
+     */
+    markTutorialCompleted(): void;
+    markFirstOrderCompleted(): void;
+    /**
+     * Reset first-time user state for both networks
+     * This is useful for testing the tutorial flow
+     * Called by Reset Account feature in settings
+     */
+    resetFirstTimeUserState(): void;
+    /**
+     * Clear pending/bridging withdrawal and deposit requests
+     * This is useful when users want to clear stuck pending indicators
+     * Called by Reset Account feature in settings
+     */
+    clearPendingTransactionRequests(): void;
+    /**
+     * Get saved trade configuration for a market
+     *
+     * @param symbol - The trading pair symbol.
+     * @returns The resulting string value.
+     */
+    getTradeConfiguration(symbol: string): {
+        leverage?: number;
+    } | undefined;
+    /**
+     * Save trade configuration for a market
+     *
+     * @param symbol - Market symbol
+     * @param leverage - Leverage value
+     */
+    saveTradeConfiguration(symbol: string, leverage: number): void;
+    /**
+     * Save pending trade configuration for a market
+     * This is a temporary configuration that expires after 5 minutes
+     *
+     * @param symbol - Market symbol
+     * @param config - Pending trade configuration (includes optional selected payment token from Pay row)
+     * @param config.amount - The amount value.
+     * @param config.leverage - The leverage multiplier.
+     * @param config.takeProfitPrice - The take profit price.
+     * @param config.stopLossPrice - The stop loss price.
+     * @param config.limitPrice - The limit price.
+     * @param config.orderType - The order type.
+     * @param config.selectedPaymentToken - The selected payment token.
+     */
+    savePendingTradeConfiguration(symbol: string, config: {
+        amount?: string;
+        leverage?: number;
+        takeProfitPrice?: string;
+        stopLossPrice?: string;
+        limitPrice?: string;
+        orderType?: OrderType;
+        /** When user used pay-with-token in PerpsPayRow: minimal token shape to restore selection */
+        selectedPaymentToken?: PerpsSelectedPaymentToken | null;
+    }): void;
+    /**
+     * Get pending trade configuration for a market
+     * Returns undefined if config doesn't exist or has expired (more than 5 minutes old)
+     *
+     * @param symbol - Market symbol
+     * @returns Pending trade configuration or undefined
+     */
+    getPendingTradeConfiguration(symbol: string): {
+        amount?: string;
+        leverage?: number;
+        takeProfitPrice?: string;
+        stopLossPrice?: string;
+        limitPrice?: string;
+        orderType?: OrderType;
+        selectedPaymentToken?: PerpsSelectedPaymentToken | null;
+    } | undefined;
+    /**
+     * Clear pending trade configuration for a market
+     *
+     * @param symbol - Market symbol
+     */
+    clearPendingTradeConfiguration(symbol: string): void;
+    /**
+     * Get saved market filter preferences
+     * Handles backward compatibility with legacy string format
+     *
+     * @returns The saved sort option ID and direction.
+     */
+    getMarketFilterPreferences(): {
+        optionId: SortOptionId;
+        direction: SortDirection;
+    };
+    /**
+     * Save market filter preferences
+     *
+     * @param optionId - Sort/filter option ID
+     * @param direction - Sort direction ('asc' or 'desc')
+     */
+    saveMarketFilterPreferences(optionId: SortOptionId, direction: SortDirection): void;
+    /**
+     * Set the selected payment token for the Perps order/deposit flow.
+     * Pass null or a token with description PERPS_CONSTANTS.PerpsBalanceTokenDescription to select Perps balance.
+     * Only required fields (address, chainId) are stored in state; description and symbol are optional.
+     *
+     * @param token - The token identifier.
+     */
+    setSelectedPaymentToken(token: PerpsSelectedPaymentToken | null): void;
+    /**
+     * Reset the selected payment token to Perps balance (null).
+     * Call when leaving the Perps order view so the next visit defaults to Perps balance.
+     */
+    resetSelectedPaymentToken(): void;
+    /**
+     * Get saved order book grouping for a market
+     *
+     * @param symbol - Market symbol
+     * @returns The saved grouping value or undefined if not set
+     */
+    getOrderBookGrouping(symbol: string): number | undefined;
+    /**
+     * Save order book grouping for a market
+     *
+     * @param symbol - Market symbol
+     * @param grouping - Price grouping value
+     */
+    saveOrderBookGrouping(symbol: string, grouping: number): void;
+    /**
+     * Toggle watchlist status for a market
+     * Watchlist markets are stored per network (testnet/mainnet)
+     *
+     * @param symbol - The trading pair symbol.
+     */
+    toggleWatchlistMarket(symbol: string): void;
+    /**
+     * Check if a market is in the watchlist on the current network
+     *
+     * @param symbol - The trading pair symbol.
+     * @returns True if the condition is met.
+     */
+    isWatchlistMarket(symbol: string): boolean;
+    /**
+     * Get all watchlist markets for the current network
+     *
+     * @returns The resulting string value.
+     */
+    getWatchlistMarkets(): string[];
+    /**
+     * Report order events to data lake API with retry (non-blocking)
+     * Thin delegation to DataLakeService
+     *
+     * @param params - The operation parameters.
+     * @param params.action - The order action.
+     * @param params.symbol - The trading pair symbol.
+     * @param params.slPrice - The stop loss price.
+     * @param params.tpPrice - The take profit price.
+     * @param params.retryCount - Internal retry counter.
+     * @param params._traceId - Internal trace ID.
+     * @returns Whether the report was sent successfully, with an optional error message.
+     */
+    protected reportOrderToDataLake(params: {
+        action: 'open' | 'close';
+        symbol: string;
+        slPrice?: number;
+        tpPrice?: number;
+        retryCount?: number;
+        _traceId?: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     /**
-     * Constructs a new {@link PerpsController}.
+     * Check if the controller is currently reinitializing
      *
-     * @param args - The arguments to this controller.
-     * @param args.messenger - The messenger suited for this controller.
-     * @param args.state - The desired state with which to initialize this
-     * controller. Missing properties will be filled in with defaults.
+     * @returns true if providers are being reinitialized
      */
-    constructor({ messenger, state, }: {
-        messenger: PerpsControllerMessenger;
-        state?: Partial<PerpsControllerState>;
-    });
+    isCurrentlyReinitializing(): boolean;
 }
-export {};
 //# sourceMappingURL=PerpsController.d.cts.map