@metamask-previews/perps-controller 0.0.0-preview-ae46ab603 → 0.0.0-preview-e4aa1532

package/dist/PerpsController.d.cts

@@ -1,107 +1,961 @@
-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 { NetworkControllerGetStateAction } from "@metamask/network-controller";
+import type { AuthenticationController } from "@metamask/profile-sync-controller";
+import type { RemoteFeatureFlagControllerState, RemoteFeatureFlagControllerStateChangeEvent, RemoteFeatureFlagControllerGetStateAction } from "@metamask/remote-feature-flag-controller";
+import { TransactionControllerTransactionConfirmedEvent, TransactionControllerTransactionFailedEvent, TransactionControllerTransactionSubmittedEvent } from "@metamask/transaction-controller";
+import type { SortOptionId } from "./constants/perpsConfig.cjs";
+import { WebSocketConnectionState } from "./types/index.cjs";
+import type { CandleData } from "./types/index.cjs";
+import type { AccountState, AssetRoute, CancelOrderParams, CancelOrderResult, CancelOrdersParams, CancelOrdersResult, ClosePositionParams, ClosePositionsParams, ClosePositionsResult, EditOrderParams, FeeCalculationParams, FeeCalculationResult, FlipPositionParams, Funding, GetAccountStateParams, GetAvailableDexsParams, GetFundingParams, GetMarketsParams, GetOrderFillsParams, GetOrdersParams, GetPositionsParams, PerpsProvider, LiquidationPriceParams, LiveDataConfig, MaintenanceMarginParams, MarginResult, MarketInfo, Order, OrderFill, OrderParams, OrderResult, PerpsControllerConfig, Position, SubscribeAccountParams, SubscribeCandlesParams, SubscribeOICapsParams, SubscribeOrderBookParams, SubscribeOrderFillsParams, SubscribeOrdersParams, SubscribePositionsParams, SubscribePricesParams, SwitchProviderResult, ToggleTestnetResult, UpdateMarginParams, UpdatePositionTPSLParams, WithdrawParams, WithdrawResult, GetHistoricalPortfolioParams, HistoricalPortfolioResult, OrderType, PerpsPlatformDependencies, PerpsActiveProviderMode, PerpsProviderType } from "./types/index.cjs";
+import { CandlePeriod } from "./types/chart.cjs";
+import type { LastTransactionResult, TransactionStatus } from "./types/transactionTypes.cjs";
+import type { SortDirection } from "./utils/sortMarkets.cjs";
+export { PERPS_ERROR_CODES, type PerpsErrorCode, } from "./constants/perpsErrorCodes.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.
+ * Initialization state enum for state machine tracking
  */
-export declare const controllerName = "PerpsController";
+export declare enum InitializationState {
+    Uninitialized = "uninitialized",
+    Initializing = "initializing",
+    Initialized = "initialized",
+    Failed = "failed"
+}
 /**
- * Describes the shape of the state object for {@link PerpsController}.
+ * State shape for PerpsController
  */
-export type PerpsControllerState = {};
+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;
+};
 /**
- * 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.
+ * Get default PerpsController state
  *
- * @returns The default {@link PerpsController} state.
- */
-export declare function getDefaultPerpsControllerState(): PerpsControllerState;
-/**
- * Retrieves the state of the {@link PerpsController}.
+ * 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)
  */
-export type PerpsControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PerpsControllerState>;
+export declare const getDefaultPerpsControllerState: () => PerpsControllerState;
 /**
- * Actions that {@link PerpsControllerMessenger} exposes to other consumers.
+ * PerpsController events
  */
-export type PerpsControllerActions = PerpsControllerGetStateAction;
+export type PerpsControllerEvents = ControllerStateChangeEvent<'PerpsController', PerpsControllerState>;
 /**
- * Actions from other messengers that {@link PerpsControllerMessenger} calls.
+ * PerpsController actions
  */
-type AllowedActions = never;
+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'];
+};
 /**
- * Published when the state of {@link PerpsController} changes.
+ * External actions the PerpsController can call
  */
-export type PerpsControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, PerpsControllerState>;
+export type AllowedActions = NetworkControllerGetStateAction | AuthenticationController.AuthenticationControllerGetBearerToken | RemoteFeatureFlagControllerGetStateAction;
 /**
- * Events that {@link PerpsControllerMessenger} exposes to other consumers.
+ * External events the PerpsController can subscribe to
  */
