@metamask-previews/perps-controller 0.0.0-preview-b0148922a → 0.0.0-preview-ee1fa5d01

package/dist/PerpsController.d.cts

@@ -1,994 +1,107 @@
-import { BaseController, ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
+import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
+import { BaseController } 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";
 /**
- * Minimal payment token stored in PerpsController state.
- * Only required fields for identification, Perps balance detection, and analytics.
+ * 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.
  */
-export type SelectedPaymentTokenSnapshot = {
-    description?: string;
-    address: string;
-    chainId: string;
-    symbol?: string;
-};
-export { PERPS_ERROR_CODES, type PerpsErrorCode } from "./perpsErrorCodes.cjs";
+export declare const controllerName = "PerpsController";
 /**
- * Initialization state enum for state machine tracking
+ * Describes the shape of the state object for {@link PerpsController}.
  */
-export declare enum InitializationState {
-    Uninitialized = "uninitialized",
-    Initializing = "initializing",
-    Initialized = "initialized",
-    Failed = "failed"
-}
+export type PerpsControllerState = {};
 /**
- * State shape for PerpsController
+ * 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 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;
-};
+export declare function getDefaultPerpsControllerState(): PerpsControllerState;
 /**
- * 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.
+ * Retrieves the state of the {@link PerpsController}.
  */
-export declare const getDefaultPerpsControllerState: () => PerpsControllerState;
+export type PerpsControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PerpsControllerState>;
 /**
- * PerpsController events
+ * Actions that {@link PerpsControllerMessenger} exposes to other consumers.
  */
-export type PerpsControllerEvents = ControllerStateChangeEvent<'PerpsController', PerpsControllerState>;
+export type PerpsControllerActions = PerpsControllerGetStateAction;
 /**
- * PerpsController actions
+ * Actions from other messengers that {@link PerpsControllerMessenger} calls.
  */
-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'];
-};
+type AllowedActions = never;
 /**
- * PerpsController messenger constraints.
- * Includes both PerpsController's own actions/events and
- * allowed actions/events from external controllers.
+ * Published when the state of {@link PerpsController} changes.
  */
-export type PerpsControllerMessenger = Messenger<'PerpsController', PerpsControllerActions | PerpsControllerAllowedActions, PerpsControllerEvents | PerpsControllerAllowedEvents>;
+export type PerpsControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PerpsControllerState>;
 /**
- * PerpsController options
+ * Events that {@link PerpsControllerMessenger} exposes to other consumers.
  */
-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';
-};
+export type PerpsControllerEvents = PerpsControllerStateChangeEvent;
+/**
+ * Events from other messengers that {@link PerpsControllerMessenger} subscribes
+ * to.
+ */
+type AllowedEvents = never;
 /**
- * PerpsController - Protocol-agnostic perpetuals trading controller
+ * The messenger restricted to actions and events accessed by
+ * {@link PerpsController}.
+ */
+export type PerpsControllerMessenger = Messenger<typeof controllerName, PerpsControllerActions | AllowedActions, PerpsControllerEvents | AllowedEvents>;
+/**
+ * `PerpsController` manages perpetual trading functionality in MetaMask.
+ *
+ * This controller provides platform-agnostic perps trading capabilities.
+ *
+ * @example
  *
- * 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
+ * ``` 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',
+ * );
+ * ```
  */
-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;
-    }>;
+export declare class PerpsController extends BaseController<typeof controllerName, PerpsControllerState, PerpsControllerMessenger> {
     /**
-     * Check if the controller is currently reinitializing
+     * Constructs a new {@link PerpsController}.
      *
-     * @returns true if providers are being reinitialized
+     * @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.
      */
-    isCurrentlyReinitializing(): boolean;
+    constructor({ messenger, state, }: {
+        messenger: PerpsControllerMessenger;
+        state?: Partial<PerpsControllerState>;
+    });
 }
+export {};
 //# sourceMappingURL=PerpsController.d.cts.map