PerpsController.ts

import {
  BaseController,
  ControllerGetStateAction,
  ControllerStateChangeEvent,
  StateMetadata,
} from '@metamask/base-controller';
import type { StateChangeListener } from '@metamask/base-controller';
import { ORIGIN_METAMASK } from '@metamask/controller-utils';
import type { Messenger } from '@metamask/messenger';
import type { Json } from '@metamask/utils';
import { v4 as uuidv4 } from 'uuid';

import { CandlePeriod } from './constants/chartConfig';
import {
  PERPS_EVENT_PROPERTY,
  PERPS_EVENT_VALUE,
} from './constants/eventNames';
import { USDC_SYMBOL } from './constants/hyperLiquidConfig';
import { PerpsMeasurementName } from './constants/performanceMetrics';
import {
  PERPS_CONSTANTS,
  MARKET_SORTING_CONFIG,
  PROVIDER_CONFIG,
  PERPS_DISK_CACHE_MARKETS,
  PERPS_DISK_CACHE_USER_DATA,
  buildProviderCacheKey,
} from './constants/perpsConfig';
import type { SortOptionId } from './constants/perpsConfig';
import type { PerpsControllerMethodActions } from './PerpsController-method-action-types';
import { PERPS_ERROR_CODES } from './perpsErrorCodes';
import { AggregatedPerpsProvider } from './providers/AggregatedPerpsProvider';
import { HyperLiquidProvider } from './providers/HyperLiquidProvider';
import { AccountService } from './services/AccountService';
import { DataLakeService } from './services/DataLakeService';
import { DepositService } from './services/DepositService';
import { EligibilityService } from './services/EligibilityService';
import { FeatureFlagConfigurationService } from './services/FeatureFlagConfigurationService';
import { MarketDataService } from './services/MarketDataService';
import { RewardsIntegrationService } from './services/RewardsIntegrationService';
import type { ServiceContext } from './services/ServiceContext';
import { TradingService } from './services/TradingService';
// PerpsStreamChannelKey removed: using string for channel keys (PerpsStreamManager.pauseChannel takes string)
import {
  WebSocketConnectionState,
  PerpsAnalyticsEvent,
  PerpsTraceNames,
  PerpsTraceOperations,
  isVersionGatedFeatureFlag,
  // Platform dependencies interface for core migration (bundles all platform-specific deps)
} from './types';
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,
  PerpsLogger,
  PerpsActiveProviderMode,
  PerpsProviderType,
  PerpsSelectedPaymentToken,
  PerpsRemoteFeatureFlagState,
  PerpsTransactionParams,
  PerpsAddTransactionOptions,
  MYXCredentials,
} from './types';
import type {
  PerpsControllerAllowedActions,
  PerpsControllerAllowedEvents,
} from './types/messenger';
import type { CandleData } from './types/perps-types';
import {
  LastTransactionResult,
  TransactionStatus,
} from './types/transactionTypes';
import { getSelectedEvmAccountFromMessenger } from './utils/accountUtils';
import { ensureError } from './utils/errorUtils';
import {
  hydrateFromDiskSync,
  persistMarketEntriesToDisk,
  persistUserEntriesToDisk,
} from './utils/perpsDiskPersistence';
import type { SortDirection } from './utils/sortMarkets';
import { wait } from './utils/wait';

/** Derived type for logger options from PerpsLogger interface */
type PerpsLoggerOptions = Parameters<PerpsLogger['error']>[1];

/**
 * Returns the first non-empty string from the given values.
 * Env vars default to '' (not null/undefined), so ?? wouldn't fall through.
 *
 * @param vals - String values to check in order.
 * @returns The first non-empty string, or '' if all are empty/undefined.
 */
export function firstNonEmpty(...vals: (string | undefined)[]): string {
  return (
    vals.find((val) => val !== null && val !== undefined && val !== '') ?? ''
  );
}

/**
 * Resolves MYX auth config from provider credentials, handling
 * testnet/mainnet fallback logic.
 *
 * @param myx - MYX provider credentials.
 * @param isTestnet - Whether the controller is in testnet mode.
 * @returns Resolved appId, apiSecret, and brokerAddress.
 */
export function resolveMyxAuthConfig(
  myx: MYXCredentials,
  isTestnet: boolean,
): { appId: string; apiSecret: string; brokerAddress: string } {
  return {
    appId: isTestnet
      ? (myx.appIdTestnet ?? '')
      : firstNonEmpty(myx.appIdMainnet, myx.appIdTestnet),
    apiSecret: isTestnet
      ? (myx.apiSecretTestnet ?? '')
      : firstNonEmpty(myx.apiSecretMainnet, myx.apiSecretTestnet),
    brokerAddress: isTestnet
      ? (myx.brokerAddressTestnet ?? '')
      : firstNonEmpty(myx.brokerAddressMainnet, myx.brokerAddressTestnet),
  };
}

// PaymentToken: minimal interface for deposit flow (replaces mobile-only AssetType)

/**
 * Minimal payment token stored in PerpsController state.
 * Only required fields for identification, Perps balance detection, and analytics.
 */
export type SelectedPaymentTokenSnapshot = {
  description?: string;
  address: string;
  chainId: string;
  symbol?: string;
};

// Re-export error codes from separate file to avoid circular dependencies
export { PERPS_ERROR_CODES, type PerpsErrorCode } from './perpsErrorCodes';

/**
 * Initialization state enum for state machine tracking
 */
export enum InitializationState {
  Uninitialized = 'uninitialized',
  Initializing = 'initializing',
  Initialized = 'initialized',
  Failed = 'failed',
}

/**
 * State shape for PerpsController
 */
export type PerpsControllerState = {
  // Active provider
  activeProvider: PerpsActiveProviderMode;
  isTestnet: boolean; // Dev toggle for testnet

  // Initialization state machine
  initializationState: InitializationState;
  initializationError: string | null;
  initializationAttempts: number;

  // Account data (persisted) - using HyperLiquid property names
  accountState: AccountState | null;

  // Perps balances per provider for portfolio display (historical data)
  perpsBalances: {
    [provider: string]: {
      totalBalance: string; // Current total account value (cash + positions) in USD
      unrealizedPnl: string; // Current P&L from open positions in USD
      accountValue1dAgo: string; // Account value 24h ago for daily change calculation in USD
      lastUpdated: number; // Timestamp of last update
    };
  };

  // Simple deposit state (transient, for UI feedback)
  depositInProgress: boolean;
  // Internal transaction id for the deposit transaction
  // We use this to fetch the bridge quotes and get the estimated time.
  lastDepositTransactionId: string | null;
  lastDepositResult: LastTransactionResult | null;

  // Simple withdrawal state (transient, for UI feedback)
  // Note: withdrawInProgress is now derived from withdrawalRequests having pending/bridging entries
  withdrawInProgress: boolean;
  lastWithdrawResult: LastTransactionResult | null;

  // FIFO guard for withdrawal completion matching.
  // Timestamp is persisted — survives app restarts so the hook skips
  // already-processed history entries even after relaunch.
  // TxHashes array is NOT persisted — it tracks completions within a
  // single session to prevent re-matching (direct completions,
  // same-millisecond API completions). Resets naturally on app restart;
  // the timestamp guard provides cross-restart protection.
  lastCompletedWithdrawalTimestamp: number | null;
  lastCompletedWithdrawalTxHashes: string[];

  // Withdrawal request tracking (persistent, for transaction history)
  withdrawalRequests: {
    id: string;
    amount: string;
    asset: string;
    accountAddress: string; // Account that initiated this withdrawal
    txHash?: string;
    timestamp: number;
    success: boolean;
    status: TransactionStatus;
    destination?: string;
    source?: string;
    transactionId?: string;
    withdrawalId?: string;
    depositId?: string;
  }[];

  // Withdrawal progress tracking (persistent across navigation)
  withdrawalProgress: {
    progress: number; // 0-100
    lastUpdated: number; // timestamp
    activeWithdrawalId: string | null; // ID of the withdrawal being tracked
  };

  // Deposit request tracking (persistent, for transaction history)
  depositRequests: {
    id: string;
    amount: string;
    asset: string;
    accountAddress: string; // Account that initiated this deposit
    txHash?: string;
    timestamp: number;
    success: boolean;
    status: TransactionStatus;
    destination?: string;
    source?: string;
    transactionId?: string;
    withdrawalId?: string;
    depositId?: string;
  }[];

  // Eligibility (Geo-Blocking)
  isEligible: boolean;

  // Tutorial/First time user tracking (per network)
  isFirstTimeUser: {
    testnet: boolean;
    mainnet: boolean;
  };

  // Notification tracking
  hasPlacedFirstOrder: {
    testnet: boolean;
    mainnet: boolean;
  };

  // Watchlist markets tracking (per network)
  watchlistMarkets: {
    testnet: string[]; // Array of watchlist market symbols for testnet
    mainnet: string[]; // Array of watchlist market symbols for mainnet
  };

  // Trade configurations per market (per network)
  tradeConfigurations: {
    testnet: {
      [marketSymbol: string]: {
        leverage?: number; // Last used leverage for this market
        orderBookGrouping?: number; // Persisted price grouping for order book
        // Pending trade configuration (temporary, expires after 5 minutes)
        pendingConfig?: {
          amount?: string; // Order size in USD
          leverage?: number; // Leverage
          takeProfitPrice?: string; // Take profit price
          stopLossPrice?: string; // Stop loss price
          limitPrice?: string; // Limit price (for limit orders)
          orderType?: OrderType; // Market vs limit
          timestamp: number; // When the config was saved (for expiration check)
        };
      };
    };
    mainnet: {
      [marketSymbol: string]: {
        leverage?: number;
        orderBookGrouping?: number; // Persisted price grouping for order book
        // Pending trade configuration (temporary, expires after 5 minutes)
        pendingConfig?: {
          amount?: string; // Order size in USD
          leverage?: number; // Leverage
          takeProfitPrice?: string; // Take profit price
          stopLossPrice?: string; // Stop loss price
          limitPrice?: string; // Limit price (for limit orders)
          orderType?: OrderType; // Market vs limit
          timestamp: number; // When the config was saved (for expiration check)
        };
      };
    };
  };

  // Market filter preferences (network-independent) - includes both sorting and filtering options
  marketFilterPreferences: {
    optionId: SortOptionId;
    direction: SortDirection;
  };

  // Error handling
  lastError: string | null;
  lastUpdateTimestamp: number;

  // HIP-3 Configuration Version (incremented when HIP-3 remote flags change)
  // Used to trigger reconnection and cache invalidation in ConnectionManager
  hip3ConfigVersion: number;

  // Selected payment token for Perps order/deposit flow (null = Perps balance). Stored as Json (minimal shape: description, address, chainId).
  selectedPaymentToken: Json | null;

  // Cached market data from background preloading (REST snapshots, not WebSocket)
  // Keyed by "providerId:network" (e.g. 'hyperliquid:mainnet', 'myx:testnet')
  cachedMarketDataByProvider: Record<
    string,
    { data: PerpsMarketData[]; timestamp: number }
  >;

  // Cached user data from background preloading (REST snapshots, not WebSocket)
  // Keyed by "providerId:network" (e.g. 'hyperliquid:mainnet', 'myx:testnet')
  cachedUserDataByProvider: Record<
    string,
    {
      positions: Position[];
      orders: Order[];
      accountState: AccountState | null;
      timestamp: number;
      address: string;
    }
  >;
};

/**
 * 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.
 */
export const getDefaultPerpsControllerState = (): PerpsControllerState => ({
  activeProvider: 'hyperliquid',
  isTestnet: false, // Default to mainnet
  initializationState: InitializationState.Uninitialized,
  initializationError: null,
  initializationAttempts: 0,
  accountState: null,
  perpsBalances: {},
  depositInProgress: false,
  lastDepositResult: null,
  withdrawInProgress: false,
  lastDepositTransactionId: null,
  lastWithdrawResult: null,
  lastCompletedWithdrawalTimestamp: null,
  lastCompletedWithdrawalTxHashes: [],
  withdrawalRequests: [],
  withdrawalProgress: {
    progress: 0,
    lastUpdated: 0,
    activeWithdrawalId: null,
  },
  depositRequests: [],
  lastError: null,
  lastUpdateTimestamp: 0,
  isEligible: false,
  isFirstTimeUser: {
    testnet: true,
    mainnet: true,
  },
  hasPlacedFirstOrder: {
    testnet: false,
    mainnet: false,
  },
  watchlistMarkets: {
    testnet: [],
    mainnet: [],
  },
  tradeConfigurations: {
    testnet: {},
    mainnet: {},
  },
  marketFilterPreferences: {
    optionId: MARKET_SORTING_CONFIG.DefaultSortOptionId,
    direction: MARKET_SORTING_CONFIG.DefaultDirection,
  },
  hip3ConfigVersion: 0,
  selectedPaymentToken: null,
  cachedMarketDataByProvider: {},
  cachedUserDataByProvider: {},
});

/**
 * State metadata for the PerpsController
 */