-export type PerpsControllerEvents = PerpsControllerStateChangeEvent;
+export type AllowedEvents = TransactionControllerTransactionSubmittedEvent | TransactionControllerTransactionConfirmedEvent | TransactionControllerTransactionFailedEvent | RemoteFeatureFlagControllerStateChangeEvent;
 /**
- * Events from other messengers that {@link PerpsControllerMessenger} subscribes
- * to.
+ * PerpsController messenger constraints
  */
-type AllowedEvents = never;
+export type PerpsControllerMessenger = Messenger<'PerpsController', PerpsControllerActions | AllowedActions, PerpsControllerEvents | AllowedEvents>;
 /**
- * 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 account utilities.
+     * 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
- *
- * ``` ts
- * import { Messenger } from '@metamask/messenger';
- * import type {
- *   PerpsControllerActions,
- *   PerpsControllerEvents,
- * } from '@metamask/perps-controller';
- * import { PerpsController } from '@metamask/perps-controller';
+ * PerpsController - Protocol-agnostic perpetuals trading 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> {
+    protected providers: Map<PerpsProviderType, PerpsProvider>;
+    protected isInitialized: boolean;
+    private initializationPromise;
+    private isReinitializing;
+    protected blockedRegionList: BlockedRegionList;
+    /**
+     * Version counter for blocked region list.
+     * Used to prevent race conditions where stale eligibility checks
+     * (started with fallback config) overwrite results from newer checks
+     * (started with remote config).
+     */
+    private blockedRegionListVersion;
+    private hip3Enabled;
+    private hip3AllowlistMarkets;
+    private hip3BlocklistMarkets;
+    private hip3ConfigSource;
+    /**
+     * 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;
+    private readonly options;
+    private readonly tradingService;
+    private readonly marketDataService;
+    private readonly accountService;
+    private readonly eligibilityService;
+    private readonly dataLakeService;
+    private readonly depositService;
+    private readonly featureFlagConfigurationService;
+    private readonly rewardsIntegrationService;
+    constructor({ messenger, state, clientConfig, infrastructure, }: PerpsControllerOptions);
+    /**
+     * Log an error using injected infrastructure logger
+     *
+     * @param error
+     * @param options
+     */
+    private logError;
+    /**
+     * Log debug message using injected infrastructure debugLogger
+     *
+     * @param args
+     */
+    private debugLog;
+    /**
+     * Debug method for validating Core integration.
+     * Logs via injected debugLogger and returns debug info.
+     *
+     * @returns Debug information object
+     */
+    debug(): {
+        timestamp: string;
+        source: string;
+        message: string;
+    };
+    /**
+     * Get metrics instance from platform dependencies
+     */
+    private getMetrics;
+    /**
+     * Clean up old withdrawal/deposit requests that don't have accountAddress
+     * These are from before the accountAddress field was added and can't be displayed
+     * in the UI (which filters by account), so we discard them
+     */
+    private migrateRequestsIfNeeded;
+    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
+     */
+    protected refreshEligibilityOnFeatureFlagChange(remoteFeatureFlagControllerState: RemoteFeatureFlagControllerState): void;
+    /**
+     * Execute an operation while temporarily pausing specified stream channels
+     * to prevent WebSocket updates from triggering UI re-renders during operations.
+     *
+     * WebSocket connections remain alive but updates are not emitted to subscribers.
+     * This prevents race conditions where UI re-renders fetch stale data during operations.
+     *
+     * @param operation - The async operation to execute
+     * @param channels - Array of stream channel names to pause
+     * @returns The result of the operation
+     *
+     * @example
+     * ```typescript
+     * // Cancel orders without stream interference
+     * await this.withStreamPause(
+     *   async () => this.provider.cancelOrders({ cancelAll: true }),
+     *   ['orders']
+     * );
+     *
+     * // Close positions and pause multiple streams
+     * await this.withStreamPause(
+     *   async () => this.provider.closePositions(positions),
+     *   ['positions', 'account', 'orders']
+     * );
+     * ```
+     */
+    private withStreamPause;
+    /**
+     * Initialize the PerpsController providers
+     * Must be called before using any other methods
+     * Prevents double initialization with promise caching
+     */
+    init(): Promise<void>;
+    /**
+     * Actual initialization implementation with retry logic
+     */
+    private performInitialization;
+    /**
+     * Generate standard error context for Logger.error calls 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 PerpsLoggerOptions with tags (searchable) and context (searchable)
+     * @private
+     *
+     * @example
+     * this.logError(error, this.getErrorContext('placeOrder', { symbol: 'BTC', operation: 'validate' }));
+     * // Creates searchable tags: feature:perps, provider:hyperliquid, network:mainnet
+     * // Creates searchable context: perps_controller.method:placeOrder, perps_controller.symbol:BTC, perps_controller.operation:validate
+     */
+    private getErrorContext;
+    /**
+     * Create a ServiceContext for dependency injection into services
+     * Provides all orchestration dependencies (tracing, analytics, state management)
+     *
+     * @param method - Method name for error context
+     * @param additionalContext - Optional additional context (e.g., rewardsController, streamManager)
+     * @returns ServiceContext with all required dependencies
+     */
+    private createServiceContext;
+    /**
+     * Ensure TradingService has controller dependencies set.
+     * Uses injectable dependencies from infrastructure for core migration compatibility.
+     */
+    private ensureTradingServiceDeps;
+    /**
+     * 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
+     */
+    placeOrder(params: OrderParams): Promise<OrderResult>;
+    /**
+     * Edit an existing order
+     * Thin delegation to TradingService
+     *
+     * @param params
+     */
+    editOrder(params: EditOrderParams): Promise<OrderResult>;
+    /**
+     * Cancel an existing order
+     *
+     * @param params
+     */
+    cancelOrder(params: CancelOrderParams): Promise<CancelOrderResult>;
+    /**
+     * Cancel multiple orders in parallel
+     * Batch version of cancelOrder() that cancels multiple orders simultaneously
+     *
+     * @param params
+     */
+    cancelOrders(params: CancelOrdersParams): Promise<CancelOrdersResult>;
+    /**
+     * Close a position (partial or full)
+     * Thin delegation to TradingService
+     *
+     * @param params
+     */
+    closePosition(params: ClosePositionParams): Promise<OrderResult>;
+    /**
+     * Close multiple positions in parallel
+     * Batch version of closePosition() that closes multiple positions simultaneously
+     *
+     * @param params
+     */
+    closePositions(params: ClosePositionsParams): Promise<ClosePositionsResult>;
+    /**
+     * Update TP/SL for an existing position
+     *
+     * @param params
+     */
+    updatePositionTPSL(params: UpdatePositionTPSLParams): Promise<OrderResult>;
+    /**
+     * Update margin for an existing position (add or remove)
+     *
+     * @param params
+     */
+    updateMargin(params: UpdateMarginParams): Promise<MarginResult>;
+    /**
+     * Flip position (reverse direction while keeping size and leverage)
+     *
+     * @param params
+     */
+    flipPosition(params: FlipPositionParams): Promise<OrderResult>;
+    /**
+     * Simplified deposit method that prepares transaction for confirmation screen
+     * No complex state tracking - just sets a loading flag
+     *
+     * @param amount
+     */
+    depositWithConfirmation(amount?: string): 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
+     * @param status
+     * @param txHash
+     */
+    updateWithdrawalStatus(withdrawalId: string, status: 'completed' | 'failed', txHash?: string): void;
+    /**
+     * Update withdrawal progress (persistent across navigation)
+     *
+     * @param progress
+     * @param activeWithdrawalId
+     */
+    updateWithdrawalProgress(progress: number, activeWithdrawalId?: string | null): void;
+    /**
+     * Get current withdrawal progress
+     */
+    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
+     *
+     * @param params
+     */
+    getPositions(params?: GetPositionsParams): Promise<Position[]>;
+    /**
+     * Get historical user fills (trade executions)
+     * Thin delegation to MarketDataService
+     *
+     * @param params
+     */
+    getOrderFills(params?: GetOrderFillsParams): Promise<OrderFill[]>;
+    /**
+     * Get historical user orders (order lifecycle)
+     * Thin delegation to MarketDataService
+     *
+     * @param params
+     */
+    getOrders(params?: GetOrdersParams): Promise<Order[]>;
+    /**
+     * Get currently open orders (real-time status)
+     * Thin delegation to MarketDataService
+     *
+     * @param params
+     */
+    getOpenOrders(params?: GetOrdersParams): Promise<Order[]>;
+    /**
+     * Get historical user funding history (funding payments)
+     * Thin delegation to MarketDataService
+     *
+     * @param params
+     */
+    getFunding(params?: GetFundingParams): Promise<Funding[]>;
+    /**
+     * Get account state (balances, etc.)
+     * Thin delegation to MarketDataService
+     *
+     * @param params
+     */
+    getAccountState(params?: GetAccountStateParams): Promise<AccountState>;
+    /**
+     * Get historical portfolio data
+     * Thin delegation to MarketDataService
+     *
+     * @param params
+     */
+    getHistoricalPortfolio(params?: GetHistoricalPortfolioParams): Promise<HistoricalPortfolioResult>;
+    /**
+     * Get available markets with optional filtering
+     * Thin delegation to MarketDataService
+     *
+     * For readOnly mode, bypasses getActiveProvider() to allow market discovery
+     * without full perps initialization (e.g., for discovery banners on spot screens)
+     *
+     * @param params
+     */
+    getMarkets(params?: GetMarketsParams): Promise<MarketInfo[]>;
+    /**
+     * 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 symbol
+     * @param interval
+     * @param limit
+     * @param endTime
+     */
+    fetchHistoricalCandles(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
+     */
+    calculateLiquidationPrice(params: LiquidationPriceParams): Promise<string>;
+    /**
+     * Calculate maintenance margin for a specific asset
+     * Returns a percentage (e.g., 0.0125 for 1.25%)
+     *
+     * @param params
+     */
+    calculateMaintenanceMargin(params: MaintenanceMarginParams): Promise<number>;
+    /**
+     * Get maximum leverage allowed for an asset
+     *
+     * @param asset
+     */
+    getMaxLeverage(asset: string): Promise<number>;
+    /**
+     * Validate order parameters according to protocol-specific rules
+     *
+     * @param params
+     */
+    validateOrder(params: OrderParams): Promise<{
+        isValid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Validate close position parameters according to protocol-specific rules
+     *
+     * @param params
+     */
+    validateClosePosition(params: ClosePositionParams): Promise<{
+        isValid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Validate withdrawal parameters according to protocol-specific rules
+     *
+     * @param params
+     */
+    validateWithdrawal(params: WithdrawParams): Promise<{
+        isValid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get supported withdrawal routes - returns complete asset and routing information
+     */
+    getWithdrawalRoutes(): AssetRoute[];
+    /**
+     * Toggle between testnet and mainnet
+     */
+    toggleTestnet(): Promise<ToggleTestnetResult>;
+    /**
+     * Switch to a different provider
+     *
+     * @param providerId
+     */
+    switchProvider(providerId: PerpsActiveProviderMode): Promise<SwitchProviderResult>;
+    /**
+     * Get current network (mainnet/testnet)
+     */
+    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
+     */
+    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 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;
+    /**
+     * Subscribe to open interest cap updates
+     * Zero additional network overhead - data comes from existing webData3 subscription
+     *
+     * @param params
+     */
+    subscribeToOICaps(params: SubscribeOICapsParams): () => void;
+    /**
+     * Configure live data throttling
+     *
+     * @param config
+     */
+    setLiveDataConfig(config: Partial<LiveDataConfig>): void;
+    /**
+     * Calculate trading fees for the active provider
+     * Each provider implements its own fee structure
+     *
+     * @param params
+     */
+    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
+     */
+    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
+     */
+    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
+     * @param config.amount
+     * @param config.leverage
+     * @param config.takeProfitPrice
+     * @param config.stopLossPrice
+     * @param config.limitPrice
+     * @param config.orderType
+     */
+    savePendingTradeConfiguration(symbol: string, config: {
+        amount?: string;
+        leverage?: number;
+        takeProfitPrice?: string;
+        stopLossPrice?: string;
+        limitPrice?: string;
+        orderType?: OrderType;
+    }): 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;
+    } | 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
+     */
+    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;
+    /**
+     * 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
+     */
+    toggleWatchlistMarket(symbol: string): void;
+    /**
+     * Check if a market is in the watchlist on the current network
+     *
+     * @param symbol
+     */
+    isWatchlistMarket(symbol: string): boolean;
+    /**
+     * Get all watchlist markets for the current network
+     */
+    getWatchlistMarkets(): string[];
+    /**
+     * Report order events to data lake API with retry (non-blocking)
+     * Thin delegation to DataLakeService
+     *
+     * @param params
+     * @param params.action
+     * @param params.symbol
+     * @param params.sl_price
+     * @param params.tp_price
+     * @param params.retryCount
+     * @param params._traceId
+     */
+    protected reportOrderToDataLake(params: {
+        action: 'open' | 'close';
+        symbol: string;
+        sl_price?: number;
+        tp_price?: 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