HyperLiquidProvider.ts

import { CaipAccountId, hasProperty } from '@metamask/utils';
import type { Hex } from '@metamask/utils';
import type {
  ExchangeClient,
  UserAbstractionResponse,
} from '@nktkas/hyperliquid';
import { v4 as uuidv4 } from 'uuid';

import type { CandlePeriod } from '../constants/chartConfig';
import {
  PERPS_EVENT_PROPERTY,
  PERPS_EVENT_VALUE,
} from '../constants/eventNames';
import {
  BASIS_POINTS_DIVISOR,
  BUILDER_FEE_CONFIG,
  FEE_RATES,
  getBridgeInfo,
  getChainId,
  HIP3_ASSET_MARKET_TYPES,
  HIP3_FEE_CONFIG,
  HIP3_MARGIN_CONFIG,
  HYPERLIQUID_WITHDRAWAL_MINUTES,
  REFERRAL_CONFIG,
  SPOT_ASSET_ID_OFFSET,
  TRADING_DEFAULTS,
  USDC_DECIMALS,
  USDH_CONFIG,
} from '../constants/hyperLiquidConfig';
import {
  ORDER_SLIPPAGE_CONFIG,
  PERFORMANCE_CONFIG,
  PERPS_CONSTANTS,
  TP_SL_CONFIG,
  WITHDRAWAL_CONSTANTS,
} from '../constants/perpsConfig';
import { PERPS_TRANSACTIONS_HISTORY_CONSTANTS } from '../constants/transactionsHistoryConfig';
import { PERPS_ERROR_CODES } from '../perpsErrorCodes';
import { DexDiscoveryCacheManager } from '../services/DexDiscoveryCacheManager';
import {
  HyperLiquidClientService,
  WebSocketConnectionState,
} from '../services/HyperLiquidClientService';
import { HyperLiquidSubscriptionService } from '../services/HyperLiquidSubscriptionService';
import { HyperLiquidWalletService } from '../services/HyperLiquidWalletService';
import {
  TradingReadinessCache,
  PerpsSigningCache,
} from '../services/TradingReadinessCache';
import { PerpsAnalyticsEvent } from '../types';
import type {
  AccountState,
  AssetRoute,
  BatchCancelOrdersParams,
  CancelOrderParams,
  CancelOrderResult,
  CancelOrdersResult,
  CandleData,
  ClosePositionParams,
  ClosePositionsParams,
  ClosePositionsResult,
  DepositParams,
  DisconnectResult,
  EditOrderParams,
  FeeCalculationParams,
  FeeCalculationResult,
  Funding,
  GetAccountStateParams,
  GetAvailableDexsParams,
  GetFundingParams,
  GetHistoricalPortfolioParams,
  GetMarketsParams,
  GetOrderFillsParams,
  GetOrdersParams,
  GetOrFetchFillsParams,
  GetPositionsParams,
  GetSupportedPathsParams,
  HistoricalPortfolioResult,
  InitializeResult,
  PerpsPlatformDependencies,
  PerpsProvider,
  LiquidationPriceParams,
  LiveDataConfig,
  MaintenanceMarginParams,
  MarginResult,
  MarketInfo,
  Order,
  OrderFill,
  OrderParams,
  OrderResult,
  PerpsMarketData,
  Position,
  ReadyToTradeResult,
  SubscribeAccountParams,
  SubscribeCandlesParams,
  SubscribeOICapsParams,
  SubscribeOrderBookParams,
  SubscribeOrderFillsParams,
  SubscribeOrdersParams,
  SubscribePositionsParams,
  SubscribePricesParams,
  ToggleTestnetResult,
  TransferBetweenDexsParams,
  TransferBetweenDexsResult,
  UpdateMarginParams,
  UpdatePositionTPSLParams,
  UserHistoryItem,
  WithdrawParams,
  WithdrawResult,
  RawLedgerUpdate,
  PerpsReadOptions,
} from '../types';
import type {
  SDKOrderParams,
  MetaResponse,
  PerpsAssetCtx,
  FrontendOrder,
  SpotMetaResponse,
} from '../types/hyperliquid-types';
import {
  HL_ABSTRACTION_WIRE,
  HL_UNIFIED_ACCOUNT_MODE,
  hyperLiquidModeFoldsSpot,
} from '../types/hyperliquid-types';
import type { PerpsControllerMessengerBase } from '../types/messenger';
import type { ExtendedAssetMeta, ExtendedPerpDex } from '../types/perps-types';
import {
  addSpotBalanceToAccountState,
  aggregateAccountStates,
} from '../utils/accountUtils';
import { ensureError } from '../utils/errorUtils';
import {
  adaptAccountStateFromSDK,
  adaptHyperLiquidLedgerUpdateToUserHistoryItem,
  adaptMarketFromSDK,
  adaptOrderFromSDK,
  adaptPositionFromSDK,
  buildAssetMapping,
  formatHyperLiquidPrice,
  formatHyperLiquidSize,
  parseAssetName,
} from '../utils/hyperLiquidAdapter';
import {
  createErrorResult,
  getMaxOrderValue,
  getSupportedPaths,
  validateAssetSupport,
  validateBalance,
  validateCoinExists,
  validateDepositParams,
  validateOrderParams,
  validateWithdrawalParams,
} from '../utils/hyperLiquidValidation';
import { transformMarketData } from '../utils/marketDataTransform';
import {
  compileMarketPattern,
  shouldIncludeMarket,
} from '../utils/marketUtils';
import type { CompiledMarketPattern } from '../utils/marketUtils';
import {
  buildOrdersArray,
  calculateFinalPositionSize,
  calculateOrderPriceAndSize,
} from '../utils/orderCalculations';
import {
  createStandaloneInfoClient,
  queryStandaloneClearinghouseStates,
  queryStandaloneOpenOrders,
} from '../utils/standaloneInfoClient';
// getStreamManagerInstance removed: use this.#deps.streamManager instead

/**
 * Type guard to check if a status is an object (not a string literal like "waitingForFill")
 * The SDK returns status as a union of object types and string literals.
 *
 * @param status - The current status.
 * @returns The result of the operation.
 */
const isStatusObject = (status: unknown): status is Record<string, unknown> =>
  typeof status === 'object' && status !== null;

// Helper method parameter interfaces (module-level for class-dependent methods only)
type GetAssetInfoParams = {
  symbol: string;
  dexName: string | null;
};

type DexFetchFailureStep = 'metaAndAssetCtxs' | 'allMids';

type DexFetchResult = {
  dex: string | null;
  meta: MetaResponse | null;
  assetCtxs: PerpsAssetCtx[];
  allMids: Record<string, string>;
  success: boolean;
  failedStep?: DexFetchFailureStep;
  errorMessage?: string;
};

type DexQueryResult<TResult> = {
  dex: string | null;
  data: TResult;
};

type DexQueryResponse<TResult> = {
  results: DexQueryResult<TResult>[];
  failedDexs: { dex: string | null; error: Error }[];
};

type CachedMarketDataSnapshot = {
  data: PerpsMarketData[];
  timestamp: number;
  contributingDexs: string[];
  failedDexs: string[];
};

type GetAssetInfoResult = {
  assetInfo: {
    name: string;
    szDecimals: number;
    maxLeverage: number;
  };
  currentPrice: number;
  meta: MetaResponse;
};

type PrepareAssetForTradingParams = {
  symbol: string;
  assetId: number;
  leverage?: number;
};

type HandleHip3PreOrderParams = {
  dexName: string;
  symbol: string;
  orderPrice: number;
  positionSize: number;
  leverage: number;
  isBuy: boolean;
  maxLeverage: number;
};

type HandleHip3PreOrderResult = {
  transferInfo: { amount: number; sourceDex: string } | null;
};

type SubmitOrderWithRollbackParams = {
  orders: SDKOrderParams[];
  grouping: 'na' | 'normalTpsl' | 'positionTpsl';
  isHip3Order: boolean;
  dexName: string | null;
  transferInfo: { amount: number; sourceDex: string } | null;
  symbol: string;
  assetId: number;
};

type HandleOrderErrorParams = {
  error: unknown;
  symbol: string;
  orderType: 'market' | 'limit';
  isBuy: boolean;
};

type GetOrFetchPriceParams = {
  symbol: string;
  dexName: string | null;
};

/**
 * HyperLiquid provider implementation
 *
 * Implements the PerpsProvider interface for HyperLiquid protocol.
 * Uses the @nktkas/hyperliquid SDK for all operations.
 * Delegates to service classes for client management, wallet integration, and subscriptions.
 *
 * HIP-3 Balance Management:
 * Attempts to use HyperLiquid's native DEX abstraction for automatic collateral transfers.
 * If not supported, falls back to programmatic balance management using SDK's sendAsset.
 */
export class HyperLiquidProvider implements PerpsProvider {
  readonly protocolId = 'hyperliquid';

  // Platform dependencies for logging and debugging
  readonly #deps: PerpsPlatformDependencies;

  // Service instances
  readonly #clientService: HyperLiquidClientService;

  readonly #walletService: HyperLiquidWalletService;

  readonly #subscriptionService: HyperLiquidSubscriptionService;

  // Asset mapping
  readonly #symbolToAssetId = new Map<string, number>();

  // Cache for user fee rates to avoid excessive API calls
  readonly #userFeeCache = new Map<
    string,
    {
      perpsTakerRate: number;
      perpsMakerRate: number;
      spotTakerRate: number;
      spotMakerRate: number;
      timestamp: number;
      ttl: number;
    }
  >();

  // Cache for max leverage values to avoid excessive API calls
  readonly #maxLeverageCache = new Map<
    string,
    { value: number; timestamp: number }
  >();

  // Cache for raw meta responses (shared across methods to avoid redundant API calls)
  // Filtering is applied on-demand (cheap array operations) - no need for separate processed cache
  readonly #cachedMetaByDex = new Map<string, MetaResponse>();

  // Last known-good market list for stale fallback when every enabled DEX fails in one fetch window.
  #cachedMarketDataWithPrices: CachedMarketDataSnapshot | null = null;

  // Session cache for spot metadata (contains USDC/USDH token info for HIP-3 collateral checks)
  // Pre-fetched in ensureReadyForTrading() to avoid API failures during order placement
  #cachedSpotMeta: SpotMetaResponse | null = null;

  // Unified DEX discovery cache — single source of truth for all perpDexs() derivatives.
  // Replaces three separate caches to eliminate desync bugs by construction.
  // All writes go through #dexDiscoveryCache.update(); readers use .state.
  readonly #dexDiscoveryCache: DexDiscoveryCacheManager;

  // Session cache for referral state (cleared on disconnect/reconnect)
  // Key: `network:userAddress`, Value: true if referral is set
  readonly #referralCheckCache = new Map<string, boolean>();

  // Session cache for builder fee approval state (cleared on disconnect/reconnect)
  // Key: `network:userAddress`, Value: true if builder fee is approved
  readonly #builderFeeCheckCache = new Map<string, boolean>();

  // Pending promise trackers for deduplicating concurrent calls
  // Prevents multiple signature requests when methods called simultaneously
  #ensureReadyPromise: Promise<void> | null = null;

  readonly #pendingBuilderFeeApprovals = new Map<string, Promise<void>>();

  // Pre-compiled patterns for fast filtering
  readonly #compiledAllowlistPatterns: CompiledMarketPattern[] = [];

  readonly #compiledBlocklistPatterns: CompiledMarketPattern[] = [];

  // Fee discount context for MetaMask reward discounts (in basis points)
  #userFeeDiscountBips?: number;

  // Feature flag configuration for HIP-3 market filtering
  readonly #hip3Enabled: boolean;

  readonly #allowlistMarkets: string[];

  readonly #blocklistMarkets: string[];

  // Emergency kill-switch for the Unified Account migration flow. Defaults
  // to true and is the expected production state after HL's DEX Abstraction
  // deprecation. Kept as a constructor option (not removed) so we can
  // disable the migration via a hot-fix release if a regression surfaces
  // in the wild — flipping this to false reverts to the legacy programmatic
  // HIP-3 transfer path that already lives in the codebase.
  #useUnifiedAccount: boolean;

  // True once DEX discovery has succeeded with real data (not a fallback).
  // When false, #ensureReadyPromise is reset after each init so the next
  // caller retries DEX discovery instead of reusing a degraded mapping.
  #dexDiscoveryComplete = false;

  // True when the most recent #ensureUnifiedAccountEnabled run ended in a
  // transient state that warrants retry (silent agent-key failure, REST
  // userAbstraction lookup failure, or keyring locked). #ensureReady resets
  // its memoized promise when this is set so the next entry retries the
  // migration instead of returning the cached resolved promise.
  #unifiedAccountSetupNeedsRetry = false;

  // Pending promise to deduplicate concurrent getValidatedDexs() calls
  #pendingValidatedDexsPromise: Promise<(string | null)[]> | null = null;

  // Cache for USDC token ID from spot metadata
  #cachedUsdcTokenId?: string;