const metadata: StateMetadata<PerpsControllerState> = {
  accountState: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  perpsBalances: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  isTestnet: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  activeProvider: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  initializationState: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  initializationError: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  initializationAttempts: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: false,
  },
  depositInProgress: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  lastDepositTransactionId: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  lastDepositResult: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  withdrawInProgress: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  lastWithdrawResult: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  lastCompletedWithdrawalTimestamp: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  lastCompletedWithdrawalTxHashes: {
    includeInStateLogs: false,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  withdrawalRequests: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  withdrawalProgress: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  depositRequests: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  lastError: {
    includeInStateLogs: false,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: false,
  },
  lastUpdateTimestamp: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: false,
  },
  isEligible: {
    includeInStateLogs: true,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  isFirstTimeUser: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  hasPlacedFirstOrder: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  watchlistMarkets: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  tradeConfigurations: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  marketFilterPreferences: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  hip3ConfigVersion: {
    includeInStateLogs: true,
    persist: true,
    includeInDebugSnapshot: false,
    usedInUi: false,
  },
  selectedPaymentToken: {
    includeInStateLogs: false,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  cachedMarketDataByProvider: {
    includeInStateLogs: false,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
  cachedUserDataByProvider: {
    includeInStateLogs: false,
    persist: false,
    includeInDebugSnapshot: false,
    usedInUi: true,
  },
};

/**
 * PerpsController events
 */
export type PerpsControllerEvents = ControllerStateChangeEvent<
  'PerpsController',
  PerpsControllerState
>;

/**
 * The action which can be used to retrieve the state of the
 * {@link PerpsController}.
 */
export type PerpsControllerGetStateAction = ControllerGetStateAction<
  'PerpsController',
  PerpsControllerState
>;

/**
 * PerpsController actions
 */
export type PerpsControllerActions =
  | PerpsControllerGetStateAction
  | PerpsControllerMethodActions;

/**
 * PerpsController messenger constraints.
 * Includes both PerpsController's own actions/events and
 * allowed actions/events from external controllers.
 */
export type PerpsControllerMessenger = Messenger<
  'PerpsController',
  PerpsControllerActions | PerpsControllerAllowedActions,
  PerpsControllerEvents | PerpsControllerAllowedEvents
>;

/**
 * PerpsController options
 */
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;
  /**
   * When true, defers the initial eligibility (geolocation) check until
   * `startEligibilityMonitoring()` is called. This prevents the eager
   * geolocation fetch from firing during wallet onboarding (privacy compliance).
   */
  deferEligibilityCheck?: boolean;
};

type BlockedRegionList = {
  list: string[];
  source: 'remote' | 'fallback';
};

const MESSENGER_EXPOSED_METHODS = [
  'calculateFees',
  'calculateLiquidationPrice',
  'calculateMaintenanceMargin',
  'cancelOrder',
  'cancelOrders',
  'clearDepositResult',
  'clearPendingTradeConfiguration',
  'clearPendingTransactionRequests',
  'clearWithdrawResult',
  'closePosition',
  'closePositions',
  'completeWithdrawalFromHistory',
  'depositWithConfirmation',
  'depositWithOrder',
  'disconnect',
  'editOrder',
  'fetchHistoricalCandles',
  'flipPosition',
  'getAccountState',
  'getActiveProvider',
  'getActiveProviderOrNull',
  'getAvailableDexs',
  'getBlockExplorerUrl',
  'getCachedMarketDataForActiveProvider',
  'getCachedUserDataForActiveProvider',
  'getCurrentNetwork',
  'getFunding',
  'getHistoricalPortfolio',
  'getMarketDataWithPrices',
  'getMarketFilterPreferences',
  'getMarkets',
  'getMaxLeverage',
  'getOpenOrders',
  'getOrderBookGrouping',
  'getOrderFills',
  'getOrders',
  'getPendingTradeConfiguration',
  'getPositions',
  'getTradeConfiguration',
  'getWatchlistMarkets',
  'getWebSocketConnectionState',
  'getWithdrawalProgress',
  'getWithdrawalRoutes',
  'init',
  'isCurrentlyReinitializing',
  'isFirstTimeUserOnCurrentNetwork',
  'isWatchlistMarket',
  'markFirstOrderCompleted',
  'markTutorialCompleted',
  'placeOrder',
  'reconnect',
  'refreshEligibility',
  'resetFirstTimeUserState',
  'resetSelectedPaymentToken',
  'saveMarketFilterPreferences',
  'saveOrderBookGrouping',
  'savePendingTradeConfiguration',
  'saveTradeConfiguration',
  'setLiveDataConfig',
  'setSelectedPaymentToken',
  'startEligibilityMonitoring',
  'startMarketDataPreload',
  'stopEligibilityMonitoring',
  'stopMarketDataPreload',
  'subscribeToAccount',
  'subscribeToCandles',
  'subscribeToConnectionState',
  'subscribeToOICaps',
  'subscribeToOrderBook',
  'subscribeToOrderFills',
  'subscribeToOrders',
  'subscribeToPositions',
  'subscribeToPrices',
  'switchProvider',
  'toggleTestnet',
  'toggleWatchlistMarket',
  'updateMargin',
  'updatePositionTPSL',
  'updateWithdrawalProgress',
  'updateWithdrawalStatus',
  'validateClosePosition',
  'validateOrder',
  'validateWithdrawal',
  'withdraw',
] as const;

/**
 * PerpsController - Protocol-agnostic perpetuals trading controller
 *
 * 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 class PerpsController extends BaseController<
  'PerpsController',
  PerpsControllerState,
  PerpsControllerMessenger
> {
  protected providers: Map<PerpsProviderType, PerpsProvider>;

  protected isInitialized = false;

  #initializationPromise: Promise<void> | null = null;

  #isReinitializing = false;

  /** Tracks the async MYX dynamic import so performInitialization can await it. */
  #myxRegistrationPromise: Promise<void> | null = null;

  protected blockedRegionList: BlockedRegionList = {
    list: [],
    source: 'fallback',
  };

  /**
   * 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).
   */
  #blockedRegionListVersion = 0;

  // Store HIP-3 configuration (mutable for runtime updates from remote flags)
  #hip3Enabled: boolean;

  #hip3AllowlistMarkets: string[];

  #hip3BlocklistMarkets: string[];

  #hip3ConfigSource: 'remote' | 'fallback' = 'fallback';

  /**
   * Check if MYX provider is enabled via feature flag
   * Uses same pattern as other feature flags in FeatureFlagConfigurationService
   *
   * @returns True if the condition is met.
   */
  #isMYXProviderEnabled(): boolean {
    const myx = this.#options.clientConfig?.providerCredentials?.myx;

    // Local env-var override (MM_PERPS_MYX_PROVIDER_ENABLED) always wins —
    // matches the UI selector (resolvePerpsMyxProviderEnabled) so controller
    // and UI agree on whether MYX is available.
    if (myx?.enabled) {
      return true;
    }

    // Credentials present → MYX is enabled regardless of remote flag.
    // Use || so empty-string env vars (default '') fall through.
    const hasCredentials = Boolean(
      // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
      myx?.appIdTestnet || myx?.appIdMainnet,
    );

    if (hasCredentials) {
      return true;
    }

    // No local override or credentials — check remote flag as fallback
    try {
      const remoteState = this.messenger.call(
        'RemoteFeatureFlagController:getState',
      );
      const remoteFlag =
        remoteState.remoteFeatureFlags?.perpsMyxProviderEnabled;

      if (isVersionGatedFeatureFlag(remoteFlag)) {
        const validated =
          this.#options.infrastructure.featureFlags.validateVersionGated(
            remoteFlag,
          );
        return validated ?? false;
      }

      return false;
    } catch {
      return false;
    }
  }

  /**
   * 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 = null;

  /**
   * Cached standalone provider for pre-initialization discovery queries.
   * Avoids creating a new HyperLiquidProvider (and potentially leaking WebSocket
   * connections) on every standalone call from the preload cycle.
   */
  #standaloneProvider: HyperLiquidProvider | null = null;

  #handlersRegistered = false;

  #standaloneProviderIsTestnet: boolean | null = null;

  #standaloneProviderHip3Version: number | null = null;

  #eligibilityCheckDeferred: boolean;

  // Store options for dependency injection (allows core package to inject platform-specific services)
  readonly #options: PerpsControllerOptions;

  // Service instances (instantiated with platform dependencies)
  readonly #tradingService: TradingService;

  readonly #marketDataService: MarketDataService;

  readonly #accountService: AccountService;

  readonly #eligibilityService: EligibilityService;

  readonly #dataLakeService: DataLakeService;

  readonly #depositService: DepositService;

  readonly #featureFlagConfigurationService: FeatureFlagConfigurationService;

  readonly #rewardsIntegrationService: RewardsIntegrationService;

  constructor({
    messenger,
    state = {},
    clientConfig = {},
    infrastructure,
    deferEligibilityCheck = false,
  }: PerpsControllerOptions) {
    super({
      name: 'PerpsController',
      metadata,
      messenger,
      state: { ...getDefaultPerpsControllerState(), ...state },
    });

    this.#eligibilityCheckDeferred = deferEligibilityCheck;

    // Store options for dependency injection
    this.#options = {
      messenger,
      state,
      clientConfig,
      infrastructure,
    };

    // Instantiate services with platform dependencies
    // Services that need cross-controller access receive the messenger
    this.#tradingService = new TradingService(infrastructure);
    this.#marketDataService = new MarketDataService(infrastructure);
    this.#accountService = new AccountService(infrastructure, messenger);
    this.#eligibilityService = new EligibilityService(infrastructure);
    this.#dataLakeService = new DataLakeService(infrastructure, messenger);
    this.#depositService = new DepositService(infrastructure, messenger);
    this.#featureFlagConfigurationService = new FeatureFlagConfigurationService(
      infrastructure,
    );
    this.#rewardsIntegrationService = new RewardsIntegrationService(
      infrastructure,
      messenger,
    );

    // Set HIP-3 fallback configuration from client (will be updated if remote flags available)
    this.#hip3Enabled = clientConfig.fallbackHip3Enabled ?? false;
    this.#hip3AllowlistMarkets = [
      ...(clientConfig.fallbackHip3AllowlistMarkets ?? []),
    ];
    this.#hip3BlocklistMarkets = [
      ...(clientConfig.fallbackHip3BlocklistMarkets ?? []),
    ];

    // Immediately set the fallback region list since RemoteFeatureFlagController is empty by default and takes a moment to populate.
    this.setBlockedRegionList(
      clientConfig.fallbackBlockedRegions ?? [],
      'fallback',
    );

    /**
     * Immediately read current state to catch any flags already loaded
     * This is necessary to avoid race conditions where the RemoteFeatureFlagController fetches flags
     * before the PerpsController initializes its RemoteFeatureFlagController subscription.
     *
     * We still subscribe in case the RemoteFeatureFlagController is not yet populated and updates later.
     */
    try {
      const currentRemoteFeatureFlagState = this.messenger.call(
        'RemoteFeatureFlagController:getState',
      );

      this.refreshEligibilityOnFeatureFlagChange(currentRemoteFeatureFlagState);
    } catch (error) {
      // If we can't read the remote feature flags at construction time, we'll rely on:
      // 1. The fallback blocked regions already set above
      // 2. The subscription to catch updates when RemoteFeatureFlagController is ready
      this.#logError(
        ensureError(error, 'PerpsController.constructor'),
        this.#getErrorContext('constructor', {
          operation: 'readRemoteFeatureFlags',
        }),
      );
    }

    // Subscribe for the full controller lifetime — intentionally not stored;
    // geo-blocking and HIP-3 flag propagation must remain active across
    // disconnect → reconnect cycles and must never be torn down.
    this.messenger.subscribe(
      'RemoteFeatureFlagController:stateChange',
      this.refreshEligibilityOnFeatureFlagChange.bind(this),
    );

    this.providers = new Map();

    // Migrate old persisted data without accountAddress
    this.#migrateRequestsIfNeeded();

    // Eagerly hydrate in-memory caches from disk so hooks see data on first render.
    // Must happen at construction time — before any React component mounts.
    this.#hydrateCacheFromDiskSync();
  }

  // ============================================================================
  // Infrastructure Access Methods
  // These methods provide access to platform-specific infrastructure via dependency injection.
  // Infrastructure is required and must be provided at instantiation time.
  // ============================================================================

  /**
   * Log an error using injected infrastructure logger
   *
   * @param error - The error that occurred.
   * @param options - The configuration options.
   */
  #logError(error: Error, options?: PerpsLoggerOptions): void {
    this.#options.infrastructure.logger.error(error, options);
  }

  /**
   * Log debug message using injected infrastructure debugLogger
   *
   * @param args - The function arguments.
   */
  #debugLog(
    ...args: (string | number | boolean | object | null | undefined)[]
  ): void {
    this.#options.infrastructure.debugLogger.log(...args);
  }

  /**
   * Resolve the provider ids that should participate in aggregated cache reads.
   *
   * Providers can still be registering when the first render happens, so we
   * also look at cache keys to recover disk-hydrated provider snapshots before
   * `init()` finishes populating `this.providers`.
   *
   * @param cacheKeys - Cache keys currently present in the relevant cache map.
   * @returns Provider ids that should be included in aggregated reads.
   */
  #getAggregatedCacheProviderIds(cacheKeys: string[]): string[] {
    const providerIds = new Set<string>();
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';

    for (const [providerId] of this.providers) {
      providerIds.add(providerId);
    }

    for (const key of cacheKeys) {
      const [providerId, network] = key.split(':');
      if (
        !providerId ||
        network !== currentNetwork ||
        providerId === 'aggregated'
      ) {
        continue;
      }

      if (
        providerId === 'hyperliquid' ||
        (providerId === 'myx' && this.#isMYXProviderEnabled()) ||
        this.providers.has(providerId as PerpsProviderType)
      ) {
        providerIds.add(providerId);
      }
    }

    return Array.from(providerIds);
  }

  /**
   * Read cached market data for the currently active provider (or aggregated).
   * Returns null when no valid cache exists or when cache has expired.
   *
   * @param options - Optional settings.
   * @param options.skipTTL - When true, bypass the 5-minute TTL check.
   * Used during initial render so disk-hydrated structural data (with
   * placeholder prices) is returned regardless of age.
   * @returns The cached market data array, or null if no valid cache.
   */
  getCachedMarketDataForActiveProvider(options?: {
    skipTTL?: boolean;
  }): PerpsMarketData[] | null {
    const { activeProvider } = this.state;
    const cache = this.state.cachedMarketDataByProvider;

    if (activeProvider === 'aggregated') {
      // Assemble from all registered provider entries
      const assembled: PerpsMarketData[] = [];
      let oldestTimestamp = Infinity;
      for (const providerId of this.#getAggregatedCacheProviderIds(
        Object.keys(cache),
      )) {
        const key = buildProviderCacheKey(providerId, this.state.isTestnet);
        const entry = cache[key];
        if (!entry || entry.data.length === 0) {
          continue;
        }
        oldestTimestamp = Math.min(oldestTimestamp, entry.timestamp);
        assembled.push(...entry.data);
      }
      if (assembled.length === 0) {
        return null;
      }
      // Check TTL against the oldest entry
      if (
        !options?.skipTTL &&
        Date.now() - oldestTimestamp > PerpsController.#preloadGuardMs * 10
      ) {
        return null;
      }
      return assembled;
    }

    // Single provider mode
    const key = buildProviderCacheKey(activeProvider, this.state.isTestnet);
    const entry = cache[key];
    if (!entry || entry.data.length === 0) {
      return null;
    }
    if (
      !options?.skipTTL &&
      Date.now() - entry.timestamp > PerpsController.#preloadGuardMs * 10
    ) {
      return null;
    }
    return entry.data;
  }

  /**
   * Read cached user data for the currently active provider (or aggregated).
   * Returns null when no valid cache exists, cache has expired, or address
   * does not match the currently selected EVM account.
   *
   * @param options - Optional settings.
   * @param options.skipTTL - When true, bypass the 60s staleness check.
   * Used during initial render so disk-hydrated user data (positions/orders)
   * is returned regardless of age, avoiding a skeleton flash.
   * @returns The cached user data, or null if no valid cache.
   */
  getCachedUserDataForActiveProvider(options?: { skipTTL?: boolean }): {
    positions: Position[];
    orders: Order[];
    accountState: AccountState | null;
  } | null {
    const { activeProvider } = this.state;
    const cache = this.state.cachedUserDataByProvider;
    const staleCutoff = PerpsController.#preloadGuardMs * 2; // 60s

    // Get current user address for validation
    let currentAddress: string | null = null;
    try {
      const evmAccount = getSelectedEvmAccountFromMessenger(this.messenger);
      currentAddress = evmAccount?.address ?? null;
    } catch {
      // Can't determine current account — trust the cache
    }

    const skipTTL = options?.skipTTL ?? false;

    const isValidEntry = (
      entry: { timestamp: number; address: string } | undefined,
    ): entry is { timestamp: number; address: string } => {
      if (!entry) {
        return false;
      }
      if (!skipTTL && Date.now() - entry.timestamp >= staleCutoff) {
        return false;
      }
      if (
        currentAddress &&
        entry.address.toLowerCase() !== currentAddress.toLowerCase()
      ) {
        return false;
      }
      return true;
    };

    if (activeProvider === 'aggregated') {
      // Assemble from all registered provider entries
      const allPositions: Position[] = [];
      const allOrders: Order[] = [];
      let defaultAccountState: AccountState | null = null;
      let hasValidEntry = false;

      for (const providerId of this.#getAggregatedCacheProviderIds(
        Object.keys(cache),
      )) {
        const key = buildProviderCacheKey(providerId, this.state.isTestnet);
        const entry = cache[key];
        if (!isValidEntry(entry)) {
          continue;
        }
        hasValidEntry = true;
        allPositions.push(...entry.positions);
        allOrders.push(...entry.orders);
        // AccountState from default provider (hyperliquid)
        if (providerId === 'hyperliquid') {
          defaultAccountState = entry.accountState;
        }
      }

      if (!hasValidEntry) {
        return null;
      }

      return {
        positions: allPositions,
        orders: allOrders,
        accountState: defaultAccountState,
      };
    }

    // Single provider mode
    const key = buildProviderCacheKey(activeProvider, this.state.isTestnet);
    const entry = cache[key];
    if (!entry || !isValidEntry(entry)) {
      return null;
    }

    return {
      positions: entry.positions,
      orders: entry.orders,
      accountState: entry.accountState,
    };
  }

  /**
   * Returns a cached standalone HyperLiquidProvider for pre-initialization
   * discovery queries. Creates a new instance on first call or when the
   * isTestnet / hip3ConfigVersion has changed since the last creation.
   *
   * @returns A HyperLiquidProvider suitable for standalone REST calls.
   */
  #getOrCreateStandaloneProvider(): HyperLiquidProvider {
    const currentIsTestnet = this.state.isTestnet;
    const currentHip3Version = this.state.hip3ConfigVersion ?? 0;

    if (
      this.#standaloneProvider &&
      this.#standaloneProviderIsTestnet === currentIsTestnet &&
      this.#standaloneProviderHip3Version === currentHip3Version
    ) {
      return this.#standaloneProvider;
    }

    // Stale or missing — tear down old one (fire-and-forget)
    if (this.#standaloneProvider) {
      const old = this.#standaloneProvider;
      Promise.resolve(old.disconnect()).catch(() => {
        /* best-effort */
      });
    }

    this.#standaloneProvider = new HyperLiquidProvider({
      isTestnet: currentIsTestnet,
      hip3Enabled: this.#hip3Enabled,
      allowlistMarkets: this.#hip3AllowlistMarkets,
      blocklistMarkets: this.#hip3BlocklistMarkets,
      platformDependencies: this.#options.infrastructure,
      messenger: this.messenger,
      builderAddressTestnet:
        this.#options.clientConfig?.providerCredentials?.hyperliquid
          ?.builderAddressTestnet,
      builderAddressMainnet:
        this.#options.clientConfig?.providerCredentials?.hyperliquid
          ?.builderAddressMainnet,
    });
    this.#standaloneProviderIsTestnet = currentIsTestnet;
    this.#standaloneProviderHip3Version = currentHip3Version;

    return this.#standaloneProvider;
  }

  /**
   * Disconnect and discard the cached standalone provider (if any).
   * Best-effort — errors are silently caught.
   */
  async #cleanupStandaloneProvider(): Promise<void> {
    if (!this.#standaloneProvider) {
      return;
    }
    try {
      await this.#standaloneProvider.disconnect();
    } catch {
      /* best-effort */
    }
    this.#standaloneProvider = null;
    this.#standaloneProviderIsTestnet = null;
    this.#standaloneProviderHip3Version = null;
  }

  /**
   * Test-observable accessor for whether a standalone provider is cached.
   *
   * @returns True if a standalone provider instance exists.
   */
  protected hasStandaloneProvider(): boolean {
    return this.#standaloneProvider !== null;
  }

  /**
   * Get metrics instance from platform dependencies
   *
   * @returns The platform metrics instance.
   */
  #getMetrics(): PerpsPlatformDependencies['metrics'] {
    return this.#options.infrastructure.metrics;
  }

  // ============================================================================
  // Messenger-based Controller Access
  // These methods use the messenger pattern for inter-controller communication
  // ============================================================================

  /**
   * Find network client ID for a given chain via messenger
   *
   * @param chainId - The chain identifier.
   * @returns The resulting string value.
   */
  #findNetworkClientIdForChain(chainId: string): string | undefined {
    return this.messenger.call(
      'NetworkController:findNetworkClientIdByChainId',
      chainId as `0x${string}`,
    );
  }

  /**
   * Submit a transaction via messenger (shows confirmation screen)
   *
   * @param txParams - The transaction parameters.
   * @param txParams.from - The sender address.
   * @param txParams.to - The recipient address.
   * @param txParams.value - The transaction value.
   * @param txParams.data - The transaction data payload.
   * @param txParams.gas - The gas limit.
   * @param options - The configuration options.
   * @param options.networkClientId - The network client identifier.
   * @param options.origin - The transaction origin.
   * @param options.type - The transaction type.
   * @param options.skipInitialGasEstimate - Whether to skip initial gas estimation.
   * @returns The transaction result containing a hash promise and transaction metadata.
   */
  async #submitTransaction(
    txParams: PerpsTransactionParams,
    options: PerpsAddTransactionOptions,
  ): Promise<{
    result: Promise<string>;
    transactionMeta: { id: string; hash?: string };
  }> {
    // Cast needed: PerpsController uses loose string types for txParams/options
    // while TransactionController uses strict branded types (TransactionParams, AddTransactionOptions)
    return this.messenger.call(
      'TransactionController:addTransaction',
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      txParams as any,
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      options as any,
    );
  }

  /**
   * 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.
   * Also drop persisted failed withdrawals — failures are surfaced via lastWithdrawResult only.
   */
  #migrateRequestsIfNeeded(): void {
    this.update((state) => {
      // Remove withdrawal requests without accountAddress - they can't be attributed to any account
      state.withdrawalRequests = state.withdrawalRequests.filter(
        (req) => Boolean(req.accountAddress) && req.status !== 'failed',
      );

      // Remove deposit requests without accountAddress - they can't be attributed to any account
      state.depositRequests = state.depositRequests.filter((req) =>
        Boolean(req.accountAddress),
      );
    });
  }

  protected setBlockedRegionList(
    list: string[],
    source: 'remote' | 'fallback',
  ): void {
    this.#featureFlagConfigurationService.setBlockedRegions({
      list,
      source,
      context: this.#createServiceContext('setBlockedRegionList', {
        getBlockedRegionList: () => this.blockedRegionList,
        setBlockedRegionList: (
          newList: string[],
          newSource: 'remote' | 'fallback',
        ) => {
          this.blockedRegionList = { list: newList, source: newSource };
          this.#blockedRegionListVersion += 1;
        },
        refreshEligibility: () => this.refreshEligibility(),
      }),
    });
  }

  /**
   * 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 {
    this.#featureFlagConfigurationService.refreshEligibility({
      remoteFeatureFlagControllerState,
      context: this.#createServiceContext(
        'refreshEligibilityOnFeatureFlagChange',
        {
          getBlockedRegionList: () => this.blockedRegionList,
          setBlockedRegionList: (
            list: string[],
            source: 'remote' | 'fallback',
          ) => {
            this.blockedRegionList = { list, source };
            this.#blockedRegionListVersion += 1;
          },
          refreshEligibility: () => this.refreshEligibility(),
          getHip3Config: () => ({
            enabled: this.#hip3Enabled,
            allowlistMarkets: this.#hip3AllowlistMarkets,
            blocklistMarkets: this.#hip3BlocklistMarkets,
            source: this.#hip3ConfigSource,
          }),
          setHip3Config: (config) => {
            if (config.enabled !== undefined) {
              this.#hip3Enabled = config.enabled;
            }
            if (config.allowlistMarkets !== undefined) {
              this.#hip3AllowlistMarkets = [...config.allowlistMarkets];
            }
            if (config.blocklistMarkets !== undefined) {
              this.#hip3BlocklistMarkets = [...config.blocklistMarkets];
            }
            if (config.source !== undefined) {
              this.#hip3ConfigSource = config.source;
            }
          },
          incrementHip3ConfigVersion: () => {
            const newVersion = (this.state.hip3ConfigVersion || 0) + 1;
            this.update((state) => {
              state.hip3ConfigVersion = newVersion;
            });
            return newVersion;
          },
        },
      ),
    });
  }

  /**
   * 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']
   * );
   * ```
   */
  async #withStreamPause<TResult>(
    operation: () => Promise<TResult>,
    channels: string[],
  ): Promise<TResult> {
    const pausedChannels: string[] = [];
    const { streamManager } = this.#options.infrastructure;

    // Pause emission on specified channels (WebSocket stays connected)
    // Track which channels successfully paused to ensure proper cleanup
    for (const channel of channels) {
      try {
        streamManager.pauseChannel(channel);
        pausedChannels.push(channel);
      } catch (error) {
        // Log error to Sentry but continue pausing remaining channels
        this.#logError(
          ensureError(error, 'PerpsController.withStreamPause'),
          this.#getErrorContext('withStreamPause', {
            operation: 'pause',
            channel: String(channel),
            pausedChannels: pausedChannels.join(','),
          }),
        );
      }
    }

    try {
      // Execute operation without stream interference
      return await operation();
    } finally {
      // Resume only channels that were successfully paused
      for (const channel of pausedChannels) {
        try {
          streamManager.resumeChannel(channel);
        } catch (error) {
          // Log error to Sentry but continue resuming remaining channels
          this.#logError(
            ensureError(error, 'PerpsController.withStreamPause'),
            this.#getErrorContext('withStreamPause', {
              operation: 'resume',
              channel: String(channel),
              pausedChannels: pausedChannels.join(','),
            }),
          );
        }
      }
    }
  }

  /**
   * 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.
   */
  async init(): Promise<void> {
    if (!this.#handlersRegistered) {
      this.messenger.registerMethodActionHandlers(
        this,
        MESSENGER_EXPOSED_METHODS,
      );
      this.#handlersRegistered = true;
    }

    if (this.isInitialized) {
      return undefined;
    }

    if (this.#initializationPromise) {
      return this.#initializationPromise;
    }

    this.#initializationPromise = this.#performInitialization();
    return this.#initializationPromise;
  }

  /**
   * Actual initialization implementation with retry logic
   */
  async #performInitialization(): Promise<void> {
    const maxAttempts = 3;
    const baseDelay = 1000;

    this.update((state) => {
      state.initializationState = InitializationState.Initializing;
      state.initializationError = null;
      state.initializationAttempts = 0;
    });

    this.#debugLog('PerpsController: Initializing providers', {
      currentNetwork: this.state.isTestnet ? 'testnet' : 'mainnet',
      existingProviders: Array.from(this.providers.keys()),
      timestamp: new Date().toISOString(),
    });

    let lastError: Error | null = null;

    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      try {
        this.update((state) => {
          state.initializationAttempts = attempt;
        });

        // Disconnect existing providers to close WebSocket connections
        const existingProviders = Array.from(this.providers.values());
        if (existingProviders.length > 0) {
          this.#debugLog('PerpsController: Disconnecting existing providers', {
            count: existingProviders.length,
            timestamp: new Date().toISOString(),
          });
          await Promise.all(
            existingProviders.map((provider) => provider.disconnect()),
          );
        }
        this.providers.clear();
        await this.#cleanupStandaloneProvider();

        this.#createProviders();

        // Await MYX dynamic import (if started) so MYX is in the providers
        // map before we assign the active provider. Runs concurrently with
        // the WebSocket readiness delay for zero additional latency.
        await Promise.all([
          wait(PERPS_CONSTANTS.ReconnectionCleanupDelayMs),
          this.#myxRegistrationPromise,
        ]);
        this.#myxRegistrationPromise = null;

        this.#assignActiveProvider();

        this.isInitialized = true;
        this.update((state) => {
          state.initializationState = InitializationState.Initialized;
          state.initializationError = null;
        });

        this.#debugLog('PerpsController: Providers initialized successfully', {
          providerCount: this.providers.size,
          activeProvider: this.state.activeProvider,
          timestamp: new Date().toISOString(),
          attempts: attempt,
        });

        return; // Exit retry loop on success
      } catch (error) {
        lastError = ensureError(error, 'PerpsController.performInitialization');

        this.#logError(
          lastError,
          this.#getErrorContext('performInitialization', {
            attempt,
            maxAttempts,
          }),
        );

        // If not the last attempt, wait before retrying (exponential backoff)
        if (attempt < maxAttempts) {
          const delay = baseDelay * Math.pow(2, attempt - 1); // 1s, 2s, 4s
          this.#debugLog(
            `PerpsController: Retrying initialization in ${delay}ms`,
            {
              attempt,
              maxAttempts,
              error: lastError.message,
            },
          );
          await wait(delay);
        }
      }
    }

    this.isInitialized = false;
    this.update((state) => {
      state.initializationState = InitializationState.Failed;
      state.initializationError = lastError?.message ?? 'Unknown error';
    });
    this.#initializationPromise = null; // Clear promise to allow retry

    this.#debugLog('PerpsController: Initialization failed', {
      error: lastError?.message,
      attempts: maxAttempts,
      timestamp: new Date().toISOString(),
    });
  }

  /**
   * Instantiate provider instances based on current state and register them.
   * Selects and assigns the active provider instance from the registry.
   * Future providers can be added here with their own authentication patterns:
   * - Some might use API keys: new BinanceProvider({ apiKey, apiSecret })
   * - Some might use different wallet patterns: new GMXProvider({ signer })
   * - Some might not need auth at all: new DydxProvider()
   */
  #createProviders(): void {
    const { activeProvider } = this.state;

    this.#debugLog(
      'PerpsController: Creating provider with HIP-3 configuration',
      {
        hip3Enabled: this.#hip3Enabled,
        hip3AllowlistMarkets: this.#hip3AllowlistMarkets,
        hip3BlocklistMarkets: this.#hip3BlocklistMarkets,
        hip3ConfigSource: this.#hip3ConfigSource,
        isTestnet: this.state.isTestnet,
        activeProvider,
      },
    );

    // Always create HyperLiquid provider as the base provider
    const hyperLiquidProvider = new HyperLiquidProvider({
      isTestnet: this.state.isTestnet,
      hip3Enabled: this.#hip3Enabled,
      allowlistMarkets: this.#hip3AllowlistMarkets,
      blocklistMarkets: this.#hip3BlocklistMarkets,
      platformDependencies: this.#options.infrastructure,
      messenger: this.messenger,
      builderAddressTestnet:
        this.#options.clientConfig?.providerCredentials?.hyperliquid
          ?.builderAddressTestnet,
      builderAddressMainnet:
        this.#options.clientConfig?.providerCredentials?.hyperliquid
          ?.builderAddressMainnet,
    });
    this.providers.set('hyperliquid', hyperLiquidProvider);

    // Register MYX provider if enabled via feature flag.
    // Dynamic import because the MYX package pulls in heavy dependencies we
    // don't want bundled in extension. Until MYX fixes their package, extension
    // doesn't ship it — the catch branch silently skips registration.
    // Uses .then()/.catch() instead of await because #createProviders is not async;
    // MYX registration completing asynchronously is fine since it's only used when
    // explicitly enabled and selected.
    const isMYXEnabled = this.#isMYXProviderEnabled();
    if (isMYXEnabled) {
      // IMPORTANT: Must use import() — NOT require() — for core/extension tree-shaking.
      // require() is synchronous and bundlers include it in the main bundle.
      // import() enables true code splitting so MYX is excluded when not enabled.
      // NOTE: Keep the path in a variable so ts-bridge does not rewrite the
      // import argument and strip the webpackIgnore magic comment in core dist.
      const myxModulePath = './providers/MYXProvider';
      this.#myxRegistrationPromise = import(
        /* webpackIgnore: true */ myxModulePath
      )
        .then(({ MYXProvider }) => {
          this.registerMYXProvider(MYXProvider);
          return undefined;
        })
        .catch((error: unknown) => this.handleMYXImportError(error));
    }
  }

  /**
   * Registers the MYX provider after dynamic import resolves.
   *
   * Extracted from the import().then() callback so it can be tested directly
   * (Jest cannot resolve dynamic imports without --experimental-vm-modules).
   *
   * @param MYXProvider - Constructor class for the MYX provider.
   */
  protected registerMYXProvider(
    MYXProvider: new (opts: {
      isTestnet: boolean;
      platformDependencies: PerpsPlatformDependencies;
      messenger: PerpsControllerMessenger;
      myxAuthConfig: ReturnType<typeof resolveMyxAuthConfig>;
    }) => PerpsProvider,
  ): void {
    const myxIsTestnet =
      PROVIDER_CONFIG.MYX_TESTNET_ONLY || this.state.isTestnet;
    const myx = this.#options.clientConfig?.providerCredentials?.myx ?? {};
    const myxAuthConfig = resolveMyxAuthConfig(myx, myxIsTestnet);
    const myxProvider = new MYXProvider({
      isTestnet: myxIsTestnet,
      platformDependencies: this.#options.infrastructure,
      messenger: this.messenger,
      myxAuthConfig,
    });
    this.providers.set('myx', myxProvider);
    this.#debugLog('PerpsController: MYX provider registered', {
      isTestnet: myxIsTestnet,
    });
  }

  /**
   * Handles errors from the MYX dynamic import.
   *
   * Module-not-found errors are expected (extension doesn't ship MYX) → debug log.
   * Other errors indicate constructor/config problems → Sentry via logError.
   *
   * @param error - The caught error from the dynamic import or constructor.
   */
  protected handleMYXImportError(error: unknown): void {
    const isModuleError =
      (error as Record<string, unknown>)?.code === 'MODULE_NOT_FOUND';
    if (isModuleError) {
      this.#debugLog(
        'PerpsController: MYX provider module not available, skipping registration',
      );
    } else {
      this.#logError(
        error instanceof Error ? error : new Error(String(error)),
        this.#getErrorContext('createProviders.myx'),
      );
    }
  }

  /**
   * Assigns the active provider instance based on the current activeProvider state.
   * Separated from #createProviders so it runs after async MYX registration settles.
   */
  #assignActiveProvider(): void {
    const { activeProvider } = this.state;
    const hyperLiquidProvider = this.providers.get('hyperliquid');

    if (!hyperLiquidProvider) {
      throw new Error(
        'HyperLiquid provider not registered — cannot assign active provider',
      );
    }

    if (activeProvider === 'aggregated') {
      this.activeProviderInstance = new AggregatedPerpsProvider({
        providers: this.providers,
        defaultProvider: 'hyperliquid',
        infrastructure: this.#options.infrastructure,
      });
      this.#debugLog(
        'PerpsController: Using aggregated provider (multi-provider)',
        { registeredProviders: Array.from(this.providers.keys()) },
      );
    } else if (activeProvider === 'hyperliquid') {
      this.activeProviderInstance = hyperLiquidProvider;
      this.#debugLog(
        `PerpsController: Using direct provider (${activeProvider})`,
      );
    } else if (activeProvider === 'myx') {
      const myxProvider = this.providers.get('myx');
      if (myxProvider) {
        this.activeProviderInstance = myxProvider;
      } else {
        this.#debugLog(
          'PerpsController: MYX provider not available, falling back to hyperliquid',
        );
        this.activeProviderInstance = hyperLiquidProvider;
        this.update((state) => {
          state.activeProvider = 'hyperliquid';
        });
      }
      this.#debugLog(
        `PerpsController: Using direct provider (${this.activeProviderInstance === hyperLiquidProvider ? 'hyperliquid' : activeProvider})`,
      );
    } else {
      throw new Error(
        `Unsupported provider: ${String(activeProvider)}. Currently only 'hyperliquid', 'myx', and 'aggregated' are supported.`,
      );
    }
  }

  /**
   * 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
   */
  #getErrorContext(
    method: string,
    extra?: Record<string, unknown>,
  ): PerpsLoggerOptions {
    return {
      tags: {
        feature: PERPS_CONSTANTS.FeatureName,
        provider: this.state.activeProvider,
        network: this.state.isTestnet ? 'testnet' : 'mainnet',
      },
      context: {
        name: 'PerpsController',
        data: {
          method,
          ...extra,
        },
      },
    };
  }

  /**
   * Returns current controller state as PerpsControllerState.
   * Used by createServiceContext to avoid deep type instantiation when building stateManager.
   *
   * @returns The current controller state cast to PerpsControllerState.
   */
  #getControllerState(): PerpsControllerState {
    return this.state as unknown as PerpsControllerState;
  }

  /**
   * 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
   */
  #createServiceContext(
    method: string,
    additionalContext?: Partial<ServiceContext>,
  ): ServiceContext {
    return {
      tracingContext: {
        provider: this.state.activeProvider,
        isTestnet: this.state.isTestnet,
      },
      errorContext: {
        controller: 'PerpsController',
        method,
      },
      stateManager: {
        update: (updater: (state: PerpsControllerState) => void) =>
          // @ts-expect-error TS2589 - excessively deep instantiation from BaseController generic
          this.update(updater),
        getState: (): PerpsControllerState => this.#getControllerState(),
      },
      ...additionalContext,
    } as ServiceContext;
  }

  /**
   * Ensure TradingService has controller dependencies set.
   * RewardsIntegrationService uses messenger internally for controller access.
   */
  #ensureTradingServiceDeps(): void {
    this.#tradingService.setControllerDependencies({
      rewardsIntegrationService: this.#rewardsIntegrationService,
    });
  }

  /**
   * 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 {
    // Check if we're in the middle of reinitializing
    if (this.isCurrentlyReinitializing()) {
      this.update((state) => {
        state.lastError = PERPS_ERROR_CODES.CLIENT_REINITIALIZING;
        state.lastUpdateTimestamp = Date.now();
      });
      throw new Error(PERPS_ERROR_CODES.CLIENT_REINITIALIZING);
    }

    // Check if not initialized
    if (
      this.state.initializationState !== InitializationState.Initialized ||
      !this.isInitialized
    ) {
      const errorMessage =
        this.state.initializationState === InitializationState.Failed
          ? `${PERPS_ERROR_CODES.CLIENT_NOT_INITIALIZED}: ${this.state.initializationError ?? 'Initialization failed'}`
          : PERPS_ERROR_CODES.CLIENT_NOT_INITIALIZED;

      this.update((state) => {
        state.lastError = errorMessage;
        state.lastUpdateTimestamp = Date.now();
      });
      throw new Error(errorMessage);
    }

    // Return the active provider instance (set during initialization based on providerMode)
    if (!this.activeProviderInstance) {
      this.update((state) => {
        state.lastError = PERPS_ERROR_CODES.PROVIDER_NOT_AVAILABLE;
        state.lastUpdateTimestamp = Date.now();
      });
      throw new Error(PERPS_ERROR_CODES.PROVIDER_NOT_AVAILABLE);
    }

    return this.activeProviderInstance;
  }

  /**
   * 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 {
    // Return null during reinitialization
    if (this.isCurrentlyReinitializing()) {
      return null;
    }

    // Return null if not initialized
    if (
      this.state.initializationState !== InitializationState.Initialized ||
      !this.isInitialized
    ) {
      return null;
    }

    // Return the active provider instance or null if not found
    return this.activeProviderInstance ?? null;
  }

  /**
   * Place a new order
   * Thin delegation to TradingService
   *
   * @param params - The operation parameters.
   * @returns The order result with order ID and status.
   */
  async placeOrder(params: OrderParams): Promise<OrderResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.placeOrder({
      provider,
      params,
      context: this.#createServiceContext('placeOrder', {
        saveTradeConfiguration: (symbol: string, leverage: number) =>
          this.saveTradeConfiguration(symbol, leverage),
      }),
      reportOrderToDataLake: (dataLakeParams) =>
        this.reportOrderToDataLake(dataLakeParams),
    });
  }

  /**
   * Edit an existing order
   * Thin delegation to TradingService
   *
   * @param params - The operation parameters.
   * @returns The updated order result with order ID and status.
   */
  async editOrder(params: EditOrderParams): Promise<OrderResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.editOrder({
      provider,
      params,
      context: this.#createServiceContext('editOrder'),
    });
  }

  /**
   * Cancel an existing order
   *
   * @param params - The operation parameters.
   * @returns The cancellation result with status.
   */
  async cancelOrder(params: CancelOrderParams): Promise<CancelOrderResult> {
    const provider = this.getActiveProvider();

    return this.#tradingService.cancelOrder({
      provider,
      params,
      context: this.#createServiceContext('cancelOrder'),
    });
  }

  /**
   * 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.
   */
  async cancelOrders(params: CancelOrdersParams): Promise<CancelOrdersResult> {
    const provider = this.getActiveProvider();

    return this.#tradingService.cancelOrders({
      provider,
      params,
      context: this.#createServiceContext('cancelOrders', {
        getOpenOrders: () => this.getOpenOrders(),
      }),
      withStreamPause: <TResult>(
        operation: () => Promise<TResult>,
        channels: string[],
      ) => this.#withStreamPause(operation, channels),
    });
  }

  /**
   * Close a position (partial or full)
   * Thin delegation to TradingService
   *
   * @param params - The operation parameters.
   * @returns The order result from the close position request.
   */
  async closePosition(params: ClosePositionParams): Promise<OrderResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.closePosition({
      provider,
      params,
      context: this.#createServiceContext('closePosition', {
        getPositions: () => this.getPositions(),
      }),
      reportOrderToDataLake: (dataLakeParams) =>
        this.reportOrderToDataLake(dataLakeParams),
    });
  }

  /**
   * 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.
   */
  async closePositions(
    params: ClosePositionsParams,
  ): Promise<ClosePositionsResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.closePositions({
      provider,
      params,
      context: this.#createServiceContext('closePositions', {
        getPositions: () => this.getPositions(),
      }),
    });
  }

  /**
   * Update TP/SL for an existing position
   *
   * @param params - The operation parameters.
   * @returns The order result from the TP/SL update.
   */
  async updatePositionTPSL(
    params: UpdatePositionTPSLParams,
  ): Promise<OrderResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.updatePositionTPSL({
      provider,
      params,
      context: this.#createServiceContext('updatePositionTPSL'),
    });
  }

  /**
   * Update margin for an existing position (add or remove)
   *
   * @param params - The operation parameters.
   * @returns The margin update result.
   */
  async updateMargin(params: UpdateMarginParams): Promise<MarginResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.updateMargin({
      provider,
      symbol: params.symbol,
      amount: params.amount,
      context: this.#createServiceContext('updateMargin'),
    });
  }

  /**
   * Flip position (reverse direction while keeping size and leverage)
   *
   * @param params - The operation parameters.
   * @returns The order result from the position flip.
   */
  async flipPosition(params: FlipPositionParams): Promise<OrderResult> {
    const provider = this.getActiveProvider();
    this.#ensureTradingServiceDeps();

    return this.#tradingService.flipPosition({
      provider,
      position: params.position,
      context: this.#createServiceContext('flipPosition'),
    });
  }

  /**
   * 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.
   */
  async depositWithConfirmation(
    params: DepositWithConfirmationParams = {},
  ): Promise<{ result: Promise<string> }> {
    const { amount, placeOrder } = params;

    let currentDepositId: string | undefined;

    try {
      // Clear any stale results when starting a new deposit flow
      // Don't set depositInProgress yet - wait until user confirms

      // Prepare deposit transaction using DepositService
      const provider = this.getActiveProvider();
      const {
        transaction,
        assetChainId,
        currentDepositId: depositId,
      } = await this.#depositService.prepareTransaction({ provider });
      currentDepositId = depositId;

      // Get current account address via messenger (outside of update() for proper typing)
      const evmAccount = getSelectedEvmAccountFromMessenger(this.messenger);
      const accountAddress = evmAccount?.address ?? 'unknown';

      this.update((state) => {
        state.lastDepositResult = null;

        // Add deposit request to tracking
        const depositRequest = {
          id: currentDepositId ?? uuidv4(),
          timestamp: Date.now(),
          amount: amount ?? '0', // Use provided amount or default to '0'
          asset: USDC_SYMBOL,
          accountAddress, // Track which account initiated deposit
          success: false, // Will be updated when transaction completes
          txHash: undefined,
          status: 'pending' as TransactionStatus,
          source: undefined,
          transactionId: undefined, // Will be set to depositId when available
        };

        state.depositRequests.unshift(depositRequest); // Add to beginning of array
      });

      const networkClientId = this.#findNetworkClientIdForChain(assetChainId);

      if (!networkClientId) {
        throw new Error(
          `No network client found for chain ${assetChainId}. Please add the network first.`,
        );
      }

      let result: Promise<string>;
      let transactionMeta: { id: string };
      let depositOrderResult: Promise<string> | null = null;

      const defaultTransactionOptions = {
        networkClientId,
        origin: ORIGIN_METAMASK,
        skipInitialGasEstimate: true,
      };

      this.#options.infrastructure.tracer.addBreadcrumb({
        category: 'perps',
        message: 'Deposit action started',
        level: 'info',
        data: {
          place_order_after_deposit: placeOrder === true,
        },
      });

      if (placeOrder) {
        // Use addTransaction to create transaction without navigating to confirmation screen
        const addResult = await this.#submitTransaction(transaction, {
          ...defaultTransactionOptions,
          type: 'perpsDepositAndOrder',
        });
        transactionMeta = addResult.transactionMeta;
        // Return transaction ID immediately (fire-and-forget for caller)
        result = Promise.resolve(transactionMeta.id);
        // Track deposit request lifecycle via the real transaction result
        depositOrderResult = addResult.result;
      } else {
        // submit shows the confirmation screen and returns a promise
        // The promise will resolve when transaction completes or reject if cancelled/failed
        const submitResult = await this.#submitTransaction(transaction, {
          ...defaultTransactionOptions,
          type: 'perpsDeposit',
        });
        result = submitResult.result;
        transactionMeta = submitResult.transactionMeta;
      }

      // Store the transaction ID and try to get amount from transaction
      this.update((state) => {
        state.lastDepositTransactionId = transactionMeta.id;
      });

      // Track the transaction lifecycle only when using submit (deposit-only flow)
      if (!placeOrder) {
        // At this point, the confirmation modal is shown to the user
        // The result promise will resolve/reject based on user action and transaction outcome

        // Track the transaction lifecycle
        // The result promise will resolve/reject based on user action and transaction outcome
        // Note: We intentionally don't set depositInProgress immediately to avoid
        // showing toasts before the user confirms the transaction

        // TODO: @abretonc7s Find a better way to trigger our custom toast notification then having to toggle the state
        // How to replace the system notifications?
        result
          .then((actualTxHash) => {
            // Transaction was successfully completed
            // Set depositInProgress to true temporarily to show success
            this.update((state) => {
              state.depositInProgress = true;
              state.lastDepositResult = {
                success: true,
                txHash: actualTxHash,
                amount: amount ?? '0',
                asset: USDC_SYMBOL, // Default asset for deposits
                timestamp: Date.now(),
                error: '',
              };

              // Update the deposit request by request ID to avoid race conditions
              if (state.depositRequests.length > 0) {
                const requestToUpdate = state.depositRequests.find(
                  (req) => req.id === currentDepositId,
                );
                if (requestToUpdate) {
                  // For deposits, we have a txHash immediately, so mark as completed
                  // (the transaction hash means the deposit was successful)
                  requestToUpdate.status = 'completed' as TransactionStatus;
                  requestToUpdate.success = true;
                  requestToUpdate.txHash = actualTxHash;
                }
              }
            });

            // Clear depositInProgress after a short delay
            setTimeout(() => {
              this.update((state) => {
                state.depositInProgress = false;
                state.lastDepositTransactionId = null;
              });
            }, 100);

            return undefined;
          })
          .catch((error) => {
            // Check if user denied/cancelled the transaction
            const errorMessage = ensureError(
              error,
              'PerpsController.initiateDeposit',
            ).message;
            const userCancelled =
              errorMessage.includes('User denied') ||
              errorMessage.includes('User rejected') ||
              errorMessage.includes('User cancelled') ||
              errorMessage.includes('User canceled');

            if (userCancelled) {
              // User cancelled - clear any state, no toast
              this.update((state) => {
                state.depositInProgress = false;
                state.lastDepositTransactionId = null;
                // Don't set lastDepositResult - no toast needed

                // Mark deposit request as cancelled
                const requestToUpdate = state.depositRequests.find(
                  (req) => req.id === currentDepositId,
                );
                if (requestToUpdate) {
                  requestToUpdate.status = 'cancelled' as TransactionStatus;
                  requestToUpdate.success = false;
                }
              });
            } else {
              // Transaction failed after confirmation - show error toast
              this.update((state) => {
                state.depositInProgress = false;
                state.lastDepositTransactionId = null;
                state.lastDepositResult = {
                  success: false,
                  error: errorMessage,
                  amount: amount ?? '0',
                  asset: USDC_SYMBOL, // Default asset for deposits
                  timestamp: Date.now(),
                  txHash: '',
                };

                // Update the deposit request by request ID to avoid race conditions
                if (state.depositRequests.length > 0) {
                  const requestToUpdate = state.depositRequests.find(
                    (req) => req.id === currentDepositId,
                  );
                  if (requestToUpdate) {
                    requestToUpdate.status = 'failed' as TransactionStatus;
                    requestToUpdate.success = false;
                  }
                }
              });
            }
          });
      } else if (depositOrderResult) {
        // Track deposit request lifecycle for deposit+order flow
        depositOrderResult
          .then((actualTxHash) => {
            this.update((state) => {
              const requestToUpdate = state.depositRequests.find(
                (req) => req.id === currentDepositId,
              );
              if (requestToUpdate) {
                requestToUpdate.status = 'completed' as TransactionStatus;
                requestToUpdate.success = true;
                requestToUpdate.txHash = actualTxHash;
              }
            });
            return undefined;
          })
          .catch((error) => {
            const errorMessage = ensureError(
              error,
              'PerpsController.depositWithOrder',
            ).message;
            const isCancellation =
              errorMessage.includes('User denied') ||
              errorMessage.includes('User rejected') ||
              errorMessage.includes('User cancelled') ||
              errorMessage.includes('User canceled');
            this.update((state) => {
              const requestToUpdate = state.depositRequests.find(
                (req) => req.id === currentDepositId,
              );
              if (requestToUpdate) {
                requestToUpdate.status = (
                  isCancellation ? 'cancelled' : 'failed'
                ) as TransactionStatus;
                requestToUpdate.success = false;
              }
            });
          });
      }

      return {
        result,
      };
    } catch (error) {
      // Check if user denied/cancelled the transaction
      const errorMessage = ensureError(
        error,
        'PerpsController.initiateDeposit',
      ).message;
      const userCancelled =
        errorMessage.includes('User denied') ||
        errorMessage.includes('User rejected') ||
        errorMessage.includes('User cancelled') ||
        errorMessage.includes('User canceled');

      if (!userCancelled) {
        // Only track actual errors, not user cancellations
        this.update((state) => {
          state.lastDepositTransactionId = null;
          // Note: lastDepositResult is already set in the catch block above

          // Mark deposit request as failed if one was created
          if (currentDepositId) {
            const request = state.depositRequests.find(
              (req) => req.id === currentDepositId,
            );
            if (request) {
              request.status = 'failed' as TransactionStatus;
              request.success = false;
            }
          }
        });
      }
      throw error;
    }
  }

  /**
   * Same as depositWithConfirmation - prepares transaction for confirmation screen.
   *
   * @returns A promise that resolves to the string result.
   */
  async depositWithOrder(): Promise<{ result: Promise<string> }> {
    return this.depositWithConfirmation({ placeOrder: true });
  }

  /**
   * Clear the last deposit result after it has been shown to the user
   */
  clearDepositResult(): void {
    this.update((state) => {
      state.lastDepositResult = null;
    });
  }

  clearWithdrawResult(): void {
    this.update((state) => {
      state.lastWithdrawResult = null;
    });
  }

  /**
   * Update withdrawal request status when it completes, or remove it on failure.
   * This is called when a withdrawal is matched with a completed withdrawal from the API.
   * When status is `failed`, the request is removed from the queue (not retained).
   *
   * @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 {
    let withdrawalAmount: string | undefined;
    let shouldTrack = false;
    let found = false;

    this.update((state) => {
      const withdrawalIndex = state.withdrawalRequests.findIndex(
        (request) => request.id === withdrawalId,
      );

      if (withdrawalIndex >= 0) {
        found = true;
        const request = state.withdrawalRequests[withdrawalIndex];
        withdrawalAmount = request.amount;
        shouldTrack =
          withdrawalAmount !== undefined && request.status !== status;

        if (status === 'failed') {
          state.withdrawalRequests.splice(withdrawalIndex, 1);
          state.withdrawInProgress = state.withdrawalRequests.some(
            (req) => req.status === 'pending' || req.status === 'bridging',
          );
          state.withdrawalProgress = {
            progress: 0,
            lastUpdated: Date.now(),
            activeWithdrawalId: null,
          };
        } else {
          request.status = status;
          request.success = status === 'completed';
          if (txHash) {
            request.txHash = txHash;
          }

          // Clear withdrawal progress when withdrawal completes
          state.withdrawalProgress = {
            progress: 0,
            lastUpdated: Date.now(),
            activeWithdrawalId: null,
          };
        }
      }
    });

    if (shouldTrack && withdrawalAmount !== undefined) {
      this.#getMetrics().trackPerpsEvent(
        PerpsAnalyticsEvent.WithdrawalTransaction,
        {
          [PERPS_EVENT_PROPERTY.STATUS]:
            status === 'completed'
              ? PERPS_EVENT_VALUE.STATUS.COMPLETED
              : PERPS_EVENT_VALUE.STATUS.FAILED,
          [PERPS_EVENT_PROPERTY.WITHDRAWAL_AMOUNT]:
            Number.parseFloat(withdrawalAmount),
        },
      );
    }

    if (found) {
      this.#debugLog('PerpsController: Updated withdrawal status', {
        withdrawalId,
        status,
        txHash,
      });
    }
  }

  /**
   * Complete a specific withdrawal detected via transaction history polling (FIFO queue).
   * Called when a completed withdrawal appears in the transaction history matching a pending request.
   *
   * Uses FIFO matching: oldest pending withdrawal is matched with first completed withdrawal
   * in history that happened after its submission time.
   *
   * @param withdrawalRequestId - The ID of the pending withdrawal request to mark as complete.
   * @param completedWithdrawal - The completed withdrawal data from the history API.
   * @param completedWithdrawal.txHash - The on-chain transaction hash.
   * @param completedWithdrawal.amount - The withdrawal amount.
   * @param completedWithdrawal.timestamp - The completion timestamp from the history API.
   * @param completedWithdrawal.asset - The asset symbol (e.g. USDC).
   */
  completeWithdrawalFromHistory(
    withdrawalRequestId: string,
    completedWithdrawal: {
      txHash: string;
      amount: string;
      timestamp: number;
      asset?: string;
    },
  ): void {
    let didRemove = false;
    this.update((state) => {
      const requestIndex = state.withdrawalRequests.findIndex(
        (req) => req.id === withdrawalRequestId,
      );

      if (requestIndex === -1) {
        return;
      }

      didRemove = true;
      state.withdrawalRequests.splice(requestIndex, 1);

      // Update the FIFO guard. The timestamp is persisted for cross-restart
      // protection. The txHashes array (not persisted) accumulates within a
      // session to prevent re-matching direct completions and same-millisecond
      // API completions. It resets naturally on app restart.
      state.lastCompletedWithdrawalTimestamp = completedWithdrawal.timestamp;
      state.lastCompletedWithdrawalTxHashes.push(completedWithdrawal.txHash);

      const hasPendingWithdrawals = state.withdrawalRequests.some(
        (req) => req.status === 'pending' || req.status === 'bridging',
      );

      state.withdrawInProgress = hasPendingWithdrawals;

      if (!hasPendingWithdrawals) {
        state.withdrawalProgress = {
          progress: 0,
          lastUpdated: Date.now(),
          activeWithdrawalId: null,
        };
      }

      state.lastUpdateTimestamp = Date.now();
    });

    if (!didRemove) {
      return;
    }

    this.#debugLog(
      'PerpsController: Completed withdrawal from transaction history (FIFO)',
      {
        withdrawalRequestId,
        txHash: completedWithdrawal.txHash,
        amount: completedWithdrawal.amount,
      },
    );

    this.#getMetrics().trackPerpsEvent(
      PerpsAnalyticsEvent.WithdrawalTransaction,
      {
        [PERPS_EVENT_PROPERTY.STATUS]: PERPS_EVENT_VALUE.STATUS.COMPLETED,
        [PERPS_EVENT_PROPERTY.WITHDRAWAL_AMOUNT]: Number.parseFloat(
          completedWithdrawal.amount,
        ),
      },
    );
  }

  /**
   * Update withdrawal progress (persistent across navigation)
   *
   * @param progress - The progress indicator.
   * @param activeWithdrawalId - The active withdrawal ID.
   */
  updateWithdrawalProgress(
    progress: number,
    activeWithdrawalId: string | null = null,
  ): void {
    this.update((state) => {
      state.withdrawalProgress = {
        progress,
        lastUpdated: Date.now(),
        activeWithdrawalId,
      };
    });
  }

  /**
   * Get current withdrawal progress
   *
   * @returns The withdrawal progress, last update timestamp, and active withdrawal ID.
   */
  getWithdrawalProgress(): {
    progress: number;
    lastUpdated: number;
    activeWithdrawalId: string | null;
  } {
    return this.state.withdrawalProgress;
  }

  /**
   * 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
   */
  async withdraw(params: WithdrawParams): Promise<WithdrawResult> {
    const provider = this.getActiveProvider();

    return this.#accountService.withdraw({
      provider,
      params,
      context: this.#createServiceContext('withdraw'),
      refreshAccountState: async () => {
        await this.getAccountState({ source: 'post_withdrawal' });
      },
    });
  }

  /**
   * 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.
   */
  async getPositions(params?: GetPositionsParams): Promise<Position[]> {
    // For standalone mode, access provider directly without initialization check
    // This allows discovery use cases (checking if user has positions) without full perps setup
    if (params?.standalone && params.userAddress) {
      // Use activeProviderInstance if available (respects provider abstraction)
      // Fallback to cached standalone provider for pre-initialization discovery
      // TODO: When adding new providers (MYX), consider a provider factory pattern
      const provider =
        this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
      return provider.getPositions(params);
    }

    const provider = this.getActiveProvider();
    return this.#marketDataService.getPositions({
      provider,
      params,
      context: this.#createServiceContext('getPositions'),
    });
  }

  /**
   * Get historical user fills (trade executions)
   * Thin delegation to MarketDataService
   *
   * @param params - The operation parameters.
   * @param options - Optional call modifiers.
   * @param options.forceRefresh - Bypass the request-coalesce cache
   * end-to-end (user-initiated refresh).
   * @returns Array of historical trade executions (fills).
   */
  async getOrderFills(
    params?: GetOrderFillsParams,
    options?: { forceRefresh?: boolean },
  ): Promise<OrderFill[]> {
    const provider = this.getActiveProvider();
    return this.#marketDataService.getOrderFills({
      provider,
      params,
      context: this.#createServiceContext('getOrderFills'),
      forceRefresh: options?.forceRefresh,
    });
  }

  /**
   * Get historical user orders (order lifecycle)
   * Thin delegation to MarketDataService
   *
   * @param params - The operation parameters.
   * @param options - Optional call modifiers.
   * @param options.forceRefresh - Bypass the request-coalesce cache
   * end-to-end (user-initiated refresh).
   * @returns Array of historical orders.
   */
  async getOrders(
    params?: GetOrdersParams,
    options?: { forceRefresh?: boolean },
  ): Promise<Order[]> {
    const provider = this.getActiveProvider();
    return this.#marketDataService.getOrders({
      provider,
      params,
      context: this.#createServiceContext('getOrders'),
      forceRefresh: options?.forceRefresh,
    });
  }

  /**
   * 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.
   */
  async getOpenOrders(params?: GetOrdersParams): Promise<Order[]> {
    // For standalone mode, access provider directly without initialization check
    if (params?.standalone && params.userAddress) {
      const provider =
        this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
      return provider.getOpenOrders(params);
    }

    const provider = this.getActiveProvider();
    return this.#marketDataService.getOpenOrders({
      provider,
      params,
      context: this.#createServiceContext('getOpenOrders'),
    });
  }

  /**
   * Get historical user funding history (funding payments)
   * Thin delegation to MarketDataService
   *
   * @param params - The operation parameters.
   * @param options - Optional call modifiers.
   * @param options.forceRefresh - Bypass the request-coalesce cache
   * end-to-end (user-initiated refresh).
   * @returns Array of historical funding payments.
   */
  async getFunding(
    params?: GetFundingParams,
    options?: { forceRefresh?: boolean },
  ): Promise<Funding[]> {
    const provider = this.getActiveProvider();
    return this.#marketDataService.getFunding({
      provider,
      params,
      context: this.#createServiceContext('getFunding'),
      forceRefresh: options?.forceRefresh,
    });
  }

  /**
   * 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.
   */
  async getAccountState(params?: GetAccountStateParams): Promise<AccountState> {
    // For standalone mode, access provider directly without initialization check
    // This allows discovery use cases (checking if user has perps funds) without full perps setup
    if (params?.standalone && params.userAddress) {
      // Use activeProviderInstance if available (respects provider abstraction)
      // Fallback to cached standalone provider for pre-initialization discovery
      const provider =
        this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
      return provider.getAccountState(params);
    }

    const provider = this.getActiveProvider();
    return this.#marketDataService.getAccountState({
      provider,
      params,
      context: this.#createServiceContext('getAccountState'),
    });
  }

  /**
   * Get historical portfolio data
   * Thin delegation to MarketDataService
   *
   * @param params - The operation parameters.
   * @returns The historical portfolio data points.
   */
  async getHistoricalPortfolio(
    params?: GetHistoricalPortfolioParams,
  ): Promise<HistoricalPortfolioResult> {
    const provider = this.getActiveProvider();
    return this.#marketDataService.getHistoricalPortfolio({
      provider,
      params,
      context: this.#createServiceContext('getHistoricalPortfolio'),
    });
  }

  /**
   * 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.
   */
  async getMarkets(params?: GetMarketsParams): Promise<MarketInfo[]> {
    // For standalone mode, access provider directly without initialization check
    // This allows discovery use cases (checking if market exists) without full perps setup
    if (params?.standalone) {
      // Use activeProviderInstance if available (respects provider abstraction)
      // Fallback to cached standalone provider for pre-initialization discovery
      const provider =
        this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
      return provider.getMarkets(params);
    }

    const provider = this.getActiveProvider();
    return this.#marketDataService.getMarkets({
      provider,
      params,
      context: this.#createServiceContext('getMarkets'),
    });
  }

  /**
   * 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.
   */
  async getMarketDataWithPrices(params?: {
    standalone?: boolean;
  }): Promise<PerpsMarketData[]> {
    if (params?.standalone) {
      // Use activeProviderInstance if available (respects provider abstraction)
      // Fallback to cached standalone provider for pre-initialization discovery
      const provider =
        this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
      return provider.getMarketDataWithPrices();
    }

    const provider = this.getActiveProvider();
    return provider.getMarketDataWithPrices();
  }

  // ============================================================================
  // Market Data Preload (client-agnostic background caching)
  // ============================================================================

  /** State paths that the preload stateChange handler reads. */
  static readonly #preloadWatchedPaths = new Set([
    'isTestnet',
    'hip3ConfigVersion',
  ]);

  #preloadTimer: ReturnType<typeof setInterval> | null = null;
  #isPreloading = false;
  #isPreloadingUserData = false;
  #preloadStateUnsubscribe: (() => void) | null = null;
  #accountChangeUnsubscribe: (() => void) | null = null;
  #previousIsTestnet: boolean | null = null;
  #previousHip3ConfigVersion: number | null = null;
  static readonly #preloadRefreshMs = 5 * 60 * 1000; // 5 min
  static readonly #preloadGuardMs = 30_000; // 30s debounce

  /**
   * Synchronously hydrate in-memory caches from disk-persisted snapshots.
   * Uses the sync MMKV API (~1ms) so data is available before any hook reads.
   * Falls back to no-op when getItemSync is not available (e.g. E2E).
   * All computed updates are applied in a single this.update() call to avoid
   * triggering state subscribers once per provider entry.
   */
  #hydrateCacheFromDiskSync(): void {
    const { marketUpdates, userUpdates, stats } = hydrateFromDiskSync(
      this.#options.infrastructure.diskCache,
      this.state.cachedMarketDataByProvider,
      this.state.cachedUserDataByProvider,
      PerpsController.#preloadGuardMs,
    );

    const hasMarketUpdates = Object.keys(marketUpdates).length > 0;
    const hasUserUpdates = Object.keys(userUpdates).length > 0;
    if (hasMarketUpdates || hasUserUpdates) {
      this.update((state) => {
        if (hasMarketUpdates) {
          Object.assign(state.cachedMarketDataByProvider, marketUpdates);
        }
        if (hasUserUpdates) {
          Object.assign(state.cachedUserDataByProvider, userUpdates);
        }
      });
    }

    this.#debugLog('PerpsController: Disk cache hydrated (sync)', {
      markets: stats.marketCount,
      positions: stats.userPositions,
      orders: stats.userOrders,
      duration_ms: stats.durationMs,
    });
  }

  /**
   * 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 {
    if (this.#preloadTimer) {
      this.#debugLog('PerpsController: Preload already started, skipping');
      return;
    }

    this.#debugLog('PerpsController: Starting market data preload');

    // Track current values for change detection
    this.#previousIsTestnet = this.state.isTestnet;
    this.#previousHip3ConfigVersion = this.state.hip3ConfigVersion;

    // Immediate preload
    this.#performMarketDataPreload().catch(() => {
      /* fire-and-forget */
    });

    // Periodic refresh
    this.#preloadTimer = setInterval(() => {
      this.#performMarketDataPreload().catch(() => {
        /* fire-and-forget */
      });
    }, PerpsController.#preloadRefreshMs);

    // Watch for isTestnet / hip3ConfigVersion changes
    const handler: StateChangeListener<PerpsControllerState> = (
      _state,
      patches,
    ) => {
      // Early-return when no watched field changed (skips ~46 unrelated updates)
      const hasRelevantChange = patches.some(
        (patch) =>
          typeof patch.path[0] === 'string' &&
          PerpsController.#preloadWatchedPaths.has(patch.path[0]),
      );
      if (!hasRelevantChange) {
        return;
      }

      const currentIsTestnet = this.state.isTestnet;
      const currentHip3Version = this.state.hip3ConfigVersion;

      const testnetChanged = currentIsTestnet !== this.#previousIsTestnet;
      const hip3Changed =
        currentHip3Version !== this.#previousHip3ConfigVersion;

      if (testnetChanged || hip3Changed) {
        this.#debugLog(
          'PerpsController: Network/config changed, re-preloading',
          {
            testnetChanged,
            hip3Changed,
            isTestnet: currentIsTestnet,
            hip3ConfigVersion: currentHip3Version,
          },
        );

        this.#previousIsTestnet = currentIsTestnet;
        this.#previousHip3ConfigVersion = currentHip3Version;

        // No need to clear user data cache — per-provider keys include the
        // network, so different networks don't collide. Re-preload will
        // populate the new key.

        this.#performMarketDataPreload().catch(() => {
          /* fire-and-forget */
        });
      }
    };

    this.messenger.subscribe('PerpsController:stateChange', handler);
    this.#preloadStateUnsubscribe = (): void => {
      this.messenger.unsubscribe('PerpsController:stateChange', handler);
    };

    // Watch for account changes via AccountTreeController
    const accountChangeHandler = (): void => {
      const evmAccount = getSelectedEvmAccountFromMessenger(this.messenger);
      const currentAddress = evmAccount?.address ?? null;

      // If any cached entry belongs to a different account, clear all entries.
      // Max 4 entries (2 providers × 2 networks) — clearing all is simple and safe.
      const hasStaleEntries = Object.values(
        this.state.cachedUserDataByProvider,
      ).some(
        (entry) =>
          currentAddress === null ||
          entry.address.toLowerCase() !== currentAddress.toLowerCase(),
      );
      if (hasStaleEntries) {
        this.#debugLog(
          'PerpsController: Account changed, clearing user data cache',
        );
        this.update((state) => {
          state.cachedUserDataByProvider = {};
        });
        // Invalidate disk-cached user data for the old account
        this.#options.infrastructure.diskCache
          .removeItem(PERPS_DISK_CACHE_USER_DATA)
          .catch(() => {
            /* fire-and-forget */
          });
        // Only preload if the new account is an EVM account
        if (currentAddress) {
          this.#performUserDataPreload().catch(() => {
            /* fire-and-forget */
          });
        }
      }
    };
    this.messenger.subscribe(
      'AccountTreeController:selectedAccountGroupChange',
      accountChangeHandler,
    );
    this.#accountChangeUnsubscribe = (): void => {
      this.messenger.unsubscribe(
        'AccountTreeController:selectedAccountGroupChange',
        accountChangeHandler,
      );
    };
  }

  /**
   * Stop background market data preloading.
   */
  stopMarketDataPreload(): void {
    this.#debugLog('PerpsController: Stopping market data preload');
    if (this.#preloadTimer) {
      clearInterval(this.#preloadTimer);
      this.#preloadTimer = null;
    }
    if (this.#preloadStateUnsubscribe) {
      this.#preloadStateUnsubscribe();
      this.#preloadStateUnsubscribe = null;
    }
    if (this.#accountChangeUnsubscribe) {
      this.#accountChangeUnsubscribe();
      this.#accountChangeUnsubscribe = null;
    }
    this.#previousIsTestnet = null;
    this.#previousHip3ConfigVersion = null;
    this.#cleanupStandaloneProvider().catch(() => {
      /* fire-and-forget to preserve sync signature */
    });
  }

  /**
   * Perform a single market data preload (best-effort, no throw).
   */
  async #performMarketDataPreload(): Promise<void> {
    if (this.#isPreloading) {
      return;
    }

    // Skip preloading during provider/network reinitialisation.
    // The activeProviderInstance still points to the OLD network's provider
    // until init() completes, so fetching now would store stale data under
    // the NEW network's cache key.
    if (this.#isReinitializing) {
      return;
    }

    // Determine actual provider and cache key for debounce
    const actualProviderId = this.activeProviderInstance
      ? this.state.activeProvider // includes 'aggregated'
      : 'hyperliquid';
    const cacheKey = buildProviderCacheKey(
      actualProviderId,
      this.state.isTestnet,
    );

    const now = Date.now();
    const existingEntry = this.state.cachedMarketDataByProvider[cacheKey];
    if (
      existingEntry &&
      now - existingEntry.timestamp < PerpsController.#preloadGuardMs
    ) {
      return;
    }

    this.#isPreloading = true;
    const traceId = uuidv4();
    const preloadStart = performance.now();
    let traceData:
      | { success: boolean; marketCount?: number; error?: string }
      | undefined;

    try {
      this.#options.infrastructure.tracer.trace({
        name: PerpsTraceNames.MarketDataPreload,
        id: traceId,
        op: PerpsTraceOperations.Operation,
        tags: {
          provider: this.state.activeProvider,
          isTestnet: this.state.isTestnet,
        },
      });

      this.#debugLog('PerpsController: Fetching market data in background');
      this.#debugLog('PerpsController: rest_preload_start');
      const data = await this.getMarketDataWithPrices({ standalone: true });
      this.#debugLog('PerpsController: rest_preload_end', {
        duration_ms: Math.round(performance.now() - preloadStart),
        markets: data.length,
      });

      // Store under per-provider key(s)
      const ts = Date.now();
      const marketDiskEntries: {
        providerNetworkKey: string;
        data: PerpsMarketData[];
        timestamp: number;
      }[] = [];
      if (
        this.state.activeProvider === 'aggregated' &&
        this.activeProviderInstance
      ) {
        // Split returned data by providerId and store each slice
        const fallbackProviderId = 'hyperliquid'; // default for items missing providerId
        const byProvider = new Map<string, PerpsMarketData[]>();
        for (const item of data) {
          const pid = item.providerId ?? fallbackProviderId;
          const existing = byProvider.get(pid);
          if (existing) {
            existing.push(item);
          } else {
            byProvider.set(pid, [item]);
          }
        }
        this.update((state) => {
          for (const [pid, slice] of byProvider) {
            const key = buildProviderCacheKey(pid, this.state.isTestnet);
            marketDiskEntries.push({
              providerNetworkKey: key,
              data: slice,
              timestamp: ts,
            });
            state.cachedMarketDataByProvider[key] = {
              data: slice,
              timestamp: ts,
            };
          }
          // Write aggregated sentinel so the staleness guard sees it
          state.cachedMarketDataByProvider[cacheKey] = {
            data: [], // sentinel — real data is in per-provider keys
            timestamp: ts,
          };
        });
      } else {
        marketDiskEntries.push({
          providerNetworkKey: cacheKey,
          data,
          timestamp: ts,
        });
        this.update((state) => {
          state.cachedMarketDataByProvider[cacheKey] = {
            data,
            timestamp: ts,
          };
        });
      }

      persistMarketEntriesToDisk(
        this.#options.infrastructure.diskCache,
        marketDiskEntries,
      );

      this.#debugLog('PerpsController: Market data preloaded', {
        marketCount: data.length,
      });

      traceData = { success: true, marketCount: data.length };

      this.#options.infrastructure.tracer.setMeasurement(
        PerpsMeasurementName.PerpsMarketDataPreload,
        performance.now() - preloadStart,
        'millisecond',
      );

      // Also preload user data (fire-and-forget, non-blocking)
      this.#performUserDataPreload().catch(() => {
        /* fire-and-forget */
      });
    } catch (error) {
      traceData = {
        success: false,
        error: ensureError(error, 'PerpsController.performMarketDataPreload')
          .message,
      };
      this.#logError(
        ensureError(error, 'PerpsController.performMarketDataPreload'),
        this.#getErrorContext('performMarketDataPreload', {
          message: 'Background preload failed',
        }),
      );
    } finally {
      this.#options.infrastructure.tracer.endTrace({
        name: PerpsTraceNames.MarketDataPreload,
        id: traceId,
        data: traceData,
      });
      this.#isPreloading = false;
    }
  }

  /**
   * Perform a single user data preload (best-effort, no throw).
   * Fetches positions, open orders, and account state via lightweight REST calls.
   */
  async #performUserDataPreload(): Promise<void> {
    if (this.#isPreloadingUserData) {
      return;
    }

    // Get current user address
    const evmAccount = getSelectedEvmAccountFromMessenger(this.messenger);
    if (!evmAccount?.address) {
      return;
    }

    const userAddress = evmAccount.address;

    // Determine actual provider (same logic as market preload)
    const actualProviderId = this.activeProviderInstance
      ? this.state.activeProvider // includes 'aggregated'
      : 'hyperliquid';
    const userCacheKey = buildProviderCacheKey(
      actualProviderId,
      this.state.isTestnet,
    );

    // Skip if cache is fresh and for same account
    const now = Date.now();
    const existingEntry = this.state.cachedUserDataByProvider[userCacheKey];
    if (
      existingEntry &&
      existingEntry.address === userAddress &&
      now - existingEntry.timestamp < PerpsController.#preloadGuardMs
    ) {
      return;
    }

    // Skip standalone REST polling when WebSocket is connected — live data is streaming
    if (
      this.getWebSocketConnectionState() === WebSocketConnectionState.Connected
    ) {
      this.#debugLog(
        'PerpsController: Skipping user data preload — WebSocket connected',
      );
      return;
    }

    this.#isPreloadingUserData = true;
    const traceId = uuidv4();
    const preloadStart = performance.now();
    let traceData:
      | {
          success: boolean;
          positionCount?: number;
          orderCount?: number;
          error?: string;
        }
      | undefined;

    try {
      this.#options.infrastructure.tracer.trace({
        name: PerpsTraceNames.UserDataPreload,
        id: traceId,
        op: PerpsTraceOperations.Operation,
        tags: {
          provider: this.state.activeProvider,
          isTestnet: this.state.isTestnet,
        },
        data: { userAddress },
      });

      this.#debugLog('PerpsController: Fetching user data in background', {
        userAddress,
      });

      const [positions, orders, accountState] = await Promise.all([
        this.getPositions({ standalone: true, userAddress }),
        this.getOpenOrders({ standalone: true, userAddress }),
        this.getAccountState({ standalone: true, userAddress }),
      ]);

      if (
        this.state.activeProvider === 'aggregated' &&
        this.activeProviderInstance
      ) {
        // Split by providerId and write one cache entry per provider key
        // (mirrors the market-data preload pattern at ~line 2976)
        const ts = Date.now();
        type UserDataBucket = {
          positions: typeof positions;
          orders: typeof orders;
          accountState: typeof accountState | null;
        };
        const fallbackProviderId = 'hyperliquid'; // default for items missing providerId
        const byProvider = new Map<string, UserDataBucket>();

        const ensureBucket = (pid: string): UserDataBucket => {
          let bucket = byProvider.get(pid);
          if (!bucket) {
            bucket = { positions: [], orders: [], accountState: null };
            byProvider.set(pid, bucket);
          }
          return bucket;
        };

        for (const pos of positions) {
          ensureBucket(pos.providerId ?? fallbackProviderId).positions.push(
            pos,
          );
        }

        for (const order of orders) {
          ensureBucket(order.providerId ?? fallbackProviderId).orders.push(
            order,
          );
        }

        // AccountState — assign to its provider bucket
        ensureBucket(
          accountState.providerId ?? fallbackProviderId,
        ).accountState = accountState;

        const diskEntries: {
          providerNetworkKey: string;
          address: string;
          positions: Position[];
          orders: Order[];
          accountState: AccountState | null;
          timestamp: number;
        }[] = [];
        this.update((state) => {
          for (const [pid, data] of byProvider) {
            const key = buildProviderCacheKey(pid, this.state.isTestnet);
            diskEntries.push({
              providerNetworkKey: key,
              address: userAddress,
              positions: data.positions,
              orders: data.orders,
              accountState: data.accountState,
              timestamp: ts,
            });
            state.cachedUserDataByProvider[key] = {
              ...data,
              timestamp: ts,
              address: userAddress,
            };
          }
          // Write aggregated sentinel so the staleness guard sees it
          state.cachedUserDataByProvider[userCacheKey] = {
            positions: [],
            orders: [],
            accountState: null,
            timestamp: ts,
            address: userAddress,
          };
        });

        persistUserEntriesToDisk(
          this.#options.infrastructure.diskCache,
          diskEntries,
        );
      } else {
        // Single provider — store directly under its key
        const ts = Date.now();
        this.update((state) => {
          state.cachedUserDataByProvider[userCacheKey] = {
            positions,
            orders,
            accountState,
            timestamp: ts,
            address: userAddress,
          };
        });

        persistUserEntriesToDisk(this.#options.infrastructure.diskCache, [
          {
            providerNetworkKey: userCacheKey,
            address: userAddress,
            positions,
            orders,
            accountState,
            timestamp: ts,
          },
        ]);
      }

      this.#debugLog('PerpsController: User data preloaded', {
        positionCount: positions.length,
        orderCount: orders.length,
        totalBalance: accountState.totalBalance,
      });

      traceData = {
        success: true,
        positionCount: positions.length,
        orderCount: orders.length,
      };

      this.#options.infrastructure.tracer.setMeasurement(
        PerpsMeasurementName.PerpsUserDataPreload,
        performance.now() - preloadStart,
        'millisecond',
      );
    } catch (error) {
      traceData = {
        success: false,
        error: ensureError(error, 'PerpsController.performUserDataPreload')
          .message,
      };
      this.#logError(
        ensureError(error, 'PerpsController.performUserDataPreload'),
        this.#getErrorContext('performUserDataPreload', {
          message: 'Background user data preload failed',
        }),
      );
    } finally {
      this.#options.infrastructure.tracer.endTrace({
        name: PerpsTraceNames.UserDataPreload,
        id: traceId,
        data: traceData,
      });
      this.#isPreloadingUserData = false;
    }
  }

  /**
   * Get list of available HIP-3 builder-deployed DEXs
   *
   * @param params - Optional parameters for filtering
   * @returns Array of DEX names
   */
  async getAvailableDexs(params?: GetAvailableDexsParams): Promise<string[]> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('getAvailableDexs');
    return this.#marketDataService.getAvailableDexs({
      provider,
      params,
      context,
    });
  }

  /**
   * 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.
   */
  async fetchHistoricalCandles(options: {
    symbol: string;
    interval: CandlePeriod;
    limit?: number;
    endTime?: number;
  }): Promise<CandleData> {
    const { symbol, interval, limit = 100, endTime } = options;
    const provider = this.getActiveProvider();
    return this.#marketDataService.fetchHistoricalCandles({
      provider,
      symbol,
      interval,
      limit,
      endTime,
      context: this.#createServiceContext('fetchHistoricalCandles'),
    });
  }

  /**
   * 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.
   */
  async calculateLiquidationPrice(
    params: LiquidationPriceParams,
  ): Promise<string> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('calculateLiquidationPrice');
    return this.#marketDataService.calculateLiquidationPrice({
      provider,
      params,
      context,
    });
  }

  /**
   * 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.
   */
  async calculateMaintenanceMargin(
    params: MaintenanceMarginParams,
  ): Promise<number> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('calculateMaintenanceMargin');
    return this.#marketDataService.calculateMaintenanceMargin({
      provider,
      params,
      context,
    });
  }

  /**
   * Get maximum leverage allowed for an asset
   *
   * @param asset - The asset identifier.
   * @returns A promise that resolves to the numeric result.
   */
  async getMaxLeverage(asset: string): Promise<number> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('getMaxLeverage');
    return this.#marketDataService.getMaxLeverage({ provider, asset, context });
  }

  /**
   * Validate order parameters according to protocol-specific rules
   *
   * @param params - The operation parameters.
   * @returns True if the condition is met.
   */
  async validateOrder(
    params: OrderParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('validateOrder');
    return this.#marketDataService.validateOrder({ provider, params, context });
  }

  /**
   * Validate close position parameters according to protocol-specific rules
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async validateClosePosition(
    params: ClosePositionParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('validateClosePosition');
    return this.#marketDataService.validateClosePosition({
      provider,
      params,
      context,
    });
  }

  /**
   * Validate withdrawal parameters according to protocol-specific rules
   *
   * @param params - The operation parameters.
   * @returns True if the condition is met.
   */
  async validateWithdrawal(
    params: WithdrawParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    const provider = this.getActiveProvider();
    return this.#accountService.validateWithdrawal({ provider, params });
  }

  /**
   * Get supported withdrawal routes - returns complete asset and routing information
   *
   * @returns Array of supported asset routes for withdrawals.
   */
  getWithdrawalRoutes(): AssetRoute[] {
    try {
      const provider = this.getActiveProvider();
      return this.#marketDataService.getWithdrawalRoutes({ provider });
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.getWithdrawalRoutes'),
        this.#getErrorContext('getWithdrawalRoutes'),
      );
      // Return empty array if provider is not available
      return [];
    }
  }

  /**
   * Toggle between testnet and mainnet
   *
   * @returns The toggle result with success status and current network mode.
   */
  async toggleTestnet(): Promise<ToggleTestnetResult> {
    // Prevent concurrent reinitializations
    if (this.isCurrentlyReinitializing()) {
      this.#debugLog(
        'PerpsController: Already reinitializing, skipping toggle',
        {
          timestamp: new Date().toISOString(),
        },
      );
      return {
        success: false,
        isTestnet: this.state.isTestnet,
        error: PERPS_ERROR_CODES.CLIENT_REINITIALIZING,
      };
    }

    this.#isReinitializing = true;

    // Store previous isTestnet for rollback on failure
    const previousIsTestnet = this.state.isTestnet;

    try {
      await this.#cleanupStandaloneProvider();

      const previousNetwork = previousIsTestnet ? 'testnet' : 'mainnet';

      this.update((state) => {
        state.isTestnet = !state.isTestnet;
      });

      const newNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';

      this.#debugLog('PerpsController: Network toggle initiated', {
        from: previousNetwork,
        to: newNetwork,
        timestamp: new Date().toISOString(),
      });

      // Reset initialization state and reinitialize provider with new testnet setting
      this.isInitialized = false;
      this.#initializationPromise = null;
      await this.init();

      // Check if initialization actually succeeded — performInitialization()
      // does not throw on failure, it sets state to Failed and resolves.
      if (this.state.initializationState === InitializationState.Failed) {
        throw new Error(
          this.state.initializationError ??
            'Network toggle initialization failed',
        );
      }

      this.#debugLog('PerpsController: Network toggle completed', {
        newNetwork,
        isTestnet: this.state.isTestnet,
        timestamp: new Date().toISOString(),
      });

      return { success: true, isTestnet: this.state.isTestnet };
    } catch (error) {
      // Rollback isTestnet to previous value
      this.update((state) => {
        state.isTestnet = previousIsTestnet;
      });

      return {
        success: false,
        isTestnet: this.state.isTestnet,
        error: ensureError(error, 'PerpsController.toggleTestnet').message,
      };
    } finally {
      this.#isReinitializing = false;

      // Re-trigger preload now that reinit is complete and the
      // activeProviderInstance points to the correct network.
      // The state-change listener may have already fired during reinit
      // but was skipped due to the #isReinitializing guard.
      if (this.#preloadTimer) {
        this.#performMarketDataPreload().catch(() => {
          /* fire-and-forget */
        });
      }
    }
  }

  /**
   * 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.
   */
  async switchProvider(
    providerId: PerpsActiveProviderMode,
  ): Promise<SwitchProviderResult> {
    // No-op if already on this provider (regardless of init state)
    if (this.state.activeProvider === providerId) {
      return { success: true, providerId };
    }

    // Validate provider is available
    // 'aggregated' is always valid, individual providers must exist in the map
    const isValidProvider =
      providerId === 'aggregated' || this.providers.has(providerId);

    if (!isValidProvider) {
      return {
        success: false,
        providerId: this.state.activeProvider,
        error: `Provider ${providerId} not available`,
      };
    }

    // Prevent concurrent switches
    if (this.isCurrentlyReinitializing()) {
      return {
        success: false,
        providerId: this.state.activeProvider,
        error: PERPS_ERROR_CODES.CLIENT_REINITIALIZING,
      };
    }

    this.#isReinitializing = true;

    // Store previous provider for rollback on failure
    const previousProvider = this.state.activeProvider;

    try {
      await this.#cleanupStandaloneProvider();

      this.#debugLog('PerpsController: Provider switch initiated', {
        from: previousProvider,
        to: providerId,
        timestamp: new Date().toISOString(),
      });

      // Provider disconnect is handled by performInitialization() during
      // reinitialization. The disconnect() method skips provider teardown
      // when isReinitializing is true to prevent double-disconnect.

      // Update state with new provider (market data cache preserved per-provider)
      this.update((state) => {
        state.activeProvider = providerId;
        state.accountState = null;
        state.initializationState = InitializationState.Uninitialized;
      });

      // Reset initialization state and reinitialize
      this.isInitialized = false;
      this.#initializationPromise = null;
      await this.init();

      // Check if initialization actually succeeded — performInitialization()
      // does not throw on failure, it sets state to Failed and resolves.
      if (this.state.initializationState === InitializationState.Failed) {
        throw new Error(
          this.state.initializationError ?? 'Provider initialization failed',
        );
      }

      this.#debugLog('PerpsController: Provider switch completed', {
        providerId,
        timestamp: new Date().toISOString(),
      });

      return { success: true, providerId };
    } catch (error) {
      // Rollback state to previous provider
      this.update((state) => {
        state.activeProvider = previousProvider;
      });

      this.#logError(
        ensureError(error, 'PerpsController.switchProvider'),
        this.#getErrorContext('switchProvider', { providerId }),
      );

      // Attempt to reinitialize the previous provider via init(),
      // which handles all provider modes including 'aggregated'.
      try {
        this.isInitialized = false;
        this.#initializationPromise = null;
        await this.init();

        this.#debugLog(
          'PerpsController: Rollback to previous provider succeeded',
          {
            previousProvider,
            timestamp: new Date().toISOString(),
          },
        );
      } catch (reinitError) {
        // Reinit also failed — mark as failed
        this.update((state) => {
          state.initializationState = InitializationState.Failed;
        });
        this.#logError(
          ensureError(reinitError, 'PerpsController.switchProvider.rollback'),
          this.#getErrorContext('switchProvider.rollback', {
            previousProvider,
          }),
        );
      }

      return {
        success: false,
        providerId: previousProvider,
        error:
          error instanceof Error
            ? error.message
            : PERPS_ERROR_CODES.UNKNOWN_ERROR,
      };
    } finally {
      this.#isReinitializing = false;

      // Re-trigger preload now that reinit is complete.
      if (this.#preloadTimer) {
        this.#performMarketDataPreload().catch(() => {
          /* fire-and-forget */
        });
      }
    }
  }

  /**
   * Get current network (mainnet/testnet)
   *
   * @returns Either 'mainnet' or 'testnet' based on the current configuration.
   */
  getCurrentNetwork(): 'mainnet' | 'testnet' {
    return this.state.isTestnet ? 'testnet' : 'mainnet';
  }

  /**
   * 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 {
    try {
      const provider = this.getActiveProvider();
      if (provider.getWebSocketConnectionState) {
        return provider.getWebSocketConnectionState();
      }
      // Fallback for providers that don't support this method
      return WebSocketConnectionState.Disconnected;
    } catch {
      // If no provider is active, return disconnected
      return WebSocketConnectionState.Disconnected;
    }
  }

  /**
   * 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 {
    try {
      const provider = this.getActiveProvider();
      if (provider.subscribeToConnectionState) {
        return provider.subscribeToConnectionState(listener);
      }
      // Fallback: immediately call with current state and return no-op unsubscribe
      listener(this.getWebSocketConnectionState(), 0);
      return () => {
        // No-op
      };
    } catch {
      // If no provider is active, call with disconnected and return no-op
      listener(WebSocketConnectionState.Disconnected, 0);
      return () => {
        // No-op
      };
    }
  }

  /**
   * Manually trigger a WebSocket reconnection attempt.
   * Used by the UI retry button when connection is lost.
   */
  async reconnect(): Promise<void> {
    this.#debugLog('[PerpsController] reconnect() called');
    try {
      const provider = this.getActiveProvider();
      if (provider.reconnect) {
        this.#debugLog('[PerpsController] Delegating to provider.reconnect()');
        await provider.reconnect();
        this.#debugLog('[PerpsController] provider.reconnect() completed');
      } else {
        this.#debugLog(
          '[PerpsController] Provider does not support reconnect()',
        );
      }
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.reconnect'),
        this.#getErrorContext('reconnect', {
          operation: 'websocket_reconnect',
        }),
      );
    }
  }

  // Live data delegation (NO Redux) - delegates to active provider

  /**
   * Subscribe to live price updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToPrices(params: SubscribePricesParams): () => void {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToPrices(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToPrices'),
        this.#getErrorContext('subscribeToPrices', {
          symbols: params.symbols?.join(','),
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * Subscribe to live position updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToPositions(params: SubscribePositionsParams): () => void {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToPositions(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToPositions'),
        this.#getErrorContext('subscribeToPositions', {
          accountId: params.accountId,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * Subscribe to live order fill updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToOrderFills(params: SubscribeOrderFillsParams): () => void {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToOrderFills(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToOrderFills'),
        this.#getErrorContext('subscribeToOrderFills', {
          accountId: params.accountId,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * Subscribe to live order updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToOrders(params: SubscribeOrdersParams): () => void {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToOrders(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToOrders'),
        this.#getErrorContext('subscribeToOrders', {
          accountId: params.accountId,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * 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 {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      const originalCallback = params.callback;
      return provider.subscribeToAccount({
        ...params,
        callback: (account: AccountState | null) => {
          if (account) {
            this.update((state) => {
              state.accountState = account;
              state.lastUpdateTimestamp = Date.now();
              state.lastError = null;
            });
          }
          originalCallback(account);
        },
      });
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToAccount'),
        this.#getErrorContext('subscribeToAccount', {
          accountId: params.accountId,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * 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 {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToOrderBook(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToOrderBook'),
        this.#getErrorContext('subscribeToOrderBook', {
          symbol: params.symbol,
          levels: params.levels,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * Subscribe to live candle updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToCandles(params: SubscribeCandlesParams): () => void {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToCandles(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToCandles'),
        this.#getErrorContext('subscribeToCandles', {
          symbol: params.symbol,
          interval: params.interval,
          duration: params.duration,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * 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 {
    const provider = this.getActiveProviderOrNull();
    if (!provider) {
      return () => {
        // No-op: Provider not initialized
      };
    }
    try {
      return provider.subscribeToOICaps(params);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.subscribeToOICaps'),
        this.#getErrorContext('subscribeToOICaps', {
          accountId: params.accountId,
        }),
      );
      return () => {
        // No-op
      };
    }
  }

  /**
   * Configure live data throttling
   *
   * @param config - The configuration object.
   */
  setLiveDataConfig(config: Partial<LiveDataConfig>): void {
    try {
      const provider = this.getActiveProvider();
      provider.setLiveDataConfig(config);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.setLiveDataConfig'),
        this.#getErrorContext('setLiveDataConfig'),
      );
    }
  }

  /**
   * 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.
   */
  async calculateFees(
    params: FeeCalculationParams,
  ): Promise<FeeCalculationResult> {
    const provider = this.getActiveProvider();
    const context = this.#createServiceContext('calculateFees');
    return this.#marketDataService.calculateFees({ provider, params, context });
  }

  /**
   * Disconnect provider and cleanup subscriptions
   * Call this when navigating away from Perps screens to prevent battery drain
   */
  async disconnect(): Promise<void> {
    this.#debugLog(
      'PerpsController: Disconnecting provider to cleanup subscriptions',
      {
        timestamp: new Date().toISOString(),
      },
    );

    // Stop preload interval and messenger subscriptions first,
    // so no background work fires while we tear down providers.
    if (this.#preloadTimer) {
      clearInterval(this.#preloadTimer);
      this.#preloadTimer = null;
    }
    if (this.#preloadStateUnsubscribe) {
      this.#preloadStateUnsubscribe();
      this.#preloadStateUnsubscribe = null;
    }
    if (this.#accountChangeUnsubscribe) {
      this.#accountChangeUnsubscribe();
      this.#accountChangeUnsubscribe = null;
    }
    this.#previousIsTestnet = null;
    this.#previousHip3ConfigVersion = null;

    // Only disconnect the provider if we're initialized
    if (this.isInitialized && !this.isCurrentlyReinitializing()) {
      try {
        const provider = this.getActiveProvider();
        await provider.disconnect();
      } catch (error) {
        this.#logError(
          ensureError(error, 'PerpsController.disconnect'),
          this.#getErrorContext('disconnect'),
        );
      }
    }

    // Clear stale reference so standalone reads don't route through old provider
    this.activeProviderInstance = null;

    // Cleanup cached standalone provider (if any) — awaited to prevent races
    await this.#cleanupStandaloneProvider();

    // Note: Feature-flag subscription is NOT cleaned up here.
    // It is a controller-lifetime concern (set once in the constructor),
    // not a session-lifetime concern. Unsubscribing here would break
    // geo-blocking / HIP-3 flag propagation after disconnect → reconnect.

    // Reset initialization state to ensure proper reconnection
    this.isInitialized = false;
    this.#initializationPromise = null;
  }

  /**
   * Eligibility (Geo-Blocking)
   */

  /**
   * Fetch geo location
   *
   * Returned in Country or Country-Region format
   * Example: FR, DE, US-MI, CA-ON
   */
  /**
   * Refresh eligibility status
   */
  /**
   * Resume eligibility monitoring after onboarding completes.
   * Clears the deferred flag and triggers an immediate eligibility check
   * using the current remote feature flag state.
   */
  startEligibilityMonitoring(): void {
    this.#eligibilityCheckDeferred = false;
    try {
      const currentState = this.messenger.call(
        'RemoteFeatureFlagController:getState',
      );
      this.refreshEligibilityOnFeatureFlagChange(currentState);
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.startEligibilityMonitoring'),
        this.#getErrorContext('startEligibilityMonitoring', {
          operation: 'readRemoteFeatureFlags',
        }),
      );
    }
  }

  /**
   * Stops geo-blocking eligibility monitoring.
   * Call this when the user disables basic functionality (e.g. useExternalServices becomes false).
   * Prevents geolocation calls until startEligibilityMonitoring() is called again.
   * Safe to call multiple times.
   */
  stopEligibilityMonitoring(): void {
    this.#eligibilityCheckDeferred = true;
  }

  async refreshEligibility(): Promise<void> {
    if (this.#eligibilityCheckDeferred) {
      return;
    }

    // Capture the current version before starting the async operation.
    // This prevents race conditions where stale eligibility checks
    // (started with fallback config) overwrite results from newer checks
    // (started with remote config after it was fetched).
    const versionAtStart = this.#blockedRegionListVersion;

    try {
      const geoLocation = await this.messenger.call(
        'GeolocationController:getGeolocation',
      );

      const isEligible = await this.#eligibilityService.checkEligibility({
        blockedRegions: this.blockedRegionList.list,
        geoLocation,
      });

      // Only update state if the blocked region list hasn't changed while we were awaiting.
      // This prevents stale fallback-based eligibility checks from overwriting
      // results from remote-based checks.
      if (this.#blockedRegionListVersion !== versionAtStart) {
        return;
      }

      this.update((state) => {
        state.isEligible = isEligible;
      });
    } catch (error) {
      this.#logError(
        ensureError(error, 'PerpsController.refreshEligibility'),
        this.#getErrorContext('refreshEligibility'),
      );

      // Only update on error if version is still current
      if (this.#blockedRegionListVersion === versionAtStart) {
        // Default to eligible on error
        this.update((state) => {
          state.isEligible = true;
        });
      }
    }
  }

  /**
   * 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 {
    const provider = this.getActiveProvider();
    return this.#marketDataService.getBlockExplorerUrl({ provider, address });
  }

  /**
   * Check if user is first-time for the current network
   *
   * @returns True if the condition is met.
   */
  isFirstTimeUserOnCurrentNetwork(): boolean {
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';
    return this.state.isFirstTimeUser[currentNetwork];
  }

  /**
   * Mark that the user has completed the tutorial/onboarding
   * This prevents the tutorial from showing again
   */
  markTutorialCompleted(): void {
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';

    this.#debugLog('PerpsController: Marking tutorial as completed', {
      timestamp: new Date().toISOString(),
      network: currentNetwork,
    });

    this.update((state) => {
      state.isFirstTimeUser[currentNetwork] = false;
    });
  }

  /*
   * Mark that user has placed their first successful order
   * This prevents the notification tooltip from showing again
   */
  markFirstOrderCompleted(): void {
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';

    this.#debugLog('PerpsController: Marking first order completed', {
      timestamp: new Date().toISOString(),
      network: currentNetwork,
    });

    this.update((state) => {
      state.hasPlacedFirstOrder[currentNetwork] = true;
    });
  }

  /**
   * 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 {
    this.#debugLog('PerpsController: Resetting first-time user state', {
      timestamp: new Date().toISOString(),
      previousState: this.state.isFirstTimeUser,
    });

    this.update((state) => {
      state.isFirstTimeUser = {
        testnet: true,
        mainnet: true,
      };
      state.hasPlacedFirstOrder = {
        testnet: false,
        mainnet: false,
      };
    });
  }

  /**
   * 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 {
    this.#debugLog('PerpsController: Clearing pending transaction requests', {
      timestamp: new Date().toISOString(),
    });

    this.update((state) => {
      // Filter out pending/bridging withdrawals, keep completed for history
      state.withdrawalRequests = state.withdrawalRequests.filter(
        (req) => req.status !== 'pending' && req.status !== 'bridging',
      );

      // Filter out pending deposits, keep completed/failed for history
      state.depositRequests = state.depositRequests.filter(
        (req) => req.status !== 'pending' && req.status !== 'bridging',
      );

      // Reset withdrawal progress
      state.withdrawalProgress = {
        progress: 0,
        lastUpdated: Date.now(),
        activeWithdrawalId: null,
      };
    });
  }

  /**
   * Get saved trade configuration for a market
   *
   * @param symbol - The trading pair symbol.
   * @returns The resulting string value.
   */
  getTradeConfiguration(symbol: string): { leverage?: number } | undefined {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';
    const config = this.state.tradeConfigurations[network]?.[symbol];

    if (!config?.leverage) {
      return undefined;
    }

    this.#debugLog('PerpsController: Retrieved trade config', {
      symbol,
      network,
      leverage: config.leverage,
    });

    return { leverage: config.leverage };
  }

  /**
   * Save trade configuration for a market
   *
   * @param symbol - Market symbol
   * @param leverage - Leverage value
   */
  saveTradeConfiguration(symbol: string, leverage: number): void {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';

    this.#debugLog('PerpsController: Saving trade configuration', {
      symbol,
      network,
      leverage,
      timestamp: new Date().toISOString(),
    });

    this.update((state) => {
      if (!state.tradeConfigurations[network]) {
        state.tradeConfigurations[network] = {};
      }

      const existingConfig = state.tradeConfigurations[network][symbol] || {};
      state.tradeConfigurations[network][symbol] = {
        ...existingConfig,
        leverage,
      };
    });
  }

  /**
   * 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 {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';

    this.#debugLog('PerpsController: Saving pending trade configuration', {
      symbol,
      network,
      config,
      timestamp: new Date().toISOString(),
    });

    this.update((state) => {
      if (!state.tradeConfigurations[network]) {
        state.tradeConfigurations[network] = {};
      }

      const existingConfig = state.tradeConfigurations[network][symbol] || {};
      state.tradeConfigurations[network][symbol] = {
        ...existingConfig,
        pendingConfig: {
          ...config,
          timestamp: Date.now(),
        },
      };
    });
  }

  /**
   * 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 {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';
    const config =
      this.state.tradeConfigurations[network]?.[symbol]?.pendingConfig;

    if (!config) {
      return undefined;
    }

    // Check if config has expired (5 minutes = 300,000 milliseconds)
    const FIVE_MINUTES_MS = 5 * 60 * 1000;
    const now = Date.now();
    const age = now - config.timestamp;

    if (age > FIVE_MINUTES_MS) {
      this.#debugLog('PerpsController: Pending trade config expired', {
        symbol,
        network,
        age,
        timestamp: config.timestamp,
      });
      // Clear expired config
      this.update((state) => {
        if (state.tradeConfigurations[network]?.[symbol]?.pendingConfig) {
          delete state.tradeConfigurations[network][symbol].pendingConfig;
        }
      });
      return undefined;
    }

    this.#debugLog('PerpsController: Retrieved pending trade config', {
      symbol,
      network,
      config,
      age,
    });

    // Return config without timestamp
    const { timestamp, ...configWithoutTimestamp } = config;
    return configWithoutTimestamp;
  }

  /**
   * Clear pending trade configuration for a market
   *
   * @param symbol - Market symbol
   */
  clearPendingTradeConfiguration(symbol: string): void {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';

    this.#debugLog('PerpsController: Clearing pending trade configuration', {
      symbol,
      network,
      timestamp: new Date().toISOString(),
    });

    this.update((state) => {
      if (state.tradeConfigurations[network]?.[symbol]?.pendingConfig) {
        delete state.tradeConfigurations[network][symbol].pendingConfig;
      }
    });
  }

  /**
   * 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;
  } {
    const pref = this.state.marketFilterPreferences;

    // Handle legacy string format (backward compatibility)
    if (typeof pref === 'string') {
      // Map legacy compound IDs to new format
      // Old format: 'priceChange-desc' or 'priceChange-asc'
      // New format: { optionId: 'priceChange', direction: 'desc'/'asc' }
      if (pref === 'priceChange-desc') {
        return {
          optionId: 'priceChange',
          direction: 'desc',
        };
      }
      if (pref === 'priceChange-asc') {
        return {
          optionId: 'priceChange',
          direction: 'asc',
        };
      }

      // Handle other simple legacy strings (e.g., 'volume', 'openInterest', etc.)
      return {
        optionId: pref as SortOptionId,
        direction: MARKET_SORTING_CONFIG.DefaultDirection,
      };
    }

    // Return new object format or default
    return (
      pref ?? {
        optionId: MARKET_SORTING_CONFIG.DefaultSortOptionId,
        direction: MARKET_SORTING_CONFIG.DefaultDirection,
      }
    );
  }

  /**
   * Save market filter preferences
   *
   * @param optionId - Sort/filter option ID
   * @param direction - Sort direction ('asc' or 'desc')
   */
  saveMarketFilterPreferences(
    optionId: SortOptionId,
    direction: SortDirection,
  ): void {
    this.#debugLog('PerpsController: Saving market filter preferences', {
      optionId,
      direction,
      timestamp: new Date().toISOString(),
    });

    this.update((state) => {
      state.marketFilterPreferences = { optionId, direction };
    });
  }

  /**
   * 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 {
    let normalized: PerpsSelectedPaymentToken | null = null;
    if (
      token !== null &&
      token.description !== PERPS_CONSTANTS.PerpsBalanceTokenDescription
    ) {
      normalized = token;
    }

    const current = this.state.selectedPaymentToken as
      | SelectedPaymentTokenSnapshot
      | null
      | undefined;
    const initialPaymentMethod =
      current === null ||
      current === undefined ||
      current?.description === PERPS_CONSTANTS.PerpsBalanceTokenDescription
        ? 'perps_balance'
        : (current?.symbol ?? 'unknown');
    const newPaymentMethod =
      token === null ||
      token.description === PERPS_CONSTANTS.PerpsBalanceTokenDescription
        ? 'perps_balance'
        : (token.symbol ?? 'unknown');

    if (initialPaymentMethod !== newPaymentMethod) {
      this.#getMetrics().trackPerpsEvent(PerpsAnalyticsEvent.UiInteraction, {
        [PERPS_EVENT_PROPERTY.INTERACTION_TYPE]:
          PERPS_EVENT_VALUE.INTERACTION_TYPE.PAYMENT_METHOD_CHANGED,
        [PERPS_EVENT_PROPERTY.INITIAL_PAYMENT_METHOD]: initialPaymentMethod,
        [PERPS_EVENT_PROPERTY.NEW_PAYMENT_METHOD]: newPaymentMethod,
      });
    }

    let snapshot: Json | null = null;
    if (normalized !== null) {
      snapshot = {
        ...(normalized.description !== undefined && {
          description: normalized.description,
        }),
        address: normalized.address,
        chainId: normalized.chainId,
        symbol: normalized.symbol,
      } as unknown as Json;
    }

    this.update((state) => {
      state.selectedPaymentToken = snapshot;
    });
  }

  /**
   * 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 {
    this.update((state) => {
      state.selectedPaymentToken = null;
    });
  }

  /**
   * 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 {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';
    const grouping =
      this.state.tradeConfigurations[network]?.[symbol]?.orderBookGrouping;

    if (grouping !== undefined) {
      this.#debugLog('PerpsController: Retrieved order book grouping', {
        symbol,
        network,
        grouping,
      });
    }

    return grouping;
  }

  /**
   * Save order book grouping for a market
   *
   * @param symbol - Market symbol
   * @param grouping - Price grouping value
   */
  saveOrderBookGrouping(symbol: string, grouping: number): void {
    const network = this.state.isTestnet ? 'testnet' : 'mainnet';

    this.#debugLog('PerpsController: Saving order book grouping', {
      symbol,
      network,
      grouping,
      timestamp: new Date().toISOString(),
    });

    this.update((state) => {
      if (!state.tradeConfigurations[network]) {
        state.tradeConfigurations[network] = {};
      }

      const existingConfig = state.tradeConfigurations[network][symbol] || {};
      state.tradeConfigurations[network][symbol] = {
        ...existingConfig,
        orderBookGrouping: grouping,
      };
    });
  }

  /**
   * Toggle watchlist status for a market
   * Watchlist markets are stored per network (testnet/mainnet)
   *
   * @param symbol - The trading pair symbol.
   */
  toggleWatchlistMarket(symbol: string): void {
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';
    const currentWatchlist = this.state.watchlistMarkets[currentNetwork];
    const isWatchlisted = currentWatchlist.includes(symbol);

    this.#debugLog('PerpsController: Toggling watchlist market', {
      timestamp: new Date().toISOString(),
      network: currentNetwork,
      symbol,
      action: isWatchlisted ? 'remove' : 'add',
    });

    this.update((state) => {
      if (isWatchlisted) {
        // Remove from watchlist
        state.watchlistMarkets[currentNetwork] = currentWatchlist.filter(
          (marketSymbol) => marketSymbol !== symbol,
        );
      } else {
        // Add to watchlist
        state.watchlistMarkets[currentNetwork] = [...currentWatchlist, symbol];
      }
    });
  }

  /**
   * 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 {
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';
    return this.state.watchlistMarkets[currentNetwork].includes(symbol);
  }

  /**
   * Get all watchlist markets for the current network
   *
   * @returns The resulting string value.
   */
  getWatchlistMarkets(): string[] {
    const currentNetwork = this.state.isTestnet ? 'testnet' : 'mainnet';
    return this.state.watchlistMarkets[currentNetwork];
  }

  /**
   * 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 async reportOrderToDataLake(params: {
    action: 'open' | 'close';
    symbol: string;
    slPrice?: number;
    tpPrice?: number;
    retryCount?: number;
    _traceId?: string;
  }): Promise<{ success: boolean; error?: string }> {
    return this.#dataLakeService.reportOrder({
      action: params.action,
      symbol: params.symbol,
      slPrice: params.slPrice,
      tpPrice: params.tpPrice,
      isTestnet: this.state.isTestnet,
      context: this.#createServiceContext('reportOrderToDataLake', {}),
      retryCount: params.retryCount,
      _traceId: params._traceId,
    });
  }

  /**
   * Check if the controller is currently reinitializing
   *
   * @returns true if providers are being reinitialized
   */
  public isCurrentlyReinitializing(): boolean {
    return this.#isReinitializing;
  }
}