  // Error mappings from HyperLiquid API errors to standardized PERPS_ERROR_CODES
  readonly #errorMappings = {
    'isolated position does not have sufficient margin available to decrease leverage':
      PERPS_ERROR_CODES.ORDER_LEVERAGE_REDUCTION_FAILED,
    'could not immediately match': PERPS_ERROR_CODES.IOC_CANCEL,
  };

  // Track whether clients have been initialized (lazy initialization)
  #clientsInitialized = false;

  // Promise-based lock to prevent race conditions in concurrent initialization
  #initializationPromise: Promise<void> | null = null;

  readonly #messenger: PerpsControllerMessengerBase;

  readonly #builderAddressTestnet?: string;

  readonly #builderAddressMainnet?: string;

  constructor(options: {
    isTestnet?: boolean;
    hip3Enabled?: boolean;
    allowlistMarkets?: string[];
    blocklistMarkets?: string[];
    useUnifiedAccount?: boolean;
    platformDependencies: PerpsPlatformDependencies;
    messenger: PerpsControllerMessengerBase;
    initialAssetMapping?: [string, number][];
    builderAddressTestnet?: string;
    builderAddressMainnet?: string;
  }) {
    this.#deps = options.platformDependencies;
    this.#messenger = options.messenger;
    this.#builderAddressTestnet = options.builderAddressTestnet;
    this.#builderAddressMainnet = options.builderAddressMainnet;
    const isTestnet = options.isTestnet ?? false;

    // Dev-friendly defaults: Enable all markets by default for easier testing (discovery mode)
    this.#hip3Enabled = options.hip3Enabled ?? false;
    this.#allowlistMarkets = options.allowlistMarkets ?? [];
    this.#blocklistMarkets = options.blocklistMarkets ?? [];

    // Attempt unified account mode, fallback to programmatic transfer if unsupported
    this.#useUnifiedAccount = options.useUnifiedAccount ?? true;

    // Initialize services with injected platform dependencies
    this.#clientService = new HyperLiquidClientService(this.#deps, {
      isTestnet,
    });
    this.#dexDiscoveryCache = new DexDiscoveryCacheManager({
      isTestnetMode: (): boolean => this.#clientService.isTestnetMode(),
      debugLogger: this.#deps.debugLogger,
      getAllowlistMarkets: (): string[] => this.#allowlistMarkets,
    });
    this.#walletService = new HyperLiquidWalletService(
      this.#deps,
      this.#messenger,
      {
        isTestnet,
      },
    );
    this.#subscriptionService = new HyperLiquidSubscriptionService(
      this.#clientService,
      this.#walletService,
      this.#deps,
      this.#hip3Enabled,
      [], // enabledDexs - will be populated after DEX discovery in buildAssetMapping
      this.#allowlistMarkets,
      this.#blocklistMarkets,
    );

    // NOTE: Clients are NOT initialized here - they'll be initialized lazily
    // when first needed. This avoids accessing Engine.context before it's ready.

    // Pre-compile filter patterns for performance (invalid patterns are skipped)
    this.#compiledAllowlistPatterns = this.#compilePatternsSafely(
      this.#allowlistMarkets,
      'allowlist',
    );
    this.#compiledBlocklistPatterns = this.#compilePatternsSafely(
      this.#blocklistMarkets,
      'blocklist',
    );

    // Populate initial asset mapping if provided (used for DI in tests)
    if (options.initialAssetMapping) {
      for (const [symbol, assetId] of options.initialAssetMapping) {
        this.#symbolToAssetId.set(symbol, assetId);
      }
    }

    // Debug: Confirm batch methods exist and show HIP-3 config
    this.#deps.debugLogger.log('[HyperLiquidProvider] Constructor complete', {
      hasBatchCancel: typeof this.cancelOrders === 'function',
      hasBatchClose: typeof this.closePositions === 'function',
      protocolId: this.protocolId,
      hip3Enabled: this.#hip3Enabled,
      allowlistMarkets: this.#allowlistMarkets,
      blocklistMarkets: this.#blocklistMarkets,
      isTestnet,
    });
  }

  /**
   * Compile market patterns safely, skipping any that fail validation.
   * Prevents a single bad pattern from crashing the entire constructor.
   *
   * @param patterns - The array of patterns to validate.
   * @param listName - The name of the list for logging context.
   * @returns The result of the operation.
   */
  #compilePatternsSafely(
    patterns: string[],
    listName: string,
  ): CompiledMarketPattern[] {
    const compiled: CompiledMarketPattern[] = [];
    for (const pattern of patterns) {
      try {
        compiled.push({ pattern, matcher: compileMarketPattern(pattern) });
      } catch (error) {
        this.#deps.logger.error(
          ensureError(error, `HyperLiquidProvider.compilePatternsSafely`),
          this.#getErrorContext('compilePatternsSafely', { listName, pattern }),
        );
      }
    }
    return compiled;
  }

  /**
   * Initialize HyperLiquid SDK clients (lazy initialization)
   *
   * This is called on first API operation to ensure Engine.context is ready.
   * Creating the wallet adapter requires accessing Engine.context.AccountTreeController,
   * which may not be available during early app initialization.
   *
   * IMPORTANT: This method awaits the WebSocket transport.ready() to ensure
   * the connection is fully established before marking initialization complete.
   */
  async #ensureClientsInitialized(): Promise<void> {
    if (this.#clientsInitialized) {
      return; // Already initialized
    }

    // Reuse existing initialization promise if one is in progress
    // This prevents race conditions when multiple methods call concurrently
    if (this.#initializationPromise) {
      await this.#initializationPromise;
      return;
    }

    // Create and cache the initialization promise
    this.#initializationPromise = (async (): Promise<void> => {
      // Double-check after acquiring the "lock"
      if (this.#clientsInitialized) {
        return;
      }

      const wallet = this.#walletService.createWalletAdapter();
      await this.#clientService.initialize(wallet);

      // Set termination callback for logging when WebSocket terminates
      // Note: Do NOT restore subscriptions here - termination means connection failed permanently
      this.#clientService.setOnTerminateCallback((error: Error) => {
        this.#deps.debugLogger.log(
          '[HyperLiquidProvider] WebSocket terminated',
          {
            error: error.message,
          },
        );
      });

      // Set reconnection callback to restore subscriptions after successful reconnection
      // This is called in handleConnectionDrop() after the WebSocket reconnects successfully
      this.#clientService.setOnReconnectCallback(async () => {
        try {
          this.#deps.debugLogger.log(
            '[HyperLiquidProvider] WebSocket reconnected, restoring subscriptions',
          );
          await this.#subscriptionService.restoreSubscriptions();
          this.#deps.streamManager.clearAllChannels();
        } catch (restoreError) {
          this.#deps.debugLogger.log(
            '[HyperLiquidProvider] Failed to restore subscriptions',
            restoreError,
          );
        }
      });

      // Only set flag AFTER successful initialization
      this.#clientsInitialized = true;

      this.#deps.debugLogger.log(
        '[HyperLiquidProvider] Clients initialized lazily',
      );
    })();

    try {
      await this.#initializationPromise;
    } finally {
      // Clear promise after completion (success or failure)
      // so future calls can retry if needed
      this.#initializationPromise = null;
    }
  }

  /**
   * Attempt to enable HyperLiquid Unified Account mode for HIP-3 orders
   *
   * If successful, HyperLiquid automatically manages collateral transfers for HIP-3 orders.
   * If not supported, disables the flag to trigger programmatic transfer fallback.
   *
   * IMPORTANT: Uses global singleton cache to prevent repeated signing requests
   * across provider reconnections (critical for hardware wallets).
   *
   * @param options - Optional configuration.
   * @param options.allowUserSigning - When true, runs the EIP-712 user-signed migration for `dexAbstraction` accounts. Defaults to false so init does not surface a signing prompt; action-time entry points (trading, withdraw) pass true.
   * @private
   */
  async #ensureUnifiedAccountEnabled(options?: {
    allowUserSigning?: boolean;
  }): Promise<void> {
    // dexAbstraction → unifiedAccount requires an EIP-712 prompt (HL blocks
    // the agent path for that transition). Init calls with allowUserSigning=false so
    // viewing the Perps section never surfaces a signing dialog. Trading and
    // withdraw entry points pass allowUserSigning=true to drive the migration when
    // the user actually intends to act.
    const allowUserSigning = options?.allowUserSigning ?? false;

    // Optimistic reset — set true below only at the failure points that
    // warrant retry (silent agent failure, REST lookup failure, keyring
    // locked). Final-state outcomes (success, prompted-failure cached,
    // already-on-compatible, defer, unknown mode, feature off) leave it
    // false so #ensureReady can keep the memoized promise.
    this.#unifiedAccountSetupNeedsRetry = false;

    if (!this.#useUnifiedAccount) {
      return; // Feature disabled
    }

    const userAddress = await this.#walletService.getUserAddressWithDefault();
    const network = this.#clientService.isTestnetMode() ? 'testnet' : 'mainnet';

    // Check global cache first to avoid repeated signing requests
    // This is CRITICAL for hardware wallets to prevent QR popup spam
    const cachedStatus = TradingReadinessCache.get(network, userAddress);
    if (cachedStatus?.attempted) {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Unified Account setup already attempted (from global cache)',
        {
          user: userAddress,
          network,
          enabled: cachedStatus.enabled,
          note: 'Skipping to prevent repeated signing requests',
        },
      );
      return;
    }

    // Check if another provider instance is currently attempting this operation
    // This prevents concurrent signing attempts across providers during reconnection
    const inFlightPromise = PerpsSigningCache.isInFlight(
      'unifiedAccount',
      network,
      userAddress,
    );
    if (inFlightPromise) {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Unified Account setup in-flight, waiting...',
        { network, userAddress },
      );
      await inFlightPromise;
      // The other instance may have finished without writing the cache (e.g.
      // an init-time call deferred a dexAbstraction migration). If the cache
      // is still empty and we are an action-time caller (allowUserSigning=true),
      // we must run our own attempt — otherwise the trade/withdraw would
      // proceed in the deprecated mode.
      const postWaitCache = TradingReadinessCache.get(network, userAddress);
      if (postWaitCache?.attempted) {
        return;
      }
      // Fall through to acquire our own lock and retry.
    }

    // Set in-flight lock to prevent concurrent attempts
    const completeInFlight = PerpsSigningCache.setInFlight(
      'unifiedAccount',
      network,
      userAddress,
    );

    let currentMode: UserAbstractionResponse | undefined;

    try {
      // Re-check cache after acquiring lock (another provider might have finished)
      const recheckCache = TradingReadinessCache.get(network, userAddress);
      if (recheckCache?.attempted) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Unified Account setup completed by another provider',
          { network, userAddress },
        );
        completeInFlight();
        return;
      }

      const infoClient = this.#clientService.getInfoClient();

      // Check current abstraction mode on-chain
      currentMode = await infoClient.userAbstraction({
        user: userAddress,
      });

      if (
        currentMode === 'unifiedAccount' ||
        currentMode === 'portfolioMargin'
      ) {
        // portfolioMargin is a superset of unifiedAccount — it already supports
        // auto-collateral management for HIP-3 orders and is more capital-efficient.
        // Downgrading portfolio margin users to unifiedAccount would be harmful,
        // so we treat both modes as already-enabled and skip migration.
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Account already in a compatible mode, skipping migration',
          { user: userAddress, network, mode: currentMode },
        );
        this.#deps.metrics.trackPerpsEvent(PerpsAnalyticsEvent.AccountSetup, {
          [PERPS_EVENT_PROPERTY.ABSTRACTION_MODE]: currentMode,
          [PERPS_EVENT_PROPERTY.STATUS]:
            PERPS_EVENT_VALUE.STATUS.ALREADY_ENABLED,
        });
        TradingReadinessCache.set(network, userAddress, {
          attempted: true,
          enabled: true,
        });
        // Record the resolved mode in the subscription service so the next
        // aggregation folds spot correctly without waiting for #refreshSpotState.
        this.#subscriptionService.setUserAbstractionMode(
          userAddress,
          currentMode,
        );
        completeInFlight();
        return;
      }

      // Defer the user-signed transition until the user attempts an action.
      // Cache is intentionally left untouched so the next entry re-evaluates;
      // the read-only userAbstraction call is cheap and gated by the in-flight
      // lock, preventing concurrent prompts.
      if (currentMode === 'dexAbstraction' && !allowUserSigning) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Deferring dexAbstraction → unifiedAccount migration to action time',
          { user: userAddress, network },
        );
        completeInFlight();
        return;
      }

      // Bail on unknown modes BEFORE firing analytics or attempting dispatch.
      // Keeps `migration_required` actionable (only fires for modes we can
      // actually migrate) and avoids re-emitting on every reconnection.
      if (
        currentMode !== 'dexAbstraction' &&
        currentMode !== 'default' &&
        currentMode !== 'disabled'
      ) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Unknown abstraction mode, skipping Unified Account migration',
          { user: userAddress, network, mode: currentMode },
        );
        completeInFlight();
        return;
      }

      // Track which mode users are currently on before we attempt migration.
      // This tells us the distribution of legacy modes across our user base.
      this.#deps.metrics.trackPerpsEvent(PerpsAnalyticsEvent.AccountSetup, {
        [PERPS_EVENT_PROPERTY.ABSTRACTION_MODE]: currentMode,
        [PERPS_EVENT_PROPERTY.STATUS]:
          PERPS_EVENT_VALUE.STATUS.MIGRATION_REQUIRED,
      });

      // Enable Unified Account mode.
      // - default / disabled: agent wallet can do this silently (no prompt)
      // - dexAbstraction: HL blocks the agent transition — requires the user's main
      //   wallet to sign an EIP-712 action via userSetAbstraction (one-time prompt)
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Enabling Unified Account mode',
        {
          user: userAddress,
          network,
          previousMode: currentMode,
          note: 'HyperLiquid will auto-manage collateral for HIP-3 orders',
        },
      );

      const exchangeClient = this.#clientService.getExchangeClient();
      if (currentMode === 'dexAbstraction') {
        // Requires EIP-712 signature from the user's main wallet (one-time migration).
        // HL blocks the dexAbstraction → unifiedAccount transition via the agent wallet,
        // so userSetAbstraction (user-signed) is the only path for legacy users.
        await exchangeClient.userSetAbstraction({
          user: userAddress,
          abstraction: HL_UNIFIED_ACCOUNT_MODE,
        });
      } else {
        // default / disabled — silent agent transition, no user prompt
        await exchangeClient.agentSetAbstraction({
          abstraction: HL_ABSTRACTION_WIRE.unifiedAccount,
        });
      }

      this.#deps.debugLogger.log(
        '✅ HyperLiquidProvider: Unified Account enabled successfully',
      );
      this.#deps.metrics.trackPerpsEvent(PerpsAnalyticsEvent.AccountSetup, {
        [PERPS_EVENT_PROPERTY.PREVIOUS_ABSTRACTION_MODE]: currentMode,
        [PERPS_EVENT_PROPERTY.ABSTRACTION_MODE]: HL_UNIFIED_ACCOUNT_MODE,
        [PERPS_EVENT_PROPERTY.STATUS]: PERPS_EVENT_VALUE.STATUS.SUCCESS,
      });
      TradingReadinessCache.set(network, userAddress, {
        attempted: true,
        enabled: true,
      });
      // Record the post-migration mode in the subscription service so it
      // immediately re-aggregates with fold=true and surfaces the unified
      // balance rather than waiting for the next #refreshSpotState.
      this.#subscriptionService.setUserAbstractionMode(
        userAddress,
        HL_UNIFIED_ACCOUNT_MODE,
      );
      completeInFlight();
    } catch (error) {
      // If keyring is locked, don't cache so it retries when unlocked
      if (ensureError(error).message === PERPS_ERROR_CODES.KEYRING_LOCKED) {
        this.#deps.debugLogger.log(
          '[ensureUnifiedAccountEnabled] Keyring locked, will retry later',
        );
        this.#unifiedAccountSetupNeedsRetry = true;
        completeInFlight();
        return;
      }

      // Cache failure ONLY for the user-prompted path
      // (`dexAbstraction → unifiedAccount` via `userSetAbstraction`). The
      // rationale for caching is "don't re-prompt a user who already saw the
      // signature dialog and rejected it" — that doesn't apply to:
      //   - Read-only userAbstraction lookup failures (no prompt; transient).
      //   - Silent agent-key paths (`default`/`disabled` → `agentSetAbstraction`
      //     does not show a UI prompt; failures are typically transient HL
      //     outages and pinning them would leave users stuck in the
      //     deprecated mode for the rest of the session).
      // Action-time retries pick up the unmigrated state and try again.
      if (currentMode === 'dexAbstraction') {
        TradingReadinessCache.set(network, userAddress, {
          attempted: true,
          enabled: false,
        });
      } else {
        // Silent agent-key failure (default/disabled) or read-only
        // userAbstraction lookup failure — neither is a final state, so
        // signal #ensureReady to drop its memoized promise and retry on
        // the next entry instead of pinning the user in the deprecated
        // mode for the provider's lifetime.
        this.#unifiedAccountSetupNeedsRetry = true;
      }

      const errorMessage = ensureError(
        error,
        'HyperLiquidProvider.ensureUnifiedAccountEnabled',
      ).message;

      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Unified Account setup failed',
        {
          user: userAddress,
          network,
          error: errorMessage,
          // Cache writes only happen on the user-prompted dexAbstraction
          // path (see P2-B logic above). Reflect that here so retry
          // behaviour is debuggable from the log alone.
          cached: currentMode === 'dexAbstraction',
        },
      );

      this.#deps.metrics.trackPerpsEvent(PerpsAnalyticsEvent.AccountSetup, {
        ...(currentMode && {
          [PERPS_EVENT_PROPERTY.PREVIOUS_ABSTRACTION_MODE]: currentMode,
          [PERPS_EVENT_PROPERTY.ABSTRACTION_MODE]: HL_UNIFIED_ACCOUNT_MODE,
        }),
        [PERPS_EVENT_PROPERTY.STATUS]: PERPS_EVENT_VALUE.STATUS.FAILED,
        [PERPS_EVENT_PROPERTY.ERROR_MESSAGE]: errorMessage,
      });

      completeInFlight();

      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.ensureUnifiedAccountEnabled'),
        this.#getErrorContext('ensureUnifiedAccountEnabled', {
          note: 'Could not enable Unified Account (user rejected, or network error)',
        }),
      );
    }
  }

  /**
   * Ensure clients are initialized and asset mapping is loaded
   * Asset mapping is built once on first call and reused for the provider's lifetime
   * since HIP-3 configuration is immutable after construction
   */
  async #ensureReady(): Promise<void> {
    // If already initializing or completed, wait for/return that promise
    // This prevents duplicate initialization flows when multiple methods called concurrently
    if (this.#ensureReadyPromise) {
      this.#deps.debugLogger.log(
        '[ensureReady] Reusing existing initialization promise',
      );
      await this.#ensureReadyPromise;
      return;
    }

    this.#deps.debugLogger.log('[ensureReady] Starting new initialization');

    // Create and track initialization promise
    this.#ensureReadyPromise = (async (): Promise<void> => {
      // Lazy initialization: ensure clients are created (safe after Engine.context is ready)
      // This awaits WebSocket transport.ready() to ensure connection is established
      await this.#ensureClientsInitialized();

      // Verify clients are properly initialized
      this.#clientService.ensureInitialized();

      // Build asset mapping on first call, or retry if DEX discovery previously failed
      if (this.#symbolToAssetId.size === 0 || !this.#dexDiscoveryComplete) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Building asset mapping',
          {
            hip3Enabled: this.#hip3Enabled,
            allowlistMarkets: this.#allowlistMarkets,
            blocklistMarkets: this.#blocklistMarkets,
          },
        );
        await this.#buildAssetMapping();
      }

      // Attempt Unified Account migration as early as possible so users aren't
      // blocked when they try to trade. Software-wallet dexAbstraction users can
      // complete the one-time EIP-712 migration during initial setup so the first
      // trade sees the unified balance. Hardware wallets remain deferred to
      // action time to avoid QR / Ledger prompt spam while browsing.
      await this.#ensureUnifiedAccountEnabled({
        allowUserSigning: !this.#walletService.isSelectedHardwareWallet(),
      });
    })();

    // Await initialization - keep the promise so subsequent calls resolve immediately
    // The promise is only reset in disconnect() for clean reconnection,
    // or when DEX discovery was degraded so the next caller retries.
    await this.#ensureReadyPromise;
    if (!this.#dexDiscoveryComplete) {
      // DEX discovery failed transiently — reset so next call retries.
      // Trading still works (main DEX mapping is populated), but HIP-3 markets
      // will be re-discovered on the next #ensureReady() call.
      this.#ensureReadyPromise = null;
    } else if (this.#unifiedAccountSetupNeedsRetry) {
      // Silent migration / lookup / keyring-locked failure left the cache
      // empty. Without resetting the memoized promise, subsequent
      // #ensureReady calls would skip retry and the user would be stuck
      // in the deprecated mode for the provider's lifetime.
      this.#ensureReadyPromise = null;
    }
    this.#deps.debugLogger.log('[ensureReady] Initialization complete');
  }

  /**
   * Ensure provider is ready for TRADING operations (signing required)
   *
   * This method performs additional setup that requires user signatures:
   * - DEX abstraction enablement (for HIP-3 auto-transfers)
   * - Builder fee approval (required for orders)
   * - Referral code setup (attribution)
   *
   * These operations are DEFERRED from ensureReady() to avoid QR popup spam
   * when users are just viewing the Perps section (critical for hardware wallets).
   *
   * Call this method before any trading operation (placeOrder, cancelOrder, etc.)
   */
  #tradingSetupPromise: Promise<void> | null = null;

  #tradingSetupComplete = false;

  async #ensureReadyForTrading(): Promise<void> {
    // First ensure basic initialization is complete
    await this.#ensureReady();

    // dexAbstraction users were deferred during init to avoid an EIP-712 prompt
    // on Perps section open. Drive the migration here, gated by its own cache so
    // already-migrated or already-rejected users are not re-prompted.
    await this.#ensureUnifiedAccountEnabled({ allowUserSigning: true });

    // If trading setup already complete, return immediately
    if (this.#tradingSetupComplete) {
      return;
    }

    // If trading setup is in progress, wait for it
    if (this.#tradingSetupPromise) {
      this.#deps.debugLogger.log(
        '[ensureReadyForTrading] Waiting for in-progress trading setup',
      );
      await this.#tradingSetupPromise;
      return;
    }

    this.#deps.debugLogger.log(
      '[ensureReadyForTrading] Starting trading setup (may require signatures)',
    );

    this.#tradingSetupPromise = (async (): Promise<void> => {
      // Pre-fetch spotMeta for HIP-3 operations (non-blocking if it fails)
      // This ensures token info (USDC/USDH indices) is available during order placement
      if (this.#hip3Enabled) {
        try {
          await this.#getCachedSpotMeta();
        } catch (error) {
          this.#deps.debugLogger.log(
            '[ensureReadyForTrading] spotMeta pre-fetch failed, will retry when needed',
            error,
          );
          // Don't throw - spotMeta will be fetched on-demand if needed
        }
      }

      // Set up builder fee approval
      try {
        await this.#ensureBuilderFeeApproval();
      } catch (error) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Builder fee approval failed',
          error,
        );
        // Don't throw - let trading continue, will fail with clear error if needed
      }

      // Set up referral code
      await this.#ensureReferralSet();

      // Only mark complete if keyring was unlocked (signing could actually happen)
      if (this.#walletService.isKeyringUnlocked()) {
        this.#tradingSetupComplete = true;
      }
    })();

    try {
      await this.#tradingSetupPromise;
    } finally {
      this.#tradingSetupPromise = null;
    }

    this.#deps.debugLogger.log(
      '[ensureReadyForTrading] Trading setup complete',
    );
  }

  /**
   * Get current price for a symbol using WebSocket cache first, REST API fallback
   * Centralizes the price fetching pattern used across multiple methods
   *
   * @param params - Parameters for fetching price
   * @param params.symbol - The symbol to get price for
   * @param params.dexName - Optional DEX name for REST API fallback
   * @returns The current price as a number
   * @throws Error if no price is available
   */
  async #getOrFetchPrice(params: GetOrFetchPriceParams): Promise<number> {
    const { symbol, dexName } = params;

    // OPTIMIZATION: Use WebSocket price cache first (0 weight), fall back to REST (2 weight)
    const cachedPrice = this.#subscriptionService.getCachedPrice(symbol);

    if (cachedPrice) {
      const price = parseFloat(cachedPrice);
      // Validate cached price: must be positive and finite
      // Covers zero, negative, NaN, and Infinity in one check
      if (price <= 0 || !isFinite(price)) {
        this.#deps.debugLogger.log(
          'WebSocket cached price invalid for getOrFetchPrice, falling back to REST',
          { symbol, cachedPrice, parsedPrice: price },
        );
        // Fall through to REST API fallback
      } else {
        this.#deps.debugLogger.log('Using WebSocket cached price', {
          symbol,
          price,
        });
        return price;
      }
    }

    // Fallback to REST API if cache miss
    this.#deps.debugLogger.log(
      'Price cache miss for getOrFetchPrice, falling back to REST allMids',
      { symbol },
    );
    const infoClient = this.#clientService.getInfoClient();
    const mids = await infoClient.allMids(
      dexName ? { dex: dexName } : undefined,
    );
    const price = parseFloat(mids[symbol] || '0');

    // Validate REST price: must be positive and finite
    if (price <= 0 || !isFinite(price)) {
      throw new Error(`Invalid price for ${symbol}: ${price}`);
    }

    return price;
  }

  /**
   * Get fills using WebSocket cache first, falling back to REST API
   * OPTIMIZATION: Uses cached fills when available (0 API weight), only calls REST on cache miss
   *
   * Cache limitation: WebSocket cache is limited to ~100 most recent fills.
   * For historical data (e.g., position-opening fills from months ago), use getOrderFills directly.
   *
   * @param params - Optional filter parameters (startTime, symbol)
   * @returns Array of order fills
   */
  public async getOrFetchFills(
    params?: GetOrFetchFillsParams,
  ): Promise<OrderFill[]> {
    // Check WebSocket cache first (0 API weight)
    const cachedFills = this.#subscriptionService.getFillsCacheIfInitialized();

    if (cachedFills !== null) {
      this.#deps.debugLogger.log('Using WebSocket cached fills', {
        count: cachedFills.length,
        params,
      });
      return this.#filterFills(cachedFills, params);
    }

    // Fallback to REST API when cache not initialized
    this.#deps.debugLogger.log(
      'Fills cache miss for getOrFetchFills, falling back to REST',
      { params },
    );
    const restFills = await this.getOrderFills(params);
    // Apply symbol filter to REST results for consistent API behavior
    // Note: getOrderFills doesn't support symbol filtering natively
    return this.#filterFills(restFills, params);
  }

  /**
   * Filter fills array by optional startTime and symbol parameters
   *
   * @param fills - Array of fills to filter
   * @param params - Optional filter parameters
   * @param params.startTime - Start timestamp in milliseconds.
   * @param params.symbol - The trading pair symbol.
   * @returns Filtered fills array
   */
  #filterFills(
    fills: OrderFill[],
    params?: { startTime?: number; symbol?: string },
  ): OrderFill[] {
    if (!params) {
      return fills;
    }

    return fills.filter((fill) => {
      if (params.startTime && fill.timestamp < params.startTime) {
        return false;
      }
      if (params.symbol && fill.symbol !== params.symbol) {
        return false;
      }
      return true;
    });
  }

  /**
   * Get all available DEXs without allowlist filtering
   * Used when skipFilters=true in getMarkets()
   *
   * @returns Array of all DEX names (null for main DEX, strings for HIP-3 DEXs)
   */
  async #getAllAvailableDexs(): Promise<(string | null)[]> {
    // Use unified state if available
    if (this.#dexDiscoveryCache.state) {
      const availableHip3Dexs: string[] = [];
      this.#dexDiscoveryCache.state.raw.forEach((dex) => {
        if (dex !== null) {
          availableHip3Dexs.push(dex.name);
        }
      });
      return [null, ...availableHip3Dexs];
    }

    // Fetch fresh from API and update unified state
    const infoClient = this.#clientService.getInfoClient();
    try {
      const allDexs = await infoClient.perpDexs();
      if (!allDexs || !Array.isArray(allDexs)) {
        return [null]; // Fallback to main DEX only
      }

      const state = this.#dexDiscoveryCache.update(allDexs);
      const availableHip3Dexs: string[] = [];
      state.raw.forEach((dex) => {
        if (dex !== null) {
          availableHip3Dexs.push(dex.name);
        }
      });
      return [null, ...availableHip3Dexs];
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getAllAvailableDexs'),
        this.#getErrorContext('getAllAvailableDexs'),
      );
      return [null]; // Fallback to main DEX only
    }
  }

  /**
   * Get validated list of DEXs to use based on feature flags and allowlist
   * Implements Step 3b from HIP-3-IMPLEMENTATION.md (lines 108-134)
   *
   * Logic Flow:
   * 1. If hip3Enabled === false → Return [null] (main DEX only)
   * 2. Fetch available DEXs via SDK: infoClient.perpDexs()
   * 3. If enabledDexs is empty [] → Return [null, ...allDiscoveredDexs] (auto-discover)
   * 4. Else filter enabledDexs against available DEXs → Return [null, ...validatedDexs] (allowlist)
   *
   * Invalid DEX names are silently filtered with debugLogger warning.
   *
   * @returns Array of DEX names to use (null = main DEX, strings = HIP-3 DEXs)
   */
  async #getValidatedDexs(): Promise<(string | null)[]> {
    // Kill switch: HIP-3 disabled, return main DEX only
    // Must check before cache — #getAllAvailableDexs() can populate
    // state.validated without the hip3Enabled gate
    if (!this.#hip3Enabled) {
      return [null];
    }

    // Return cached result if available
    if (this.#dexDiscoveryCache.state?.validated) {
      return this.#dexDiscoveryCache.state.validated;
    }

    // If a fetch is already in progress, reuse the pending promise
    // This prevents duplicate perpDexs() API calls from concurrent callers
    if (this.#pendingValidatedDexsPromise !== null) {
      this.#deps.debugLogger.log(
        '[getValidatedDexs] Reusing pending promise for perpDexs fetch',
      );
      return this.#pendingValidatedDexsPromise;
    }

    // Create and cache the pending promise for deduplication
    this.#pendingValidatedDexsPromise = this.#fetchValidatedDexsInternal();

    try {
      const result = await this.#pendingValidatedDexsPromise;
      return result;
    } finally {
      // Clear the pending promise when done (success or error)
      this.#pendingValidatedDexsPromise = null;
    }
  }

  /**
   * Internal method that performs the actual perpDexs fetch and caching
   * Separated from getValidatedDexs to enable promise deduplication
   *
   * @returns A promise that resolves to the result.
   */
  async #fetchValidatedDexsInternal(): Promise<(string | null)[]> {
    // Kill switch: HIP-3 disabled, return main DEX only
    if (!this.#hip3Enabled) {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: HIP-3 disabled via hip3Enabled flag',
      );
      const state = this.#dexDiscoveryCache.update([null]);
      return state.validated;
    }

    // Fetch all available DEXs from HyperLiquid
    const infoClient = this.#clientService.getInfoClient();
    let allDexs;
    try {
      allDexs = await infoClient.perpDexs();
    } catch (error) {
      // debugLogger not logger.error: this is a handled transient failure — the app
      // recovers to main DEX via return [null]. Sending to Sentry as error() is noise.
      this.#deps.debugLogger.log(
        '[fetchValidatedDexsInternal] perpDexs() call failed, falling back to main DEX',
        {
          error: String(error),
          ...this.#getErrorContext('getValidatedDexs.perpDexs'),
        },
      );
      // Do not cache — transient error, allow retry on next call
      return [null];
    }

    // Validate API response
    if (!allDexs || !Array.isArray(allDexs)) {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Failed to fetch DEX list (invalid response), falling back to main DEX only',
        { allDexs },
      );
      // Do not cache — may be transient, allow retry on next call
      return [null];
    }

    // Atomically update unified state (raw + validated + timestamp)
    const state = this.#dexDiscoveryCache.update(allDexs);

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Available DEXs (market filtering applied at data layer)',
      {
        count: state.validated.filter((dex) => dex !== null).length,
        dexNames: state.validated.filter((dex) => dex !== null),
      },
    );

    return state.validated;
  }

  /**
   * Get cached meta response for a DEX, fetching from API if not cached
   * This helper consolidates cache logic to avoid redundant API calls across the provider
   *
   * @param params - The operation parameters.
   * @param params.dexName - DEX name (null for main DEX).
   * @param params.skipCache - If true, bypass cache and fetch fresh data.
   * @returns MetaResponse with universe data.
   * @throws Error if API returns invalid data
   */
  async #getCachedMeta(params: {
    dexName: string | null;
    skipCache?: boolean;
  }): Promise<MetaResponse> {
    const { dexName, skipCache } = params;
    // Use empty string for main DEX key (consistent with buildAssetMapping cache population)
    const dexKey = dexName ?? '';
    const dexDisplayName = dexKey || 'main';

    // Skip cache if requested (forces fresh fetch)
    if (!skipCache) {
      const cached = this.#cachedMetaByDex.get(dexKey);
      if (cached) {
        this.#deps.debugLogger.log(
          '[getCachedMeta] Using cached meta response',
          {
            dex: dexDisplayName,
            universeSize: cached.universe.length,
          },
        );
        return cached;
      }
    }

    // Cache miss or skipCache=true - fetch from API
    const infoClient = this.#clientService.getInfoClient();
    // Pass dex only for HIP-3 DEXs; omit for main DEX (empty string).
    // Testnet API returns null when dex="" is explicitly sent.
    const meta = await infoClient.meta(dexKey ? { dex: dexKey } : undefined);

    // Defensive validation before caching
    if (!meta?.universe || !Array.isArray(meta.universe)) {
      throw new Error(
        `[HyperLiquidProvider] Invalid meta response for DEX ${dexDisplayName}: universe is ${meta?.universe ? 'not an array' : 'missing'}`,
      );
    }

    // Store raw meta response for reuse
    this.#cachedMetaByDex.set(dexKey, meta);
    await this.#backfillAssetMapForDex(dexName, meta);

    this.#deps.debugLogger.log(
      '[getCachedMeta] Fetched and cached meta response',
      {
        dex: dexDisplayName,
        universeSize: meta.universe.length,
        skipCache,
      },
    );

    return meta;
  }

  /**
   * Backfill the asset ID map for a single DEX from a fresh meta response.
   * Used to repair partial asset mapping when an individual DEX becomes available later.
   *
   * @param dex - DEX name (null for main DEX).
   * @param meta - Meta response containing the DEX universe.
   * @returns True if the mapping was rebuilt for the DEX.
   */
  async #backfillAssetMapForDex(
    dex: string | null,
    meta: MetaResponse,
  ): Promise<boolean> {
    if (!meta?.universe || !Array.isArray(meta.universe)) {
      return false;
    }

    if (!this.#dexDiscoveryCache.state) {
      try {
        await this.#getValidatedDexs();
      } catch (error) {
        this.#deps.debugLogger.log(
          '[backfillAssetMapForDex] Unable to refresh validated DEXs before rebuilding asset map',
          {
            dex: dex ?? 'main',
            error: ensureError(
              error,
              'HyperLiquidProvider.backfillAssetMapForDex',
            ).message,
          },
        );
      }
    }

    const allPerpDexs = this.#dexDiscoveryCache.state?.raw ?? [null];
    const perpDexIndex = allPerpDexs.findIndex((entry) => {
      if (dex === null) {
        return entry === null;
      }
      return entry !== null && entry.name === dex;
    });

    if (perpDexIndex === -1) {
      this.#deps.debugLogger.log(
        '[backfillAssetMapForDex] Could not find perpDexIndex for DEX',
        { dex: dex ?? 'main' },
      );
      return false;
    }

    const { symbolToAssetId } = buildAssetMapping({
      metaUniverse: meta.universe,
      dex,
      perpDexIndex,
    });

    symbolToAssetId.forEach((assetId, coin) => {
      this.#symbolToAssetId.set(coin, assetId);
    });

    this.#deps.debugLogger.log(
      '[backfillAssetMapForDex] Rebuilt asset mapping for DEX',
      {
        dex: dex ?? 'main',
        dexAssetCount: symbolToAssetId.size,
        totalAssetCount: this.#symbolToAssetId.size,
      },
    );

    return symbolToAssetId.size > 0;
  }

  /**
   * Resolve an asset ID, repairing the DEX-specific map when meta is available but the map is stale.
   *
   * @param params - Resolution parameters.
   * @param params.symbol - Asset symbol to resolve.
   * @param params.dexName - DEX name (null for main DEX).
   * @param params.meta - Optional pre-fetched meta for the DEX.
   * @returns The asset ID.
   */
  async #getAssetIdWithRepair(params: {
    symbol: string;
    dexName: string | null;
    meta?: MetaResponse;
  }): Promise<number> {
    const { symbol, dexName } = params;
    const existingAssetId = this.#symbolToAssetId.get(symbol);

    if (existingAssetId !== undefined) {
      return existingAssetId;
    }

    const meta =
      params.meta ?? (await this.#getCachedMeta({ dexName: dexName ?? null }));
    const assetExistsInMeta = meta.universe.some(
      (asset) => asset.name === symbol,
    );

    if (assetExistsInMeta) {
      await this.#backfillAssetMapForDex(dexName, meta);
      const repairedAssetId = this.#symbolToAssetId.get(symbol);
      if (repairedAssetId !== undefined) {
        return repairedAssetId;
      }
    }

    this.#deps.debugLogger.log('Asset ID lookup failed', {
      requestedCoin: symbol,
      dexName: dexName ?? 'main',
      mapSize: this.#symbolToAssetId.size,
      mapContainsAsset: this.#symbolToAssetId.has(symbol),
      assetExistsInMeta,
      allKeys: Array.from(this.#symbolToAssetId.keys()).slice(0, 20),
    });

    throw new Error(`Asset ID not found for ${symbol}`);
  }

  /**
   * Fetch spot metadata with session-based caching
   * Contains token info (USDC, USDH indices) needed for HIP-3 collateral checks
   * Pre-fetched in ensureReadyForTrading() to ensure availability during order placement
   *
   * @returns SpotMetaResponse with tokens and universe data
   */
  async #getCachedSpotMeta(): Promise<SpotMetaResponse> {
    if (this.#cachedSpotMeta) {
      this.#deps.debugLogger.log('[getCachedSpotMeta] Using cached spotMeta', {
        tokensCount: this.#cachedSpotMeta.tokens.length,
        universeCount: this.#cachedSpotMeta.universe.length,
      });
      return this.#cachedSpotMeta;
    }

    const infoClient = this.#clientService.getInfoClient();
    const spotMeta = await infoClient.spotMeta();

    this.#cachedSpotMeta = spotMeta;
    this.#deps.debugLogger.log(
      '[getCachedSpotMeta] Fetched and cached spotMeta',
      {
        tokensCount: spotMeta.tokens.length,
        universeCount: spotMeta.universe.length,
      },
    );

    return spotMeta;
  }

  /**
   * Fetch perpDexs data with TTL-based caching
   * Returns deployerFeeScale info needed for dynamic fee calculation
   *
   * @returns Array of ExtendedPerpDex objects (null entries represent main DEX)
   */
  async #getCachedPerpDexs(): Promise<ExtendedPerpDex[]> {
    const now = Date.now();

    // Return cached data if still valid (uses unified state timestamp for TTL)
    if (
      this.#dexDiscoveryCache.state &&
      now - this.#dexDiscoveryCache.state.timestamp <
        HIP3_FEE_CONFIG.PerpDexsCacheTtlMs
    ) {
      const raw = this.#dexDiscoveryCache.state.raw as ExtendedPerpDex[];
      this.#deps.debugLogger.log(
        '[getCachedPerpDexs] Using cached perpDexs data',
        {
          age: `${Math.round((now - this.#dexDiscoveryCache.state.timestamp) / 1000)}s`,
          count: raw.length,
        },
      );
      return raw;
    }

    // Fetch fresh data from API
    // Note: SDK types are incomplete, but API returns deployerFeeScale
    await this.#ensureClientsInitialized();
    const infoClient = this.#clientService.getInfoClient();
    const perpDexs =
      (await infoClient.perpDexs()) as unknown as ExtendedPerpDex[];

    // Atomically update unified state (raw + validated + timestamp)
    this.#dexDiscoveryCache.update(perpDexs);

    this.#deps.debugLogger.log(
      '[getCachedPerpDexs] Fetched and cached perpDexs data',
      {
        count: perpDexs.length,
        dexes: perpDexs
          .filter((dex) => dex !== null)
          .map((dex) => ({
            name: dex.name,
            deployerFeeScale: dex.deployerFeeScale,
          })),
      },
    );

    return perpDexs;
  }

  /**
   * Calculate HIP-3 fee multiplier using HyperLiquid's official formula
   * Fetches deployerFeeScale from perpDexs API and growthMode from meta API
   *
   * Formula from HyperLiquid docs:
   * - scaleIfHip3 = deployerFeeScale < 1 ? deployerFeeScale + 1 : deployerFeeScale * 2
   * - growthModeScale = growthMode ? 0.1 : 1
   * - finalMultiplier = scaleIfHip3 * growthModeScale
   *
   * @param params - The operation parameters.
   * @param params.dexName - The DEX identifier (empty string for main DEX).
   * @param params.assetSymbol - The asset symbol.
   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees#fee-formula-for-developers
   * @returns The result of the operation.
   */
  async #calculateHip3FeeMultiplier(params: {
    dexName: string;
    assetSymbol: string;
  }): Promise<number> {
    const { dexName, assetSymbol } = params;

    try {
      // Get deployerFeeScale from perpDexs
      const perpDexs = await this.#getCachedPerpDexs();
      const dexInfo = perpDexs.find((dex) => dex?.name === dexName);
      const parsedScale = parseFloat(dexInfo?.deployerFeeScale ?? '');
      const deployerFeeScale = Number.isNaN(parsedScale)
        ? HIP3_FEE_CONFIG.DefaultDeployerFeeScale
        : parsedScale;

      // Get growthMode from meta for this specific asset
      const meta = await this.#getCachedMeta({ dexName });
      const fullAssetName = `${dexName}:${assetSymbol}`;
      const assetMeta = meta.universe.find(
        (univ) => (univ as ExtendedAssetMeta).name === fullAssetName,
      ) as ExtendedAssetMeta | undefined;
      const isGrowthMode = assetMeta?.growthMode === 'enabled';

      // Apply official formula
      const scaleIfHip3 =
        deployerFeeScale < 1 ? deployerFeeScale + 1 : deployerFeeScale * 2;
      const growthModeScale = isGrowthMode
        ? HIP3_FEE_CONFIG.GrowthModeScale
        : 1;

      const finalMultiplier = scaleIfHip3 * growthModeScale;

      this.#deps.debugLogger.log('HIP-3 Dynamic Fee Calculation', {
        dexName,
        assetSymbol,
        fullAssetName,
        deployerFeeScale,
        isGrowthMode,
        scaleIfHip3,
        growthModeScale,
        finalMultiplier,
      });

      return finalMultiplier;
    } catch (error) {
      this.#deps.debugLogger.log(
        'HIP-3 Fee Calculation Failed, using fallback',
        {
          dexName,
          assetSymbol,
          error: ensureError(
            error,
            'HyperLiquidProvider.calculateHip3FeeMultiplier',
          ).message,
        },
      );
      // Safe fallback: standard HIP-3 2x multiplier (no Growth Mode discount)
      return HIP3_FEE_CONFIG.DefaultDeployerFeeScale * 2;
    }
  }

  /**
   * Generate session cache key for user-specific caches
   * Format: "network:userAddress" (address normalized to lowercase)
   *
   * @param network - 'mainnet' or 'testnet'
   * @param userAddress - User's Ethereum address
   * @returns Cache key for session-based caches
   */
  #getCacheKey(network: string, userAddress: string): string {
    return `${network}:${userAddress.toLowerCase()}`;
  }

  /**
   * Fetch markets for a specific DEX with optional filtering
   * Uses session-based caching via getCachedMeta() - no TTL, cleared on disconnect
   *
   * @param params - The operation parameters.
   * @param params.dex - DEX name (null for main DEX).
   * @param params.skipFilters - If true, skip HIP-3 filtering (return all markets).
   * @param params.skipCache - If true, bypass cache and fetch fresh data.
   * @returns Array of MarketInfo objects.
   */
  async #fetchMarketsForDex(params: {
    dex: string | null;
    skipFilters?: boolean;
    skipCache?: boolean;
  }): Promise<MarketInfo[]> {
    const { dex, skipFilters = false, skipCache = false } = params;

    // Get raw meta response (uses session cache unless skipCache=true)
    const meta = await this.#getCachedMeta({ dexName: dex, skipCache });

    if (!meta.universe || !Array.isArray(meta.universe)) {
      this.#deps.debugLogger.log(
        `HyperLiquidProvider: Invalid universe data for DEX ${dex ?? 'main'}`,
      );
      return [];
    }

    // Transform to MarketInfo format
    const markets = meta.universe.map((asset) => adaptMarketFromSDK(asset));

    // Apply HIP-3 filtering on-demand (cheap array operation)
    // Skip filtering for main DEX (null) or if explicitly requested
    const filteredMarkets =
      skipFilters || dex === null
        ? markets
        : markets.filter((market) =>
            shouldIncludeMarket(
              market.name,
              dex,
              this.#hip3Enabled,
              this.#compiledAllowlistPatterns,
              this.#compiledBlocklistPatterns,
            ),
          );

    this.#deps.debugLogger.log('HyperLiquidProvider: Fetched markets for DEX', {
      dex: dex ?? 'main',
      marketCount: filteredMarkets.length,
      skipFilters,
      skipCache,
    });

    return filteredMarkets;
  }

  /**
   * Get USDC token ID from spot metadata
   * Returns format: "USDC:{hex_token_id}"
   * Caches result to avoid repeated API calls
   *
   * @returns A promise that resolves to the string result.
   */
  async #getUsdcTokenId(): Promise<string> {
    if (this.#cachedUsdcTokenId) {
      return this.#cachedUsdcTokenId;
    }

    const spotMeta = await this.#getCachedSpotMeta();

    const usdcToken = spotMeta.tokens.find((tok) => tok.name === 'USDC');
    if (!usdcToken) {
      throw new Error('USDC token not found in spot metadata');
    }

    this.#cachedUsdcTokenId = `USDC:${usdcToken.tokenId}`;
    this.#deps.debugLogger.log('HyperLiquidProvider: USDC token ID cached', {
      tokenId: this.#cachedUsdcTokenId,
    });

    return this.#cachedUsdcTokenId;
  }

  /**
   * Check if a HIP-3 DEX uses USDH as collateral (vs USDC)
   * Per HyperLiquid docs: USDH DEXs pull collateral from spot balance automatically
   *
   * @param dexName - The DEX identifier (empty string for main DEX).
   * @returns A promise that resolves to the boolean result.
   */
  async #isUsdhCollateralDex(dexName: string): Promise<boolean> {
    const meta = await this.#getCachedMeta({ dexName });
    const spotMeta = await this.#getCachedSpotMeta();

    const collateralToken = spotMeta.tokens.find(
      (tok: { index: number }) => tok.index === meta.collateralToken,
    );

    const isUsdh = collateralToken?.name === USDH_CONFIG.TokenName;

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Checked DEX collateral type',
      {
        dexName,
        collateralTokenIndex: meta.collateralToken,
        collateralTokenName: collateralToken?.name,
        isUsdh,
      },
    );

    return isUsdh;
  }

  /**
   * Get user's USDH balance in spot wallet
   *
   * @returns A promise that resolves to the numeric result.
   */
  async #getSpotUsdhBalance(): Promise<number> {
    const infoClient = this.#clientService.getInfoClient();
    const userAddress = await this.#walletService.getUserAddressWithDefault();

    const spotState = await infoClient.spotClearinghouseState({
      user: userAddress,
    });

    const usdhBalance = spotState.balances.find(
      (b: { coin: string }) => b.coin === USDH_CONFIG.TokenName,
    );

    const balance = usdhBalance ? parseFloat(usdhBalance.total) : 0;

    this.#deps.debugLogger.log('HyperLiquidProvider: Spot USDH balance', {
      balance,
      userAddress,
    });

    return balance;
  }

  /**
   * Get user's USDC balance in spot wallet
   * Required for USDH DEX orders - need USDC in spot to swap to USDH
   *
   * @returns A promise that resolves to the numeric result.
   */
  async #getSpotUsdcBalance(): Promise<number> {
    const infoClient = this.#clientService.getInfoClient();
    const userAddress = await this.#walletService.getUserAddressWithDefault();

    const spotState = await infoClient.spotClearinghouseState({
      user: userAddress,
    });

    const usdcBalance = spotState.balances.find(
      (b: { coin: string }) => b.coin === 'USDC',
    );

    const balance = usdcBalance ? parseFloat(usdcBalance.total) : 0;

    this.#deps.debugLogger.log('HyperLiquidProvider: Spot USDC balance', {
      balance,
      userAddress,
    });

    return balance;
  }

  /**
   * Transfer USDC from main perps wallet to spot wallet
   * Required before swapping USDC→USDH for USDH DEX orders
   *
   * @param amount - The amount value.
   * @returns A promise that resolves to the result.
   */
  async #transferUsdcToSpot(
    amount: number,
  ): Promise<{ success: boolean; error?: string }> {
    const exchangeClient = this.#clientService.getExchangeClient();
    const userAddress = await this.#walletService.getUserAddressWithDefault();

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Transferring USDC to spot',
      {
        amount,
        userAddress,
      },
    );

    try {
      const result = await exchangeClient.sendAsset({
        destination: userAddress,
        sourceDex: '', // Main perps DEX (empty string)
        destinationDex: 'spot',
        token: await this.#getUsdcTokenId(),
        amount: amount.toString(),
      });

      if (result.status === 'ok') {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: USDC transferred to spot',
          {
            amount,
          },
        );
        return { success: true };
      }

      return { success: false, error: PERPS_ERROR_CODES.TRANSFER_FAILED };
    } catch (error) {
      const errorMsg = ensureError(
        error,
        'HyperLiquidProvider.transferUSDCToPerps',
      ).message;
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: USDC transfer to spot failed',
        {
          error: errorMsg,
        },
      );
      return { success: false, error: errorMsg };
    }
  }

  /**
   * Swap USDC to USDH on spot market
   * Returns the result of the swap including filled size
   *
   * @param amount - The amount value.
   * @returns A promise that resolves to the result.
   */
  async #swapUsdcToUsdh(
    amount: number,
  ): Promise<{ success: boolean; filledSize?: number; error?: string }> {
    const spotMeta = await this.#getCachedSpotMeta();

    // Find USDH and USDC tokens by name
    const usdhToken = spotMeta.tokens.find(
      (tok: { name: string }) => tok.name === USDH_CONFIG.TokenName,
    );
    const usdcToken = spotMeta.tokens.find(
      (tok: { name: string }) => tok.name === 'USDC',
    );

    if (!usdhToken || !usdcToken) {
      return {
        success: false,
        error: PERPS_ERROR_CODES.SPOT_PAIR_NOT_FOUND,
      };
    }

    // Find USDH/USDC pair by token indices (NOT by name - name is @230)
    const usdhUsdcPair = spotMeta.universe.find(
      (univ: { tokens: number[] }) =>
        univ.tokens.includes(usdhToken.index) &&
        univ.tokens.includes(usdcToken.index),
    );

    if (!usdhUsdcPair) {
      return { success: false, error: PERPS_ERROR_CODES.SPOT_PAIR_NOT_FOUND };
    }

    const spotAssetId = SPOT_ASSET_ID_OFFSET + usdhUsdcPair.index;

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Found USDH/USDC spot pair',
      {
        pairIndex: usdhUsdcPair.index,
        pairName: usdhUsdcPair.name,
        spotAssetId,
        usdhTokenIndex: usdhToken.index,
        usdcTokenIndex: usdcToken.index,
      },
    );

    // Get current mid price
    const infoClient = this.#clientService.getInfoClient();
    const allMids = await infoClient.allMids();
    const pairKey = `@${usdhUsdcPair.index}`;
    const usdhPrice = parseFloat(allMids[pairKey] || '1');

    if (usdhPrice === 0) {
      return {
        success: false,
        error: PERPS_ERROR_CODES.PRICE_UNAVAILABLE,
      };
    }

    // Calculate order parameters
    // USDH is pegged 1:1 to USDC, add small slippage buffer
    const slippageMultiplier =
      1 + USDH_CONFIG.SwapSlippageBps / BASIS_POINTS_DIVISOR;
    const maxPrice = usdhPrice * slippageMultiplier;

    // Size in USDH = amount / price (since we're buying USDH with USDC)
    let sizeInUsdh = amount / usdhPrice;

    // Format size according to HyperLiquid requirements
    let formattedSize = sizeInUsdh.toFixed(usdhToken.szDecimals);

    // CRITICAL: Ensure USDC cost meets $10 minimum after rounding
    // At price ~0.999995, buying 10.00 USDH costs 9.99995 USDC (under minimum)
    // Bump up by one increment if needed to meet minimum
    const minSpotOrderValue = TRADING_DEFAULTS.amount.mainnet;
    const estimatedCost = parseFloat(formattedSize) * usdhPrice;
    if (estimatedCost < minSpotOrderValue) {
      const increment = Math.pow(10, -usdhToken.szDecimals); // 0.01 for szDecimals=2
      sizeInUsdh = parseFloat(formattedSize) + increment;
      formattedSize = sizeInUsdh.toFixed(usdhToken.szDecimals);
    }

    // Format price according to HyperLiquid requirements
    const formattedPrice = formatHyperLiquidPrice({
      price: maxPrice,
      szDecimals: usdhToken.szDecimals,
    });

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Placing USDC→USDH swap order',
      {
        usdcAmount: amount,
        usdhPrice,
        maxPrice: formattedPrice,
        size: formattedSize,
        szDecimals: usdhToken.szDecimals,
      },
    );

    try {
      const exchangeClient = this.#clientService.getExchangeClient();
      const result = await exchangeClient.order({
        orders: [
          {
            a: spotAssetId,
            b: true, // Buy USDH
            p: formattedPrice,
            s: formattedSize,
            r: false, // Not reduce-only
            t: { limit: { tif: 'Ioc' } }, // Immediate-or-cancel
          },
        ],
        grouping: 'na',
      });

      if (result.status !== 'ok') {
        return {
          success: false,
          error: PERPS_ERROR_CODES.SWAP_FAILED,
        };
      }

      // Check order status
      const status = result.response?.data?.statuses?.[0];
      if (isStatusObject(status) && hasProperty(status, 'error')) {
        return { success: false, error: String(status.error) };
      }

      // Note: `in` narrows the HyperLiquid SDK discriminated union to the
      // branch that has `filled`; `hasProperty` only narrows the key and
      // types `status.filled` as `unknown`, which loses access to `.totalSz`.
      /* eslint-disable no-restricted-syntax */
      const filledSize =
        isStatusObject(status) && 'filled' in status
          ? parseFloat(status.filled?.totalSz ?? '0')
          : 0;
      /* eslint-enable no-restricted-syntax */

      this.#deps.debugLogger.log(
        'HyperLiquidProvider: USDC→USDH swap completed',
        {
          success: true,
          filledSize,
          requestedSize: formattedSize,
        },
      );

      return { success: true, filledSize };
    } catch (error) {
      const errorMsg = ensureError(
        error,
        'HyperLiquidProvider.swapUSDCToUSDH',
      ).message;
      this.#deps.debugLogger.log('HyperLiquidProvider: USDC→USDH swap error', {
        error: errorMsg,
      });
      return { success: false, error: errorMsg };
    }
  }

  /**
   * Ensure sufficient USDH collateral in spot for HIP-3 DEX order
   * If user lacks USDH, auto-swap from USDC
   *
   * @param dexName - The DEX identifier (empty string for main DEX).
   * @param requiredMargin - The required margin amount.
   */
  async #ensureUsdhCollateralForOrder(
    dexName: string,
    requiredMargin: number,
  ): Promise<void> {
    const spotUsdhBalance = await this.#getSpotUsdhBalance();

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Checking USDH collateral',
      {
        dexName,
        requiredMargin,
        spotUsdhBalance,
      },
    );

    if (spotUsdhBalance >= requiredMargin) {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Sufficient USDH in spot',
      );
      return;
    }

    const shortfall = requiredMargin - spotUsdhBalance;
    // HyperLiquid spot has $10 minimum order value
    const minSpotOrderValue = TRADING_DEFAULTS.amount.mainnet;

    // If user has some USDH already, we can swap just the shortfall (if >= $10)
    // If user has zero USDH, they need at least $10 for first swap
    const swapAmount =
      spotUsdhBalance > 0 && shortfall >= minSpotOrderValue
        ? shortfall
        : Math.max(shortfall, minSpotOrderValue);

    // Step 1: Check spot USDC balance
    const spotUsdcBalance = await this.#getSpotUsdcBalance();

    // Calculate total available USDC (spot + what we can transfer from perps)
    // For now, check if we have enough in spot first
    const totalUsdcNeeded = swapAmount - spotUsdcBalance;

    // Step 2: If insufficient USDC in spot, transfer from main perps
    if (spotUsdcBalance < swapAmount) {
      const transferAmount = totalUsdcNeeded;

      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Transferring USDC to spot for swap',
        {
          spotUsdcBalance,
          swapAmount,
          transferAmount,
        },
      );

      const transferResult = await this.#transferUsdcToSpot(transferAmount);
      if (!transferResult.success) {
        // Provide user-friendly error for insufficient funds
        if (transferResult.error?.includes('Insufficient balance')) {
          throw new Error(
            `Insufficient USDC balance. Need $${swapAmount.toFixed(2)} for USDH swap but transfer failed. Please deposit more USDC to your HyperLiquid account.`,
          );
        }
        throw new Error(
          `Failed to transfer USDC to spot: ${transferResult.error}`,
        );
      }
    }

    // Step 3: Swap USDC → USDH
    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Swapping USDC→USDH for collateral',
      {
        shortfall,
        swapAmount,
        minOrderValue: minSpotOrderValue,
      },
    );

    const swapResult = await this.#swapUsdcToUsdh(swapAmount);

    if (!swapResult.success) {
      throw new Error(
        `Failed to acquire USDH collateral for ${dexName}: ${swapResult.error}`,
      );
    }

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: USDH collateral acquired',
      {
        dexName,
        filledSize: swapResult.filledSize,
      },
    );
  }

  /**
   * Build asset ID mapping from market metadata
   * Fetches metadata for feature-flag-enabled DEXs and builds a unified mapping
   * with DEX-prefixed keys for HIP-3 assets (e.g., "xyz:XYZ100" → assetId)
   *
   * Per HIP-3-IMPLEMENTATION.md:
   * - Main DEX: assetId = index (0, 1, 2, ...)
   * - HIP-3 DEX: assetId = BASE_ASSET_ID + (perpDexIndex × DEX_MULTIPLIER) + index
   *
   * This enables proper order routing - when placeOrder({ symbol: "xyz:XYZ100" }) is called,
   * the asset ID lookup succeeds and the order routes to the correct DEX.
   */
  async #buildAssetMapping(): Promise<void> {
    // Get feature-flag-validated DEXs to map (respects hip3Enabled and enabledDexs)
    let dexsToMap: (string | null)[];
    try {
      dexsToMap = await this.#getValidatedDexs();
    } catch (dexError) {
      // If getValidatedDexs fails, fall back to main DEX only to keep the provider
      // functional. Without this, a transient perpDexs() failure would permanently
      // brick #ensureReady via the cached rejected promise.
      // Do not update #dexDiscoveryCache here — leave state null
      // so #getValidatedDexs retries on the next call (same as #fetchValidatedDexsInternal).
      this.#deps.debugLogger.log(
        '[buildAssetMapping] getValidatedDexs failed, falling back to main DEX',
        { error: String(dexError) },
      );
      dexsToMap = [null];
    }

    // Local fallback only — never write [null] into #dexDiscoveryCache here.
    // That state is owned exclusively by #dexDiscoveryCache.update(); writing a
    // fallback here would prevent subsequent callers from retrying perpDexs().
    const allPerpDexs = this.#dexDiscoveryCache.state?.raw ?? [null];

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Starting asset mapping rebuild',
      {
        dexs: dexsToMap,
        previousMapSize: this.#symbolToAssetId.size,
        hip3Enabled: this.#hip3Enabled,
        allowlistMarkets: this.#allowlistMarkets,
        blocklistMarkets: this.#blocklistMarkets,
        timestamp: new Date().toISOString(),
      },
    );

    // Update subscription service with current feature flags
    // Extract HIP-3 DEX names (filter out null which represents main DEX)
    const enabledDexs = dexsToMap.filter((dex): dex is string => dex !== null);

    await this.#subscriptionService.updateFeatureFlags(
      this.#hip3Enabled,
      enabledDexs,
      this.#allowlistMarkets,
      this.#blocklistMarkets,
    );

    // Fetch metadata for each DEX in parallel using metaAndAssetCtxs
    // Optimization: Check cache first - getMarketDataWithPrices may have already fetched
    // If not cached, fetch via metaAndAssetCtxs and populate cache for other methods
    const infoClient = this.#clientService.getInfoClient();
    const allMetas = await Promise.allSettled(
      dexsToMap.map((dex) => {
        const dexKey = dex ?? '';

        // Check if already cached (e.g., by getMarketDataWithPrices running in parallel)
        const cachedMeta = this.#cachedMetaByDex.get(dexKey);
        if (cachedMeta) {
          this.#deps.debugLogger.log(
            `[buildAssetMapping] Using cached meta for ${dex ?? 'main'}`,
            { universeSize: cachedMeta.universe.length },
          );
          return Promise.resolve({
            dex,
            meta: cachedMeta,
            success: true as const,
          });
        }

        // Not cached, fetch and populate cache
        const dexParam = dex ?? undefined;
        return infoClient
          .metaAndAssetCtxs(dexParam ? { dex: dexParam } : undefined)
          .then((result) => {
            const meta = result?.[0] || null;
            const assetCtxs = result?.[1] || [];
            // Cache meta for later use by getCachedMeta
            if (meta?.universe) {
              this.#cachedMetaByDex.set(dexKey, meta);
              // Also populate subscription service cache to avoid redundant API calls
              this.#subscriptionService.setDexMetaCache(dexKey, meta);
              // Cache assetCtxs for getMarketDataWithPrices (avoids duplicate metaAndAssetCtxs calls)
              this.#subscriptionService.setDexAssetCtxsCache(dexKey, assetCtxs);
            }
            return { dex, meta, success: true as const };
          })
          .catch((error) => {
            this.#deps.debugLogger.log(
              `HyperLiquidProvider: Failed to fetch metaAndAssetCtxs for DEX ${
                dex ?? 'main'
              }`,
              { error },
            );
            return { dex, meta: null, success: false as const };
          });
      }),
    );

    // Build mapping with DEX prefixes for HIP-3 DEXs using the utility function
    this.#symbolToAssetId.clear();
    let dexDiscoveryComplete = this.#dexDiscoveryCache.state !== null;

    allMetas.forEach((result) => {
      if (
        result.status === 'fulfilled' &&
        result.value.success &&
        result.value.meta
      ) {
        const { dex, meta } = result.value;

        // Validate that meta.universe exists and is an array
        if (!meta.universe || !Array.isArray(meta.universe)) {
          this.#deps.debugLogger.log(
            `HyperLiquidProvider: Skipping DEX ${
              dex ?? 'main'
            } - invalid or missing universe data`,
            {
              hasUniverse: Boolean(meta.universe),
              isArray: Array.isArray(meta.universe),
            },
          );
          dexDiscoveryComplete = false;
          return;
        }

        // Find perpDexIndex for this DEX in the perpDexs array
        // Main DEX (dex=null) is at index 0
        // HIP-3 DEXs are at indices 1, 2, 3, etc.
        const perpDexIndex = allPerpDexs.findIndex((entry) => {
          if (dex === null) {
            return entry === null; // Main DEX
          }
          return entry !== null && entry.name === dex;
        });

        if (perpDexIndex === -1) {
          this.#deps.debugLogger.log(
            `HyperLiquidProvider: Could not find perpDexIndex for DEX ${
              dex ?? 'main'
            }`,
          );
          dexDiscoveryComplete = false;
          return;
        }

        // Use the utility function to build mapping for this DEX
        const { symbolToAssetId } = buildAssetMapping({
          metaUniverse: meta.universe,
          dex,
          perpDexIndex,
        });

        // Merge into provider's map
        symbolToAssetId.forEach((assetId, coin) => {
          this.#symbolToAssetId.set(coin, assetId);
        });
      } else {
        dexDiscoveryComplete = false;
      }
    });

    this.#dexDiscoveryComplete = dexDiscoveryComplete;

    const allKeys = Array.from(this.#symbolToAssetId.keys());
    const mainDexKeys = allKeys.filter((key) => !key.includes(':')).slice(0, 5);
    const hip3Keys = allKeys.filter((key) => key.includes(':')).slice(0, 10);

    this.#deps.debugLogger.log('HyperLiquidProvider: Asset mapping built', {
      totalAssets: this.#symbolToAssetId.size,
      dexCount: dexsToMap.length,
      mainDexSample: mainDexKeys,
      hip3Sample: hip3Keys,
    });
  }

  /**
   * Set user fee discount context for next operations
   * Used by PerpsController to apply MetaMask reward discounts
   *
   * @param discountBips - The discount in basis points (e.g., 550 = 5.5%)
   */
  setUserFeeDiscount(discountBips: number | undefined): void {
    this.#userFeeDiscountBips = discountBips;

    this.#deps.debugLogger.log('HyperLiquid: Fee discount context updated', {
      discountBips,
      discountPercentage: discountBips ? discountBips / 100 : undefined,
      isActive: discountBips !== undefined,
    });
  }

  /**
   * Query user data across all enabled DEXs in parallel
   *
   * DRY helper for multi-DEX user data queries. Handles feature flag logic
   * and DEX iteration in one place. Uses cached getValidatedDexs() to avoid
   * redundant perpDexs() API calls.
   *
   * @param baseParams - Base parameters (e.g., { user: '0x...' })
   * @param queryFn - API method to call per DEX
   * @returns Array of results per DEX with DEX identifier
   * @example
   * ```typescript
   * const results = await this.#queryUserDataAcrossDexs(
   *   { user: userAddress },
   *   (p) => infoClient.clearinghouseState(p)
   * );
   * ```
   */
  async #queryUserDataAcrossDexs<
    TParams extends Record<string, unknown>,
    TResult,
  >(
    baseParams: TParams,
    queryFn: (params: TParams & { dex?: string }) => Promise<TResult>,
  ): Promise<DexQueryResponse<TResult>> {
    const enabledDexs = await this.#getValidatedDexs();

    const settledResults = await Promise.allSettled(
      enabledDexs.map(async (dex) => {
        const params = dex
          ? ({ ...baseParams, dex } as TParams & { dex: string })
          : (baseParams as TParams & { dex?: string });
        return queryFn(params);
      }),
    );

    const results: DexQueryResult<TResult>[] = [];
    const failedDexs: DexQueryResponse<TResult>['failedDexs'] = [];

    settledResults.forEach((result, index) => {
      const dex = enabledDexs[index];
      if (result.status === 'fulfilled') {
        results.push({ dex, data: result.value });
        return;
      }

      failedDexs.push({
        dex,
        error: ensureError(
          result.reason,
          'HyperLiquidProvider.queryUserDataAcrossDexs',
        ),
      });
    });

    return { results, failedDexs };
  }

  /**
   * Map HyperLiquid API errors to standardized PERPS_ERROR_CODES
   *
   * @param error - The error that occurred.
   * @returns The result of the operation.
   */
  #mapError(error: unknown): Error {
    const { message } = ensureError(error, 'HyperLiquidProvider.mapError');

    for (const [pattern, code] of Object.entries(this.#errorMappings)) {
      if (message.toLowerCase().includes(pattern.toLowerCase())) {
        return new Error(code);
      }
    }

    // Return original error to preserve stack trace for unmapped errors
    return ensureError(error, 'HyperLiquidProvider.mapError');
  }

  /**
   * Get error context for logging with searchable tags and context.
   * Enables Sentry dashboard filtering by feature, provider, and network.
   *
   * @param method - The method name where the error occurred
   * @param extra - Optional additional context fields (becomes searchable context data)
   * @returns LoggerErrorOptions with tags (searchable) and context (searchable)
   * @private
   * @example
   * this.#deps.logger.error(error, this.#getErrorContext('placeOrder', { symbol: 'BTC', orderType: 'limit' }));
   * // Creates searchable tags: feature:perps, provider:hyperliquid, network:mainnet
   * // Creates searchable context: perps_provider.method:placeOrder, perps_provider.symbol:BTC, perps_provider.orderType:limit
   */
  #getErrorContext(
    method: string,
    extra?: Record<string, unknown>,
  ): {
    tags?: Record<string, string | number>;
    context?: { name: string; data: Record<string, unknown> };
    extras?: Record<string, unknown>;
  } {
    return {
      tags: {
        feature: PERPS_CONSTANTS.FeatureName,
        provider: this.protocolId,
        network: this.#clientService.isTestnetMode() ? 'testnet' : 'mainnet',
      },
      context: {
        name: 'HyperLiquidProvider',
        data: {
          method,
          ...extra,
        },
      },
    };
  }

  /**
   * Get supported deposit routes with complete asset and routing information
   *
   * @param params - The operation parameters.
   * @returns The result of the operation.
   */
  getDepositRoutes(params?: GetSupportedPathsParams): AssetRoute[] {
    const isTestnet = params?.isTestnet ?? this.#clientService.isTestnetMode();
    const supportedAssets = getSupportedPaths({ ...params, isTestnet });
    const bridgeInfo = getBridgeInfo(isTestnet);

    return supportedAssets.map((assetId) => ({
      assetId,
      chainId: bridgeInfo.chainId,
      contractAddress: bridgeInfo.contractAddress,
      constraints: {
        minAmount: WITHDRAWAL_CONSTANTS.DefaultMinAmount,
        estimatedMinutes: HYPERLIQUID_WITHDRAWAL_MINUTES,
        fees: {
          fixed: WITHDRAWAL_CONSTANTS.DefaultFeeAmount,
          token: WITHDRAWAL_CONSTANTS.DefaultFeeToken,
        },
      },
    }));
  }

  /**
   * Get supported withdrawal routes with complete asset and routing information
   *
   * @param params - The operation parameters.
   * @returns The result of the operation.
   */
  getWithdrawalRoutes(params?: GetSupportedPathsParams): AssetRoute[] {
    // For HyperLiquid, withdrawal routes are the same as deposit routes
    return this.getDepositRoutes(params);
  }

  /**
   * Check current builder fee approval for the user
   *
   * @returns Current max fee rate or null if not approved
   */
  async #checkBuilderFeeApproval(): Promise<number | null> {
    const infoClient = this.#clientService.getInfoClient();
    const userAddress = await this.#walletService.getUserAddressWithDefault();
    const builder = this.#getBuilderAddress(
      this.#clientService.isTestnetMode(),
    );

    return infoClient.maxBuilderFee({
      user: userAddress,
      builder,
    });
  }

  /**
   * Ensure builder fee is approved for MetaMask
   * Called once during initialization (ensureReady) to set up builder fee for the session
   * Uses session cache to avoid redundant API calls until disconnect/reconnect
   *
   * Cache semantics: Uses GLOBAL cache to persist across provider reconnections
   * This prevents repeated signing requests for hardware wallets.
   *
   * Note: This is network-specific - testnet and mainnet have separate builder fee states
   */
  async #ensureBuilderFeeApproval(): Promise<void> {
    const isTestnet = this.#clientService.isTestnetMode();
    const network = isTestnet ? 'testnet' : 'mainnet';
    const builderAddress = this.#getBuilderAddress(isTestnet);
    const userAddress = await this.#walletService.getUserAddressWithDefault();
    const cacheKey = this.#getCacheKey(network, userAddress);

    // Check GLOBAL cache first to avoid repeated signing requests across reconnections
    // This is CRITICAL for hardware wallets to prevent QR popup spam
    const globalCached = PerpsSigningCache.getBuilderFee(network, userAddress);
    if (globalCached?.attempted) {
      this.#deps.debugLogger.log(
        '[ensureBuilderFeeApproval] Using global cache (prevents QR popup spam)',
        { network, success: globalCached.success },
      );
      if (globalCached.success) {
        this.#builderFeeCheckCache.set(cacheKey, true);
      }
      return;
    }

    // Check if another provider instance is currently attempting this operation
    const inFlightPromise = PerpsSigningCache.isInFlight(
      'builderFee',
      network,
      userAddress,
    );
    if (inFlightPromise) {
      this.#deps.debugLogger.log(
        '[ensureBuilderFeeApproval] Global in-flight, waiting...',
        { network },
      );
      await inFlightPromise;
      return;
    }

    // Set global in-flight lock
    const completeInFlight = PerpsSigningCache.setInFlight(
      'builderFee',
      network,
      userAddress,
    );

    try {
      // Re-check cache after acquiring lock
      const recheckCache = PerpsSigningCache.getBuilderFee(
        network,
        userAddress,
      );
      if (recheckCache?.attempted) {
        this.#deps.debugLogger.log(
          '[ensureBuilderFeeApproval] Completed by another provider',
          { network },
        );
        completeInFlight();
        return;
      }

      const { isApproved, requiredDecimal } =
        await this.#checkBuilderFeeStatus();

      if (isApproved) {
        // User already has approval on-chain
        PerpsSigningCache.setBuilderFee(network, userAddress, {
          attempted: true,
          success: true,
        });
        this.#builderFeeCheckCache.set(cacheKey, true);

        this.#deps.debugLogger.log(
          '[ensureBuilderFeeApproval] Already approved on-chain',
          { network },
        );
      } else {
        this.#deps.debugLogger.log(
          '[ensureBuilderFeeApproval] Approval required (will show signing request)',
          { builder: builderAddress, requiredDecimal },
        );

        const exchangeClient = this.#clientService.getExchangeClient();
        const maxFeeRate = BUILDER_FEE_CONFIG.MaxFeeRate;

        await exchangeClient.approveBuilderFee({
          builder: builderAddress,
          maxFeeRate,
        });

        // Verify approval was successful before caching
        const afterApprovalDecimal = await this.#checkBuilderFeeApproval();

        if (
          afterApprovalDecimal === null ||
          afterApprovalDecimal < requiredDecimal
        ) {
          throw new Error(
            '[HyperLiquidProvider] Builder fee approval verification failed',
          );
        }

        // Cache success in BOTH global and instance caches
        PerpsSigningCache.setBuilderFee(network, userAddress, {
          attempted: true,
          success: true,
        });
        this.#builderFeeCheckCache.set(cacheKey, true);

        this.#deps.debugLogger.log(
          '[ensureBuilderFeeApproval] Approval successful',
          {
            builder: builderAddress,
            maxFeeRate,
          },
        );
      }
      completeInFlight();
    } catch (error) {
      // If keyring is locked, don't cache so it retries when unlocked
      if (ensureError(error).message === PERPS_ERROR_CODES.KEYRING_LOCKED) {
        this.#deps.debugLogger.log(
          '[ensureBuilderFeeApproval] Keyring locked, will retry later',
        );
        completeInFlight();
        return;
      }

      // Cache failure to prevent retries
      PerpsSigningCache.setBuilderFee(network, userAddress, {
        attempted: true,
        success: false,
      });

      this.#deps.debugLogger.log(
        '[ensureBuilderFeeApproval] Failed, cached to prevent retries',
        {
          network,
          error: ensureError(
            error,
            'HyperLiquidProvider.ensureBuilderFeeApproval',
          ).message,
        },
      );

      completeInFlight();
      throw error;
    }
  }

  /**
   * Check if builder fee is approved for the current user
   *
   * @returns Object with approval status and current rate
   */
  async #checkBuilderFeeStatus(): Promise<{
    isApproved: boolean;
    currentRate: number | null;
    requiredDecimal: number;
  }> {
    const currentApproval = await this.#checkBuilderFeeApproval();
    const requiredDecimal = BUILDER_FEE_CONFIG.MaxFeeDecimal;

    return {
      isApproved:
        currentApproval !== null && currentApproval >= requiredDecimal,
      currentRate: currentApproval,
      requiredDecimal,
    };
  }

  /**
   * Get available balance for a specific DEX
   *
   * @param params - Balance query parameters
   * @param params.dex - DEX name (null = main, 'xyz' = HIP-3)
   * @returns Available balance in USDC
   * @private
   */
  async #getBalanceForDex(params: { dex: string | null }): Promise<number> {
    const { dex } = params;
    const userAddress = await this.#walletService.getUserAddressWithDefault();
    const infoClient = this.#clientService.getInfoClient();

    const queryParams = dex
      ? { user: userAddress, dex }
      : { user: userAddress };

    const accountState = await infoClient.clearinghouseState(queryParams);
    const adapted = adaptAccountStateFromSDK(accountState);
    return parseFloat(adapted.withdrawableBalance);
  }

  /**
   * Find source DEX with sufficient balance for transfer
   * Strategy: Prefer main DEX → other HIP-3 DEXs
   *
   * @param params - Source search parameters
   * @param params.targetDex - Target DEX name
   * @param params.requiredAmount - Required balance shortfall
   * @returns Source DEX info or null if insufficient funds
   * @private
   */
  async #findSourceDexWithBalance(params: {
    targetDex: string;
    requiredAmount: number;
  }): Promise<{ sourceDex: string; available: number } | null> {
    const { targetDex, requiredAmount } = params;

    // Try main DEX first
    try {
      const mainBalance = await this.#getBalanceForDex({ dex: null });
      if (mainBalance >= requiredAmount) {
        return { sourceDex: '', available: mainBalance };
      }
    } catch (error) {
      this.#deps.debugLogger.log('Could not fetch main DEX balance', { error });
    }

    // Try other HIP-3 DEXs
    // Get all available DEXs from cache (includes all HIP-3 DEXs since we no longer filter)
    const availableDexs =
      this.#dexDiscoveryCache.state?.validated?.filter(
        (dex): dex is string => dex !== null,
      ) ?? [];
    for (const dex of availableDexs) {
      if (dex === targetDex) {
        continue;
      }

      try {
        const balance = await this.#getBalanceForDex({ dex });
        if (balance >= requiredAmount) {
          return { sourceDex: dex, available: balance };
        }
      } catch (error) {
        this.#deps.debugLogger.log(`Could not fetch balance for DEX ${dex}`, {
          error,
        });
      }
    }

    return null;
  }

  /**
   * Auto-transfer funds for HIP-3 orders when insufficient balance
   * Only called for HIP-3 markets (not main DEX)
   *
   * @param params - Transfer parameters
   * @param params.targetDex - HIP-3 DEX name (e.g., 'xyz')
   * @param params.requiredMargin - Required margin with buffer
   * @returns Transfer info for rollback, or null if no transfer needed
   * @private
   */
  async #autoTransferForHip3Order(params: {
    targetDex: string;
    requiredMargin: number;
  }): Promise<{ amount: number; sourceDex: string } | null> {
    const { targetDex, requiredMargin } = params;

    // Check target DEX balance
    const targetBalance = await this.#getBalanceForDex({ dex: targetDex });

    this.#deps.debugLogger.log('HyperLiquidProvider: HIP-3 balance check', {
      targetDex,
      targetBalance: targetBalance.toFixed(2),
      requiredMargin: requiredMargin.toFixed(2),
      shortfall: Math.max(0, requiredMargin - targetBalance).toFixed(2),
    });

    // Sufficient balance - no transfer needed
    if (targetBalance >= requiredMargin) {
      return null;
    }

    // Calculate shortfall and find source
    const shortfall = requiredMargin - targetBalance;
    const source = await this.#findSourceDexWithBalance({
      targetDex,
      requiredAmount: shortfall,
    });

    if (!source) {
      throw new Error(
        `Insufficient balance for HIP-3 order. Required: ${requiredMargin.toFixed(
          2,
        )} USDC on ${targetDex} DEX, Available: ${targetBalance.toFixed(
          2,
        )} USDC. Please transfer funds to ${targetDex} DEX.`,
      );
    }

    // Execute transfer
    const transferAmount = Math.min(shortfall, source.available).toFixed(
      USDC_DECIMALS,
    );

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Executing HIP-3 auto-transfer',
      {
        from: source.sourceDex || 'main',
        to: targetDex,
        amount: transferAmount,
      },
    );

    const result = await this.transferBetweenDexs({
      sourceDex: source.sourceDex,
      destinationDex: targetDex,
      amount: transferAmount,
    });

    if (!result.success) {
      throw new Error(
        `Auto-transfer failed: ${result.error ?? 'Unknown error'}`,
      );
    }

    this.#deps.debugLogger.log(
      '✅ HyperLiquidProvider: HIP-3 auto-transfer complete',
      {
        amount: transferAmount,
        from: source.sourceDex || 'main',
        to: targetDex,
      },
    );

    return {
      amount: parseFloat(transferAmount),
      sourceDex: source.sourceDex,
    };
  }

  /**
   * Auto-transfer freed margin back to main DEX after closing a HIP-3 position
   *
   * This method transfers the margin released from closing a position back to
   * the main DEX to prevent balance fragmentation across HIP-3 DEXs.
   *
   * Design: Non-blocking operation - failures are logged but don't affect the
   * position close operation. Extensible for future configuration options.
   *
   * @param params - Transfer configuration
   * @param params.sourceDex - HIP-3 DEX name to transfer from
   * @param params.freedMargin - Amount of margin released from position close
   * @param params.transferAll - (Future) Transfer all available balance instead
   * @param params.skipTransfer - (Future) Skip auto-transfer if disabled
   * @returns Transfer info if successful, null if skipped/failed
   * @private
   */
  async #autoTransferBackAfterClose(params: {
    sourceDex: string;
    freedMargin: number;
    transferAll?: boolean;
    skipTransfer?: boolean;
  }): Promise<{ amount: number; destinationDex: string } | null> {
    const {
      sourceDex,
      freedMargin,
      transferAll = false,
      skipTransfer = false,
    } = params;

    // Future: Check user preference to skip auto-transfer
    if (skipTransfer) {
      this.#deps.debugLogger.log(
        'Auto-transfer back skipped (disabled by config)',
      );
      return null;
    }

    try {
      this.#deps.debugLogger.log('Attempting auto-transfer back to main DEX', {
        sourceDex,
        freedMargin: freedMargin.toFixed(2),
        transferAll,
      });

      // Get current balance on HIP-3 DEX
      const sourceBalance = await this.#getBalanceForDex({ dex: sourceDex });

      if (sourceBalance <= 0) {
        this.#deps.debugLogger.log('No balance to transfer back', {
          sourceBalance,
        });
        return null;
      }

      // Determine transfer amount
      const transferAmount = transferAll
        ? sourceBalance
        : Math.min(freedMargin, sourceBalance);

      if (transferAmount <= 0) {
        this.#deps.debugLogger.log('Transfer amount too small', {
          transferAmount,
        });
        return null;
      }

      this.#deps.debugLogger.log('Transferring back to main DEX', {
        amount: transferAmount.toFixed(USDC_DECIMALS),
        from: sourceDex,
        to: 'main',
      });

      // Execute transfer back to main DEX (empty string '' represents main DEX)
      const result = await this.transferBetweenDexs({
        sourceDex,
        destinationDex: '',
        amount: transferAmount.toFixed(USDC_DECIMALS),
      });

      if (!result.success) {
        this.#deps.debugLogger.log('❌ Auto-transfer back failed', {
          error: result.error,
        });
        return null;
      }

      this.#deps.debugLogger.log('✅ Auto-transfer back successful', {
        amount: transferAmount.toFixed(USDC_DECIMALS),
        from: sourceDex,
        to: 'main',
      });

      return {
        amount: transferAmount,
        destinationDex: '',
      };
    } catch (error) {
      // Non-blocking: Log error but don't throw
      this.#deps.debugLogger.log('❌ Auto-transfer back exception', {
        error,
        sourceDex,
        freedMargin,
      });
      return null;
    }
  }

  /**
   * Calculate required margin for HIP-3 order based on existing position
   * Handles three scenarios:
   * 1. Increasing existing position - requires TOTAL margin (temporary over-funding)
   * 2. Reducing/flipping position - requires margin for new order only
   * 3. New position - requires margin for new order only
   *
   * @param params - The operation parameters.
   * @param params.symbol - The trading pair symbol.
   * @param params.dexName - The DEX identifier (empty string for main DEX).
   * @param params.positionSize - The position size value.
   * @param params.orderPrice - The order price value.
   * @param params.leverage - The leverage multiplier.
   * @param params.isBuy - Whether this is a buy order.
   * @private
   * @returns The result of the operation.
   */
  async #calculateHip3RequiredMargin(params: {
    symbol: string;
    dexName: string;
    positionSize: number;
    orderPrice: number;
    leverage: number;
    isBuy: boolean;
  }): Promise<number> {
    const { symbol, dexName, positionSize, orderPrice, leverage, isBuy } =
      params;

    // Get existing position to check if we're increasing
    const positions = await this.getPositions();
    const existingPosition = positions.find((pos) => pos.symbol === symbol);

    let requiredMarginWithBuffer: number;

    // HyperLiquid validates isolated margin by checking if available balance >= TOTAL position margin
    // When increasing a position, we need to ensure enough funds are available for the TOTAL combined size
    if (existingPosition) {
      const existingIsLong = parseFloat(existingPosition.size) > 0;
      const orderIsLong = isBuy;

      if (existingIsLong === orderIsLong) {
        // Increasing position - HyperLiquid validates spendableBalance >= totalRequiredMargin
        // BEFORE reallocating existing locked margin. Must transfer TOTAL margin temporarily.
        const existingSize = Math.abs(parseFloat(existingPosition.size));
        const existingMargin = parseFloat(existingPosition.marginUsed);
        const totalSize = existingSize + positionSize;
        const totalNotionalValue = totalSize * orderPrice;
        const totalRequiredMargin = totalNotionalValue / leverage;

        // Accept temporary over-funding - excess will be reclaimed after order succeeds
        requiredMarginWithBuffer =
          totalRequiredMargin * HIP3_MARGIN_CONFIG.BufferMultiplier;

        this.#deps.debugLogger.log(
          'HyperLiquidProvider: HIP-3 margin calculation (TOTAL margin - temporary over-funding)',
          {
            symbol,
            dex: dexName,
            existingSize: existingSize.toFixed(4),
            existingMargin: existingMargin.toFixed(2),
            newSize: positionSize.toFixed(4),
            totalSize: totalSize.toFixed(4),
            totalNotionalValue: totalNotionalValue.toFixed(2),
            leverage,
            totalRequiredMargin: totalRequiredMargin.toFixed(2),
            requiredMarginWithBuffer: requiredMarginWithBuffer.toFixed(2),
            note: 'Transferring TOTAL margin (HyperLiquid validates before reallocation). Will auto-rebalance excess after success.',
          },
        );
      } else {
        // Reducing or flipping position - just need margin for new order
        const notionalValue = positionSize * orderPrice;
        const requiredMargin = notionalValue / leverage;
        requiredMarginWithBuffer =
          requiredMargin * HIP3_MARGIN_CONFIG.BufferMultiplier;

        this.#deps.debugLogger.log(
          'HyperLiquidProvider: HIP-3 margin calculation (reducing position)',
          {
            symbol,
            dex: dexName,
            notionalValue: notionalValue.toFixed(2),
            leverage,
            requiredMargin: requiredMargin.toFixed(2),
            requiredMarginWithBuffer: requiredMarginWithBuffer.toFixed(2),
          },
        );
      }
    } else {
      // No existing position - just need margin for this order
      const notionalValue = positionSize * orderPrice;
      const requiredMargin = notionalValue / leverage;
      requiredMarginWithBuffer =
        requiredMargin * HIP3_MARGIN_CONFIG.BufferMultiplier;

      this.#deps.debugLogger.log(
        'HyperLiquidProvider: HIP-3 margin calculation (new position)',
        {
          symbol,
          dex: dexName,
          notionalValue: notionalValue.toFixed(2),
          leverage,
          requiredMargin: requiredMargin.toFixed(2),
          requiredMarginWithBuffer: requiredMarginWithBuffer.toFixed(2),
        },
      );
    }

    return requiredMarginWithBuffer;
  }

  /**
   * Handle post-order balance check and auto-rebalance for HIP-3 orders
   * After a successful order, checks available balance and transfers excess back to main DEX
   * Does not throw errors - logs them for monitoring
   *
   * @param params - The operation parameters.
   * @param params.dexName - The DEX identifier (empty string for main DEX).
   * @param params.transferInfo - The transfer information.
   * @param params.transferInfo.amount - The amount value.
   * @param params.transferInfo.sourceDex - The source DEX for the transfer.
   * @private
   */
  async #handleHip3PostOrderRebalance(params: {
    dexName: string;
    transferInfo: { amount: number; sourceDex: string };
  }): Promise<void> {
    const { dexName, transferInfo } = params;

    try {
      const postOrderBalance = await this.#getBalanceForDex({ dex: dexName });
      const transferredAmount = transferInfo.amount;
      const leftoverAmount = postOrderBalance;
      const leftoverPercentage =
        transferredAmount > 0 ? (leftoverAmount / transferredAmount) * 100 : 0;

      this.#deps.debugLogger.log(
        '✅ HyperLiquidProvider: Order succeeded - post-order balance',
        {
          dex: dexName,
          transferredAmount: transferredAmount.toFixed(2),
          availableAfterOrder: leftoverAmount.toFixed(2),
          leftoverPercentage: `${leftoverPercentage.toFixed(2)}%`,
        },
      );

      // Auto-rebalance: Reclaim excess funds back to main DEX
      const desiredBuffer = HIP3_MARGIN_CONFIG.RebalanceDesiredBuffer;
      const excessAmount = postOrderBalance - desiredBuffer;
      const minimumTransferThreshold = HIP3_MARGIN_CONFIG.RebalanceMinThreshold;

      if (excessAmount > minimumTransferThreshold) {
        try {
          this.#deps.debugLogger.log(
            '🔄 HyperLiquidProvider: Auto-rebalancing excess margin back to main DEX',
            {
              dex: dexName,
              spendableBalance: postOrderBalance.toFixed(2),
              desiredBuffer: desiredBuffer.toFixed(2),
              excessAmount: excessAmount.toFixed(2),
              destinationDex: transferInfo.sourceDex,
            },
          );

          await this.transferBetweenDexs({
            sourceDex: dexName,
            destinationDex: transferInfo.sourceDex,
            amount: excessAmount.toFixed(USDC_DECIMALS),
          });

          this.#deps.debugLogger.log(
            '✅ HyperLiquidProvider: Auto-rebalance completed',
            {
              transferredBack: excessAmount.toFixed(2),
              from: dexName,
              to: transferInfo.sourceDex,
            },
          );
        } catch (rebalanceError) {
          // Don't fail the order if rebalance fails (order already succeeded)
          this.#deps.logger.error(
            ensureError(
              rebalanceError,
              'HyperLiquidProvider.placeOrder:autoRebalance',
            ),
            this.#getErrorContext('placeOrder:autoRebalance', {
              dex: dexName,
              excessAmount: excessAmount.toFixed(2),
              note: 'Auto-rebalance failed - funds remain on HIP-3 DEX',
            }),
          );
        }
      } else {
        this.#deps.debugLogger.log(
          'ℹ️ HyperLiquidProvider: No auto-rebalance needed',
          {
            excessAmount: excessAmount.toFixed(2),
            threshold: minimumTransferThreshold.toFixed(2),
            note: 'Excess below minimum transfer threshold',
          },
        );
      }
    } catch (balanceCheckError) {
      // Don't fail the order if balance check fails - log for monitoring
      this.#deps.logger.error(
        ensureError(
          balanceCheckError,
          'HyperLiquidProvider.placeOrder:postOrderBalanceCheck',
        ),
        this.#getErrorContext('placeOrder:postOrderBalanceCheck', {
          dex: dexName,
          note: 'Failed to verify post-order balance for auto-rebalance',
        }),
      );
    }
  }

  /**
   * Handle rollback of HIP-3 transfer when order fails
   * Attempts to return funds to source DEX
   * Does not throw errors - logs them for monitoring
   *
   * @param params - The operation parameters.
   * @param params.dexName - The DEX identifier (empty string for main DEX).
   * @param params.transferInfo - The transfer information.
   * @param params.transferInfo.amount - The amount value.
   * @param params.transferInfo.sourceDex - The source DEX for the transfer.
   * @private
   */
  async #handleHip3OrderRollback(params: {
    dexName: string;
    transferInfo: { amount: number; sourceDex: string };
  }): Promise<void> {
    const { dexName, transferInfo } = params;

    try {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Rolling back failed order transfer',
        {
          from: dexName,
          to: transferInfo.sourceDex || 'main',
          amount: transferInfo.amount.toFixed(USDC_DECIMALS),
          reason: 'order_failed',
        },
      );

      const rollbackResult = await this.transferBetweenDexs({
        sourceDex: dexName, // From HIP-3 DEX
        destinationDex: transferInfo.sourceDex, // Back to source
        amount: transferInfo.amount.toFixed(USDC_DECIMALS),
      });

      if (rollbackResult.success) {
        this.#deps.debugLogger.log(
          '✅ HyperLiquidProvider: Rollback successful',
          {
            amount: transferInfo.amount.toFixed(USDC_DECIMALS),
            returnedTo: transferInfo.sourceDex || 'main',
          },
        );
      } else {
        this.#deps.logger.error(
          new Error(rollbackResult.error ?? 'Rollback transfer failed'),
          this.#getErrorContext('placeOrder:rollback', {
            dex: dexName,
            amount: transferInfo.amount.toFixed(USDC_DECIMALS),
            note: 'Rollback failed - funds remain on HIP-3 DEX',
          }),
        );
      }
    } catch (rollbackError) {
      // Log but don't throw - original order error is more important
      this.#deps.logger.error(
        ensureError(rollbackError, 'HyperLiquidProvider.placeOrder:rollback'),
        this.#getErrorContext('placeOrder:rollback:exception', {
          dex: dexName,
          amount: transferInfo.amount.toFixed(USDC_DECIMALS),
          note: 'Rollback threw exception - funds remain on HIP-3 DEX',
        }),
      );
    }
  }

  // ============================================================================
  // Helper Methods for placeOrder Refactoring
  // ============================================================================

  /**
   * Validates order parameters before placement using provider-level validation
   *
   * @param params - The operation parameters.
   * @throws Error if validation fails
   */
  async #validateOrderBeforePlacement(params: OrderParams): Promise<void> {
    this.#deps.debugLogger.log(
      'Provider: Validating order before placement:',
      params,
    );

    const validation = await this.validateOrder(params);
    if (!validation.isValid) {
      throw new Error(
        validation.error ?? 'Order validation failed at provider level',
      );
    }
  }

  /**
   * Gets asset info and current price from the correct DEX
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async #getAssetInfo(params: GetAssetInfoParams): Promise<GetAssetInfoResult> {
    const { symbol, dexName } = params;

    const meta = await this.#getCachedMeta({ dexName });

    const assetInfo = meta.universe.find((asset) => asset.name === symbol);
    if (!assetInfo) {
      throw new Error(
        `Asset ${symbol} not found in ${dexName ?? 'main'} DEX universe`,
      );
    }

    const currentPrice = await this.#getOrFetchPrice({
      symbol,
      dexName: dexName ?? null,
    });

    return { assetInfo, currentPrice, meta };
  }

  /**
   * Prepares asset for trading by updating leverage if specified
   *
   * @param params - The operation parameters.
   */
  async #prepareAssetForTrading(
    params: PrepareAssetForTradingParams,
  ): Promise<void> {
    const { symbol, assetId, leverage } = params;

    if (!leverage) {
      return;
    }

    this.#deps.debugLogger.log('Updating leverage before order:', {
      symbol,
      assetId,
      requestedLeverage: leverage,
      leverageType: 'isolated',
    });

    const exchangeClient = this.#clientService.getExchangeClient();
    const leverageResult = await exchangeClient.updateLeverage({
      asset: assetId,
      isCross: false,
      leverage,
    });

    if (leverageResult.status !== 'ok') {
      throw new Error(
        `Failed to update leverage: ${JSON.stringify(leverageResult)}`,
      );
    }

    this.#deps.debugLogger.log('Leverage updated successfully:', {
      symbol,
      leverage,
    });
  }

  /**
   * Handles HIP-3 pre-order balance management
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async #handleHip3PreOrder(
    params: HandleHip3PreOrderParams,
  ): Promise<HandleHip3PreOrderResult> {
    const { dexName, symbol, orderPrice, positionSize, leverage, isBuy } =
      params;

    // Check if this DEX uses USDH collateral (vs USDC)
    // For USDH DEXs, HyperLiquid automatically pulls from spot balance
    const isUsdhDex = await this.#isUsdhCollateralDex(dexName);
    if (isUsdhDex) {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: USDH-collateralized DEX detected',
        {
          dexName,
          symbol,
        },
      );

      // Calculate required margin and ensure USDH is in spot
      const requiredMargin = await this.#calculateHip3RequiredMargin({
        symbol,
        dexName,
        positionSize,
        orderPrice,
        leverage,
        isBuy,
      });

      await this.#ensureUsdhCollateralForOrder(dexName, requiredMargin);

      // Unified Account will pull USDH from spot automatically
      return { transferInfo: null };
    }

    if (this.#useUnifiedAccount) {
      this.#deps.debugLogger.log('Using Unified Account (no manual transfer)', {
        symbol,
        dex: dexName,
      });
      return { transferInfo: null };
    }

    this.#deps.debugLogger.log('Using manual auto-transfer', {
      symbol,
      dex: dexName,
    });

    const requiredMarginWithBuffer = await this.#calculateHip3RequiredMargin({
      symbol,
      dexName,
      positionSize,
      orderPrice,
      leverage,
      isBuy,
    });

    try {
      const transferInfo = await this.#autoTransferForHip3Order({
        targetDex: dexName,
        requiredMargin: requiredMarginWithBuffer,
      });
      return { transferInfo };
    } catch (transferError) {
      const errorMsg = (transferError as Error)?.message || '';

      if (errorMsg.includes('Cannot transfer with DEX abstraction enabled')) {
        this.#deps.debugLogger.log(
          'Detected DEX abstraction is enabled, switching mode',
        );
        this.#useUnifiedAccount = true;
        return { transferInfo: null };
      }

      throw transferError;
    }
  }

  /**
   * Submits order with atomic rollback for HIP-3 failures
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async #submitOrderWithRollback(
    params: SubmitOrderWithRollbackParams,
  ): Promise<OrderResult> {
    const { orders, grouping, isHip3Order, dexName, transferInfo, symbol } =
      params;

    const exchangeClient = this.#clientService.getExchangeClient();

    // Calculate discounted builder fee
    let builderFee = BUILDER_FEE_CONFIG.MaxFeeTenthsBps;
    if (this.#userFeeDiscountBips !== undefined) {
      builderFee = Math.floor(
        builderFee * (1 - this.#userFeeDiscountBips / BASIS_POINTS_DIVISOR),
      );
      this.#deps.debugLogger.log('Applying builder fee discount', {
        originalFee: BUILDER_FEE_CONFIG.MaxFeeTenthsBps,
        discountBips: this.#userFeeDiscountBips,
        discountedFee: builderFee,
      });
    }

    this.#deps.debugLogger.log('Submitting order via asset ID routing', {
      symbol,
      assetId: orders[0].a,
      orderCount: orders.length,
      mainOrder: orders[0],
      dexName: dexName ?? 'main',
      isHip3: Boolean(dexName),
    });

    try {
      const result = await exchangeClient.order({
        orders,
        grouping,
        builder: {
          b: this.#getBuilderAddress(this.#clientService.isTestnetMode()),
          f: builderFee,
        },
      });

      if (result.status !== 'ok') {
        throw new Error(`Order failed: ${JSON.stringify(result)}`);
      }

      const status = result.response?.data?.statuses?.[0];
      // Note: `in` narrows the HyperLiquid SDK discriminated union to the
      // branch that has the property; `hasProperty` types the property as
      // `unknown`, losing downstream access to `.oid`, `.totalSz`, `.avgPx`.
      /* eslint-disable no-restricted-syntax */
      const restingOrder =
        isStatusObject(status) && 'resting' in status ? status.resting : null;
      const filledOrder =
        isStatusObject(status) && 'filled' in status ? status.filled : null;
      /* eslint-enable no-restricted-syntax */

      // Success - auto-rebalance excess funds
      if (isHip3Order && transferInfo && dexName) {
        await this.#handleHip3PostOrderRebalance({ dexName, transferInfo });
      }

      return {
        success: true,
        orderId: restingOrder?.oid?.toString() ?? filledOrder?.oid?.toString(),
        filledSize: filledOrder?.totalSz,
        averagePrice: filledOrder?.avgPx,
      };
    } catch (orderError) {
      // Failure - rollback transfer
      if (transferInfo && dexName) {
        await this.#handleHip3OrderRollback({ dexName, transferInfo });
      }
      throw orderError;
    }
  }

  /**
   * Handles order errors with proper error mapping
   *
   * @param params - The operation parameters.
   * @returns The result of the operation.
   */
  #handleOrderError(params: HandleOrderErrorParams): OrderResult {
    const { error, symbol, orderType, isBuy } = params;

    this.#deps.logger.error(
      ensureError(error, 'HyperLiquidProvider.handleOrderError'),
      this.#getErrorContext('placeOrder', {
        symbol,
        orderType,
        isBuy,
      }),
    );

    const mappedError = this.#mapError(error);
    return createErrorResult(mappedError, { success: false });
  }

  /**
   * Place an order using direct wallet signing
   *
   * Refactored to use helper methods for better maintainability and reduced complexity.
   * Each helper method is focused on a single responsibility.
   *
   * @param params - Order parameters
   * @param retryCount - Internal retry counter to prevent infinite loops (default: 0)
   * @returns A promise that resolves to the result.
   */
  async placeOrder(params: OrderParams, retryCount = 0): Promise<OrderResult> {
    // Hoisted so the retry path in the catch block can use the fetched price
    // even when the caller (e.g. flipPosition) omits currentPrice from params.
    let effectivePrice: number | undefined;
    try {
      this.#deps.debugLogger.log('Placing order via HyperLiquid SDK:', params);

      // Basic sync validation (backward compatibility)
      const validation = validateOrderParams({
        coin: params.symbol,
        size: params.size,
        price: params.price,
        orderType: params.orderType,
      });
      if (!validation.isValid) {
        throw new Error(validation.error);
      }

      // Extract DEX name for API calls (main DEX = null)
      const { dex: dexName } = parseAssetName(params.symbol);

      // 1. Get asset info and current price before validation so price-less
      // callers (e.g. flipPosition) can validate against the live fetched price.
      const { assetInfo, currentPrice, meta } = await this.#getAssetInfo({
        symbol: params.symbol,
        dexName,
      });

      // Allow override with UI-provided price (optimization to avoid API call).
      effectivePrice =
        params.currentPrice && params.currentPrice > 0
          ? params.currentPrice
          : currentPrice;

      if (params.currentPrice && params.currentPrice > 0) {
        this.#deps.debugLogger.log('Using provided current price:', {
          coin: params.symbol,
          providedPrice: effectivePrice,
          source: 'UI price feed',
        });
      }

      // Validate order at provider level (enforces USD validation rules).
      // Pass effectivePrice so price-less market orders (e.g. flipPosition)
      // validate against the live fetched price instead of failing with
      // ORDER_PRICE_REQUIRED.
      await this.#validateOrderBeforePlacement({
        ...params,
        currentPrice: effectivePrice,
      });

      // Ensure provider is ready for trading (includes signing operations).
      // Kept after validation so invalid orders never trigger signature prompts
      // (builder-fee approval, DEX abstraction enablement, etc.).
      await this.#ensureReadyForTrading();

      // Debug: Log asset map state before order placement
      const allMapKeys = Array.from(this.#symbolToAssetId.keys());
      const hip3Keys = allMapKeys.filter((key) => key.includes(':'));
      const assetExists = this.#symbolToAssetId.has(params.symbol);
      this.#deps.debugLogger.log('Asset map state at order time', {
        requestedCoin: params.symbol,
        assetExistsInMap: assetExists,
        totalAssetsInMap: this.#symbolToAssetId.size,
        hip3AssetsCount: hip3Keys.length,
        hip3AssetsSample: hip3Keys.slice(0, 10),
        hip3Enabled: this.#hip3Enabled,
        allowlistMarkets: this.#allowlistMarkets,
        blocklistMarkets: this.#blocklistMarkets,
      });

      // 2. Calculate final position size with USD reconciliation
      const { finalPositionSize } = calculateFinalPositionSize({
        usdAmount: params.usdAmount,
        size: params.size,
        currentPrice: effectivePrice,
        priceAtCalculation: params.priceAtCalculation,
        maxSlippageBps: params.maxSlippageBps,
        szDecimals: assetInfo.szDecimals,
        leverage: params.leverage,
      });

      // 3. Calculate order price and formatted size
      const { orderPrice, formattedSize, formattedPrice } =
        calculateOrderPriceAndSize({
          orderType: params.orderType,
          isBuy: params.isBuy,
          finalPositionSize,
          currentPrice: effectivePrice,
          limitPrice: params.price,
          slippage: params.slippage,
          szDecimals: assetInfo.szDecimals,
        });

      // 4. Get asset ID and validate it exists
      const assetId = await this.#getAssetIdWithRepair({
        symbol: params.symbol,
        dexName,
        meta,
      });

      this.#deps.debugLogger.log('Resolved DEX-specific asset ID', {
        coin: params.symbol,
        dex: dexName ?? 'main',
        assetId,
      });

      // 5. Update leverage if specified
      await this.#prepareAssetForTrading({
        symbol: params.symbol,
        assetId,
        leverage: params.leverage,
      });

      // 6. Handle HIP-3 balance management (if applicable)
      const isHip3Order = dexName !== null;
      let transferInfo: { amount: number; sourceDex: string } | null = null;

      if (isHip3Order && dexName) {
        const effectiveLeverage = params.leverage ?? assetInfo.maxLeverage ?? 1;
        const hip3Result = await this.#handleHip3PreOrder({
          dexName,
          symbol: params.symbol,
          orderPrice,
          positionSize: parseFloat(formattedSize),
          leverage: effectiveLeverage,
          isBuy: params.isBuy,
          maxLeverage: assetInfo.maxLeverage,
        });
        transferInfo = hip3Result.transferInfo;
      }

      // 7. Build orders array (main + TP/SL if specified)
      const { orders, grouping } = buildOrdersArray({
        assetId,
        isBuy: params.isBuy,
        formattedPrice,
        formattedSize,
        reduceOnly: params.reduceOnly ?? false,
        orderType: params.orderType,
        clientOrderId: params.clientOrderId,
        takeProfitPrice: params.takeProfitPrice,
        stopLossPrice: params.stopLossPrice,
        szDecimals: assetInfo.szDecimals,
        grouping: params.grouping,
      });

      // 8. Submit order with atomic rollback
      return await this.#submitOrderWithRollback({
        orders,
        grouping,
        isHip3Order,
        dexName,
        transferInfo,
        symbol: params.symbol,
        assetId,
      });
    } catch (error) {
      // Retry mechanism for $10 minimum order errors
      // This handles the case where UI price feed slightly differs from HyperLiquid's orderbook price
      const errorMessage = ensureError(
        error,
        'HyperLiquidProvider.placeOrder',
      ).message;
      const isMinimumOrderError =
        errorMessage.includes('Order must have minimum value of $10') ||
        errorMessage.includes('Order 0: Order must have minimum value');

      if (isMinimumOrderError && retryCount === 0) {
        let adjustedUsdAmount: string;
        let originalValue: string | undefined;

        if (params.usdAmount) {
          // USD-based order: adjust the USD amount directly
          originalValue = params.usdAmount;
          adjustedUsdAmount = (parseFloat(params.usdAmount) * 1.015).toFixed(2);
        } else if (effectivePrice) {
          // Size-based order: calculate USD from size and adjust.
          // Use the hoisted effectivePrice (fetched live price) so callers that
          // omit currentPrice (e.g. flipPosition) can still recover from the
          // $10-minimum edge case.
          const sizeValue = parseFloat(params.size);
          const estimatedUsd = sizeValue * effectivePrice;
          originalValue = `${estimatedUsd.toFixed(2)} (calculated from size ${params.size})`;
          adjustedUsdAmount = (estimatedUsd * 1.015).toFixed(2);
        } else {
          // No price information available - cannot retry
          return this.#handleOrderError({
            error,
            symbol: params.symbol,
            orderType: params.orderType,
            isBuy: params.isBuy,
          });
        }

        this.#deps.debugLogger.log(
          'Retrying order with adjusted size due to minimum value error',
          {
            originalValue,
            adjustedUsdAmount,
            retryCount,
          },
        );

        return this.placeOrder(
          {
            ...params,
            usdAmount: adjustedUsdAmount,
          },
          1, // Retry count = 1, prevents further retries
        );
      }

      return this.#handleOrderError({
        error,
        symbol: params.symbol,
        orderType: params.orderType,
        isBuy: params.isBuy,
      });
    }
  }

  /**
   * Edit an existing order (pending/unfilled order)
   *
   * Note: This modifies price/size of a pending order. It CANNOT add TP/SL to an existing order.
   * For adding TP/SL to an existing position, use updatePositionTPSL instead.
   *
   * @param params - The operation parameters.
   * @param params.orderId - The order ID to modify
   * @param params.newOrder - New order parameters (price, size, etc.)
   * @returns A promise that resolves to the result.
   */
  async editOrder(params: EditOrderParams): Promise<OrderResult> {
    try {
      this.#deps.debugLogger.log('Editing order:', params);

      // Validate size is positive (validateOrderParams no longer validates size)
      const size = parseFloat(params.newOrder.size || '0');
      if (size <= 0) {
        return {
          success: false,
          error: PERPS_ERROR_CODES.ORDER_SIZE_POSITIVE,
        };
      }

      // Validate new order parameters
      const validation = validateOrderParams({
        coin: params.newOrder.symbol,
        size: params.newOrder.size,
        price: params.newOrder.price,
        orderType: params.newOrder.orderType,
      });
      if (!validation.isValid) {
        throw new Error(validation.error);
      }

      // Ensure provider is ready for trading (includes signing operations)
      await this.#ensureReadyForTrading();

      // Extract DEX name for API calls (main DEX = null)
      const { dex: dexName } = parseAssetName(params.newOrder.symbol);

      // Get asset info and prices (uses cache to avoid redundant API calls)
      const meta = await this.#getCachedMeta({ dexName });

      // asset.name format: "BTC" for main DEX, "xyz:XYZ100" for HIP-3
      const assetInfo = meta.universe.find(
        (asset) => asset.name === params.newOrder.symbol,
      );
      if (!assetInfo) {
        throw new Error(
          `Asset ${params.newOrder.symbol} not found in ${
            dexName ?? 'main'
          } DEX universe`,
        );
      }

      const currentPrice = await this.#getOrFetchPrice({
        symbol: params.newOrder.symbol,
        dexName: dexName ?? null,
      });

      // Calculate order parameters using the same logic as placeOrder
      let orderPrice: number;
      let formattedSize: string;

      if (params.newOrder.orderType === 'market') {
        const positionSize = parseFloat(params.newOrder.size);
        const slippage =
          params.newOrder.slippage ??
          ORDER_SLIPPAGE_CONFIG.DefaultMarketSlippageBps / 10000;
        orderPrice = params.newOrder.isBuy
          ? currentPrice * (1 + slippage)
          : currentPrice * (1 - slippage);
        formattedSize = formatHyperLiquidSize({
          size: positionSize,
          szDecimals: assetInfo.szDecimals,
        });
      } else {
        if (!params.newOrder.price) {
          throw new Error(PERPS_ERROR_CODES.ORDER_LIMIT_PRICE_REQUIRED);
        }
        orderPrice = parseFloat(params.newOrder.price);
        formattedSize = formatHyperLiquidSize({
          size: parseFloat(params.newOrder.size),
          szDecimals: assetInfo.szDecimals,
        });
      }

      const formattedPrice = formatHyperLiquidPrice({
        price: orderPrice,
        szDecimals: assetInfo.szDecimals,
      });
      const assetId = await this.#getAssetIdWithRepair({
        symbol: params.newOrder.symbol,
        dexName,
        meta,
      });

      // Build new order parameters
      const newOrder: SDKOrderParams = {
        a: assetId,
        b: params.newOrder.isBuy,
        p: formattedPrice,
        s: formattedSize,
        r: params.newOrder.reduceOnly ?? false,
        // Same TIF logic as placeOrder - see documentation above for details
        t:
          params.newOrder.orderType === 'limit'
            ? { limit: { tif: 'Gtc' } } // Standard limit order
            : { limit: { tif: 'FrontendMarket' } }, // True market order
        c: params.newOrder.clientOrderId
          ? (params.newOrder.clientOrderId as Hex)
          : undefined,
      };

      // Submit modification via SDK
      const exchangeClient = this.#clientService.getExchangeClient();
      const result = await exchangeClient.modify({
        oid:
          typeof params.orderId === 'string'
            ? (params.orderId as Hex)
            : params.orderId,
        order: newOrder,
      });

      if (result.status !== 'ok') {
        throw new Error(`Order modification failed: ${JSON.stringify(result)}`);
      }

      return {
        success: true,
        orderId: params.orderId.toString(),
      };
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.editOrder'),
        this.#getErrorContext('editOrder', {
          orderId: params.orderId,
          coin: params.newOrder.symbol,
          orderType: params.newOrder.orderType,
        }),
      );
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Cancel an order
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async cancelOrder(params: CancelOrderParams): Promise<CancelOrderResult> {
    try {
      this.#deps.debugLogger.log('Canceling order:', params);

      // Validate coin exists
      const coinValidation = validateCoinExists(
        params.symbol,
        this.#symbolToAssetId,
      );
      if (!coinValidation.isValid) {
        throw new Error(coinValidation.error);
      }

      // Ensure provider is ready for trading (includes signing operations)
      await this.#ensureReadyForTrading();

      const exchangeClient = this.#clientService.getExchangeClient();
      const asset = await this.#getAssetIdWithRepair({
        symbol: params.symbol,
        dexName: parseAssetName(params.symbol).dex,
      });

      const result = await exchangeClient.cancel({
        cancels: [
          {
            a: asset,
            o: parseInt(params.orderId, 10),
          },
        ],
      });

      const success = result.response?.data?.statuses?.[0] === 'success';

      return {
        success,
        orderId: params.orderId,
        error: success ? undefined : 'Order cancellation failed',
      };
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.cancelOrder'),
        this.#getErrorContext('cancelOrder', {
          orderId: params.orderId,
          coin: params.symbol,
        }),
      );
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Cancel multiple orders in a single batch API call
   * Optimized implementation that uses HyperLiquid's batch cancel endpoint
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async cancelOrders(
    params: BatchCancelOrdersParams,
  ): Promise<CancelOrdersResult> {
    try {
      this.#deps.debugLogger.log('Batch canceling orders:', {
        count: params.length,
      });

      if (params.length === 0) {
        return {
          success: false,
          successCount: 0,
          failureCount: 0,
          results: [],
        };
      }

      // Ensure provider is ready for trading (includes signing operations)
      await this.#ensureReadyForTrading();

      const exchangeClient = this.#clientService.getExchangeClient();

      // Map orders to SDK format and validate coins
      const cancelRequests = await Promise.all(
        params.map(async (order) => {
          const asset = await this.#getAssetIdWithRepair({
            symbol: order.symbol,
            dexName: parseAssetName(order.symbol).dex,
          });
          return {
            a: asset,
            o: parseInt(order.orderId, 10),
          };
        }),
      );

      // Single batch API call
      const result = await exchangeClient.cancel({
        cancels: cancelRequests,
      });

      // Parse response statuses (one per order)
      const { statuses } = result.response.data;
      const successCount = statuses.filter(
        (status) => status === 'success',
      ).length;
      const failureCount = statuses.length - successCount;

      return {
        success: successCount > 0,
        successCount,
        failureCount,
        results: statuses.map((status, index) => ({
          orderId: params[index].orderId,
          symbol: params[index].symbol,
          success: status === 'success',
          error:
            status === 'success'
              ? undefined
              : (status as { error: string }).error,
        })),
      };
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.cancelOrders'),
        this.#getErrorContext('cancelOrders', {
          orderCount: params.length,
        }),
      );
      // Return all orders as failed
      return {
        success: false,
        successCount: 0,
        failureCount: params.length,
        results: params.map((order) => ({
          orderId: order.orderId,
          symbol: order.symbol,
          success: false,
          error:
            error instanceof Error
              ? error.message
              : PERPS_ERROR_CODES.BATCH_CANCEL_FAILED,
        })),
      };
    }
  }

  async closePositions(
    params: ClosePositionsParams,
  ): Promise<ClosePositionsResult> {
    // Declare outside try block so it's accessible in catch block
    let positionsToClose: Position[] = [];

    try {
      // Ensure provider is ready for trading (includes signing operations)
      await this.#ensureReadyForTrading();

      // Get all current positions from cache (avoids 429 rate limiting)
      const positions = await this.getPositions();

      // Filter positions based on params
      positionsToClose =
        params.closeAll === true ||
        !params.symbols ||
        params.symbols.length === 0
          ? positions
          : positions.filter((pos) => params.symbols?.includes(pos.symbol));

      this.#deps.debugLogger.log('Batch closing positions:', {
        count: positionsToClose.length,
        closeAll: params.closeAll,
        coins: params.symbols,
      });

      if (positionsToClose.length === 0) {
        return {
          success: false,
          successCount: 0,
          failureCount: 0,
          results: [],
        };
      }

      // Get exchange client for order submission
      const exchangeClient = this.#clientService.getExchangeClient();

      // Pre-fetch meta for all unique DEXs to avoid N API calls in loop
      const uniqueDexs = [
        ...new Set(
          positionsToClose.map(
            (pos) => parseAssetName(pos.symbol).dex ?? 'main',
          ),
        ),
      ];
      await Promise.all(
        uniqueDexs.map((dex) =>
          this.#getCachedMeta({ dexName: dex === 'main' ? null : dex }),
        ),
      );

      // Track HIP-3 positions and freed margins for post-close transfers
      const hip3Transfers: {
        sourceDex: string;
        freedMargin: number;
      }[] = [];

      // Build orders array
      const orders: SDKOrderParams[] = [];

      for (const position of positionsToClose) {
        // Extract DEX name for HIP-3 positions
        const { dex: dexName } = parseAssetName(position.symbol);
        const isHip3Position = position.symbol.includes(':');

        // Get asset info for formatting (uses cache populated above)
        const meta = await this.#getCachedMeta({ dexName });

        const assetInfo = meta.universe.find(
          (asset) => asset.name === position.symbol,
        );
        if (!assetInfo) {
          throw new Error(
            `Asset ${position.symbol} not found in ${
              dexName ?? 'main'
            } DEX universe`,
          );
        }

        // Get asset ID
        const assetId = await this.#getAssetIdWithRepair({
          symbol: position.symbol,
          dexName,
          meta,
        });

        // Calculate position details (always full close)
        const positionSize = parseFloat(position.size);
        const isBuy = positionSize < 0; // Close opposite side
        const closeSize = Math.abs(positionSize);
        const totalMarginUsed = parseFloat(position.marginUsed);

        // Track HIP-3 transfers (full position close means all margin is freed)
        if (isHip3Position && dexName && !this.#useUnifiedAccount) {
          hip3Transfers.push({
            sourceDex: dexName,
            freedMargin: totalMarginUsed,
          });
        }

        const currentPrice = await this.#getOrFetchPrice({
          symbol: position.symbol,
          dexName: dexName ?? null,
        });

        // Calculate order price with slippage
        const slippage = ORDER_SLIPPAGE_CONFIG.DefaultMarketSlippageBps / 10000;
        const orderPrice = isBuy
          ? currentPrice * (1 + slippage)
          : currentPrice * (1 - slippage);

        // Format size and price
        const formattedSize = formatHyperLiquidSize({
          size: closeSize,
          szDecimals: assetInfo.szDecimals,
        });

        const formattedPrice = formatHyperLiquidPrice({
          price: orderPrice,
          szDecimals: assetInfo.szDecimals,
        });

        // Build reduce-only order
        orders.push({
          a: assetId,
          b: isBuy,
          p: formattedPrice,
          s: formattedSize,
          r: true, // reduceOnly
          t: { limit: { tif: 'Ioc' } }, // Immediate or cancel for market-like execution
        });
      }

      // Calculate discounted builder fee if reward discount is active
      let builderFee = BUILDER_FEE_CONFIG.MaxFeeTenthsBps;
      if (this.#userFeeDiscountBips !== undefined) {
        builderFee = Math.floor(
          builderFee * (1 - this.#userFeeDiscountBips / BASIS_POINTS_DIVISOR),
        );
      }

      // Single batch API call
      const result = await exchangeClient.order({
        orders,
        grouping: 'na',
        builder: {
          b: this.#getBuilderAddress(this.#clientService.isTestnetMode()),
          f: builderFee,
        },
      });

      // Parse response statuses (one per order)
      const { statuses } = result.response.data;
      const successCount = statuses.filter(
        (stat) =>
          isStatusObject(stat) &&
          (hasProperty(stat, 'filled') || hasProperty(stat, 'resting')),
      ).length;
      const failureCount = statuses.length - successCount;

      // Handle HIP-3 margin transfers for successful closes
      if (!this.#useUnifiedAccount) {
        for (let i = 0; i < statuses.length; i++) {
          const status = statuses[i];
          const isSuccess =
            isStatusObject(status) &&
            (hasProperty(status, 'filled') || hasProperty(status, 'resting'));

          if (isSuccess && hip3Transfers[i]) {
            const { sourceDex, freedMargin } = hip3Transfers[i];
            this.#deps.debugLogger.log(
              'Position closed successfully, initiating manual auto-transfer back',
              { symbol: positionsToClose[i].symbol, freedMargin },
            );

            // Non-blocking: Transfer freed margin back to main DEX
            await this.#autoTransferBackAfterClose({
              sourceDex,
              freedMargin,
            });
          }
        }
      }

      return {
        success: successCount > 0,
        successCount,
        failureCount,
        results: statuses.map((status, index) => ({
          symbol: positionsToClose[index].symbol,
          success:
            isStatusObject(status) &&
            (hasProperty(status, 'filled') || hasProperty(status, 'resting')),
          error:
            isStatusObject(status) && hasProperty(status, 'error')
              ? String(status.error)
              : undefined,
        })),
      };
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.closePositions'),
        this.#getErrorContext('closePositions', {
          positionCount: positionsToClose.length,
        }),
      );
      // Return all positions as failed
      return {
        success: false,
        successCount: 0,
        failureCount: positionsToClose.length,
        results: positionsToClose.map((position) => ({
          symbol: position.symbol,
          success: false,
          error:
            error instanceof Error
              ? error.message
              : PERPS_ERROR_CODES.BATCH_CLOSE_FAILED,
        })),
      };
    }
  }

  /**
   * Update TP/SL for an existing position
   *
   * This creates new TP/SL orders for the position using 'positionTpsl' grouping.
   * These are separate orders that will close the position when triggered.
   *
   * Key differences from editOrder:
   * - editOrder: Modifies pending orders (before fill)
   * - updatePositionTPSL: Creates TP/SL orders for filled positions
   *
   * HyperLiquid supports two TP/SL types:
   * 1. 'normalTpsl' - Tied to a parent order (set when placing the order)
   * 2. 'positionTpsl' - Tied to a position (can be set/modified after fill)
   *
   * @param params - The operation parameters.
   * @param params.symbol - Asset symbol of the position
   * @param params.takeProfitPrice - TP price (undefined to remove)
   * @param params.stopLossPrice - SL price (undefined to remove)
   * @returns A promise that resolves to the result.
   */
  async updatePositionTPSL(
    params: UpdatePositionTPSLParams,
  ): Promise<OrderResult> {
    try {
      this.#deps.debugLogger.log('Updating position TP/SL:', params);

      const {
        symbol,
        takeProfitPrice,
        stopLossPrice,
        position: livePosition,
      } = params;

      // Ensure provider is ready for trading (includes signing operations)
      await this.#ensureReadyForTrading();

      // Use live position (from WebSocket) if available, otherwise fetch via REST
      // Preferring WebSocket data avoids rate limiting issues with the REST API
      let position: Position | undefined = livePosition;

      if (position) {
        this.#deps.debugLogger.log('Using live position from WebSocket', {
          symbol: position.symbol,
          size: position.size,
        });
      } else {
        // Fallback: fetch positions via REST API (legacy behavior)
        this.#deps.debugLogger.log(
          'No live position passed, falling back to REST API fetch',
        );
        let positions: Position[];
        try {
          positions = await this.getPositions({ skipCache: true });
        } catch (error) {
          this.#deps.logger.error(
            ensureError(error, 'HyperLiquidProvider.updatePositionTPSL'),
            this.#getErrorContext('updatePositionTPSL > getPositions', {
              symbol,
            }),
          );
          throw error;
        }
        position = positions.find((pos) => pos.symbol === symbol);
      }

      if (!position) {
        throw new Error(`No position found for ${symbol}`);
      }

      const positionSize = Math.abs(parseFloat(position.size));
      const isLong = parseFloat(position.size) > 0;

      // Get clients for API calls (ensureReady already called at method start)
      const infoClient = this.#clientService.getInfoClient();
      const exchangeClient = this.#clientService.getExchangeClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault();

      // Extract DEX name for API calls (main DEX = null)
      const { dex: dexName } = parseAssetName(symbol);

      // Cancel existing TP/SL orders for this position
      // OPTIMIZATION: Use WebSocket cache first (0 weight), fall back to single-DEX REST (20 weight)
      // Previously: queryUserDataAcrossDexs queried ALL DEXs (20 weight × N DEXs = 40+ weight)
      const assetId = await this.#getAssetIdWithRepair({
        symbol,
        dexName,
      });

      let cancelRequests: { a: number; o: number }[] = [];

      // Use atomic getter to prevent race condition between check and get
      const cachedOrders =
        this.#subscriptionService.getOrdersCacheIfInitialized();

      if (cachedOrders === null) {
        // Fallback: Query only the specific DEX (20 weight instead of 40+)
        this.#deps.debugLogger.log(
          'WebSocket cache not initialized, falling back to single-DEX REST query',
          { dex: dexName ?? 'main' },
        );

        const orders = await infoClient.frontendOpenOrders({
          user: userAddress,
          dex: dexName ?? undefined,
        });

        // Filter using raw SDK response properties
        const tpslOrders = orders.filter(
          (order) =>
            order.coin === symbol &&
            order.reduceOnly &&
            order.isPositionTpsl ===
              Boolean(TP_SL_CONFIG.UsePositionBoundTpsl) &&
            order.isTrigger &&
            (order.orderType.includes('Take Profit') ||
              order.orderType.includes('Stop')),
        );

        cancelRequests = tpslOrders.map((order) => ({
          a: assetId,
          o: order.oid,
        }));
      } else {
        // WebSocket cache available - use it (no API call, 0 weight)
        this.#deps.debugLogger.log(
          'Using WebSocket cache for TP/SL orders lookup',
          { cachedOrdersCount: cachedOrders.length },
        );

        // Filter using normalized Order type properties, matching the REST fallback criteria:
        // - symbol matches
        // - isTrigger === true
        // - reduceOnly === true
        // - isPositionTpsl matches the configured mode (only cancel position-bound TP/SL,
        //   not normalTpsl children that belong to pending limit orders)
        // - detailedOrderType contains 'Take Profit' or 'Stop'
        const tpslOrders = cachedOrders.filter(
          (order) =>
            order.symbol === symbol &&
            order.reduceOnly === true &&
            order.isTrigger === true &&
            order.isPositionTpsl ===
              Boolean(TP_SL_CONFIG.UsePositionBoundTpsl) &&
            order.detailedOrderType &&
            (order.detailedOrderType.includes('Take Profit') ||
              order.detailedOrderType.includes('Stop')),
        );
        cancelRequests = tpslOrders.map((order) => ({
          a: assetId,
          o: parseInt(order.orderId, 10),
        }));
      }

      if (cancelRequests.length > 0) {
        this.#deps.debugLogger.log(
          `Canceling ${cancelRequests.length} existing TP/SL orders for ${symbol}`,
        );

        const cancelResult = await exchangeClient.cancel({
          cancels: cancelRequests,
        });
        this.#deps.debugLogger.log('Cancel result:', cancelResult);
      }

      // Get asset info (dexName already extracted above) - uses cache
      const meta = await this.#getCachedMeta({ dexName });

      // Check if meta is an error response (string) or doesn't have universe property
      if (
        !meta ||
        typeof meta === 'string' ||
        !meta.universe ||
        !Array.isArray(meta.universe)
      ) {
        this.#deps.debugLogger.log(
          'Failed to fetch metadata for asset mapping',
          {
            meta,
            dex: dexName ?? 'main',
          },
        );
        throw new Error(
          `Failed to fetch market metadata for DEX ${dexName ?? 'main'}`,
        );
      }

      // asset.name format: "BTC" for main DEX, "xyz:XYZ100" for HIP-3
      const assetInfo = meta.universe.find((asset) => asset.name === symbol);
      if (!assetInfo) {
        throw new Error(
          `Asset ${symbol} not found in ${dexName ?? 'main'} DEX universe`,
        );
      }

      // assetId already validated above when building cancelRequests

      // Build orders array for TP/SL
      const orders: SDKOrderParams[] = [];

      const size = TP_SL_CONFIG.UsePositionBoundTpsl
        ? '0'
        : formatHyperLiquidSize({
            size: positionSize,
            szDecimals: assetInfo.szDecimals,
          });
      // Take Profit order
      if (takeProfitPrice) {
        const tpOrder: SDKOrderParams = {
          a: assetId,
          b: !isLong, // Opposite side to close position
          p: formatHyperLiquidPrice({
            price: parseFloat(takeProfitPrice),
            szDecimals: assetInfo.szDecimals,
          }),
          s: size,
          r: true, // Always reduce-only for position TP
          t: {
            trigger: {
              isMarket: false, // Limit order when triggered
              triggerPx: formatHyperLiquidPrice({
                price: parseFloat(takeProfitPrice),
                szDecimals: assetInfo.szDecimals,
              }),
              tpsl: 'tp',
            },
          },
        };
        orders.push(tpOrder);
      }

      // Stop Loss order
      if (stopLossPrice) {
        const slOrder: SDKOrderParams = {
          a: assetId,
          b: !isLong, // Opposite side to close position
          p: formatHyperLiquidPrice({
            price: parseFloat(stopLossPrice),
            szDecimals: assetInfo.szDecimals,
          }),
          s: size,
          r: true, // Always reduce-only for position SL
          t: {
            trigger: {
              isMarket: true, // Market order when triggered for faster execution
              triggerPx: formatHyperLiquidPrice({
                price: parseFloat(stopLossPrice),
                szDecimals: assetInfo.szDecimals,
              }),
              tpsl: 'sl',
            },
          },
        };
        orders.push(slOrder);
      }

      // If no new orders, we've just cancelled existing ones (clearing TP/SL)
      if (orders.length === 0) {
        this.#deps.debugLogger.log(
          'No new TP/SL orders to place - existing ones cancelled',
        );
        return {
          success: true,
          // No orderId since we only cancelled orders, didn't place new ones
        };
      }

      // Calculate discounted builder fee if reward discount is active
      let builderFee = BUILDER_FEE_CONFIG.MaxFeeTenthsBps;
      if (this.#userFeeDiscountBips !== undefined) {
        builderFee = Math.floor(
          builderFee * (1 - this.#userFeeDiscountBips / BASIS_POINTS_DIVISOR),
        );
        this.#deps.debugLogger.log(
          'HyperLiquid: Applying builder fee discount to TP/SL',
          {
            originalFee: BUILDER_FEE_CONFIG.MaxFeeTenthsBps,
            discountBips: this.#userFeeDiscountBips,
            discountedFee: builderFee,
          },
        );
      }

      // Submit via SDK exchange client with positionTpsl grouping
      const result = await exchangeClient.order({
        orders,
        grouping: 'positionTpsl',
        builder: {
          b: this.#getBuilderAddress(this.#clientService.isTestnetMode()),
          f: builderFee,
        },
      });

      if (result.status !== 'ok') {
        throw new Error(`TP/SL update failed: ${JSON.stringify(result)}`);
      }

      return {
        success: true,
        orderId: 'TP/SL orders placed',
      };
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.updatePositionTPSL'),
        this.#getErrorContext('updatePositionTPSL', {
          symbol: params.symbol,
          hasTakeProfit: params.takeProfitPrice !== undefined,
          hasStopLoss: params.stopLossPrice !== undefined,
        }),
      );
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Close a position
   *
   * For HIP-3 positions, this method automatically transfers freed margin
   * back to the main DEX after successfully closing the position.
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async closePosition(params: ClosePositionParams): Promise<OrderResult> {
    try {
      this.#deps.debugLogger.log('Closing position:', params);

      // Ensure provider is ready for trading (includes signing operations)
      await this.#ensureReadyForTrading();

      // Use provided position (from WebSocket) or fetch from cache
      // This avoids unnecessary API calls and prevents 429 rate limiting
      let { position } = params;
      if (!position) {
        const positions = await this.getPositions();
        position = positions.find((pos) => pos.symbol === params.symbol);
      }

      if (!position) {
        throw new Error(`No position found for ${params.symbol}`);
      }

      const positionSize = parseFloat(position.size);
      const isBuy = positionSize < 0;
      const closeSize = params.size ?? Math.abs(positionSize).toString();

      // Capture position details BEFORE closing for freed margin calculation
      const totalMarginUsed = parseFloat(position.marginUsed);
      const totalPositionSize = Math.abs(positionSize);
      const closeSizeNum = parseFloat(closeSize);
      const isHip3Position = position.symbol.includes(':');
      const hip3Dex = isHip3Position ? position.symbol.split(':')[0] : null;

      // Calculate freed margin proportionally
      const freedMarginRatio = closeSizeNum / totalPositionSize;
      const freedMargin = totalMarginUsed * freedMarginRatio;

      // Get current price for validation if not provided (and not a full close)
      // Full closes don't need price for validation
      let { currentPrice } = params;
      if (!currentPrice && params.size && !params.usdAmount) {
        // Partial close without USD or price: use limit price as fallback for validation
        // For limit orders, the limit price is a reasonable proxy for validation purposes
        if (params.price && params.orderType === 'limit') {
          currentPrice = parseFloat(params.price);
          this.#deps.debugLogger.log(
            'Using limit price for close position validation (limit order)',
            {
              coin: params.symbol,
              currentPrice,
            },
          );
        }
        // Note: For market orders without usdAmount/currentPrice, validation will fail
        // with "price_required" error, which is correct behavior (prevents invalid orders)
      }

      this.#deps.debugLogger.log('Position close details', {
        coin: position.symbol,
        isHip3Position,
        hip3Dex,
        totalMarginUsed,
        closedSize: closeSize,
        freedMargin: freedMargin.toFixed(2),
      });

      // Execute position close with consistent slippage handling
      const result = await this.placeOrder({
        symbol: params.symbol,
        isBuy,
        size: closeSize,
        orderType: params.orderType ?? 'market',
        price: params.price,
        reduceOnly: true,
        isFullClose: !params.size, // True if closing 100% (size not provided)
        // Pass through price and slippage parameters for consistent validation
        currentPrice,
        usdAmount: params.usdAmount,
        priceAtCalculation: params.priceAtCalculation,
        maxSlippageBps: params.maxSlippageBps,
      });

      // Return freed margin using native abstraction or programmatic transfer
      if (
        result.success &&
        isHip3Position &&
        hip3Dex &&
        !this.#useUnifiedAccount
      ) {
        this.#deps.debugLogger.log(
          'Position closed successfully, initiating manual auto-transfer back',
        );

        // Non-blocking: Transfer freed margin back to main DEX
        await this.#autoTransferBackAfterClose({
          sourceDex: hip3Dex,
          freedMargin,
        });
      } else if (
        result.success &&
        isHip3Position &&
        hip3Dex &&
        this.#useUnifiedAccount
      ) {
        this.#deps.debugLogger.log(
          'Position closed - Unified Account will auto-return freed margin',
          {
            coin: params.symbol,
            dex: hip3Dex,
            note: 'HyperLiquid handles return automatically',
          },
        );
      }

      return result;
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.closePosition'),
        this.#getErrorContext('closePosition', {
          coin: params.symbol,
          orderType: params.orderType,
        }),
      );
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Update margin for an existing position (add or remove)
   *
   * @param params - Margin adjustment parameters
   * @param params.symbol - Asset symbol (e.g., 'BTC', 'ETH')
   * @param params.amount - Amount to adjust as string (positive = add, negative = remove)
   * @param params.providerId - Optional provider identifier (ignored, always uses HyperLiquid)
   * @returns Promise resolving to margin adjustment result
   *
   * Note: HyperLiquid uses micro-units (multiply by 1e6) for the ntli parameter.
   * The SDK's updateIsolatedMargin requires:
   * - asset: Asset ID (number)
   * - isBuy: Position direction (true for long, false for short)
   * - ntli: Amount in micro-units (amount * 1e6)
   */
  async updateMargin(params: UpdateMarginParams): Promise<MarginResult> {
    try {
      this.#deps.debugLogger.log('Updating position margin:', params);

      const { symbol, amount } = params;

      // Ensure provider is ready
      await this.#ensureReady();

      // Get current position to determine direction (from cache to avoid 429 rate limiting)
      const positions = await this.getPositions();
      const position = positions.find((pos) => pos.symbol === symbol);

      if (!position) {
        throw new Error(`No position found for ${symbol}`);
      }

      // Determine position direction
      const isBuy = parseFloat(position.size) > 0; // true for long, false for short

      // Get asset ID for the symbol
      const assetId = await this.#getAssetIdWithRepair({
        symbol,
        dexName: parseAssetName(symbol).dex,
      });

      // Convert amount to micro-units (HyperLiquid SDK requirement)
      const amountFloat = parseFloat(amount);
      const ntli = Math.floor(amountFloat * 1e6);

      this.#deps.debugLogger.log('Margin adjustment details', {
        symbol,
        assetId,
        isBuy,
        amount: amountFloat,
        ntli,
      });

      // Guard: confirm spendableBalance can cover margin addition.
      // spendableBalance is already mode-aware (includes free spot in Unified,
      // excludes it in Standard), so no extra spot fetch needed.
      if (amountFloat > 0) {
        const accountState = await this.getAccountState();
        const spendable = parseFloat(accountState.spendableBalance);

        if (spendable < amountFloat) {
          throw new Error(
            `Insufficient balance for margin addition: need ${amountFloat}, available ${spendable.toFixed(2)}`,
          );
        }
      }

      // Call SDK to update isolated margin
      const exchangeClient = this.#clientService.getExchangeClient();
      const result = await exchangeClient.updateIsolatedMargin({
        asset: assetId,
        isBuy,
        ntli,
      });

      this.#deps.debugLogger.log('Margin update result:', result);

      if (result.status !== 'ok') {
        throw new Error(`Margin adjustment failed: ${JSON.stringify(result)}`);
      }

      return {
        success: true,
      };
    } catch (error) {
      const safeError = ensureError(error, 'HyperLiquidProvider.updateMargin');
      this.#deps.logger.error(
        safeError,
        this.#getErrorContext('updateMargin', {
          symbol: params.symbol,
          amount: params.amount,
        }),
      );
      return {
        success: false,
        error: safeError.message,
      };
    }
  }

  /**
   * Get validated DEXs for standalone mode using a standalone InfoClient.
   * Similar to getValidatedDexs() but doesn't require full initialization.
   * Reuses cachedValidatedDexs to avoid redundant perpDexs() calls.
   *
   * @returns A promise that resolves to the result.
   */
  async #getStandaloneValidatedDexs(): Promise<(string | null)[]> {
    // Return cached result if available (unified state)
    if (this.#dexDiscoveryCache.state?.validated) {
      return this.#dexDiscoveryCache.state.validated;
    }

    // Kill switch: HIP-3 disabled, return main DEX only
    if (!this.#hip3Enabled) {
      const state = this.#dexDiscoveryCache.update([null]);
      return state.validated;
    }

    // Fetch available DEXs via standalone client
    const standaloneInfoClient = createStandaloneInfoClient({
      isTestnet: this.#clientService.isTestnetMode(),
    });
    let allDexs;
    try {
      allDexs = await standaloneInfoClient.perpDexs();
    } catch {
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: standalone perpDexs() failed, falling back to main DEX only',
      );
      // Do not cache — transient error, allow retry on next call
      return [null];
    }

    // Validate response
    if (!allDexs || !Array.isArray(allDexs)) {
      // Do not cache — may be transient, allow retry on next call
      return [null];
    }

    // Atomically update unified state (raw + validated + timestamp).
    // buildAssetMapping uses state.raw for perpDexIndex computation.
    const state = this.#dexDiscoveryCache.update(allDexs);
    return state.validated;
  }

  /**
   * Get current positions with TP/SL prices
   *
   * Note on TP/SL orders:
   * - normalTpsl: TP/SL tied to parent order, only placed after parent fills
   * - positionTpsl: TP/SL tied to position, placed immediately
   *
   * This means TP/SL prices may not appear immediately after placing an order
   * with TP/SL. They will only show up once the parent order is filled and
   * the child TP/SL orders are actually placed on the order book.
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async getPositions(params?: GetPositionsParams): Promise<Position[]> {
    try {
      // Path 0: Standalone mode for lightweight position queries
      // Creates a standalone InfoClient without requiring full initialization
      // No wallet, WebSocket, or account setup needed - just HTTP API call
      // Use for discovery use cases like showing positions on token details page
      if (params?.standalone && params.userAddress) {
        const { userAddress } = params;
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Getting positions in standalone mode',
          { userAddress },
        );

        const standaloneInfoClient = createStandaloneInfoClient({
          isTestnet: this.#clientService.isTestnetMode(),
        });
        const dexs = await this.#getStandaloneValidatedDexs();
        const results = await queryStandaloneClearinghouseStates(
          standaloneInfoClient,
          userAddress,
          dexs,
        );

        // Combine and filter positions from all DEXs
        // Skip TP/SL lookup (would require additional API call)
        const positions = results.flatMap((state) =>
          state.assetPositions
            .filter((assetPos) => assetPos.position.szi !== '0')
            .map((assetPos) => adaptPositionFromSDK(assetPos)),
        );

        this.#deps.debugLogger.log(
          'HyperLiquidProvider: standalone positions fetched',
          { count: positions.length },
        );

        return positions;
      }

      // Try WebSocket cache first (unless explicitly bypassed)
      if (
        !params?.skipCache &&
        this.#subscriptionService.isPositionsCacheInitialized()
      ) {
        const cachedPositions =
          this.#subscriptionService.getCachedPositions() ?? [];
        this.#deps.debugLogger.log('Using cached positions from WebSocket', {
          count: cachedPositions.length,
        });
        return cachedPositions;
      }

      // Fallback to API call
      this.#deps.debugLogger.log(
        'Fetching positions via API',
        params?.skipCache ? '(skipCache requested)' : '(cache not initialized)',
      );

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      // Query positions and orders across all enabled DEXs in parallel
      const [stateResponse, orderResponse] = await Promise.all([
        this.#queryUserDataAcrossDexs({ user: userAddress }, (userParam) =>
          infoClient.clearinghouseState(userParam),
        ),
        this.#queryUserDataAcrossDexs({ user: userAddress }, (userParam) =>
          infoClient.frontendOpenOrders(userParam),
        ),
      ]);
      const { results: stateResults, failedDexs: failedStateDexs } =
        stateResponse;
      const { results: orderResults, failedDexs: failedOrderDexs } =
        orderResponse;

      if (failedStateDexs.length > 0 || failedOrderDexs.length > 0) {
        this.#deps.debugLogger.log(
          'Partial multi-DEX position fetch completed with failures',
          {
            failedStateDexs: failedStateDexs.map(
              ({ dex, error }) => `${dex ?? 'main'}:${error.message}`,
            ),
            failedOrderDexs: failedOrderDexs.map(
              ({ dex, error }) => `${dex ?? 'main'}:${error.message}`,
            ),
          },
        );
      }

      // Combine all orders from all DEXs for TP/SL lookup
      const allOrders = orderResults.flatMap((result) => result.data);

      this.#deps.debugLogger.log('Frontend open orders (all DEXs):', {
        count: allOrders.length,
        orders: allOrders.map((ord) => ({
          coin: ord.coin,
          oid: ord.oid,
          orderType: ord.orderType,
          reduceOnly: ord.reduceOnly,
          isTrigger: ord.isTrigger,
          triggerPx: ord.triggerPx,
          isPositionTpsl: ord.isPositionTpsl,
          side: ord.side,
          sz: ord.sz,
        })),
      });

      // Combine and process positions from all DEXs
      const allPositions = stateResults.flatMap((result) =>
        result.data.assetPositions
          .filter((assetPos) => assetPos.position.szi !== '0')
          .map((assetPos) => {
            const position = adaptPositionFromSDK(assetPos);

            // Find TP/SL orders for this position
            // First check direct trigger orders (raw SDK uses 'coin', adapted position uses 'symbol')
            // Only match position-bound TP/SL orders when UsePositionBoundTpsl is enabled,
            // to avoid picking up normalTpsl children from pending limit orders
            const positionOrders = allOrders.filter(
              (order) =>
                order.coin === position.symbol &&
                order.isTrigger &&
                order.reduceOnly &&
                order.isPositionTpsl ===
                  Boolean(TP_SL_CONFIG.UsePositionBoundTpsl),
            );

            // Also check for parent orders that might have TP/SL children
            const parentOrdersWithChildren = allOrders.filter(
              (order) =>
                order.coin === position.symbol &&
                order.children &&
                order.children.length > 0,
            );

            // Look for TP and SL trigger orders
            let takeProfitPrice: string | undefined;
            let stopLossPrice: string | undefined;

            // Check direct trigger orders
            positionOrders.forEach((order) => {
              // Frontend orders have explicit orderType field
              if (
                order.orderType === 'Take Profit Market' ||
                order.orderType === 'Take Profit Limit'
              ) {
                takeProfitPrice = order.triggerPx;
                this.#deps.debugLogger.log(
                  `Found TP order for ${position.symbol}:`,
                  {
                    triggerPrice: order.triggerPx,
                    orderId: order.oid,
                    orderType: order.orderType,
                    isPositionTpsl: order.isPositionTpsl,
                  },
                );
              } else if (
                order.orderType === 'Stop Market' ||
                order.orderType === 'Stop Limit'
              ) {
                stopLossPrice = order.triggerPx;
                this.#deps.debugLogger.log(
                  `Found SL order for ${position.symbol}:`,
                  {
                    triggerPrice: order.triggerPx,
                    orderId: order.oid,
                    orderType: order.orderType,
                    isPositionTpsl: order.isPositionTpsl,
                  },
                );
              }
            });

            // Check child orders (for normalTpsl grouping)
            parentOrdersWithChildren.forEach((parentOrder) => {
              this.#deps.debugLogger.log(
                `Parent order with children for ${position.symbol}:`,
                {
                  parentOid: parentOrder.oid,
                  childrenCount: parentOrder.children.length,
                },
              );

              parentOrder.children.forEach((childOrderUnknown) => {
                const childOrder = childOrderUnknown as FrontendOrder;
                if (childOrder.isTrigger && childOrder.reduceOnly) {
                  if (
                    childOrder.orderType === 'Take Profit Market' ||
                    childOrder.orderType === 'Take Profit Limit'
                  ) {
                    takeProfitPrice = childOrder.triggerPx;
                    this.#deps.debugLogger.log(
                      `Found TP child order for ${position.symbol}:`,
                      {
                        triggerPrice: childOrder.triggerPx,
                        orderId: childOrder.oid,
                        orderType: childOrder.orderType,
                      },
                    );
                  } else if (
                    childOrder.orderType === 'Stop Market' ||
                    childOrder.orderType === 'Stop Limit'
                  ) {
                    stopLossPrice = childOrder.triggerPx;
                    this.#deps.debugLogger.log(
                      `Found SL child order for ${position.symbol}:`,
                      {
                        triggerPrice: childOrder.triggerPx,
                        orderId: childOrder.oid,
                        orderType: childOrder.orderType,
                      },
                    );
                  }
                }
              });
            });

            return {
              ...position,
              takeProfitPrice,
              stopLossPrice,
            };
          }),
      );

      return allPositions;
    } catch (error) {
      this.#deps.debugLogger.log('Error getting positions:', error);
      return [];
    }
  }

  /**
   * Get historical user fills (trade executions)
   *
   * @param params - The operation parameters.
   * @param options - Optional cache-control modifiers for this read.
   * @returns A promise that resolves to the result.
   */
  async getOrderFills(
    params?: GetOrderFillsParams,
    options?: PerpsReadOptions,
  ): Promise<OrderFill[]> {
    try {
      this.#deps.debugLogger.log(
        'Getting user fills via HyperLiquid SDK:',
        params,
      );

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      // Use userFillsByTime when startTime is provided for time-filtered queries,
      // otherwise use userFills for backward compatibility
      const rawFills = params?.startTime
        ? await infoClient.userFillsByTime({
            user: userAddress,
            startTime: params.startTime,
            endTime: params.endTime,
            aggregateByTime: params?.aggregateByTime ?? false,
          })
        : await infoClient.userFills({
            user: userAddress,
            aggregateByTime: params?.aggregateByTime ?? false,
          });

      this.#deps.debugLogger.log('User fills received:', {
        count: rawFills?.length ?? 0,
      });

      // Start fetching historical orders in parallel with fill transformation.
      // The fills API does not return order type, so we cross-reference
      // with historical orders to enable TP/SL pill rendering in activity.
      // Routed through the client-service coalesce so the enrichment sidecar
      // rides the same cache as an explicit getOrders call, preventing a
      // second REST fire under rapid market switching.
      const historicalOrdersPromise = this.#clientService
        .fetchHistoricalOrders(userAddress, {
          forceRefresh: options?.forceRefresh,
        })
        .catch((enrichError: unknown) => {
          this.#deps.debugLogger.log(
            'Warning: failed to enrich fills with order types:',
            enrichError,
          );
          return null;
        });

      // Transform HyperLiquid fills to abstract OrderFill type
      const fills = (rawFills || []).reduce((acc: OrderFill[], fill) => {
        // Perps only, no Spots
        if (!['Buy', 'Sell'].includes(fill.dir)) {
          acc.push({
            orderId: fill.oid?.toString() || '',
            symbol: fill.coin,
            side: fill.side === 'A' ? 'sell' : 'buy',
            startPosition: fill.startPosition,
            size: fill.sz,
            price: fill.px,
            fee: fill.fee,
            feeToken: fill.feeToken,
            timestamp: fill.time,
            pnl: fill.closedPnl,
            direction: fill.dir,
            success: true,
            liquidation: fill.liquidation
              ? {
                  liquidatedUser: fill.liquidation.liquidatedUser,
                  markPx: fill.liquidation.markPx,
                  method: fill.liquidation.method,
                }
              : undefined,
          });
        }

        return acc;
      }, []);

      // Enrich fills with detailedOrderType from historical orders
      // Wrapped in its own try/catch so a malformed order never discards fetched fills
      try {
        const rawOrders = await historicalOrdersPromise;
        if (rawOrders) {
          const orderTypeByOid = new Map<string, string>();
          for (const rawOrder of rawOrders) {
            const oid = rawOrder.order?.oid?.toString();
            if (oid && rawOrder.order?.orderType && !orderTypeByOid.has(oid)) {
              orderTypeByOid.set(oid, rawOrder.order.orderType);
            }
          }
          for (const fill of fills) {
            const orderType = orderTypeByOid.get(fill.orderId);
            if (orderType) {
              fill.detailedOrderType = orderType;
            }
          }
        }
      } catch (enrichError) {
        this.#deps.debugLogger.log(
          'Error enriching fills with order types:',
          enrichError,
        );
      }

      return fills;
    } catch (error) {
      this.#deps.debugLogger.log('Error getting user fills:', error);
      return [];
    }
  }

  /**
   * Get historical orders (order lifecycle)
   *
   * @param params - The operation parameters.
   * @param options - Optional cache-control modifiers for this read.
   * @returns A promise that resolves to the result.
   */
  async getOrders(
    params?: GetOrdersParams,
    options?: PerpsReadOptions,
  ): Promise<Order[]> {
    try {
      this.#deps.debugLogger.log(
        'Getting user orders via HyperLiquid SDK:',
        params,
      );

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      const rawOrders = await this.#clientService.fetchHistoricalOrders(
        userAddress,
        { forceRefresh: options?.forceRefresh },
      );

      this.#deps.debugLogger.log('User orders received:', {
        count: rawOrders?.length ?? 0,
      });

      // Transform HyperLiquid orders to abstract Order type
      const orders: Order[] = (rawOrders || []).map((rawOrder) => {
        const { order, status, statusTimestamp } = rawOrder;
        // Normalize side: HyperLiquid uses 'A' (Ask/Sell) and 'B' (Bid/Buy)
        const normalizedSide = order.side === 'B' ? 'buy' : 'sell';

        // Normalize status
        let normalizedStatus: Order['status'];
        switch (status) {
          case 'open':
            normalizedStatus = 'open';
            break;
          case 'filled':
            normalizedStatus = 'filled';
            break;
          case 'canceled':
          case 'marginCanceled':
          case 'vaultWithdrawalCanceled':
          case 'openInterestCapCanceled':
          case 'selfTradeCanceled':
          case 'reduceOnlyCanceled':
          case 'siblingFilledCanceled':
          case 'delistedCanceled':
          case 'liquidatedCanceled':
          case 'scheduledCancel':
          case 'reduceOnlyRejected':
            normalizedStatus = 'canceled';
            break;
          case 'rejected':
            // case 'minTradeNtlRejected':
            normalizedStatus = 'rejected';
            break;
          case 'triggered':
            normalizedStatus = 'triggered';
            break;
          default:
            normalizedStatus = 'queued';
        }

        // Calculate filled and remaining size
        const originalSize = parseFloat(order.origSz || order.sz);
        const currentSize = parseFloat(order.sz);
        const filledSize = originalSize - currentSize;

        return {
          orderId: order.oid?.toString() || '',
          symbol: order.coin,
          side: normalizedSide,
          orderType: order.orderType?.toLowerCase().includes('limit')
            ? 'limit'
            : 'market',
          size: order.sz,
          originalSize: order.origSz || order.sz,
          price: order.limitPx || '0',
          filledSize: filledSize.toString(),
          remainingSize: currentSize.toString(),
          status: normalizedStatus,
          timestamp: statusTimestamp,
          lastUpdated: statusTimestamp,
          detailedOrderType: order.orderType, // Full order type from exchange (e.g., 'Take Profit Limit', 'Stop Market')
          isTrigger: order.isTrigger,
          reduceOnly: order.reduceOnly,
        };
      });

      return orders;
    } catch (error) {
      this.#deps.debugLogger.log('Error getting user orders:', error);
      return [];
    }
  }

  /**
   * Get currently open orders (real-time status)
   * Uses frontendOpenOrders API to get only currently active orders
   * Aggregates orders from all enabled DEXs (main + HIP-3)
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async getOpenOrders(params?: GetOrdersParams): Promise<Order[]> {
    try {
      // Path 0: Standalone mode for lightweight open order queries
      // Creates a standalone InfoClient without requiring full initialization
      // No wallet, WebSocket, or account setup needed - just HTTP API call
      if (params?.standalone && params.userAddress) {
        const { userAddress } = params;
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Getting open orders in standalone mode',
          { userAddress },
        );

        const standaloneInfoClient = createStandaloneInfoClient({
          isTestnet: this.#clientService.isTestnetMode(),
        });
        const dexs = await this.#getStandaloneValidatedDexs();
        const orderResults = await queryStandaloneOpenOrders(
          standaloneInfoClient,
          userAddress,
          dexs,
        );

        // Combine all orders from all DEXs and adapt (without position context in standalone mode)
        const orders = orderResults.flatMap((dexOrders) =>
          dexOrders.map((order) => adaptOrderFromSDK(order, undefined)),
        );

        this.#deps.debugLogger.log(
          'HyperLiquidProvider: standalone open orders fetched',
          { count: orders.length },
        );

        return orders;
      }

      // Try WebSocket cache first (unless explicitly bypassed)
      // Use atomic getter to prevent race condition between check and get
      if (!params?.skipCache) {
        const cachedOrders =
          this.#subscriptionService.getOrdersCacheIfInitialized();
        if (cachedOrders !== null) {
          this.#deps.debugLogger.log(
            'Using cached open orders from WebSocket',
            {
              count: cachedOrders.length,
            },
          );
          return cachedOrders;
        }
      }

      // Fallback to API call
      this.#deps.debugLogger.log(
        'Fetching open orders via API',
        params?.skipCache ? '(skipCache requested)' : '(cache not initialized)',
      );

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      // Query orders across all enabled DEXs in parallel
      const { results: orderResults, failedDexs } =
        await this.#queryUserDataAcrossDexs(
          { user: userAddress },
          (userParam) => infoClient.frontendOpenOrders(userParam),
        );

      if (failedDexs.length > 0) {
        this.#deps.debugLogger.log(
          'Partial multi-DEX open order fetch completed with failures',
          {
            failedDexs: failedDexs.map(
              ({ dex, error }) => `${dex ?? 'main'}:${error.message}`,
            ),
          },
        );
      }

      // Combine all orders from all DEXs
      const rawOrders = orderResults.flatMap((result) => result.data);

      // Get positions for order context (already multi-DEX aware)
      const positions = await this.getPositions();

      this.#deps.debugLogger.log('Currently open orders received (all DEXs):', {
        count: rawOrders.length,
      });

      // Transform HyperLiquid open orders to abstract Order type using adapter
      // Raw SDK orders use 'coin', adapted positions use 'symbol'
      const orders: Order[] = (rawOrders || []).map((order) => {
        const position = positions.find((pos) => pos.symbol === order.coin);
        return adaptOrderFromSDK(order, position);
      });

      return orders;
    } catch (error) {
      this.#deps.debugLogger.log('Error getting currently open orders:', error);
      return [];
    }
  }

  /**
   * Get user funding history
   *
   * @param params - The operation parameters.
   * @param _options - Cache-control modifiers (unused — funding has no
   * provider-internal cache; coalescing happens at MarketDataService).
   * @returns A promise that resolves to the result.
   */
  async getFunding(
    params?: GetFundingParams,
    _options?: PerpsReadOptions,
  ): Promise<Funding[]> {
    try {
      this.#deps.debugLogger.log(
        'Getting user funding via HyperLiquid SDK:',
        params,
      );

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      // On-demand loading: the default window is one 30-day page so the
      // initial fetch costs exactly 1 API call (~24 weight vs 312 previously).
      // When loadMoreFunding in usePerpsTransactionHistory passes explicit
      // startTime/endTime for an older 30-day page the while-loop below still
      // produces exactly 1 chunk. The 365-day max lookback is enforced by the
      // caller.
      //
      // Each chunk is fetched via fetchWindowWithAutoSplit: if a call returns
      // FUNDING_HISTORY_API_LIMIT records the window has hit the API cap and
      // the oldest records would be silently dropped. The function splits the
      // window in half and recurses until every sub-window is under the cap,
      // guaranteeing complete results regardless of position count or activity.
      const finalEndTime = params?.endTime ?? Date.now();
      const pageWindowMs =
        PERPS_TRANSACTIONS_HISTORY_CONSTANTS.FUNDING_HISTORY_PAGE_WINDOW_DAYS *
        24 *
        60 *
        60 *
        1000;
      const finalStartTime = params?.startTime ?? finalEndTime - pageWindowMs; // Default: most recent 30-day window only

      const minSplitWindowMs =
        PERPS_TRANSACTIONS_HISTORY_CONSTANTS.MIN_SPLIT_WINDOW_MS;
      const apiLimit =
        PERPS_TRANSACTIONS_HISTORY_CONSTANTS.FUNDING_HISTORY_API_LIMIT;

      // Fetches a single window. If the result hits the API cap the window is
      // split in half and both halves are fetched in parallel, recursively,
      // until every sub-window is under the cap.
      const fetchWindowWithAutoSplit = async (
        windowStart: number,
        windowEnd: number,
      ): Promise<Awaited<ReturnType<typeof infoClient.userFunding>>> => {
        const result = await infoClient.userFunding({
          user: userAddress,
          startTime: windowStart,
          endTime: windowEnd,
        });
        const records = result ?? [];
        if (
          records.length >= apiLimit &&
          windowEnd - windowStart > minSplitWindowMs
        ) {
          const mid = windowStart + Math.floor((windowEnd - windowStart) / 2);
          const [left, right] = await Promise.all([
            fetchWindowWithAutoSplit(windowStart, mid),
            fetchWindowWithAutoSplit(mid, windowEnd),
          ]);
          return [...(left ?? []), ...(right ?? [])];
        }
        return records;
      };

      const chunks: { start: number; end: number }[] = [];
      let chunkEnd = finalEndTime;
      while (chunkEnd > finalStartTime) {
        const chunkStart = Math.max(finalStartTime, chunkEnd - pageWindowMs);
        chunks.push({ start: chunkStart, end: chunkEnd });
        chunkEnd = chunkStart;
      }

      const pages = await Promise.all(
        chunks.map((chunk) => fetchWindowWithAutoSplit(chunk.start, chunk.end)),
      );

      // Deduplicate at chunk boundaries — adjacent windows share their boundary
      // timestamp (chunkEnd of N === chunkStart of N+1) and the API is
      // inclusive on both sides, so a record can appear in both adjacent calls.
      // Funding records share a zero hash, so we key on time + coin instead.
      const seen = new Set<string>();
      const allRaw = pages.flat().filter((record) => {
        const key = `${record.time}-${record.delta.coin}`;
        if (seen.has(key)) {
          return false;
        }
        seen.add(key);
        return true;
      });
      allRaw.sort((a, b) => a.time - b.time);

      this.#deps.debugLogger.log('User funding received:', {
        count: allRaw.length,
        chunks: chunks.length,
      });

      // Transform HyperLiquid funding to abstract Funding type
      const funding: Funding[] = allRaw.map(({ delta, hash, time }) => ({
        symbol: delta.coin,
        amountUsd: delta.usdc,
        rate: delta.fundingRate,
        timestamp: time,
        transactionHash: hash,
      }));

      return funding;
    } catch (error) {
      this.#deps.debugLogger.log('Error getting user funding:', error);
      return [];
    }
  }

  /**
   * Get user non-funding ledger updates (deposits, transfers, withdrawals)
   *
   * @param params - The operation parameters.
   * @param params.accountId - The CAIP account ID.
   * @param params.startTime - Start timestamp in milliseconds.
   * @param params.endTime - End timestamp in milliseconds.
   * @returns The result of the operation.
   */
  async getUserNonFundingLedgerUpdates(params?: {
    accountId?: string;
    startTime?: number;
    endTime?: number;
  }): Promise<RawLedgerUpdate[]> {
    try {
      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId as CaipAccountId | undefined,
      );

      const rawLedgerUpdates = await infoClient.userNonFundingLedgerUpdates({
        user: userAddress,
        startTime: params?.startTime ?? 0,
        endTime: params?.endTime,
      });

      return rawLedgerUpdates ?? [];
    } catch (error) {
      this.#deps.logger.error(
        ensureError(
          error,
          'HyperLiquidProvider.getUserNonFundingLedgerUpdates',
        ),
        this.#getErrorContext('getUserNonFundingLedgerUpdates', params),
      );
      return [];
    }
  }

  /**
   * Resolve the provider's currently active CAIP account identifier.
   * Used by the MarketDataService REST coalesce layer so cached payloads
   * are keyed by the actual resolved address rather than a shared
   * "default" sentinel — prevents one account's data from being served
   * after an account switch within the coalesce TTL window.
   *
   * @returns CAIP account id for the currently selected HyperLiquid account.
   */
  async getCurrentAccountId(): Promise<CaipAccountId> {
    return this.#walletService.getCurrentAccountId();
  }

  /**
   * Get user history (deposits, withdrawals, transfers)
   *
   * @param params - The operation parameters.
   * @param params.accountId - The CAIP account ID.
   * @param params.startTime - Start timestamp in milliseconds.
   * @param params.endTime - End timestamp in milliseconds.
   * @returns The result of the operation.
   */
  async getUserHistory(params?: {
    accountId?: CaipAccountId;
    startTime?: number;
    endTime?: number;
  }): Promise<UserHistoryItem[]> {
    try {
      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      const rawLedgerUpdates = await infoClient.userNonFundingLedgerUpdates({
        user: userAddress,
        startTime: params?.startTime ?? 0,
        endTime: params?.endTime,
      });

      // Transform the raw ledger updates to UserHistoryItem format
      return adaptHyperLiquidLedgerUpdateToUserHistoryItem(rawLedgerUpdates);
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getUserHistory'),
        this.#getErrorContext('getUserHistory'),
      );
      return [];
    }
  }

  async getHistoricalPortfolio(
    params?: GetHistoricalPortfolioParams,
  ): Promise<HistoricalPortfolioResult> {
    try {
      this.#deps.debugLogger.log(
        'Getting historical portfolio via HyperLiquid SDK:',
        params,
      );

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      // Get portfolio data
      const portfolioData = await infoClient.portfolio({
        user: userAddress,
      });

      // Calculate target time (default to 24 hours ago)
      const targetTime = Date.now() - 24 * 60 * 60 * 1000;

      // Get UTC 00:00 of the target day
      const targetDate = new Date(targetTime);
      const targetTimestamp = targetDate.getTime();

      // Get the account value history from the last week's data
      const weeklyPeriod = portfolioData?.[1];
      const weekData = weeklyPeriod?.[1];
      const accountValueHistory = weekData?.accountValueHistory || [];

      // Find entries that are before the target timestamp, then get the closest one
      const entriesBeforeTarget = accountValueHistory.filter(
        ([timestamp]) => timestamp < targetTimestamp,
      );

      let closestEntry = null;
      let smallestDiff = Infinity;
      for (const entry of entriesBeforeTarget) {
        const [timestamp] = entry;
        const diff = targetTimestamp - timestamp;
        if (diff < smallestDiff) {
          smallestDiff = diff;
          closestEntry = entry;
        }
      }

      const result: HistoricalPortfolioResult = closestEntry
        ? {
            accountValue1dAgo: closestEntry[1] || '0',
            timestamp: closestEntry[0] || 0,
          }
        : {
            accountValue1dAgo:
              accountValueHistory?.[accountValueHistory.length - 1]?.[1] || '0',
            timestamp: 0,
          };

      this.#deps.debugLogger.log('Historical portfolio result:', result);
      return result;
    } catch (error) {
      this.#deps.debugLogger.log('Error getting historical portfolio:', error);
      return {
        accountValue1dAgo: '0',
        timestamp: 0,
      };
    }
  }

  /**
   * Get account state
   * Aggregates balances across all enabled DEXs (main + HIP-3)
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async getAccountState(params?: GetAccountStateParams): Promise<AccountState> {
    try {
      // Path 0: Standalone mode for lightweight account state queries
      // Creates a standalone InfoClient without requiring full initialization
      // No wallet, WebSocket, or account setup needed - just HTTP API call
      // Use for discovery use cases like checking if user has perps funds
      if (params?.standalone && params.userAddress) {
        const { userAddress } = params;
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Getting account state in standalone mode',
          { userAddress },
        );

        const standaloneInfoClient = createStandaloneInfoClient({
          isTestnet: this.#clientService.isTestnetMode(),
        });
        const dexs = await this.#getStandaloneValidatedDexs();
        const [
          standaloneSpotStateResult,
          standalonePerpsResults,
          standaloneAbstractionResult,
        ] = await Promise.all([
          standaloneInfoClient
            .spotClearinghouseState({ user: userAddress })
            .catch((error: unknown) => {
              this.#deps.debugLogger.log(
                'Standalone spot state fetch failed — falling back to perps-only totals',
                {
                  error: ensureError(
                    error,
                    'HyperLiquidProvider.getAccountState.standalone.spot',
                  ).message,
                },
              );
              return null;
            }),
          queryStandaloneClearinghouseStates(
            standaloneInfoClient,
            userAddress,
            dexs,
          ),
          standaloneInfoClient
            .userAbstraction({ user: userAddress })
            .catch((error: unknown) => {
              this.#deps.debugLogger.log(
                'Standalone userAbstraction fetch failed; spot fold disabled until the mode resolves',
                {
                  error: ensureError(
                    error,
                    'HyperLiquidProvider.getAccountState.standalone.abstraction',
                  ).message,
                },
              );
              return null;
            }),
        ]);

        // Aggregate account states across all DEXs, then apply spot-backed
        // adjustments so streamed/standalone/full paths report the same totals.
        const dexAccountStates = standalonePerpsResults.map((perpsState) =>
          adaptAccountStateFromSDK(perpsState),
        );
        const aggregatedAccountState = addSpotBalanceToAccountState(
          aggregateAccountStates(dexAccountStates),
          standaloneSpotStateResult,
          {
            foldIntoCollateral: hyperLiquidModeFoldsSpot(
              standaloneAbstractionResult,
            ),
          },
        );

        this.#deps.debugLogger.log(
          'HyperLiquidProvider: standalone account state fetched',
          { totalBalance: aggregatedAccountState.totalBalance },
        );

        return aggregatedAccountState;
      }

      this.#deps.debugLogger.log('Getting account state via HyperLiquid SDK');

      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault(
        params?.accountId,
      );

      this.#deps.debugLogger.log(
        'User address for account state:',
        userAddress,
      );
      this.#deps.debugLogger.log(
        'Network mode:',
        this.#clientService.isTestnetMode() ? 'TESTNET' : 'MAINNET',
      );

      // Get Spot balance, Perps states across DEXs, and the HL abstraction
      // mode (Unified / Standard / Portfolio / DEX-abstraction). Mode decides
      // whether spot USDC is perps collateral — see addSpotBalanceToAccountState.
      // One transient DEX failure should not blank the entire account state.
      const [spotStateResult, perpsStateResult, abstractionResult] =
        await Promise.allSettled([
          infoClient.spotClearinghouseState({ user: userAddress }),
          this.#queryUserDataAcrossDexs({ user: userAddress }, (userParam) =>
            infoClient.clearinghouseState(userParam),
          ),
          infoClient.userAbstraction({ user: userAddress }),
        ]);
      const spotState =
        spotStateResult.status === 'fulfilled' ? spotStateResult.value : null;
      const abstractionMode =
        abstractionResult.status === 'fulfilled'
          ? abstractionResult.value
          : null;
      if (abstractionResult.status === 'rejected') {
        this.#deps.debugLogger.log(
          'User abstraction fetch failed; spot fold disabled until the mode resolves',
          {
            error: ensureError(
              abstractionResult.reason,
              'HyperLiquidProvider.getAccountState.abstraction',
            ).message,
          },
        );
      }
      const perpsResponse =
        perpsStateResult.status === 'fulfilled'
          ? perpsStateResult.value
          : {
              results: [],
              failedDexs: [
                {
                  dex: null,
                  error: ensureError(
                    perpsStateResult.reason,
                    'HyperLiquidProvider.getAccountState.perps',
                  ),
                },
              ],
            };
      const perpsStateResults = perpsResponse.results;
      const failedPerpsDexs = perpsResponse.failedDexs;

      if (spotStateResult.status === 'rejected') {
        this.#deps.debugLogger.log(
          'Spot state fetch failed during account state aggregation',
          {
            error: ensureError(
              spotStateResult.reason,
              'HyperLiquidProvider.getAccountState.spot',
            ).message,
          },
        );
      }

      if (failedPerpsDexs.length > 0) {
        this.#deps.debugLogger.log(
          'Perps account state completed with partial DEX failures',
          {
            failedDexs: failedPerpsDexs.map(
              ({ dex, error }) => `${dex ?? 'main'}:${error.message}`,
            ),
          },
        );
      }

      if (perpsStateResults.length === 0) {
        const failedDexNames = failedPerpsDexs.map(({ dex }) => dex ?? 'main');
        const spotErrorMessage =
          spotStateResult.status === 'rejected'
            ? ensureError(
                spotStateResult.reason,
                'HyperLiquidProvider.getAccountState.spot',
              ).message
            : undefined;
        throw new Error(
          `Failed to fetch account state (failedDexs=[${failedDexNames.join(',')}], spotError=${spotErrorMessage ?? 'none'})`,
        );
      }

      this.#deps.debugLogger.log('Spot state:', spotState);
      this.#deps.debugLogger.log('Perps states (all DEXs):', {
        dexCount: perpsStateResults.length,
      });

      // Aggregate account states from all DEXs
      // Each DEX has independent positions and margin, we sum them
      const dexAccountStates = perpsStateResults.map((result) => {
        const dexAccountState = adaptAccountStateFromSDK(result.data);
        this.#deps.debugLogger.log(
          `DEX ${result.dex ?? 'main'} account state:`,
          {
            totalBalance: dexAccountState.totalBalance,
            spendableBalance: dexAccountState.spendableBalance,
            withdrawableBalance: dexAccountState.withdrawableBalance,
            marginUsed: dexAccountState.marginUsed,
            unrealizedPnl: dexAccountState.unrealizedPnl,
          },
        );
        return dexAccountState;
      });
      const aggregatedAccountState = addSpotBalanceToAccountState(
        aggregateAccountStates(dexAccountStates),
        spotState,
        { foldIntoCollateral: hyperLiquidModeFoldsSpot(abstractionMode) },
      );

      // Build per-sub-account breakdown (HIP-3 DEXs map to sub-accounts)
      const subAccountBreakdown: Record<
        string,
        {
          spendableBalance: string;
          withdrawableBalance: string;
          totalBalance: string;
        }
      > = {};
      perpsStateResults.forEach((result) => {
        const { dex, data: perpsState } = result;
        const dexAccountState = adaptAccountStateFromSDK(perpsState);
        const subAccountKey = dex ?? ''; // Empty string for main DEX

        subAccountBreakdown[subAccountKey] = {
          spendableBalance: dexAccountState.spendableBalance,
          withdrawableBalance: dexAccountState.withdrawableBalance,
          totalBalance: dexAccountState.totalBalance,
        };
      });

      // Add sub-account breakdown to result
      aggregatedAccountState.subAccountBreakdown = subAccountBreakdown;

      this.#deps.debugLogger.log(
        'Aggregated account state:',
        aggregatedAccountState,
      );

      return aggregatedAccountState;
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getAccountState'),
        this.#getErrorContext('getAccountState', {
          accountId: params?.accountId,
        }),
      );
      // Re-throw the error so the controller can handle it properly
      // This allows the UI to show proper error messages instead of zeros
      throw ensureError(error, 'HyperLiquidProvider.getAccountState');
    }
  }

  /**
   * Get available markets with multi-DEX aggregation support (HIP-3)
   * Handles three query patterns:
   * 1. Symbol filtering: Groups symbols by DEX, fetches in parallel
   * 2. Multi-DEX aggregation: Fetches from all enabled DEXs when no specific DEX requested
   * 3. Single DEX query: Fetches from main or specific DEX
   *
   * @param params - Optional parameters for filtering
   * @returns A promise that resolves to the result.
   */
  async getMarkets(params?: GetMarketsParams): Promise<MarketInfo[]> {
    try {
      // Path 0: Standalone mode for lightweight discovery queries
      // Creates a standalone InfoClient without requiring full initialization
      // No wallet, WebSocket, or account setup needed - just HTTP API call
      // Use for discovery use cases like checking if a perps market exists
      if (params?.standalone) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Getting markets in standalone mode',
          { symbolCount: params?.symbols?.length },
        );

        // Create standalone client - bypasses all initialization (wallet, WebSocket, etc.)
        const standaloneInfoClient = createStandaloneInfoClient({
          isTestnet: this.#clientService.isTestnetMode(),
        });

        // Simple path: fetch main DEX markets only (no HIP-3 multi-DEX)
        const meta = await standaloneInfoClient.meta();

        if (!meta?.universe || !Array.isArray(meta.universe)) {
          throw new Error(
            'Invalid universe data received from HyperLiquid API',
          );
        }

        // Transform to MarketInfo format
        const markets = meta.universe.map((asset) => adaptMarketFromSDK(asset));

        // Filter by symbols if provided
        if (params?.symbols?.length) {
          return markets.filter((market) =>
            params.symbols?.some(
              (symbol) => market.name.toUpperCase() === symbol.toUpperCase(),
            ),
          );
        }

        return markets;
      }

      // Ensure full initialization including asset mapping
      // This is deduplicated - concurrent calls wait for the same promise
      await this.#ensureReady();

      // Path 1: Symbol filtering - group by DEX and fetch in parallel
      if (params?.symbols && params.symbols.length > 0) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: Getting markets with symbol filter',
          {
            symbolCount: params.symbols.length,
          },
        );

        // Group symbols by DEX
        const symbolsByDex = new Map<string | null, string[]>();
        params.symbols.forEach((symbol) => {
          const { dex } = parseAssetName(symbol);
          const existing = symbolsByDex.get(dex);
          if (existing) {
            existing.push(symbol);
          } else {
            symbolsByDex.set(dex, [symbol]);
          }
        });

        // Query each unique DEX in parallel (with caching)
        const marketArrays = await Promise.all(
          Array.from(symbolsByDex.keys()).map(async (dex) =>
            this.#fetchMarketsForDex({
              dex,
              skipFilters: params?.skipFilters,
            }),
          ),
        );

        // Combine and filter by requested symbols
        const allMarkets = marketArrays.flat();
        return allMarkets.filter((market) =>
          params.symbols?.some(
            (symbol) => market.name.toLowerCase() === symbol.toLowerCase(),
          ),
        );
      }

      // Path 2: Multi-DEX aggregation - fetch from all enabled DEXs
      if (!params?.dex && this.#hip3Enabled) {
        // Determine which DEXs to query based on skipFilters flag
        const dexsToQuery = params?.skipFilters
          ? await this.#getAllAvailableDexs()
          : await this.#getValidatedDexs();

        if (dexsToQuery.length > 1) {
          // More than just main DEX
          this.#deps.debugLogger.log(
            'HyperLiquidProvider: Fetching markets from DEXs',
            {
              dexCount: dexsToQuery.length,
              skipFilters: params?.skipFilters ?? false,
            },
          );

          const marketArrays = await Promise.all(
            dexsToQuery.map(async (dex) => {
              try {
                return await this.#fetchMarketsForDex({
                  dex,
                  skipFilters: params?.skipFilters,
                });
              } catch (error) {
                this.#deps.logger.error(
                  ensureError(error, 'HyperLiquidProvider.getMarkets'),
                  this.#getErrorContext('getMarkets.multiDex', {
                    dex: dex ?? 'main',
                  }),
                );
                return []; // Continue with other DEXs on error
              }
            }),
          );

          return marketArrays.flat();
        }
      }

      // Path 3: Single DEX query (main DEX or specific DEX) - with caching
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: Getting markets for single DEX',
        {
          dex: params?.dex ?? 'main',
        },
      );

      return await this.#fetchMarketsForDex({
        dex: params?.dex ?? null,
        skipFilters: params?.skipFilters,
      });
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getMarkets'),
        this.#getErrorContext('getMarkets', {
          dex: params?.dex,
          symbolCount: params?.symbols?.length,
        }),
      );
      return [];
    }
  }

  /**
   * Get list of available HIP-3 DEXs that have markets
   * Useful for debugging and manual DEX selection
   *
   * @returns Array of DEX names (excluding main DEX)
   */
  async getAvailableHip3Dexs(): Promise<string[]> {
    try {
      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      if (!this.#hip3Enabled) {
        this.#deps.debugLogger.log('HIP-3 disabled, no DEXs available');
        return [];
      }

      const infoClient = this.#clientService.getInfoClient();

      // Get all DEXs from API
      const allDexs = await infoClient.perpDexs();

      if (!allDexs || !Array.isArray(allDexs)) {
        this.#deps.debugLogger.log('perpDexs() returned invalid data');
        return [];
      }

      // Extract HIP-3 DEX names (filter out null which is main DEX)
      const hip3DexNames: string[] = [];
      allDexs.forEach((dex) => {
        if (dex !== null && hasProperty(dex, 'name')) {
          hip3DexNames.push(dex.name);
        }
      });

      this.#deps.debugLogger.log(
        `Found ${hip3DexNames.length} HIP-3 DEXs from perpDexs() API`,
      );

      // Filter to only DEXs that have markets
      const dexsWithMarkets: string[] = [];
      await Promise.all(
        hip3DexNames.map(async (dexName) => {
          try {
            const meta = await this.#getCachedMeta({ dexName });
            if (
              meta.universe &&
              Array.isArray(meta.universe) &&
              meta.universe.length > 0
            ) {
              dexsWithMarkets.push(dexName);
              this.#deps.debugLogger.log(
                `  ✅ ${dexName}: ${meta.universe.length} markets`,
              );
            } else {
              this.#deps.debugLogger.log(`  ⚠️ ${dexName}: no markets`);
            }
          } catch (error) {
            this.#deps.debugLogger.log(
              `  ❌ ${dexName}: error querying`,
              error,
            );
          }
        }),
      );

      this.#deps.debugLogger.log(
        `${dexsWithMarkets.length} DEXs have markets:`,
        dexsWithMarkets,
      );
      return dexsWithMarkets.sort((a, b) => a.localeCompare(b));
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getAvailableHip3Dexs'),
        this.#getErrorContext('getAvailableHip3Dexs'),
      );
      return [];
    }
  }

  /**
   * Get allMids for a DEX — uses WS snapshot as primary source, REST as fallback.
   *
   * @param infoClient - The HyperLiquid info client (used only on cold start).
   * @param dexParam - Optional DEX parameter (empty string for main DEX).
   * @returns allMids record.
   */
  async #getAllMids(
    infoClient: ReturnType<
      typeof HyperLiquidClientService.prototype.getInfoClient
    >,
    dexParam?: string,
  ): Promise<Record<string, string>> {
    const wsSnapshot =
      this.#subscriptionService.getLastAllMidsSnapshot?.(dexParam);
    if (wsSnapshot) {
      return wsSnapshot;
    }

    this.#deps.debugLogger.log(
      '[getMarketDataWithPrices] No WS allMids snapshot, falling back to REST',
      { dexParam: dexParam ?? 'main' },
    );
    const mids = await infoClient.allMids(
      dexParam ? { dex: dexParam } : undefined,
    );
    return mids ?? {};
  }

  async #fetchSingleDexFresh(
    infoClient: ReturnType<
      typeof HyperLiquidClientService.prototype.getInfoClient
    >,
    dex: string | null,
  ): Promise<DexFetchResult> {
    const dexParam = dex ?? '';

    let metaAndCtxs: [MetaResponse | null, PerpsAssetCtx[]] | null = null;
    try {
      metaAndCtxs = (await infoClient.metaAndAssetCtxs(
        dexParam ? { dex: dexParam } : undefined,
      )) as [MetaResponse | null, PerpsAssetCtx[]] | null;
    } catch (error) {
      return {
        dex,
        meta: null,
        assetCtxs: [],
        allMids: {},
        success: false,
        failedStep: 'metaAndAssetCtxs',
        errorMessage: ensureError(
          error,
          'HyperLiquidProvider.getMarketDataWithPrices.metaAndAssetCtxs',
        ).message,
      };
    }

    const meta = metaAndCtxs?.[0] ?? null;
    const assetCtxs = metaAndCtxs?.[1] ?? [];

    let dexAllMids: Record<string, string> = {};
    let allMidsErrorMessage: string | undefined;
    try {
      dexAllMids = await this.#getAllMids(infoClient, dexParam || undefined);
    } catch (error) {
      allMidsErrorMessage = ensureError(
        error,
        'HyperLiquidProvider.getMarketDataWithPrices.allMids',
      ).message;
    }

    if (meta?.universe) {
      this.#cachedMetaByDex.set(dexParam, meta);
      this.#subscriptionService.setDexMetaCache(dexParam, meta);
      this.#subscriptionService.setDexAssetCtxsCache(dexParam, assetCtxs);
      await this.#backfillAssetMapForDex(dex, meta);
    }

    return {
      dex,
      meta,
      assetCtxs,
      allMids: dexAllMids,
      success: Boolean(meta?.universe),
      failedStep: allMidsErrorMessage ? 'allMids' : undefined,
      errorMessage: allMidsErrorMessage,
    };
  }

  #mergeDexResultsInto(
    results: DexFetchResult[],
    combinedUniverse: MetaResponse['universe'],
    combinedAssetCtxs: PerpsAssetCtx[],
    combinedAllMids: Record<string, string>,
  ): void {
    results.forEach((result) => {
      if (result.success && result.meta?.universe) {
        const marketsFromDex = result.meta.universe;
        const filteredMarkets =
          result.dex === null
            ? marketsFromDex
            : marketsFromDex.filter((asset) =>
                shouldIncludeMarket(
                  asset.name,
                  result.dex,
                  this.#hip3Enabled,
                  this.#compiledAllowlistPatterns,
                  this.#compiledBlocklistPatterns,
                ),
              );

        combinedUniverse.push(...filteredMarkets);
        combinedAssetCtxs.push(...result.assetCtxs);
        Object.assign(combinedAllMids, result.allMids);
      }
    });
  }

  #cacheFreshMarketDataSnapshot(
    marketData: PerpsMarketData[],
    results: DexFetchResult[],
  ): PerpsMarketData[] {
    const freshMarketData = marketData.map((market) => ({
      ...market,
      isStale: false,
    }));
    this.#cachedMarketDataWithPrices = {
      data: freshMarketData.map((market) => ({ ...market })),
      timestamp: Date.now(),
      contributingDexs: results
        .filter((result) => result.success && result.meta?.universe)
        .map((result) => result.dex ?? 'main'),
      failedDexs: results
        .filter((result) => !result.success)
        .map((result) => result.dex ?? 'main'),
    };
    return freshMarketData;
  }

  #getStaleMarketDataSnapshot(): PerpsMarketData[] | null {
    if (!this.#cachedMarketDataWithPrices) {
      return null;
    }

    return this.#cachedMarketDataWithPrices.data.map((market) => ({
      ...market,
      isStale: true,
    }));
  }

  /**
   * Get market data with prices, volumes, and 24h changes
   * Aggregates data from all enabled DEXs (main + HIP-3) when equity is enabled
   *
   * Note: This is called once during initialization and cached by PerpsStreamManager.
   * Real-time price updates come from WebSocket subscriptions, not this method.
   *
   * @returns A promise that resolves to the combined market data from all enabled DEXs.
   */
  async getMarketDataWithPrices(): Promise<PerpsMarketData[]> {
    this.#deps.debugLogger.log(
      'Getting market data with prices via HyperLiquid SDK',
    );

    // Ensure asset mapping is built first (populates meta cache)
    // This guarantees buildAssetMapping has run before we check cache,
    // eliminating duplicate metaAndAssetCtxs API calls from race conditions
    await this.#ensureReady();

    // Use HTTP transport for market data fetches — these are one-shot request/response calls
    // that don't benefit from WebSocket. When the WebSocket is in CONNECTING state (after app
    // backgrounding or network transitions), the SDK buffers messages causing timeouts.
    const infoClient = this.#clientService.getInfoClient({ useHttp: true });

    // Get enabled DEXs respecting feature flags (uses cached perpDexs)
    const enabledDexs = await this.#getValidatedDexs();

    // Fetch meta, assetCtxs, and allMids for each enabled DEX in parallel.
    // Check the meta cache first to avoid redundant API calls when buildAssetMapping
    // has already populated it; on cache miss, delegate to #fetchSingleDexFresh.
    const dexDataResults = await Promise.all(
      enabledDexs.map(async (dex) => {
        const dexKey = dex ?? '';
        const dexParam = dex ?? '';
        const cachedMeta = this.#cachedMetaByDex.get(dexKey);
        if (!cachedMeta) {
          this.#deps.debugLogger.log(
            `[getMarketDataWithPrices] Cache miss for ${dex ?? 'main'}, fetching`,
          );
          return this.#fetchSingleDexFresh(infoClient, dex);
        }

        this.#deps.debugLogger.log(
          `[getMarketDataWithPrices] Using cached meta for ${dex ?? 'main'}`,
          { universeSize: cachedMeta.universe.length },
        );

        let metaForDex = cachedMeta;
        let assetCtxs =
          this.#subscriptionService.getDexAssetCtxsCache(dexKey) ?? [];
        let failedStep: DexFetchFailureStep | undefined;
        let errorMessage: string | undefined;

        if (assetCtxs.length !== metaForDex.universe.length) {
          try {
            const freshResult = await infoClient.metaAndAssetCtxs(
              dexParam ? { dex: dexParam } : undefined,
            );
            const freshMeta = freshResult?.[0] ?? null;
            const freshAssetCtxs = freshResult?.[1] ?? [];

            if (
              !freshMeta?.universe ||
              freshAssetCtxs.length !== freshMeta.universe.length
            ) {
              return {
                dex,
                meta: null,
                assetCtxs: [],
                allMids: {},
                success: false,
                failedStep: 'metaAndAssetCtxs' as const,
                errorMessage:
                  'metaAndAssetCtxs returned mismatched universe/assetCtxs lengths',
              };
            }

            metaForDex = freshMeta;
            assetCtxs = freshAssetCtxs;
            this.#cachedMetaByDex.set(dexKey, freshMeta);
            this.#subscriptionService.setDexMetaCache(dexKey, freshMeta);
            this.#subscriptionService.setDexAssetCtxsCache(dexKey, assetCtxs);
            await this.#backfillAssetMapForDex(dex, freshMeta);
          } catch (error) {
            return {
              dex,
              meta: null,
              assetCtxs: [],
              allMids: {},
              success: false,
              failedStep: 'metaAndAssetCtxs' as const,
              errorMessage: ensureError(
                error,
                'HyperLiquidProvider.getMarketDataWithPrices.metaAndAssetCtxs',
              ).message,
            };
          }
        }

        let dexAllMids: Record<string, string> = {};
        try {
          dexAllMids = await this.#getAllMids(
            infoClient,
            dexParam || undefined,
          );
        } catch (error) {
          failedStep = 'allMids';
          errorMessage = ensureError(
            error,
            'HyperLiquidProvider.getMarketDataWithPrices.allMids',
          ).message;
        }

        return {
          dex,
          meta: metaForDex,
          assetCtxs,
          allMids: dexAllMids,
          success: true,
          failedStep,
          errorMessage,
        };
      }),
    );

    // Combine universe, assetCtxs, and allMids from all DEXs
    const combinedUniverse: MetaResponse['universe'] = [];
    const combinedAssetCtxs: PerpsAssetCtx[] = [];
    const combinedAllMids: Record<string, string> = {};
    let latestDexResults = dexDataResults;

    this.#mergeDexResultsInto(
      dexDataResults,
      combinedUniverse,
      combinedAssetCtxs,
      combinedAllMids,
    );

    if (combinedUniverse.length === 0) {
      combinedUniverse.length = 0;
      combinedAssetCtxs.length = 0;
      for (const key of Object.keys(combinedAllMids)) {
        delete combinedAllMids[key];
      }

      const retryDelayMs = 2000;
      this.#deps.debugLogger.log(
        `[getMarketDataWithPrices] All DEXs returned empty, retrying in ${retryDelayMs}ms`,
      );
      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));

      const retryResults = await Promise.all(
        enabledDexs.map((dex) => this.#fetchSingleDexFresh(infoClient, dex)),
      );

      this.#mergeDexResultsInto(
        retryResults,
        combinedUniverse,
        combinedAssetCtxs,
        combinedAllMids,
      );

      latestDexResults = retryResults;

      if (combinedUniverse.length === 0) {
        const failedDexs = retryResults
          .filter((result) => !result.success)
          .map((result) => result.dex ?? 'main');
        const succeededDexs = retryResults
          .filter((result) => result.success)
          .map((result) => result.dex ?? 'main');
        const failedDetails = retryResults
          .filter((result) => result.errorMessage)
          .map(
            (result) =>
              `${result.dex ?? 'main'}:${result.failedStep ?? 'unknown'}:${
                result.errorMessage
              }`,
          );
        const staleMarketData = this.#getStaleMarketDataSnapshot();

        if (staleMarketData) {
          this.#deps.debugLogger.log(
            '[getMarketDataWithPrices] Returning stale cached market data after retry failure',
            {
              failedDexs,
              failedDetails,
              cachedAt:
                this.#cachedMarketDataWithPrices?.timestamp ?? Date.now(),
            },
          );
          return staleMarketData;
        }

        const wsState = this.#clientService.getConnectionState();
        throw new Error(
          `Failed to fetch market data - no markets available (enabledDexs=${enabledDexs.length}, failed=[${failedDexs.join(',')}], succeeded=[${succeededDexs.join(',')}], wsState=${wsState}, details=[${failedDetails.join(';')}])`,
        );
      }

      this.#deps.debugLogger.log('[getMarketDataWithPrices] Retry succeeded', {
        marketCount: combinedUniverse.length,
      });
    }

    const partialFailures = latestDexResults.filter(
      (result) => result.errorMessage,
    );
    if (partialFailures.length > 0) {
      this.#deps.debugLogger.log(
        'Market data fetch completed with partial per-DEX failures',
        {
          failures: partialFailures.map(
            (result) =>
              `${result.dex ?? 'main'}:${result.failedStep ?? 'unknown'}:${
                result.errorMessage
              }`,
          ),
        },
      );
    }

    this.#deps.debugLogger.log(
      'HyperLiquidProvider: Aggregated market data from all DEXs',
      {
        dexCount: enabledDexs.length,
        totalMarkets: combinedUniverse.length,
        mainDexMarkets: latestDexResults[0]?.meta?.universe?.length ?? 0,
        hip3Markets:
          combinedUniverse.length -
          (latestDexResults[0]?.meta?.universe?.length ?? 0),
      },
    );

    // Debug: Log combinedAllMids to diagnose price lookup issues
    const hip3Keys = Object.keys(combinedAllMids).filter((key) =>
      key.includes(':'),
    );
    this.#deps.debugLogger.log('Combined allMids price data:', {
      totalKeys: Object.keys(combinedAllMids).length,
      allKeys: Object.keys(combinedAllMids),
      hip3Keys,
      hip3Prices: Object.fromEntries(
        hip3Keys.map((key) => [key, combinedAllMids[key]]),
      ),
      samplePrices: Object.fromEntries(
        Object.entries(combinedAllMids).slice(0, 5),
      ),
    });

    // Transform to UI-friendly format using standalone utility
    const transformedMarketData = transformMarketData(
      {
        universe: combinedUniverse,
        assetCtxs: combinedAssetCtxs,
        allMids: combinedAllMids,
      },
      this.#deps.marketDataFormatters,
      HIP3_ASSET_MARKET_TYPES,
    );

    return this.#cacheFreshMarketDataSnapshot(
      transformedMarketData,
      latestDexResults,
    );
  }

  /**
   * Validate deposit parameters according to HyperLiquid-specific rules
   * This method enforces protocol-specific requirements like minimum amounts
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async validateDeposit(
    params: DepositParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    return validateDepositParams({
      amount: params.amount,
      assetId: params.assetId,
      isTestnet: this.#clientService.isTestnetMode(),
    });
  }

  /**
   * Validate order parameters according to HyperLiquid-specific rules
   * This includes minimum order sizes, leverage limits, and other protocol requirements
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async validateOrder(
    params: OrderParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    try {
      // Basic parameter validation
      const basicValidation = validateOrderParams({
        coin: params.symbol,
        size: params.size,
        price: params.price,
        orderType: params.orderType,
      });
      if (!basicValidation.isValid) {
        return basicValidation;
      }

      // Check minimum order size using consistent defaults (matching useMinimumOrderAmount hook)
      // Note: For full validation with market-specific limits, use async methods
      const minimumOrderSize = this.#clientService.isTestnetMode()
        ? TRADING_DEFAULTS.amount.testnet
        : TRADING_DEFAULTS.amount.mainnet;

      // Skip USD validation and minimum check for full closes (100% position close)
      if (params.reduceOnly && params.isFullClose) {
        this.#deps.debugLogger.log(
          'Full close detected: skipping USD validation and $10 minimum',
        );
      } else {
        // Calculate order value in USD for minimum validation
        let orderValueUSD: number;

        if (params.usdAmount) {
          // Preferred: Use provided USD amount (source of truth, no rounding loss)
          orderValueUSD = parseFloat(params.usdAmount);

          this.#deps.debugLogger.log(
            'Validating USD amount (source of truth):',
            {
              usdAmount: orderValueUSD,
              minimumRequired: minimumOrderSize,
            },
          );
        } else {
          // Fallback: Calculate from size × price
          const size = parseFloat(params.size || '0');
          let priceForValidation = params.currentPrice;

          // For limit orders without currentPrice, use limit price as fallback
          if (
            !priceForValidation &&
            params.price &&
            params.orderType === 'limit'
          ) {
            priceForValidation = parseFloat(params.price);
            this.#deps.debugLogger.log(
              'Using limit price for order validation (limit order):',
              {
                size,
                limitPrice: priceForValidation,
              },
            );
          }

          if (!priceForValidation) {
            return {
              isValid: false,
              error: PERPS_ERROR_CODES.ORDER_PRICE_REQUIRED,
            };
          }

          orderValueUSD = size * priceForValidation;

          this.#deps.debugLogger.log('Validating calculated USD from size:', {
            size,
            price: priceForValidation,
            calculatedUsd: orderValueUSD,
            minimumRequired: minimumOrderSize,
          });
        }

        // Validate minimum order size
        if (orderValueUSD < minimumOrderSize) {
          return {
            isValid: false,
            error: PERPS_ERROR_CODES.ORDER_SIZE_MIN,
          };
        }
      }

      // Asset-specific leverage validation
      if (params.leverage && params.symbol) {
        try {
          const maxLeverage = await this.getMaxLeverage(params.symbol);
          if (params.leverage < 1 || params.leverage > maxLeverage) {
            return {
              isValid: false,
              error: PERPS_ERROR_CODES.ORDER_LEVERAGE_INVALID,
            };
          }
        } catch (error) {
          // Log the error before falling back
          this.#deps.debugLogger.log(
            'Failed to get max leverage for symbol',
            error,
          );
          // If we can't get max leverage, use the default as fallback
          const defaultMaxLeverage = PERPS_CONSTANTS.DefaultMaxLeverage;
          if (params.leverage < 1 || params.leverage > defaultMaxLeverage) {
            return {
              isValid: false,
              error: PERPS_ERROR_CODES.ORDER_LEVERAGE_INVALID,
            };
          }
        }
      }

      // Check if order leverage meets existing position requirement (HyperLiquid protocol constraint)
      if (
        params.leverage &&
        params.existingPositionLeverage &&
        params.leverage < params.existingPositionLeverage
      ) {
        return {
          isValid: false,
          error: PERPS_ERROR_CODES.ORDER_LEVERAGE_BELOW_POSITION,
        };
      }

      // Validate order value against max limits
      if (params.currentPrice && params.leverage) {
        try {
          const maxLeverage = await this.getMaxLeverage(params.symbol);

          const maxOrderValue = getMaxOrderValue(maxLeverage, params.orderType);
          const orderValue = parseFloat(params.size) * params.currentPrice;

          if (orderValue > maxOrderValue) {
            return {
              isValid: false,
              error: PERPS_ERROR_CODES.ORDER_MAX_VALUE_EXCEEDED,
            };
          }
        } catch (error) {
          this.#deps.debugLogger.log(
            'Failed to validate max order value',
            error,
          );
          // Continue without max order validation if we can't get leverage
        }
      }

      return { isValid: true };
    } catch (error) {
      return {
        isValid: false,
        error:
          error instanceof Error
            ? error.message
            : PERPS_ERROR_CODES.UNKNOWN_ERROR,
      };
    }
  }

  /**
   * Validate close position parameters according to HyperLiquid-specific rules
   * Note: Full validation including remaining position size requires position data
   * which should be passed from the UI layer
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async validateClosePosition(
    params: ClosePositionParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    try {
      // Basic validation
      if (!params.symbol) {
        return {
          isValid: false,
          error: PERPS_ERROR_CODES.ORDER_COIN_REQUIRED,
        };
      }

      // If closing with limit order, must have price
      if (params.orderType === 'limit' && !params.price) {
        return {
          isValid: false,
          error: PERPS_ERROR_CODES.ORDER_LIMIT_PRICE_REQUIRED,
        };
      }

      // Determine minimum order size (needed for precedence logic)
      const minimumOrderSize = this.#clientService.isTestnetMode()
        ? TRADING_DEFAULTS.amount.testnet
        : TRADING_DEFAULTS.amount.mainnet;

      // Validate close size & minimum only if size provided (partial close)
      if (params.size) {
        const closeSize = parseFloat(params.size);
        const price = params.currentPrice
          ? parseFloat(params.currentPrice.toString())
          : undefined;
        const orderValueUSD =
          price && !isNaN(closeSize) ? closeSize * price : undefined;

        // Precedence rule: if size <= 0 treat as minimum_amount failure (more actionable)
        if (isNaN(closeSize) || closeSize <= 0) {
          return {
            isValid: false,
            error: PERPS_ERROR_CODES.ORDER_SIZE_MIN,
          };
        }

        // Enforce minimum order value for partial closes when price known
        if (orderValueUSD !== undefined && orderValueUSD < minimumOrderSize) {
          return {
            isValid: false,
            error: PERPS_ERROR_CODES.ORDER_SIZE_MIN,
          };
        }

        // Note: Remaining position validation stays in UI layer.
      }
      // Full closes (size undefined) bypass minimum check by design
      // Note: For full closes (when size is undefined), there is no minimum
      // This allows users to close positions worth less than $10 completely

      return { isValid: true };
    } catch (error) {
      return {
        isValid: false,
        error:
          error instanceof Error
            ? error.message
            : PERPS_ERROR_CODES.UNKNOWN_ERROR,
      };
    }
  }

  /**
   * Validate withdrawal parameters - placeholder for future implementation
   *
   * @param _params - The unused operation parameters.
   * @returns A promise that resolves to the result.
   */
  async validateWithdrawal(
    _params: WithdrawParams,
  ): Promise<{ isValid: boolean; error?: string }> {
    // Placeholder - to be implemented when needed
    return { isValid: true };
  }

  /**
   * Withdraw funds from HyperLiquid trading account
   *
   * This initiates a withdrawal request via HyperLiquid's API (withdraw3 endpoint).
   *
   * HyperLiquid Bridge Process:
   * - Funds are immediately deducted from L1 balance on HyperLiquid
   * - Validators sign the withdrawal (2/3 of staking power required)
   * - Bridge contract on destination chain processes the withdrawal
   * - After dispute period, USDC is sent to destination address
   * - Total time: ~5 minutes
   * - Fee: 1 USDC (covers Arbitrum gas costs)
   * - No ETH required from user
   *
   * Note: Withdrawals won't appear as incoming transactions until the
   * finalization phase completes (~5 minutes after initiation)
   *
   * @param params Withdrawal parameters
   * @returns Result with txHash (HyperLiquid internal) and withdrawal ID
   */
  async withdraw(params: WithdrawParams): Promise<WithdrawResult> {
    try {
      this.#deps.debugLogger.log('HyperLiquidProvider: STARTING WITHDRAWAL', {
        params,
        timestamp: new Date().toISOString(),
        assetId: params.assetId,
        amount: params.amount,
        destination: params.destination,
        isTestnet: this.#clientService.isTestnetMode(),
      });

      // Step 1: Validate withdrawal parameters
      this.#deps.debugLogger.log('HyperLiquidProvider: VALIDATING PARAMETERS');
      const validation = validateWithdrawalParams(params);
      if (!validation.isValid) {
        this.#deps.debugLogger.log(
          '❌ HyperLiquidProvider: PARAMETER VALIDATION FAILED',
          {
            error: validation.error,
            params,
            validationResult: validation,
          },
        );
        throw new Error(validation.error);
      }
      this.#deps.debugLogger.log('HyperLiquidProvider: PARAMETERS VALIDATED');

      // Step 2: Get supported withdrawal routes and validate asset
      this.#deps.debugLogger.log('HyperLiquidProvider: CHECKING ASSET SUPPORT');
      const supportedRoutes = this.getWithdrawalRoutes();
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: SUPPORTED WITHDRAWAL ROUTES',
        {
          routeCount: supportedRoutes.length,
          routes: supportedRoutes.map((route) => ({
            assetId: route.assetId,
            chainId: route.chainId,
            contractAddress: route.contractAddress,
          })),
        },
      );

      // This check is already done in validateWithdrawalParams, but TypeScript needs explicit check
      if (!params.assetId) {
        this.#deps.debugLogger.log('HyperLiquidProvider: MISSING ASSET ID', {
          error: PERPS_ERROR_CODES.WITHDRAW_ASSET_ID_REQUIRED,
          params,
        });
        throw new Error(PERPS_ERROR_CODES.WITHDRAW_ASSET_ID_REQUIRED);
      }

      const assetValidation = validateAssetSupport(
        params.assetId,
        supportedRoutes,
      );
      if (!assetValidation.isValid) {
        this.#deps.debugLogger.log(
          '❌ HyperLiquidProvider: ASSET NOT SUPPORTED',
          {
            error: assetValidation.error,
            assetId: params.assetId,
            supportedAssets: supportedRoutes.map((route) => route.assetId),
          },
        );
        throw new Error(assetValidation.error);
      }
      this.#deps.debugLogger.log('HyperLiquidProvider: ASSET SUPPORTED', {
        assetId: params.assetId,
      });

      // Step 3: Determine destination address
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: DETERMINING DESTINATION ADDRESS',
      );
      let destination: Hex;
      if (params.destination) {
        destination = params.destination;
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: USING PROVIDED DESTINATION',
          {
            destination,
          },
        );
      } else {
        destination = await this.#walletService.getUserAddressWithDefault();
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: USING USER WALLET ADDRESS',
          {
            destination,
          },
        );
      }

      // Step 4: Ensure client is ready
      this.#deps.debugLogger.log('HyperLiquidProvider: ENSURING CLIENT READY');
      await this.#ensureReady();
      await this.#ensureUnifiedAccountEnabled({ allowUserSigning: true });
      const exchangeClient = this.#clientService.getExchangeClient();
      this.#deps.debugLogger.log('HyperLiquidProvider: CLIENT READY');

      // Step 5: Validate amount against account balance
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: CHECKING ACCOUNT BALANCE',
      );
      const accountState = await this.getAccountState();
      const withdrawableBalance = parseFloat(accountState.withdrawableBalance);
      this.#deps.debugLogger.log('HyperLiquidProvider: ACCOUNT BALANCE', {
        withdrawableBalance,
        spendableBalance: accountState.spendableBalance,
        totalBalance: accountState.totalBalance,
        marginUsed: accountState.marginUsed,
        unrealizedPnl: accountState.unrealizedPnl,
      });

      // This check is already done in validateWithdrawalParams, but TypeScript needs explicit check
      if (!params.amount) {
        this.#deps.debugLogger.log('HyperLiquidProvider: MISSING AMOUNT', {
          error: PERPS_ERROR_CODES.WITHDRAW_AMOUNT_REQUIRED,
          params,
        });
        throw new Error(PERPS_ERROR_CODES.WITHDRAW_AMOUNT_REQUIRED);
      }

      const withdrawAmount = parseFloat(params.amount);
      this.#deps.debugLogger.log('HyperLiquidProvider: WITHDRAWAL AMOUNT', {
        requestedAmount: withdrawAmount,
        withdrawableBalance,
        sufficientBalance: withdrawAmount <= withdrawableBalance,
      });

      // Validate against withdrawableBalance — the mode-aware cap.
      // No spot sweep: withdrawableBalance already reflects what withdraw3
      // can pull. In Unified mode HL handles cross-wallet internally; in
      // Standard mode spot is not withdrawable via perps.
      const balanceValidation = validateBalance(
        withdrawAmount,
        withdrawableBalance,
      );
      if (!balanceValidation.isValid) {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: INSUFFICIENT BALANCE',
          {
            error: balanceValidation.error,
            requestedAmount: withdrawAmount,
            withdrawableBalance,
            difference: withdrawAmount - withdrawableBalance,
          },
        );
        throw new Error(balanceValidation.error);
      }
      this.#deps.debugLogger.log('✅ HyperLiquidProvider: BALANCE SUFFICIENT');

      // Step 6: Execute withdrawal via HyperLiquid SDK (API call)
      this.#deps.debugLogger.log('HyperLiquidProvider: CALLING WITHDRAW3 API', {
        destination,
        amount: params.amount,
        endpoint: 'withdraw3',
        timestamp: new Date().toISOString(),
      });

      const result = await exchangeClient.withdraw3({
        destination,
        amount: params.amount,
      });

      this.#deps.debugLogger.log(
        'HyperLiquidProvider: WITHDRAW3 API RESPONSE',
        {
          status: result.status,
          response: result,
          timestamp: new Date().toISOString(),
        },
      );

      if (result.status === 'ok') {
        this.#deps.debugLogger.log(
          'HyperLiquidProvider: WITHDRAWAL SUBMITTED SUCCESSFULLY',
          {
            destination,
            amount: params.amount,
            assetId: params.assetId,
            status: result.status,
          },
        );

        const now = Date.now();
        const withdrawalId = `hl_${uuidv4()}`;

        return {
          success: true,
          withdrawalId,
          estimatedArrivalTime: now + 5 * 60 * 1000, // HyperLiquid typically takes ~5 minutes
          // Don't set txHash if we don't have a real transaction hash
          // HyperLiquid's withdraw3 API doesn't return a transaction hash immediately
        };
      }

      const errorMessage = `Withdrawal failed: ${String(result.status)}`;
      this.#deps.debugLogger.log('HyperLiquidProvider: WITHDRAWAL FAILED', {
        error: errorMessage,
        status: result.status,
        response: result,
        params,
      });
      return {
        success: false,
        error: errorMessage,
      };
    } catch (error) {
      const safeError = ensureError(
        error,
        'HyperLiquidProvider.initiateWithdrawal',
      );
      this.#deps.debugLogger.log('HyperLiquidProvider: WITHDRAWAL EXCEPTION', {
        error: safeError.message,
        errorType: safeError.name,
        stack: safeError.stack,
        params,
        timestamp: new Date().toISOString(),
      });
      this.#deps.logger.error(
        safeError,
        this.#getErrorContext('withdraw', {
          assetId: params.assetId,
          amount: params.amount,
          destination: params.destination,
        }),
      );
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Transfer USDC collateral between DEXs (main ↔ HIP-3)
   *
   * Verified working on mainnet via Phantom wallet testing (10/15/2025).
   * See docs/perps/HIP-3-IMPLEMENTATION.md for complete transaction flow.
   *
   * @param params - Transfer parameters
   * @param params.sourceDex - Source DEX name ('' = main, 'xyz' = HIP-3)
   * @param params.destinationDex - Destination DEX name ('' = main, 'xyz' = HIP-3)
   * @param params.amount - USDC amount to transfer
   * @returns Transfer result with success status and transaction hash
   * @example
   * // Transfer 10 USDC from main DEX to xyz HIP-3 DEX
   * await transferBetweenDexs({
   *   sourceDex: '',
   *   destinationDex: 'xyz',
   *   amount: '10'
   * });
   */
  async transferBetweenDexs(
    params: TransferBetweenDexsParams,
  ): Promise<TransferBetweenDexsResult> {
    try {
      this.#deps.debugLogger.log('HyperLiquidProvider: STARTING DEX TRANSFER', {
        params,
        timestamp: new Date().toISOString(),
      });

      // Validate parameters
      if (!params.amount || parseFloat(params.amount) <= 0) {
        throw new Error('Transfer amount must be greater than 0');
      }

      if (params.sourceDex === params.destinationDex) {
        throw new Error('Source and destination DEX must be different');
      }

      // Get user address
      const userAddress = await this.#walletService.getUserAddressWithDefault();
      this.#deps.debugLogger.log('HyperLiquidProvider: USER ADDRESS', {
        userAddress,
      });

      // Ensure client ready
      await this.#ensureReady();
      const exchangeClient = this.#clientService.getExchangeClient();

      // Execute transfer using SDK sendAsset()
      // Note: SDK docs say "testnet-only" but it works on mainnet (verified via Phantom)
      this.#deps.debugLogger.log(
        'HyperLiquidProvider: CALLING SEND_ASSET API',
        {
          sourceDex: params.sourceDex || '(main)',
          destinationDex: params.destinationDex || '(main)',
          amount: params.amount,
        },
      );

      const result = await exchangeClient.sendAsset({
        destination: userAddress,
        sourceDex: params.sourceDex,
        destinationDex: params.destinationDex,
        token: await this.#getUsdcTokenId(), // Query correct USDC token ID dynamically
        amount: params.amount,
      });

      this.#deps.debugLogger.log('HyperLiquidProvider: SEND_ASSET RESPONSE', {
        status: result.status,
        timestamp: new Date().toISOString(),
      });

      if (result.status === 'ok') {
        this.#deps.debugLogger.log(
          '✅ HyperLiquidProvider: TRANSFER SUCCESSFUL',
        );
        return {
          success: true,
          // Note: sendAsset doesn't return txHash in response
          // User can verify transfer in explorer by timestamp
        };
      }

      throw new Error(PERPS_ERROR_CODES.TRANSFER_FAILED);
    } catch (error) {
      const safeError = ensureError(
        error,
        'HyperLiquidProvider.transferToSpot',
      );
      this.#deps.debugLogger.log('❌ HyperLiquidProvider: TRANSFER FAILED', {
        error: safeError.message,
        params,
      });
      this.#deps.logger.error(
        safeError,
        this.#getErrorContext('transferBetweenDexs', { ...params }),
      );
      return {
        success: false,
        error: safeError.message,
      };
    }
  }

  /**
   * Subscribe to live price updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToPrices(params: SubscribePricesParams): () => void {
    // Handle async subscription service by immediately returning cleanup function
    // The subscription service will load correct funding rates before any callbacks
    let unsubscribe: (() => void) | undefined;
    let cancelled = false;

    this.#subscriptionService
      .subscribeToPrices(params)
      .then((unsub) => {
        // If cleanup was called before subscription completed, immediately unsubscribe
        if (cancelled) {
          unsub();
        } else {
          unsubscribe = unsub;
        }
        return undefined;
      })
      .catch((error) => {
        this.#deps.logger.error(
          ensureError(error, 'HyperLiquidProvider.subscribeToPrices'),
          this.#getErrorContext('subscribeToPrices', {
            symbols: params.symbols,
          }),
        );
        return undefined;
      });

    return () => {
      cancelled = true;
      if (unsubscribe) {
        unsubscribe();
      }
    };
  }

  /**
   * Subscribe to live position updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToPositions(params: SubscribePositionsParams): () => void {
    return this.#subscriptionService.subscribeToPositions(params);
  }

  /**
   * Subscribe to live order fill updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToOrderFills(params: SubscribeOrderFillsParams): () => void {
    return this.#subscriptionService.subscribeToOrderFills(params);
  }

  /**
   * Subscribe to live order updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToOrders(params: SubscribeOrdersParams): () => void {
    return this.#subscriptionService.subscribeToOrders(params);
  }

  /**
   * Subscribe to live account updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToAccount(params: SubscribeAccountParams): () => void {
    return this.#subscriptionService.subscribeToAccount(params);
  }

  /**
   * Subscribe to open interest cap updates
   * Zero additional overhead - data extracted from existing webData2 subscription
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToOICaps(params: SubscribeOICapsParams): () => void {
    return this.#subscriptionService.subscribeToOICaps(params);
  }

  /**
   * 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 {
    return this.#subscriptionService.subscribeToOrderBook(params);
  }

  /**
   * Subscribe to live candle updates
   *
   * @param params - The operation parameters.
   * @returns A cleanup function to remove the subscription.
   */
  subscribeToCandles(params: SubscribeCandlesParams): () => void {
    return this.#clientService.subscribeToCandles(params);
  }

  /**
   * Configure live data settings
   *
   * @param config - The configuration object.
   */
  setLiveDataConfig(config: Partial<LiveDataConfig>): void {
    this.#deps.debugLogger.log('Live data config updated:', config);
  }

  /**
   * Toggle testnet mode
   *
   * @returns A promise that resolves to the result.
   */
  async toggleTestnet(): Promise<ToggleTestnetResult> {
    try {
      const newIsTestnet = !this.#clientService.isTestnetMode();

      // Await pending initialization to prevent race condition where
      // the IIFE sets clientsInitialized = true after we reset it
      const pendingInit = this.#initializationPromise;
      this.#initializationPromise = null;

      if (pendingInit) {
        try {
          await pendingInit;
        } catch {
          // Ignore - we're switching networks anyway
        }
      }

      // Update all services
      this.#clientService.setTestnetMode(newIsTestnet);
      this.#walletService.setTestnetMode(newIsTestnet);

      // Reset initialization flag so clients will be recreated on next use
      this.#clientsInitialized = false;

      return {
        success: true,
        isTestnet: newIsTestnet,
      };
    } catch (error) {
      return createErrorResult(error, {
        success: false,
        isTestnet: this.#clientService.isTestnetMode(),
      });
    }
  }

  /**
   * Initialize provider (ensures clients are ready)
   *
   * @returns A promise that resolves to the result.
   */
  async initialize(): Promise<InitializeResult> {
    try {
      // Ensure clients are initialized (lazy initialization)
      await this.#ensureClientsInitialized();
      return {
        success: true,
        chainId: getChainId(this.#clientService.isTestnetMode()),
      };
    } catch (error) {
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Check if ready to trade
   *
   * @returns A promise that resolves to the result.
   */
  async isReadyToTrade(): Promise<ReadyToTradeResult> {
    try {
      const exchangeClient = this.#clientService.getExchangeClient();
      const infoClient = this.#clientService.getInfoClient();
      const walletConnected = Boolean(exchangeClient) && Boolean(infoClient);

      let accountConnected = false;
      try {
        await this.#walletService.getCurrentAccountId();
        accountConnected = true;
      } catch (error) {
        this.#deps.debugLogger.log('Account not connected:', error);
        accountConnected = false;
      }

      const ready = walletConnected && accountConnected;

      return {
        ready,
        walletConnected,
        networkSupported: true,
      };
    } catch (error) {
      return {
        ready: false,
        walletConnected: false,
        networkSupported: false,
        error:
          error instanceof Error
            ? error.message
            : PERPS_ERROR_CODES.UNKNOWN_ERROR,
      };
    }
  }

  /**
   * Calculate liquidation price using HyperLiquid's formula
   * Formula: liq_price = price - side * margin_available / position_size / (1 - maintenanceMarginRatio * side)
   * where maintenanceMarginRatio = 1 / MAINTENANCE_LEVERAGE = 1 / (2 * max_leverage)
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the string result.
   */
  async calculateLiquidationPrice(
    params: LiquidationPriceParams,
  ): Promise<string> {
    const { entryPrice, leverage, direction, asset } = params;

    // Validate inputs
    if (
      !isFinite(entryPrice) ||
      !isFinite(leverage) ||
      entryPrice <= 0 ||
      leverage <= 0
    ) {
      return '0.00';
    }

    // Get asset's max leverage to calculate maintenance margin
    let maxLeverage = PERPS_CONSTANTS.DefaultMaxLeverage; // Default fallback
    if (asset) {
      try {
        maxLeverage = await this.getMaxLeverage(asset);
      } catch (error) {
        this.#deps.debugLogger.log(
          'Failed to get max leverage for asset, using default',
          {
            asset,
            error,
          },
        );
        // Use default if we can't fetch the asset's max leverage
      }
    }

    // Calculate maintenance leverage and margin according to HyperLiquid docs
    const maintenanceLeverage = 2 * maxLeverage;
    const maintenanceMarginRatio = 1 / maintenanceLeverage;
    const side = direction === 'long' ? 1 : -1;

    // For isolated margin, we use the standard formula
    // margin_available = initial_margin - maintenance_margin_required
    const initialMargin = 1 / leverage;
    const maintenanceMargin = 1 / maintenanceLeverage;

    // Check if position can be opened
    if (initialMargin < maintenanceMargin) {
      // Position cannot be opened - leverage exceeds maximum allowed (2 * maxLeverage)
      throw new Error(
        `Invalid leverage: ${leverage}x exceeds maximum allowed leverage of ${maintenanceLeverage}x`,
      );
    }

    try {
      // HyperLiquid liquidation formula
      // For isolated margin: margin_available = isolated_margin - maintenance_margin_required
      const marginAvailable = initialMargin - maintenanceMargin;

      // Simplified calculation when position size is 1 unit
      // liq_price = price - side * margin_available * price / (1 - maintenanceMarginRatio * side)
      const denominator = 1 - maintenanceMarginRatio * side;
      if (Math.abs(denominator) < 0.0001) {
        // Avoid division by very small numbers
        return String(entryPrice);
      }

      const liquidationPrice =
        entryPrice - (side * marginAvailable * entryPrice) / denominator;

      // Ensure liquidation price is non-negative
      return String(Math.max(0, liquidationPrice));
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.calculateLiquidationPrice'),
        this.#getErrorContext('calculateLiquidationPrice', {
          asset: params.asset,
          entryPrice: params.entryPrice,
          leverage: params.leverage,
          direction: params.direction,
        }),
      );
      return '0.00';
    }
  }

  /**
   * Calculate maintenance margin for a specific asset
   * According to HyperLiquid docs: maintenance_margin = 1 / (2 * max_leverage)
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the numeric result.
   */
  async calculateMaintenanceMargin(
    params: MaintenanceMarginParams,
  ): Promise<number> {
    const { asset } = params;

    // Get asset's max leverage
    const maxLeverage = await this.getMaxLeverage(asset);

    // Maintenance margin = 1 / (2 * max_leverage)
    // This varies from 1.25% (for 40x) to 16.7% (for 3x) depending on the asset
    return 1 / (2 * maxLeverage);
  }

  /**
   * 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> {
    try {
      // Check cache first
      const cached = this.#maxLeverageCache.get(asset);
      const now = Date.now();

      if (
        cached &&
        now - cached.timestamp < PERFORMANCE_CONFIG.MaxLeverageCacheDurationMs
      ) {
        return cached.value;
      }

      // Read-only operation: only need client initialization, not full ensureReady()
      // (no DEX abstraction, referral, or builder fee needed for metadata)
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      // Extract DEX name for API calls (main DEX = null)
      const { dex: dexName } = parseAssetName(asset);

      // Get asset info (uses cache to avoid redundant API calls)
      const meta = await this.#getCachedMeta({ dexName });

      // Check if meta and universe exist and is valid
      // This should never happen since getCachedMeta validates, but defensive check
      if (!meta?.universe || !Array.isArray(meta.universe)) {
        this.#deps.logger.error(
          new Error(
            '[HyperLiquidProvider] Invalid meta response in getMaxLeverage',
          ),
          this.#getErrorContext('getMaxLeverage', {
            asset,
            dexName: dexName ?? 'main',
            note: 'Meta or universe not available, using default max leverage',
          }),
        );
        return PERPS_CONSTANTS.DefaultMaxLeverage;
      }

      // asset.name format: "BTC" for main DEX, "xyz:XYZ100" for HIP-3
      const assetInfo = meta.universe.find((univ) => univ.name === asset);
      if (!assetInfo) {
        this.#deps.debugLogger.log(
          `Asset ${asset} not found in universe, using default max leverage`,
        );
        return PERPS_CONSTANTS.DefaultMaxLeverage;
      }

      // Cache the result
      this.#maxLeverageCache.set(asset, {
        value: assetInfo.maxLeverage,
        timestamp: now,
      });

      return assetInfo.maxLeverage;
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getMaxLeverage'),
        this.#getErrorContext('getMaxLeverage', {
          asset,
        }),
      );
      return PERPS_CONSTANTS.DefaultMaxLeverage;
    }
  }

  /**
   * Calculate fees based on HyperLiquid's fee structure
   * Returns fee rate as decimal (e.g., 0.00045 for 0.045%)
   *
   * Uses the SDK's userFees API to get actual discounted rates when available,
   * falling back to base rates if the API is unavailable or user not connected.
   *
   * @param params - The operation parameters.
   * @returns A promise that resolves to the result.
   */
  async calculateFees(
    params: FeeCalculationParams,
  ): Promise<FeeCalculationResult> {
    const { orderType, isMaker = false, amount, symbol } = params;

    // Start with base rates from config
    let feeRate =
      orderType === 'market' || !isMaker ? FEE_RATES.taker : FEE_RATES.maker;

    // Parse symbol to detect HIP-3 DEX (e.g., "xyz:TSLA" → dex="xyz", parsedSymbol="TSLA")
    const { dex, symbol: parsedSymbol } = parseAssetName(symbol);
    const isHip3Asset = dex !== null;

    // Calculate HIP-3 fee multiplier dynamically (handles Growth Mode)
    let hip3Multiplier = 1;
    if (isHip3Asset && dex && parsedSymbol) {
      hip3Multiplier = await this.#calculateHip3FeeMultiplier({
        dexName: dex,
        assetSymbol: parsedSymbol,
      });
      const originalRate = feeRate;
      feeRate *= hip3Multiplier;

      this.#deps.debugLogger.log('HIP-3 Dynamic Fee Multiplier Applied', {
        symbol,
        dex,
        parsedSymbol,
        originalBaseRate: originalRate,
        hip3BaseRate: feeRate,
        hip3Multiplier,
      });
    }

    this.#deps.debugLogger.log('HyperLiquid Fee Calculation Started', {
      orderType,
      isMaker,
      amount,
      symbol,
      isHip3Asset,
      hip3Multiplier,
      baseFeeRate: feeRate,
      baseTakerRate: FEE_RATES.taker,
      baseMakerRate: FEE_RATES.maker,
    });

    // Try to get user-specific rates if wallet is connected
    try {
      const userAddress = await this.#walletService.getUserAddressWithDefault();

      this.#deps.debugLogger.log('User Address Retrieved', {
        userAddress,
        network: this.#clientService.isTestnetMode() ? 'testnet' : 'mainnet',
      });

      // Check cache first
      if (this.#isFeeCacheValid(userAddress)) {
        const cached = this.#userFeeCache.get(userAddress);
        if (cached) {
          // Market orders always use taker rate, limit orders check isMaker
          let userFeeRate =
            orderType === 'market' || !isMaker
              ? cached.perpsTakerRate
              : cached.perpsMakerRate;

          // Apply HIP-3 dynamic multiplier to user-specific rates (includes Growth Mode)
          if (isHip3Asset && hip3Multiplier > 0) {
            userFeeRate *= hip3Multiplier;
          }

          feeRate = userFeeRate;

          this.#deps.debugLogger.log('📦 Using Cached Fee Rates', {
            cacheHit: true,
            perpsTakerRate: cached.perpsTakerRate,
            perpsMakerRate: cached.perpsMakerRate,
            spotTakerRate: cached.spotTakerRate,
            spotMakerRate: cached.spotMakerRate,
            selectedRate: feeRate,
            isHip3Asset,
            hip3Multiplier,
            cacheExpiry: new Date(cached.timestamp + cached.ttl).toISOString(),
            cacheAge: `${Math.round((Date.now() - cached.timestamp) / 1000)}s`,
          });
        }
      } else {
        this.#deps.debugLogger.log(
          'Fetching Fresh Fee Rates from HyperLiquid API',
          {
            cacheHit: false,
            userAddress,
          },
        );

        // Fetch fresh rates from SDK
        // Read-only operation: only need client initialization
        await this.#ensureClientsInitialized();
        this.#clientService.ensureInitialized();
        const infoClient = this.#clientService.getInfoClient();
        const userFees = await infoClient.userFees({
          user: userAddress,
        });

        this.#deps.debugLogger.log('HyperLiquid userFees API Response', {
          userCrossRate: userFees.userCrossRate,
          userAddRate: userFees.userAddRate,
          activeReferralDiscount: userFees.activeReferralDiscount,
          activeStakingDiscount: userFees.activeStakingDiscount,
        });

        // Parse base user rates (these don't include discounts as expected)
        const baseUserTakerRate = parseFloat(userFees.userCrossRate);
        const baseUserMakerRate = parseFloat(userFees.userAddRate);
        const baseUserSpotTakerRate = parseFloat(userFees.userSpotCrossRate);
        const baseUserSpotMakerRate = parseFloat(userFees.userSpotAddRate);

        // Apply discounts manually since HyperLiquid API doesn't apply them
        const referralDiscount = parseFloat(
          userFees.activeReferralDiscount || '0',
        );
        const stakingDiscount = parseFloat(
          userFees.activeStakingDiscount?.discount || '0',
        );

        // Calculate total discount (referral + staking, but not compounding)
        const totalDiscount = Math.min(referralDiscount + stakingDiscount, 0.4); // Cap at 40%

        // Apply discount to rates
        const perpsTakerRate = baseUserTakerRate * (1 - totalDiscount);
        const perpsMakerRate = baseUserMakerRate * (1 - totalDiscount);
        const spotTakerRate = baseUserSpotTakerRate * (1 - totalDiscount);
        const spotMakerRate = baseUserSpotMakerRate * (1 - totalDiscount);

        this.#deps.debugLogger.log('Fee Discount Calculation', {
          discounts: {
            referral: `${(referralDiscount * 100).toFixed(1)}%`,
            staking: `${(stakingDiscount * 100).toFixed(1)}%`,
            total: `${(totalDiscount * 100).toFixed(1)}%`,
          },
          rates: {
            before: {
              taker: `${(baseUserTakerRate * 100).toFixed(4)}%`,
              maker: `${(baseUserMakerRate * 100).toFixed(4)}%`,
            },
            after: {
              taker: `${(perpsTakerRate * 100).toFixed(4)}%`,
              maker: `${(perpsMakerRate * 100).toFixed(4)}%`,
            },
          },
        });

        // Validate all rates are valid numbers before caching
        if (
          isNaN(perpsTakerRate) ||
          isNaN(perpsMakerRate) ||
          isNaN(spotTakerRate) ||
          isNaN(spotMakerRate) ||
          perpsTakerRate < 0 ||
          perpsMakerRate < 0 ||
          spotTakerRate < 0 ||
          spotMakerRate < 0
        ) {
          this.#deps.debugLogger.log('Fee Rate Validation Failed', {
            validation: {
              perpsTakerValid: !isNaN(perpsTakerRate) && perpsTakerRate >= 0,
              perpsMakerValid: !isNaN(perpsMakerRate) && perpsMakerRate >= 0,
              spotTakerValid: !isNaN(spotTakerRate) && spotTakerRate >= 0,
              spotMakerValid: !isNaN(spotMakerRate) && spotMakerRate >= 0,
            },
            rawValues: {
              perpsTakerRate,
              perpsMakerRate,
              spotTakerRate,
              spotMakerRate,
            },
          });
          throw new Error('Invalid fee rates received from API');
        }

        const rates = {
          perpsTakerRate,
          perpsMakerRate,
          spotTakerRate,
          spotMakerRate,
          timestamp: Date.now(),
          ttl: 5 * 60 * 1000, // 5 minutes
        };

        this.#userFeeCache.set(userAddress, rates);
        // Market orders always use taker rate, limit orders check isMaker
        let userFeeRate =
          orderType === 'market' || !isMaker
            ? rates.perpsTakerRate
            : rates.perpsMakerRate;

        // Apply HIP-3 dynamic multiplier to API-fetched rates (includes Growth Mode)
        if (isHip3Asset && hip3Multiplier > 0) {
          userFeeRate *= hip3Multiplier;
        }

        feeRate = userFeeRate;

        this.#deps.debugLogger.log('Fee Rates Validated and Cached', {
          selectedRate: feeRate,
          selectedRatePercentage: `${(feeRate * 100).toFixed(4)}%`,
          discountApplied: perpsTakerRate < FEE_RATES.taker,
          isHip3Asset,
          hip3Multiplier,
          cacheExpiry: new Date(rates.timestamp + rates.ttl).toISOString(),
        });
      }
    } catch (error) {
      // Silently fall back to base rates
      const safeError = ensureError(
        error,
        'HyperLiquidProvider.getFeeSchedule',
      );
      this.#deps.debugLogger.log(
        'Fee API Call Failed - Falling Back to Base Rates',
        {
          error: safeError.message,
          errorType: safeError.name,
          fallbackTakerRate: FEE_RATES.taker,
          fallbackMakerRate: FEE_RATES.maker,
          userAddress: 'unknown',
        },
      );
    }

    const parsedAmount = amount ? parseFloat(amount) : 0;

    // Protocol base fee (HyperLiquid's fee)
    const protocolFeeRate = feeRate;
    let protocolFeeAmount: number | undefined;
    if (amount === undefined) {
      protocolFeeAmount = undefined;
    } else if (isNaN(parsedAmount)) {
      protocolFeeAmount = 0;
    } else {
      protocolFeeAmount = parsedAmount * protocolFeeRate;
    }

    // MetaMask builder fee (0.1% = 0.001) with optional reward discount
    let metamaskFeeRate = BUILDER_FEE_CONFIG.MaxFeeDecimal;

    // Apply MetaMask reward discount if active
    if (this.#userFeeDiscountBips !== undefined) {
      const discount = this.#userFeeDiscountBips / BASIS_POINTS_DIVISOR; // Convert basis points to decimal
      metamaskFeeRate = BUILDER_FEE_CONFIG.MaxFeeDecimal * (1 - discount);

      this.#deps.debugLogger.log('HyperLiquid: Applied MetaMask fee discount', {
        originalRate: BUILDER_FEE_CONFIG.MaxFeeDecimal,
        discountBips: this.#userFeeDiscountBips,
        discountPercentage: this.#userFeeDiscountBips / 100,
        adjustedRate: metamaskFeeRate,
        discountAmount: BUILDER_FEE_CONFIG.MaxFeeDecimal * discount,
      });
    }

    const validAmountForMetamaskFee = isNaN(parsedAmount)
      ? 0
      : parsedAmount * metamaskFeeRate;
    const metamaskFeeAmount =
      amount === undefined ? undefined : validAmountForMetamaskFee;

    // Total fees
    const totalFeeRate = protocolFeeRate + metamaskFeeRate;
    const validAmountForTotalFee = isNaN(parsedAmount)
      ? 0
      : parsedAmount * totalFeeRate;
    const totalFeeAmount =
      amount === undefined ? undefined : validAmountForTotalFee;

    const result = {
      // Total fees
      feeRate: totalFeeRate,
      feeAmount: totalFeeAmount,

      // Protocol fees
      protocolFeeRate,
      protocolFeeAmount,

      // MetaMask fees
      metamaskFeeRate,
      metamaskFeeAmount,
    };

    this.#deps.debugLogger.log('Final Fee Calculation Result', {
      orderType,
      amount,
      fees: {
        protocolRate: `${(protocolFeeRate * 100).toFixed(4)}%`,
        metamaskRate: `${(metamaskFeeRate * 100).toFixed(4)}%`,
        totalRate: `${(totalFeeRate * 100).toFixed(4)}%`,
        totalAmount: totalFeeAmount,
      },
      usingFallbackRates:
        protocolFeeRate === FEE_RATES.taker ||
        protocolFeeRate === FEE_RATES.maker,
    });

    return result;
  }

  /**
   * Check if the fee cache is valid for a user
   *
   * @param userAddress - The user's wallet address.
   * @private
   * @returns True if the condition is met.
   */
  #isFeeCacheValid(userAddress: string): boolean {
    const cached = this.#userFeeCache.get(userAddress);
    if (!cached) {
      return false;
    }
    return Date.now() - cached.timestamp < cached.ttl;
  }

  /**
   * Clear fee cache for a specific user or all users
   *
   * @param userAddress - Optional address to clear cache for
   */
  public clearFeeCache(userAddress?: string): void {
    if (userAddress) {
      this.#userFeeCache.delete(userAddress);
      this.#deps.debugLogger.log('Cleared fee cache for user', { userAddress });
    } else {
      this.#userFeeCache.clear();
      this.#deps.debugLogger.log('Cleared all fee cache');
    }
  }

  /**
   * Escape hatch for agentic validation flows and test harnesses that drive
   * HL mutations directly. NOT part of the PerpsProvider interface.
   * Production code paths must go through the provider's own methods.
   *
   * @returns A promise resolving to the underlying HyperLiquid SDK
   * ExchangeClient. Promise shape matches the existing agentic flows
   * (hl-provision-fixture) that chain `.then` on the result.
   */
  public async getExchangeClient(): Promise<ExchangeClient> {
    return this.#clientService.getExchangeClient();
  }

  /**
   * Disconnect provider
   *
   * @returns A promise that resolves to the result.
   */
  async disconnect(): Promise<DisconnectResult> {
    try {
      this.#deps.debugLogger.log('HyperLiquid: Disconnecting provider', {
        isTestnet: this.#clientService.isTestnetMode(),
        timestamp: new Date().toISOString(),
      });

      // Clear subscriptions through subscription service
      this.#subscriptionService.clearAll();

      // Clear fee cache
      this.clearFeeCache();

      // Clear session caches (ensures fresh state on reconnect/account switch)
      this.#referralCheckCache.clear();
      this.#builderFeeCheckCache.clear();
      // NOTE: UnifiedAccountCache is global and NOT cleared on disconnect
      // to prevent repeated signing requests across reconnections
      this.#cachedMetaByDex.clear();
      this.#cachedSpotMeta = null;
      this.#dexDiscoveryCache.reset();
      this.#dexDiscoveryComplete = false;

      // Await pending initialization before clearing to prevent the IIFE from
      // setting clientsInitialized = true after disconnect completes
      const pendingInit = this.#initializationPromise;
      const pendingReady = this.#ensureReadyPromise;
      const pendingTradingSetup = this.#tradingSetupPromise;

      // Clear references first to prevent new callers from reusing
      this.#initializationPromise = null;
      this.#ensureReadyPromise = null;
      this.#tradingSetupPromise = null;
      this.#tradingSetupComplete = false;
      this.#pendingBuilderFeeApprovals.clear();

      // Wait for pending operations to complete (ignore errors)
      // This prevents IIFEs from setting state after disconnect completes
      if (pendingInit) {
        try {
          await pendingInit;
        } catch {
          // Ignore - we're disconnecting anyway
        }
      }
      if (pendingReady) {
        try {
          await pendingReady;
        } catch {
          // Ignore - we're disconnecting anyway
        }
      }

      if (pendingTradingSetup) {
        try {
          await pendingTradingSetup;
        } catch {
          // Ignore - we're disconnecting anyway
        }
      }

      // Reset client initialization flag so wallet adapter will be recreated with new account
      // This fixes account synchronization issue where old account's address persists in wallet adapter
      this.#clientsInitialized = false;

      // Disconnect client service
      await this.#clientService.disconnect();

      this.#deps.debugLogger.log('HyperLiquid: Provider fully disconnected', {
        timestamp: new Date().toISOString(),
      });

      return { success: true };
    } catch (error) {
      return createErrorResult(error, { success: false });
    }
  }

  /**
   * Lightweight WebSocket health check using SDK's built-in ready() method
   * Checks if WebSocket connection is open without making expensive API calls
   *
   * @param timeoutMs - Optional timeout in milliseconds (defaults to WEBSOCKET_PING_TIMEOUT_MS)
   * @throws {Error} If WebSocket connection times out or fails
   */
  async ping(timeoutMs?: number): Promise<void> {
    // Read-only operation: only need client initialization
    await this.#ensureClientsInitialized();
    this.#clientService.ensureInitialized();

    const subscriptionClient = this.#clientService.getSubscriptionClient();
    if (!subscriptionClient) {
      throw new Error('Subscription client not initialized');
    }

    const timeout = timeoutMs ?? PERPS_CONSTANTS.WebsocketPingTimeoutMs;

    this.#deps.debugLogger.log(
      `HyperLiquid: WebSocket health check ping starting (timeout: ${timeout}ms)`,
    );

    const controller = new AbortController();
    let didTimeout = false;

    const timeoutId = setTimeout(() => {
      didTimeout = true;
      controller.abort();
    }, timeout);

    try {
      // Use SDK's built-in ready() method which checks socket.readyState === OPEN
      // This is much more efficient than creating a subscription just for health check
      await subscriptionClient.config_.transport.ready(controller.signal);

      this.#deps.debugLogger.log(
        'HyperLiquid: WebSocket health check ping succeeded',
      );
    } catch (error) {
      // Check if we timed out first
      if (didTimeout) {
        this.#deps.debugLogger.log(
          `HyperLiquid: WebSocket health check ping timed out after ${timeout}ms`,
        );
        throw new Error(PERPS_ERROR_CODES.CONNECTION_TIMEOUT);
      }

      // Otherwise throw the actual error
      this.#deps.debugLogger.log(
        'HyperLiquid: WebSocket health check ping failed',
        error,
      );
      throw ensureError(error, 'HyperLiquidProvider.ping');
    } finally {
      clearTimeout(timeoutId);
    }
  }

  /**
   * Get the current WebSocket connection state from the client service.
   * Used by the UI to monitor connection health and show notifications.
   *
   * @returns The current WebSocket connection state
   */
  getWebSocketConnectionState(): WebSocketConnectionState {
    return this.#clientService.getConnectionState();
  }

  /**
   * Subscribe to WebSocket connection state changes.
   * The listener will be called immediately with the current state and whenever the state changes.
   *
   * @param listener - Callback function that receives the new connection state and reconnection attempt
   * @returns Unsubscribe function to remove the listener
   */
  subscribeToConnectionState(
    listener: (
      state: WebSocketConnectionState,
      reconnectionAttempt: number,
    ) => void,
  ): () => void {
    return this.#clientService.subscribeToConnectionState(listener);
  }

  /**
   * Manually trigger a WebSocket reconnection attempt.
   * Used by the UI retry button when connection is lost.
   *
   * @returns A promise that resolves when the operation completes.
   */
  async reconnect(): Promise<void> {
    return this.#clientService.reconnect();
  }

  /**
   * Get list of available HIP-3 builder-deployed DEXs
   *
   * @param _params - Optional parameters (reserved for future filters/pagination)
   * @returns Array of DEX names (empty string '' represents main DEX)
   */
  async getAvailableDexs(_params?: GetAvailableDexsParams): Promise<string[]> {
    try {
      // Read-only operation: only need client initialization
      await this.#ensureClientsInitialized();
      this.#clientService.ensureInitialized();

      const infoClient = this.#clientService.getInfoClient();
      const dexs = await infoClient.perpDexs();

      // Map DEX objects to names: null -> '' (main DEX), object -> object.name
      return dexs.map((dex) => (dex === null ? '' : dex.name));
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.getAvailableDexs'),
        {
          context: {
            name: 'HyperLiquidProvider.getAvailableDexs',
            data: { action: 'fetch_available_dexs' },
          },
        },
      );
      throw error;
    }
  }

  async fetchHistoricalCandles(options: {
    symbol: string;
    interval: CandlePeriod;
    limit?: number;
    endTime?: number;
  }): Promise<CandleData> {
    this.#clientService.ensureInitialized();
    const result = await this.#clientService.fetchHistoricalCandles(options);
    return (
      result ?? {
        symbol: options.symbol,
        interval: options.interval,
        candles: [],
      }
    );
  }

  /**
   * 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 network = this.#clientService.isTestnetMode() ? 'testnet' : 'mainnet';
    const baseUrl =
      network === 'testnet'
        ? 'https://app.hyperliquid-testnet.xyz'
        : 'https://app.hyperliquid.xyz';

    if (address) {
      return `${baseUrl}/explorer/address/${address}`;
    }

    return `${baseUrl}/explorer`;
  }

  #getBuilderAddress(isTestnet: boolean): string {
    // || intentional: env vars default to '' which must fall through to the hardcoded default
    if (isTestnet) {
      // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
      return this.#builderAddressTestnet || BUILDER_FEE_CONFIG.TestnetBuilder;
    }
    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
    return this.#builderAddressMainnet || BUILDER_FEE_CONFIG.MainnetBuilder;
  }

  #getReferralCode(isTestnet: boolean): string {
    return isTestnet
      ? REFERRAL_CONFIG.TestnetCode
      : REFERRAL_CONFIG.MainnetCode;
  }

  /**
   * Ensure user has a MetaMask referral code set
   * Called once during initialization (ensureReady) to set up referral for the session
   * Uses GLOBAL cache to persist across provider reconnections
   * This prevents repeated signing requests for hardware wallets.
   *
   * Note: This is network-specific - testnet and mainnet have separate referral states
   * Note: Non-blocking - failures are logged to Sentry but don't prevent trading
   */
  async #ensureReferralSet(): Promise<void> {
    const isTestnet = this.#clientService.isTestnetMode();
    const network = isTestnet ? 'testnet' : 'mainnet';
    const expectedReferralCode = this.#getReferralCode(isTestnet);
    const referrerAddress = this.#getBuilderAddress(isTestnet);

    let userAddress: string;
    try {
      userAddress = await this.#walletService.getUserAddressWithDefault();
    } catch {
      return; // Can't proceed without address
    }

    if (userAddress.toLowerCase() === referrerAddress.toLowerCase()) {
      this.#deps.debugLogger.log(
        '[ensureReferralSet] User is builder, skipping',
        { network },
      );
      return;
    }

    // Check GLOBAL cache first
    const globalCached = PerpsSigningCache.getReferral(network, userAddress);
    if (globalCached?.attempted) {
      this.#deps.debugLogger.log(
        '[ensureReferralSet] Using global cache (prevents QR popup spam)',
        { network, success: globalCached.success },
      );
      return;
    }

    // Check if another provider is currently attempting this
    const inFlightPromise = PerpsSigningCache.isInFlight(
      'referral',
      network,
      userAddress,
    );
    if (inFlightPromise) {
      this.#deps.debugLogger.log(
        '[ensureReferralSet] Global in-flight, waiting...',
        { network },
      );
      await inFlightPromise;
      return;
    }

    // Set global in-flight lock
    const completeInFlight = PerpsSigningCache.setInFlight(
      'referral',
      network,
      userAddress,
    );

    try {
      // Re-check cache after acquiring lock
      const recheckCache = PerpsSigningCache.getReferral(network, userAddress);
      if (recheckCache?.attempted) {
        this.#deps.debugLogger.log(
          '[ensureReferralSet] Completed by another provider',
          { network },
        );
        completeInFlight();
        return;
      }

      const isReady = await this.#isReferralCodeReady();
      if (!isReady) {
        this.#deps.debugLogger.log(
          '[ensureReferralSet] Builder referral not ready, skipping',
          { network },
        );
        completeInFlight();
        return; // Don't cache - retry when ready
      }

      // Check if user already has a referral on-chain
      const hasReferral = await this.#checkReferralSet();

      if (hasReferral) {
        // Already has referral on-chain
        PerpsSigningCache.setReferral(network, userAddress, {
          attempted: true,
          success: true,
        });
        this.#deps.debugLogger.log(
          '[ensureReferralSet] Already has referral on-chain',
          { network },
        );
      } else {
        this.#deps.debugLogger.log(
          '[ensureReferralSet] Setting referral (will show signing request)',
          { network, referralCode: expectedReferralCode },
        );
        const result = await this.#setReferralCode();
        if (result) {
          this.#deps.debugLogger.log(
            '[ensureReferralSet] Referral set successfully',
            { network },
          );
          PerpsSigningCache.setReferral(network, userAddress, {
            attempted: true,
            success: true,
          });
        } else {
          PerpsSigningCache.setReferral(network, userAddress, {
            attempted: true,
            success: false,
          });
          this.#deps.debugLogger.log(
            '[ensureReferralSet] Failed, cached to prevent retries',
            { network },
          );
        }
      }
      completeInFlight();
    } catch (error) {
      // If keyring is locked, don't cache so it retries when unlocked
      if (ensureError(error).message === PERPS_ERROR_CODES.KEYRING_LOCKED) {
        this.#deps.debugLogger.log(
          '[ensureReferralSet] Keyring locked, will retry later',
        );
        completeInFlight();
        return;
      }

      // Cache failure to prevent retries
      PerpsSigningCache.setReferral(network, userAddress, {
        attempted: true,
        success: false,
      });
      this.#deps.debugLogger.log(
        '[ensureReferralSet] Error, cached to prevent retries',
        {
          network,
          error: ensureError(error, 'HyperLiquidProvider.ensureReferralSet')
            .message,
        },
      );
      completeInFlight();

      // Non-blocking: Log to Sentry but don't throw
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.ensureReferralSet'),
        this.#getErrorContext('ensureReferralSet', {
          note: 'Referral setup failed (non-blocking), cached to prevent retries',
        }),
      );
    }
  }

  /**
   * Check if the referral code is ready to be used
   *
   * @returns Promise resolving to true if referral code is ready
   */
  async #isReferralCodeReady(): Promise<boolean> {
    try {
      const infoClient = this.#clientService.getInfoClient();
      const isTestnet = this.#clientService.isTestnetMode();
      const code = this.#getReferralCode(isTestnet);
      const referrerAddr = this.#getBuilderAddress(isTestnet);

      const referral = await infoClient.referral({ user: referrerAddr });

      const stage = referral.referrerState?.stage;

      if (stage === 'ready') {
        const onFile = referral.referrerState?.data?.code || '';
        if (onFile.toUpperCase() !== code.toUpperCase()) {
          throw new Error(
            `Ready for referrals but there is a config code mismatch ${onFile} vs ${code}`,
          );
        }
        return true;
      }

      // Not ready yet - log as debugLogger since this is expected during setup phase
      this.#deps.debugLogger.log(
        '[isReferralCodeReady] Referral code not ready',
        {
          stage,
          code,
          referrerAddr,
        },
      );
      return false;
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.isReferralCodeReady'),
        this.#getErrorContext('isReferralCodeReady', {
          code: this.#getReferralCode(this.#clientService.isTestnetMode()),
          referrerAddress: this.#getBuilderAddress(
            this.#clientService.isTestnetMode(),
          ),
        }),
      );
      return false;
    }
  }

  /**
   * Check if user has a referral code set with HyperLiquid
   *
   * @returns Promise resolving to true if referral is set, false otherwise
   */
  async #checkReferralSet(): Promise<boolean> {
    try {
      const infoClient = this.#clientService.getInfoClient();
      const userAddress = await this.#walletService.getUserAddressWithDefault();

      // Call HyperLiquid API to check if user has a referral set
      const referralData = await infoClient.referral({
        user: userAddress,
      });

      this.#deps.debugLogger.log('Referral check result:', {
        userAddress,
        referralData,
      });

      return Boolean(referralData?.referredBy?.code);
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.checkReferralSet'),
        this.#getErrorContext('checkReferralSet', {
          note: 'Error checking referral status, will retry',
        }),
      );
      // do not throw here, return false as we can try to set it again
      return false;
    }
  }

  /**
   * Set MetaMask as the user's referrer on HyperLiquid
   *
   * @returns A promise that resolves to the boolean result.
   */
  async #setReferralCode(): Promise<boolean> {
    try {
      const exchangeClient = this.#clientService.getExchangeClient();
      const referralCode = this.#getReferralCode(
        this.#clientService.isTestnetMode(),
      );

      this.#deps.debugLogger.log('[setReferralCode] Setting referral code', {
        code: referralCode,
        network: this.#clientService.isTestnetMode() ? 'testnet' : 'mainnet',
      });

      // set the referral code
      const result = await exchangeClient.setReferrer({
        code: referralCode,
      });

      this.#deps.debugLogger.log(
        '[setReferralCode] Referral code set result',
        result,
      );

      return result?.status === 'ok';
    } catch (error) {
      this.#deps.logger.error(
        ensureError(error, 'HyperLiquidProvider.setReferralCode'),
        this.#getErrorContext('setReferralCode', {
          code: this.#getReferralCode(this.#clientService.isTestnetMode()),
        }),
      );
      // Rethrow to be caught by retry logic in ensureReferralSet
      throw error;
    }
  }
}