@metamask-previews/perps-controller 16.1.0-preview-abca9bcea → 17.0.0-preview-0a30e47

package/dist/services/DexDiscoveryCacheManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DexDiscoveryCacheManager.js","sourceRoot":"","sources":["../../src/services/DexDiscoveryCacheManager.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  MAINNET_HIP3_CONFIG,\n  TESTNET_HIP3_CONFIG,\n} from '../constants/hyperLiquidConfig.js';\nimport type {\n  DexDiscoveryState,\n  ExtendedPerpDex,\n} from '../types/perps-types.js';\n\ntype DexDiscoveryDeps = {\n  isTestnetMode: () => boolean;\n  debugLogger: { log: (...args: unknown[]) => void };\n  getAllowlistMarkets: () => string[];\n};\n\n/**\n * Manages the unified DEX discovery cache — single source of truth for all perpDexs() derivatives.\n *\n * Extracted from HyperLiquidProvider to isolate cache logic.\n * All writes go through update(); readers use .state.\n */\nexport class DexDiscoveryCacheManager {\n  /**\n   * Unified DEX discovery state.\n   * null = not yet fetched; object = raw + validated + timestamp.\n   */\n  state: DexDiscoveryState | null = null;\n\n  readonly #deps: DexDiscoveryDeps;\n\n  constructor(deps: DexDiscoveryDeps) {\n    this.#deps = deps;\n  }\n\n  /**\n   * Single atomic writer for DEX discovery state.\n   * All code paths that fetch perpDexs() MUST call this — no direct field writes.\n   *\n   * @param allDexs - Raw perpDexs() API response array.\n   * @returns The newly created unified discovery state.\n   */\n  update(allDexs: (ExtendedPerpDex | null)[]): DexDiscoveryState {\n    const validated = this.computeValidatedDexs(allDexs);\n    const newState: DexDiscoveryState = {\n      raw: allDexs,\n      validated,\n      timestamp: Date.now(),\n    };\n    this.state = newState;\n    return newState;\n  }\n\n  /**\n   * Reset state to null (used on disconnect/reconnect).\n   */\n  reset(): void {\n    this.state = null;\n  }\n\n  /**\n   * Pure filtering of perpDexs() response into validated DEX names.\n   * Encapsulates testnet/mainnet feature-flag logic.\n   *\n   * @param allDexs - Raw perpDexs() API response array.\n   * @returns Filtered DEX name list (null = main DEX, strings = HIP-3 DEXs).\n   */\n  computeValidatedDexs(allDexs: (ExtendedPerpDex | null)[]): (string | null)[] {\n    const availableHip3Dexs: string[] = [];\n    allDexs.forEach((dex) => {\n      if (dex !== null) {\n        availableHip3Dexs.push(dex.name);\n      }\n    });\n\n    if (this.#deps.isTestnetMode()) {\n      const { EnabledDexs, AutoDiscoverAll } = TESTNET_HIP3_CONFIG;\n\n      if (!AutoDiscoverAll) {\n        if (EnabledDexs.length === 0) {\n          this.#deps.debugLogger.log(\n            'HyperLiquidProvider: Testnet - using main DEX only (HIP-3 DEXs filtered)',\n            {\n              availableHip3Dexs: availableHip3Dexs.length,\n              reason: 'TESTNET_HIP3_CONFIG.EnabledDexs is empty',\n            },\n          );\n          return [null];\n        }\n\n        const filteredDexs = availableHip3Dexs.filter((dex) =>\n          EnabledDexs.includes(dex),\n        );\n        this.#deps.debugLogger.log(\n          'HyperLiquidProvider: Testnet - filtered to allowed DEXs',\n          {\n            allowedDexs: EnabledDexs,\n            filteredDexs,\n            availableHip3Dexs: availableHip3Dexs.length,\n          },\n        );\n        return [null, ...filteredDexs];\n      }\n\n      this.#deps.debugLogger.log(\n        'HyperLiquidProvider: Testnet - AUTO_DISCOVER_ALL enabled, using all DEXs',\n        { totalDexCount: availableHip3Dexs.length + 1 },\n      );\n    } else {\n      const { AutoDiscoverAll } = MAINNET_HIP3_CONFIG;\n\n      if (!AutoDiscoverAll) {\n        const allowedDexsFromAllowlist = this.extractDexsFromAllowlist();\n\n        if (allowedDexsFromAllowlist.length === 0) {\n          this.#deps.debugLogger.log(\n            'HyperLiquidProvider: Mainnet - using main DEX only (no HIP-3 DEXs in allowlist)',\n            {\n              availableHip3Dexs: availableHip3Dexs.length,\n              allowlistMarkets: this.#deps.getAllowlistMarkets(),\n            },\n          );\n          return [null];\n        }\n\n        const filteredDexs = availableHip3Dexs.filter((dex) =>\n          allowedDexsFromAllowlist.includes(dex),\n        );\n        this.#deps.debugLogger.log(\n          'HyperLiquidProvider: Mainnet - filtered to allowlist DEXs',\n          {\n            allowedDexsFromAllowlist,\n            filteredDexs,\n            availableHip3Dexs: availableHip3Dexs.length,\n          },\n        );\n        return [null, ...filteredDexs];\n      }\n\n      this.#deps.debugLogger.log(\n        'HyperLiquidProvider: Mainnet - AUTO_DISCOVER_ALL enabled, using all DEXs',\n        { totalDexCount: availableHip3Dexs.length + 1 },\n      );\n    }\n\n    this.#deps.debugLogger.log(\n      'HyperLiquidProvider: All DEXs enabled (market filtering at data layer)',\n      {\n        mainDex: true,\n        hip3Dexs: availableHip3Dexs,\n        totalDexCount: availableHip3Dexs.length + 1,\n      },\n    );\n    return [null, ...availableHip3Dexs];\n  }\n\n  /**\n   * Extract unique DEX names from allowlist market patterns.\n   * Patterns can be: \"xyz:*\" (wildcard), \"xyz:TSLA\" (exact), or \"xyz\" (DEX shorthand).\n   *\n   * @returns Array of unique DEX names from the allowlist.\n   */\n  extractDexsFromAllowlist(): string[] {\n    const allowlistMarkets = this.#deps.getAllowlistMarkets();\n    if (allowlistMarkets.length === 0) {\n      return [];\n    }\n\n    const dexNames = new Set<string>();\n\n    for (const pattern of allowlistMarkets) {\n      const colonIndex = pattern.indexOf(':');\n      if (colonIndex > 0) {\n        const dex = pattern.substring(0, colonIndex);\n        dexNames.add(dex);\n      } else if (pattern.length > 0 && !pattern.includes('*')) {\n        if (/^[a-z][a-z0-9]*$/iu.test(pattern)) {\n          dexNames.add(pattern.toLowerCase());\n        }\n      }\n    }\n\n    return Array.from(dexNames);\n  }\n}\n"]}

package/dist/services/EligibilityService.d.ts

@@ -0,0 +1,28 @@
+import type { PerpsPlatformDependencies, CheckEligibilityParams } from '../types/index.js';
+/**
+ * EligibilityService
+ *
+ * Handles eligibility checking based on geolocation and blocked regions.
+ * Geolocation is sourced externally from the GeolocationController.
+ *
+ * Instance-based service with constructor injection of platform dependencies.
+ */
+export declare class EligibilityService {
+    #private;
+    /**
+     * Create a new EligibilityService instance
+     *
+     * @param deps - Platform dependencies for logging, metrics, etc.
+     */
+    constructor(deps: PerpsPlatformDependencies);
+    /**
+     * Check if user is eligible based on geo-blocked regions.
+     *
+     * @param options - The eligibility check parameters.
+     * @param options.blockedRegions - List of blocked region codes (e.g., ['US', 'CN']).
+     * @param options.geoLocation - The user's geolocation string from GeolocationController.
+     * @returns True if eligible (not in blocked region), false otherwise.
+     */
+    checkEligibility(options: CheckEligibilityParams): Promise<boolean>;
+}
+//# sourceMappingURL=EligibilityService.d.ts.map

package/dist/services/EligibilityService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EligibilityService.d.ts","sourceRoot":"","sources":["../../src/services/EligibilityService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;GAOG;AACH,qBAAa,kBAAkB;;IAG7B;;;;OAIG;IACH,YAAY,IAAI,EAAE,yBAAyB,EAE1C;IAED;;;;;;;OAOG;IACG,gBAAgB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CA0CxE;CACF"}

package/dist/services/EligibilityService.js

@@ -0,0 +1,61 @@
+import { PERPS_CONSTANTS } from '../constants/perpsConfig.js';
+import { ensureError } from '../utils/errorUtils.js';
+/**
+ * EligibilityService
+ *
+ * Handles eligibility checking based on geolocation and blocked regions.
+ * Geolocation is sourced externally from the GeolocationController.
+ *
+ * Instance-based service with constructor injection of platform dependencies.
+ */
+export class EligibilityService {
+    #deps;
+    /**
+     * Create a new EligibilityService instance
+     *
+     * @param deps - Platform dependencies for logging, metrics, etc.
+     */
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /**
+     * Check if user is eligible based on geo-blocked regions.
+     *
+     * @param options - The eligibility check parameters.
+     * @param options.blockedRegions - List of blocked region codes (e.g., ['US', 'CN']).
+     * @param options.geoLocation - The user's geolocation string from GeolocationController.
+     * @returns True if eligible (not in blocked region), false otherwise.
+     */
+    async checkEligibility(options) {
+        const { blockedRegions, geoLocation } = options;
+        try {
+            this.#deps.debugLogger.log('EligibilityService: Checking eligibility', {
+                blockedRegionsCount: blockedRegions.length,
+                geoLocation,
+            });
+            if (geoLocation !== 'UNKNOWN') {
+                const isEligible = blockedRegions.every((geoBlockedRegion) => !geoLocation
+                    .toUpperCase()
+                    .startsWith(geoBlockedRegion.toUpperCase()));
+                this.#deps.debugLogger.log('EligibilityService: Eligibility check completed', {
+                    geoLocation,
+                    isEligible,
+                    blockedRegions,
+                });
+                return isEligible;
+            }
+            return true;
+        }
+        catch (error) {
+            this.#deps.logger.error(ensureError(error, 'EligibilityService.checkEligibility'), {
+                tags: { feature: PERPS_CONSTANTS.FeatureName },
+                context: {
+                    name: 'EligibilityService.checkEligibility',
+                    data: {},
+                },
+            });
+            return true;
+        }
+    }
+}
+//# sourceMappingURL=EligibilityService.js.map

package/dist/services/EligibilityService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EligibilityService.js","sourceRoot":"","sources":["../../src/services/EligibilityService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAK9D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAkB;IACpB,KAAK,CAA4B;IAE1C;;;;OAIG;IACH,YAAY,IAA+B;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,gBAAgB,CAAC,OAA+B;QACpD,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;QAChD,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,0CAA0C,EAAE;gBACrE,mBAAmB,EAAE,cAAc,CAAC,MAAM;gBAC1C,WAAW;aACZ,CAAC,CAAC;YAEH,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CACrC,CAAC,gBAAgB,EAAE,EAAE,CACnB,CAAC,WAAW;qBACT,WAAW,EAAE;qBACb,UAAU,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC,CAChD,CAAC;gBAEF,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,iDAAiD,EACjD;oBACE,WAAW;oBACX,UAAU;oBACV,cAAc;iBACf,CACF,CAAC;gBAEF,OAAO,UAAU,CAAC;YACpB,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CACrB,WAAW,CAAC,KAAK,EAAE,qCAAqC,CAAC,EACzD;gBACE,IAAI,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,WAAW,EAAE;gBAC9C,OAAO,EAAE;oBACP,IAAI,EAAE,qCAAqC;oBAC3C,IAAI,EAAE,EAAE;iBACT;aACF,CACF,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF","sourcesContent":["import { PERPS_CONSTANTS } from '../constants/perpsConfig.js';\nimport type {\n  PerpsPlatformDependencies,\n  CheckEligibilityParams,\n} from '../types/index.js';\nimport { ensureError } from '../utils/errorUtils.js';\n\n/**\n * EligibilityService\n *\n * Handles eligibility checking based on geolocation and blocked regions.\n * Geolocation is sourced externally from the GeolocationController.\n *\n * Instance-based service with constructor injection of platform dependencies.\n */\nexport class EligibilityService {\n  readonly #deps: PerpsPlatformDependencies;\n\n  /**\n   * Create a new EligibilityService instance\n   *\n   * @param deps - Platform dependencies for logging, metrics, etc.\n   */\n  constructor(deps: PerpsPlatformDependencies) {\n    this.#deps = deps;\n  }\n\n  /**\n   * Check if user is eligible based on geo-blocked regions.\n   *\n   * @param options - The eligibility check parameters.\n   * @param options.blockedRegions - List of blocked region codes (e.g., ['US', 'CN']).\n   * @param options.geoLocation - The user's geolocation string from GeolocationController.\n   * @returns True if eligible (not in blocked region), false otherwise.\n   */\n  async checkEligibility(options: CheckEligibilityParams): Promise<boolean> {\n    const { blockedRegions, geoLocation } = options;\n    try {\n      this.#deps.debugLogger.log('EligibilityService: Checking eligibility', {\n        blockedRegionsCount: blockedRegions.length,\n        geoLocation,\n      });\n\n      if (geoLocation !== 'UNKNOWN') {\n        const isEligible = blockedRegions.every(\n          (geoBlockedRegion) =>\n            !geoLocation\n              .toUpperCase()\n              .startsWith(geoBlockedRegion.toUpperCase()),\n        );\n\n        this.#deps.debugLogger.log(\n          'EligibilityService: Eligibility check completed',\n          {\n            geoLocation,\n            isEligible,\n            blockedRegions,\n          },\n        );\n\n        return isEligible;\n      }\n\n      return true;\n    } catch (error) {\n      this.#deps.logger.error(\n        ensureError(error, 'EligibilityService.checkEligibility'),\n        {\n          tags: { feature: PERPS_CONSTANTS.FeatureName },\n          context: {\n            name: 'EligibilityService.checkEligibility',\n            data: {},\n          },\n        },\n      );\n      return true;\n    }\n  }\n}\n"]}

package/dist/services/FeatureFlagConfigurationService.d.ts

@@ -0,0 +1,73 @@
+import type { PerpsPlatformDependencies, PerpsRemoteFeatureFlagState } from '../types/index.js';
+import type { ServiceContext } from './ServiceContext.js';
+/**
+ * FeatureFlagConfigurationService
+ *
+ * Handles HIP-3 configuration and geo-blocking configuration from remote feature flags.
+ * Implements "sticky remote" pattern: once remote config is loaded, never downgrade to fallback.
+ * Orchestrates validation, change detection, and version management for feature flag updates.
+ *
+ * Responsibilities:
+ * - Remote feature flag validation and parsing
+ * - HIP-3 configuration management (equity, allowlist, blocklist)
+ * - Geo-blocking configuration from remote flags
+ * - Change detection and version management
+ * - "Sticky remote" pattern enforcement (never downgrade)
+ *
+ * Instance-based service with constructor injection of platform dependencies.
+ */
+export declare class FeatureFlagConfigurationService {
+    #private;
+    /**
+     * Create a new FeatureFlagConfigurationService instance
+     *
+     * @param deps - Platform dependencies for logging, metrics, etc.
+     */
+    constructor(deps: PerpsPlatformDependencies);
+    /**
+     * Refresh HIP-3 configuration when remote feature flags change.
+     * This method extracts HIP-3 settings from remote flags, validates them,
+     * and updates internal state if they differ from current values.
+     * When config changes, increments hip3ConfigVersion to trigger ConnectionManager reconnection.
+     *
+     * Follows the "sticky remote" pattern: once remote config is loaded, never downgrade to fallback.
+     *
+     * @param options - Configuration object
+     * @param options.remoteFeatureFlagControllerState - Remote feature flag state
+     * @param options.context - ServiceContext providing state access callbacks
+     */
+    refreshHip3Config(options: {
+        remoteFeatureFlagControllerState: PerpsRemoteFeatureFlagState;
+        context: ServiceContext;
+    }): void;
+    /**
+     * Respond to RemoteFeatureFlagController state changes
+     * Refreshes user eligibility based on geo-blocked regions defined in remote feature flag.
+     * Uses fallback configuration when remote feature flag is undefined.
+     * Note: Initial eligibility is set in the constructor if fallback regions are provided.
+     *
+     * @param options - Configuration object
+     * @param options.remoteFeatureFlagControllerState - Remote feature flag state
+     * @param options.context - ServiceContext providing callbacks
+     */
+    refreshEligibility(options: {
+        remoteFeatureFlagControllerState: PerpsRemoteFeatureFlagState;
+        context: ServiceContext;
+    }): void;
+    /**
+     * Set blocked region list with "never downgrade" pattern enforcement
+     * Updates the blocked region list and triggers eligibility refresh.
+     * Implements "sticky remote": once remote regions are set, never downgrade to fallback.
+     *
+     * @param options - Configuration object
+     * @param options.list - Array of blocked region codes
+     * @param options.source - Source of the list ('remote' or 'fallback')
+     * @param options.context - ServiceContext providing callbacks
+     */
+    setBlockedRegions(options: {
+        list: string[];
+        source: 'remote' | 'fallback';
+        context: ServiceContext;
+    }): void;
+}
+//# sourceMappingURL=FeatureFlagConfigurationService.d.ts.map

package/dist/services/FeatureFlagConfigurationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureFlagConfigurationService.d.ts","sourceRoot":"","sources":["../../src/services/FeatureFlagConfigurationService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,yBAAyB,EACzB,2BAA2B,EAC5B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,+BAA+B;;IAG1C;;;;OAIG;IACH,YAAY,IAAI,EAAE,yBAAyB,EAE1C;IAuID;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,gCAAgC,EAAE,2BAA2B,CAAC;QAC9D,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI,CA2HP;IAED;;;;;;;;;OASG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAC1B,gCAAgC,EAAE,2BAA2B,CAAC;QAC9D,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI,CAsBP;IAED;;;;;;;;;OASG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;QAC9B,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI,CAoCP;CACF"}

package/dist/services/FeatureFlagConfigurationService.js

@@ -0,0 +1,266 @@
+import { hasProperty } from '@metamask/utils';
+import { PERPS_CONSTANTS } from '../constants/perpsConfig.js';
+import { isVersionGatedFeatureFlag } from '../types/index.js';
+import { ensureError } from '../utils/errorUtils.js';
+import { validateMarketPattern } from '../utils/marketUtils.js';
+import { parseCommaSeparatedString, stripQuotes, } from '../utils/stringParseUtils.js';
+/**
+ * FeatureFlagConfigurationService
+ *
+ * Handles HIP-3 configuration and geo-blocking configuration from remote feature flags.
+ * Implements "sticky remote" pattern: once remote config is loaded, never downgrade to fallback.
+ * Orchestrates validation, change detection, and version management for feature flag updates.
+ *
+ * Responsibilities:
+ * - Remote feature flag validation and parsing
+ * - HIP-3 configuration management (equity, allowlist, blocklist)
+ * - Geo-blocking configuration from remote flags
+ * - Change detection and version management
+ * - "Sticky remote" pattern enforcement (never downgrade)
+ *
+ * Instance-based service with constructor injection of platform dependencies.
+ */
+export class FeatureFlagConfigurationService {
+    #deps;
+    /**
+     * Create a new FeatureFlagConfigurationService instance
+     *
+     * @param deps - Platform dependencies for logging, metrics, etc.
+     */
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /**
+     * Validate and parse market list from remote feature flags
+     * Handles both string (comma-separated) and array formats from LaunchDarkly
+     *
+     * @param remoteValue - The raw value from remote feature flags (string or array).
+     * @param fieldName - The name of the field being validated (for logging).
+     * @param currentValue - The current local market list as fallback reference.
+     * @returns The validated market list, or undefined if validation fails.
+     */
+    #validateMarketList(remoteValue, fieldName, currentValue) {
+        this.#deps.debugLogger.log(`PerpsController: HIP-3 ${fieldName} validation`, {
+            remoteValue,
+            type: typeof remoteValue,
+            isArray: Array.isArray(remoteValue),
+        });
+        // LaunchDarkly returns comma-separated strings for list values
+        // Values may have literal quotes (e.g., '"xyz"') due to JSON encoding quirks
+        if (typeof remoteValue === 'string') {
+            const parsed = this.#filterValidPatterns(parseCommaSeparatedString(remoteValue).map(stripQuotes), fieldName);
+            if (parsed.length > 0) {
+                this.#deps.debugLogger.log(`PerpsController: HIP-3 ${fieldName} validated from string`, { validatedMarkets: parsed });
+                return parsed;
+            }
+            this.#deps.debugLogger.log(`PerpsController: HIP-3 ${fieldName} string was empty after parsing`, { fallbackValue: currentValue });
+            return undefined;
+        }
+        // Fallback: Validate array of non-empty strings
+        if (Array.isArray(remoteValue) &&
+            remoteValue.every((item) => typeof item === 'string' && item.length > 0)) {
+            const validatedMarkets = this.#filterValidPatterns(remoteValue
+                .map((market) => stripQuotes(market.trim()))
+                .filter((market) => market.length > 0), fieldName);
+            if (validatedMarkets.length > 0) {
+                this.#deps.debugLogger.log(`PerpsController: HIP-3 ${fieldName} validated from array`, { validatedMarkets });
+                return validatedMarkets;
+            }
+            this.#deps.debugLogger.log(`PerpsController: HIP-3 ${fieldName} array was empty after filtering`, { fallbackValue: currentValue });
+            return undefined;
+        }
+        this.#deps.debugLogger.log(`PerpsController: HIP-3 ${fieldName} validation FAILED - falling back to local config`, {
+            reason: Array.isArray(remoteValue)
+                ? 'Array contains non-string or empty values'
+                : 'Invalid type (expected string or array)',
+            fallbackValue: currentValue,
+        });
+        return undefined;
+    }
+    /**
+     * Filter out patterns that fail market pattern validation.
+     * Invalid patterns are logged and dropped instead of propagated downstream.
+     *
+     * @param patterns - The array of market patterns to validate.
+     * @param fieldName - The name of the field being validated (for logging).
+     * @returns The filtered array containing only valid market patterns.
+     */
+    #filterValidPatterns(patterns, fieldName) {
+        return patterns.filter((pattern) => {
+            try {
+                validateMarketPattern(pattern);
+                return true;
+            }
+            catch (error) {
+                this.#deps.logger.error(ensureError(error, `FeatureFlagConfigurationService.filterValidPatterns`), {
+                    tags: { feature: PERPS_CONSTANTS.FeatureName },
+                    context: {
+                        name: 'FeatureFlagConfigurationService.filterValidPatterns',
+                        data: { fieldName, pattern },
+                    },
+                });
+                return false;
+            }
+        });
+    }
+    /**
+     * Check if arrays have different values (order-independent comparison)
+     *
+     * @param a - The first string array to compare.
+     * @param b - The second string array to compare.
+     * @returns True if the arrays contain different values.
+     */
+    #arraysHaveDifferentValues(a, b) {
+        return (JSON.stringify([...a].sort((itemA, itemB) => itemA.localeCompare(itemB))) !==
+            JSON.stringify([...b].sort((itemA, itemB) => itemA.localeCompare(itemB))));
+    }
+    /**
+     * Refresh HIP-3 configuration when remote feature flags change.
+     * This method extracts HIP-3 settings from remote flags, validates them,
+     * and updates internal state if they differ from current values.
+     * When config changes, increments hip3ConfigVersion to trigger ConnectionManager reconnection.
+     *
+     * Follows the "sticky remote" pattern: once remote config is loaded, never downgrade to fallback.
+     *
+     * @param options - Configuration object
+     * @param options.remoteFeatureFlagControllerState - Remote feature flag state
+     * @param options.context - ServiceContext providing state access callbacks
+     */
+    refreshHip3Config(options) {
+        const { remoteFeatureFlagControllerState, context } = options;
+        if (!context.getHip3Config ||
+            !context.setHip3Config ||
+            !context.incrementHip3ConfigVersion) {
+            throw new Error('Required HIP-3 callbacks not available in ServiceContext');
+        }
+        const remoteFlags = remoteFeatureFlagControllerState.remoteFeatureFlags;
+        const currentConfig = context.getHip3Config();
+        // Extract and validate remote HIP-3 equity enabled flag
+        const equityFlag = remoteFlags?.perpsHip3Enabled;
+        // Use type guard to validate before calling - validatedVersionGatedFeatureFlag also
+        // handles invalid flags internally, but proper typing requires the guard
+        const validatedEquity = isVersionGatedFeatureFlag(equityFlag)
+            ? this.#deps.featureFlags.validateVersionGated(equityFlag)
+            : undefined;
+        this.#deps.debugLogger.log('PerpsController: HIP-3 equity flag validation', {
+            equityFlag,
+            validatedEquity,
+            willUse: validatedEquity === undefined ? 'fallback' : 'remote',
+        });
+        // Extract and validate remote HIP-3 market lists
+        const validatedAllowlistMarkets = hasProperty(remoteFlags, 'perpsHip3AllowlistMarkets')
+            ? this.#validateMarketList(remoteFlags.perpsHip3AllowlistMarkets, 'allowlistMarkets', currentConfig.allowlistMarkets)
+            : undefined;
+        const validatedBlocklistMarkets = hasProperty(remoteFlags, 'perpsHip3BlocklistMarkets')
+            ? this.#validateMarketList(remoteFlags.perpsHip3BlocklistMarkets, 'blocklistMarkets', currentConfig.blocklistMarkets)
+            : undefined;
+        // Detect changes (only if we have valid remote values)
+        const equityChanged = validatedEquity !== undefined &&
+            validatedEquity !== currentConfig.enabled;
+        const allowlistMarketsChanged = validatedAllowlistMarkets !== undefined &&
+            this.#arraysHaveDifferentValues(validatedAllowlistMarkets, currentConfig.allowlistMarkets);
+        const blocklistMarketsChanged = validatedBlocklistMarkets !== undefined &&
+            this.#arraysHaveDifferentValues(validatedBlocklistMarkets, currentConfig.blocklistMarkets);
+        if (equityChanged || allowlistMarketsChanged || blocklistMarketsChanged) {
+            this.#deps.debugLogger.log('PerpsController: HIP-3 config changed via remote feature flags', {
+                equityChanged,
+                allowlistMarketsChanged,
+                blocklistMarketsChanged,
+                oldEquity: currentConfig.enabled,
+                newEquity: validatedEquity,
+                oldAllowlistMarkets: currentConfig.allowlistMarkets,
+                newAllowlistMarkets: validatedAllowlistMarkets,
+                oldBlocklistMarkets: currentConfig.blocklistMarkets,
+                newBlocklistMarkets: validatedBlocklistMarkets,
+                source: 'remote',
+            });
+            // Update internal state (sticky remote - never downgrade)
+            context.setHip3Config({
+                enabled: validatedEquity,
+                allowlistMarkets: validatedAllowlistMarkets
+                    ? [...validatedAllowlistMarkets]
+                    : undefined,
+                blocklistMarkets: validatedBlocklistMarkets
+                    ? [...validatedBlocklistMarkets]
+                    : undefined,
+                source: 'remote',
+            });
+            // Increment version to trigger ConnectionManager reconnection and cache clearing
+            const newVersion = context.incrementHip3ConfigVersion();
+            this.#deps.debugLogger.log('PerpsController: Incremented hip3ConfigVersion to trigger reconnection', {
+                newVersion,
+                newHip3Enabled: validatedEquity ?? currentConfig.enabled,
+                newHip3AllowlistMarkets: validatedAllowlistMarkets ?? currentConfig.allowlistMarkets,
+                newHip3BlocklistMarkets: validatedBlocklistMarkets ?? currentConfig.blocklistMarkets,
+            });
+            // Note: ConnectionManager will handle:
+            // 1. Detecting hip3ConfigVersion change via Redux monitoring
+            // 2. Clearing all StreamManager caches
+            // 3. Calling reconnectWithNewContext() -> initializeProviders()
+            // 4. Provider reinitialization will read the new HIP-3 config below
+        }
+    }
+    /**
+     * Respond to RemoteFeatureFlagController state changes
+     * Refreshes user eligibility based on geo-blocked regions defined in remote feature flag.
+     * Uses fallback configuration when remote feature flag is undefined.
+     * Note: Initial eligibility is set in the constructor if fallback regions are provided.
+     *
+     * @param options - Configuration object
+     * @param options.remoteFeatureFlagControllerState - Remote feature flag state
+     * @param options.context - ServiceContext providing callbacks
+     */
+    refreshEligibility(options) {
+        const { remoteFeatureFlagControllerState, context } = options;
+        const perpsGeoBlockedRegionsFeatureFlag = 
+        // NOTE: Do not use perpsPerpTradingGeoBlockedCountries as it is deprecated.
+        remoteFeatureFlagControllerState.remoteFeatureFlags
+            ?.perpsPerpTradingGeoBlockedCountriesV2;
+        const remoteBlockedRegions = perpsGeoBlockedRegionsFeatureFlag?.blockedRegions;
+        if (Array.isArray(remoteBlockedRegions)) {
+            this.setBlockedRegions({
+                list: remoteBlockedRegions,
+                source: 'remote',
+                context,
+            });
+        }
+        // Also check for HIP-3 config changes
+        this.refreshHip3Config({ remoteFeatureFlagControllerState, context });
+    }
+    /**
+     * Set blocked region list with "never downgrade" pattern enforcement
+     * Updates the blocked region list and triggers eligibility refresh.
+     * Implements "sticky remote": once remote regions are set, never downgrade to fallback.
+     *
+     * @param options - Configuration object
+     * @param options.list - Array of blocked region codes
+     * @param options.source - Source of the list ('remote' or 'fallback')
+     * @param options.context - ServiceContext providing callbacks
+     */
+    setBlockedRegions(options) {
+        const { list, source, context } = options;
+        if (!context.getBlockedRegionList ||
+            !context.setBlockedRegionList ||
+            !context.refreshEligibility) {
+            throw new Error('Required blocked region callbacks not available in ServiceContext');
+        }
+        const currentList = context.getBlockedRegionList();
+        // Never downgrade from remote to fallback
+        if (source === 'fallback' && currentList.source === 'remote') {
+            return;
+        }
+        if (Array.isArray(list)) {
+            context.setBlockedRegionList(list, source);
+        }
+        context.refreshEligibility().catch((error) => {
+            this.#deps.logger.error(ensureError(error, 'FeatureFlagConfigurationService.setBlockedRegions'), {
+                tags: { feature: PERPS_CONSTANTS.FeatureName },
+                context: {
+                    name: 'FeatureFlagConfigurationService.setBlockedRegions',
+                    data: { source },
+                },
+            });
+        });
+    }
+}
+//# sourceMappingURL=FeatureFlagConfigurationService.js.map

package/dist/services/FeatureFlagConfigurationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureFlagConfigurationService.js","sourceRoot":"","sources":["../../src/services/FeatureFlagConfigurationService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAK9D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,yBAAyB,EACzB,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAGtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,+BAA+B;IACjC,KAAK,CAA4B;IAE1C;;;;OAIG;IACH,YAAY,IAA+B;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;OAQG;IACH,mBAAmB,CACjB,WAAoB,EACpB,SAAiB,EACjB,YAAsB;QAEtB,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,0BAA0B,SAAS,aAAa,EAChD;YACE,WAAW;YACX,IAAI,EAAE,OAAO,WAAW;YACxB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;SACpC,CACF,CAAC;QAEF,+DAA+D;QAC/D,6EAA6E;QAC7E,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CACtC,yBAAyB,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,EACvD,SAAS,CACV,CAAC;YAEF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,0BAA0B,SAAS,wBAAwB,EAC3D,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAC7B,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,0BAA0B,SAAS,iCAAiC,EACpE,EAAE,aAAa,EAAE,YAAY,EAAE,CAChC,CAAC;YACF,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,gDAAgD;QAChD,IACE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;YAC1B,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EACxE,CAAC;YACD,MAAM,gBAAgB,GAAG,IAAI,CAAC,oBAAoB,CAC/C,WAAwB;iBACtB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;iBAC3C,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,EACxC,SAAS,CACV,CAAC;YAEF,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,0BAA0B,SAAS,uBAAuB,EAC1D,EAAE,gBAAgB,EAAE,CACrB,CAAC;gBACF,OAAO,gBAAgB,CAAC;YAC1B,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,0BAA0B,SAAS,kCAAkC,EACrE,EAAE,aAAa,EAAE,YAAY,EAAE,CAChC,CAAC;YACF,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,0BAA0B,SAAS,mDAAmD,EACtF;YACE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;gBAChC,CAAC,CAAC,2CAA2C;gBAC7C,CAAC,CAAC,yCAAyC;YAC7C,aAAa,EAAE,YAAY;SAC5B,CACF,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;;OAOG;IACH,oBAAoB,CAAC,QAAkB,EAAE,SAAiB;QACxD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YACjC,IAAI,CAAC;gBACH,qBAAqB,CAAC,OAAO,CAAC,CAAC;gBAC/B,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CACrB,WAAW,CACT,KAAK,EACL,qDAAqD,CACtD,EACD;oBACE,IAAI,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,WAAW,EAAE;oBAC9C,OAAO,EAAE;wBACP,IAAI,EAAE,qDAAqD;wBAC3D,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;qBAC7B;iBACF,CACF,CAAC;gBACF,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,0BAA0B,CAAC,CAAW,EAAE,CAAW;QACjD,OAAO,CACL,IAAI,CAAC,SAAS,CACZ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAC1D;YACD,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAC1E,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,OAGjB;QACC,MAAM,EAAE,gCAAgC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAE9D,IACE,CAAC,OAAO,CAAC,aAAa;YACtB,CAAC,OAAO,CAAC,aAAa;YACtB,CAAC,OAAO,CAAC,0BAA0B,EACnC,CAAC;YACD,MAAM,IAAI,KAAK,CACb,0DAA0D,CAC3D,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,gCAAgC,CAAC,kBAAkB,CAAC;QACxE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;QAE9C,wDAAwD;QACxD,MAAM,UAAU,GAAG,WAAW,EAAE,gBAAgB,CAAC;QACjD,oFAAoF;QACpF,yEAAyE;QACzE,MAAM,eAAe,GAAG,yBAAyB,CAAC,UAAU,CAAC;YAC3D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,oBAAoB,CAAC,UAAU,CAAC;YAC1D,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,+CAA+C,EAC/C;YACE,UAAU;YACV,eAAe;YACf,OAAO,EAAE,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;SAC/D,CACF,CAAC;QAEF,iDAAiD;QACjD,MAAM,yBAAyB,GAAG,WAAW,CAC3C,WAAW,EACX,2BAA2B,CAC5B;YACC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CACtB,WAAW,CAAC,yBAAyB,EACrC,kBAAkB,EAClB,aAAa,CAAC,gBAAgB,CAC/B;YACH,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,yBAAyB,GAAG,WAAW,CAC3C,WAAW,EACX,2BAA2B,CAC5B;YACC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CACtB,WAAW,CAAC,yBAAyB,EACrC,kBAAkB,EAClB,aAAa,CAAC,gBAAgB,CAC/B;YACH,CAAC,CAAC,SAAS,CAAC;QAEd,uDAAuD;QACvD,MAAM,aAAa,GACjB,eAAe,KAAK,SAAS;YAC7B,eAAe,KAAK,aAAa,CAAC,OAAO,CAAC;QAC5C,MAAM,uBAAuB,GAC3B,yBAAyB,KAAK,SAAS;YACvC,IAAI,CAAC,0BAA0B,CAC7B,yBAAyB,EACzB,aAAa,CAAC,gBAAgB,CAC/B,CAAC;QACJ,MAAM,uBAAuB,GAC3B,yBAAyB,KAAK,SAAS;YACvC,IAAI,CAAC,0BAA0B,CAC7B,yBAAyB,EACzB,aAAa,CAAC,gBAAgB,CAC/B,CAAC;QAEJ,IAAI,aAAa,IAAI,uBAAuB,IAAI,uBAAuB,EAAE,CAAC;YACxE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,gEAAgE,EAChE;gBACE,aAAa;gBACb,uBAAuB;gBACvB,uBAAuB;gBACvB,SAAS,EAAE,aAAa,CAAC,OAAO;gBAChC,SAAS,EAAE,eAAe;gBAC1B,mBAAmB,EAAE,aAAa,CAAC,gBAAgB;gBACnD,mBAAmB,EAAE,yBAAyB;gBAC9C,mBAAmB,EAAE,aAAa,CAAC,gBAAgB;gBACnD,mBAAmB,EAAE,yBAAyB;gBAC9C,MAAM,EAAE,QAAQ;aACjB,CACF,CAAC;YAEF,0DAA0D;YAC1D,OAAO,CAAC,aAAa,CAAC;gBACpB,OAAO,EAAE,eAAe;gBACxB,gBAAgB,EAAE,yBAAyB;oBACzC,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAAC;oBAChC,CAAC,CAAC,SAAS;gBACb,gBAAgB,EAAE,yBAAyB;oBACzC,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAAC;oBAChC,CAAC,CAAC,SAAS;gBACb,MAAM,EAAE,QAAQ;aACjB,CAAC,CAAC;YAEH,iFAAiF;YACjF,MAAM,UAAU,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC;YAExD,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CACxB,wEAAwE,EACxE;gBACE,UAAU;gBACV,cAAc,EAAE,eAAe,IAAI,aAAa,CAAC,OAAO;gBACxD,uBAAuB,EACrB,yBAAyB,IAAI,aAAa,CAAC,gBAAgB;gBAC7D,uBAAuB,EACrB,yBAAyB,IAAI,aAAa,CAAC,gBAAgB;aAC9D,CACF,CAAC;YAEF,uCAAuC;YACvC,6DAA6D;YAC7D,uCAAuC;YACvC,gEAAgE;YAChE,oEAAoE;QACtE,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,kBAAkB,CAAC,OAGlB;QACC,MAAM,EAAE,gCAAgC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAE9D,MAAM,iCAAiC;QACrC,4EAA4E;QAC5E,gCAAgC,CAAC,kBAAkB;YACjD,EAAE,qCAAqC,CAAC;QAE5C,MAAM,oBAAoB,GACxB,iCACD,EAAE,cAAc,CAAC;QAElB,IAAI,KAAK,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,iBAAiB,CAAC;gBACrB,IAAI,EAAE,oBAAoB;gBAC1B,MAAM,EAAE,QAAQ;gBAChB,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QAED,sCAAsC;QACtC,IAAI,CAAC,iBAAiB,CAAC,EAAE,gCAAgC,EAAE,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;;OASG;IACH,iBAAiB,CAAC,OAIjB;QACC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAE1C,IACE,CAAC,OAAO,CAAC,oBAAoB;YAC7B,CAAC,OAAO,CAAC,oBAAoB;YAC7B,CAAC,OAAO,CAAC,kBAAkB,EAC3B,CAAC;YACD,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;QAEnD,0CAA0C;QAC1C,IAAI,MAAM,KAAK,UAAU,IAAI,WAAW,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7D,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,CAAC,kBAAkB,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC3C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CACrB,WAAW,CAAC,KAAK,EAAE,mDAAmD,CAAC,EACvE;gBACE,IAAI,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,WAAW,EAAE;gBAC9C,OAAO,EAAE;oBACP,IAAI,EAAE,mDAAmD;oBACzD,IAAI,EAAE,EAAE,MAAM,EAAE;iBACjB;aACF,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import { hasProperty } from '@metamask/utils';\n\nimport { PERPS_CONSTANTS } from '../constants/perpsConfig.js';\nimport { isVersionGatedFeatureFlag } from '../types/index.js';\nimport type {\n  PerpsPlatformDependencies,\n  PerpsRemoteFeatureFlagState,\n} from '../types/index.js';\nimport { ensureError } from '../utils/errorUtils.js';\nimport { validateMarketPattern } from '../utils/marketUtils.js';\nimport {\n  parseCommaSeparatedString,\n  stripQuotes,\n} from '../utils/stringParseUtils.js';\nimport type { ServiceContext } from './ServiceContext.js';\n\n/**\n * FeatureFlagConfigurationService\n *\n * Handles HIP-3 configuration and geo-blocking configuration from remote feature flags.\n * Implements \"sticky remote\" pattern: once remote config is loaded, never downgrade to fallback.\n * Orchestrates validation, change detection, and version management for feature flag updates.\n *\n * Responsibilities:\n * - Remote feature flag validation and parsing\n * - HIP-3 configuration management (equity, allowlist, blocklist)\n * - Geo-blocking configuration from remote flags\n * - Change detection and version management\n * - \"Sticky remote\" pattern enforcement (never downgrade)\n *\n * Instance-based service with constructor injection of platform dependencies.\n */\nexport class FeatureFlagConfigurationService {\n  readonly #deps: PerpsPlatformDependencies;\n\n  /**\n   * Create a new FeatureFlagConfigurationService instance\n   *\n   * @param deps - Platform dependencies for logging, metrics, etc.\n   */\n  constructor(deps: PerpsPlatformDependencies) {\n    this.#deps = deps;\n  }\n\n  /**\n   * Validate and parse market list from remote feature flags\n   * Handles both string (comma-separated) and array formats from LaunchDarkly\n   *\n   * @param remoteValue - The raw value from remote feature flags (string or array).\n   * @param fieldName - The name of the field being validated (for logging).\n   * @param currentValue - The current local market list as fallback reference.\n   * @returns The validated market list, or undefined if validation fails.\n   */\n  #validateMarketList(\n    remoteValue: unknown,\n    fieldName: string,\n    currentValue: string[],\n  ): string[] | undefined {\n    this.#deps.debugLogger.log(\n      `PerpsController: HIP-3 ${fieldName} validation`,\n      {\n        remoteValue,\n        type: typeof remoteValue,\n        isArray: Array.isArray(remoteValue),\n      },\n    );\n\n    // LaunchDarkly returns comma-separated strings for list values\n    // Values may have literal quotes (e.g., '\"xyz\"') due to JSON encoding quirks\n    if (typeof remoteValue === 'string') {\n      const parsed = this.#filterValidPatterns(\n        parseCommaSeparatedString(remoteValue).map(stripQuotes),\n        fieldName,\n      );\n\n      if (parsed.length > 0) {\n        this.#deps.debugLogger.log(\n          `PerpsController: HIP-3 ${fieldName} validated from string`,\n          { validatedMarkets: parsed },\n        );\n        return parsed;\n      }\n\n      this.#deps.debugLogger.log(\n        `PerpsController: HIP-3 ${fieldName} string was empty after parsing`,\n        { fallbackValue: currentValue },\n      );\n      return undefined;\n    }\n\n    // Fallback: Validate array of non-empty strings\n    if (\n      Array.isArray(remoteValue) &&\n      remoteValue.every((item) => typeof item === 'string' && item.length > 0)\n    ) {\n      const validatedMarkets = this.#filterValidPatterns(\n        (remoteValue as string[])\n          .map((market) => stripQuotes(market.trim()))\n          .filter((market) => market.length > 0),\n        fieldName,\n      );\n\n      if (validatedMarkets.length > 0) {\n        this.#deps.debugLogger.log(\n          `PerpsController: HIP-3 ${fieldName} validated from array`,\n          { validatedMarkets },\n        );\n        return validatedMarkets;\n      }\n\n      this.#deps.debugLogger.log(\n        `PerpsController: HIP-3 ${fieldName} array was empty after filtering`,\n        { fallbackValue: currentValue },\n      );\n      return undefined;\n    }\n\n    this.#deps.debugLogger.log(\n      `PerpsController: HIP-3 ${fieldName} validation FAILED - falling back to local config`,\n      {\n        reason: Array.isArray(remoteValue)\n          ? 'Array contains non-string or empty values'\n          : 'Invalid type (expected string or array)',\n        fallbackValue: currentValue,\n      },\n    );\n    return undefined;\n  }\n\n  /**\n   * Filter out patterns that fail market pattern validation.\n   * Invalid patterns are logged and dropped instead of propagated downstream.\n   *\n   * @param patterns - The array of market patterns to validate.\n   * @param fieldName - The name of the field being validated (for logging).\n   * @returns The filtered array containing only valid market patterns.\n   */\n  #filterValidPatterns(patterns: string[], fieldName: string): string[] {\n    return patterns.filter((pattern) => {\n      try {\n        validateMarketPattern(pattern);\n        return true;\n      } catch (error) {\n        this.#deps.logger.error(\n          ensureError(\n            error,\n            `FeatureFlagConfigurationService.filterValidPatterns`,\n          ),\n          {\n            tags: { feature: PERPS_CONSTANTS.FeatureName },\n            context: {\n              name: 'FeatureFlagConfigurationService.filterValidPatterns',\n              data: { fieldName, pattern },\n            },\n          },\n        );\n        return false;\n      }\n    });\n  }\n\n  /**\n   * Check if arrays have different values (order-independent comparison)\n   *\n   * @param a - The first string array to compare.\n   * @param b - The second string array to compare.\n   * @returns True if the arrays contain different values.\n   */\n  #arraysHaveDifferentValues(a: string[], b: string[]): boolean {\n    return (\n      JSON.stringify(\n        [...a].sort((itemA, itemB) => itemA.localeCompare(itemB)),\n      ) !==\n      JSON.stringify([...b].sort((itemA, itemB) => itemA.localeCompare(itemB)))\n    );\n  }\n\n  /**\n   * Refresh HIP-3 configuration when remote feature flags change.\n   * This method extracts HIP-3 settings from remote flags, validates them,\n   * and updates internal state if they differ from current values.\n   * When config changes, increments hip3ConfigVersion to trigger ConnectionManager reconnection.\n   *\n   * Follows the \"sticky remote\" pattern: once remote config is loaded, never downgrade to fallback.\n   *\n   * @param options - Configuration object\n   * @param options.remoteFeatureFlagControllerState - Remote feature flag state\n   * @param options.context - ServiceContext providing state access callbacks\n   */\n  refreshHip3Config(options: {\n    remoteFeatureFlagControllerState: PerpsRemoteFeatureFlagState;\n    context: ServiceContext;\n  }): void {\n    const { remoteFeatureFlagControllerState, context } = options;\n\n    if (\n      !context.getHip3Config ||\n      !context.setHip3Config ||\n      !context.incrementHip3ConfigVersion\n    ) {\n      throw new Error(\n        'Required HIP-3 callbacks not available in ServiceContext',\n      );\n    }\n\n    const remoteFlags = remoteFeatureFlagControllerState.remoteFeatureFlags;\n    const currentConfig = context.getHip3Config();\n\n    // Extract and validate remote HIP-3 equity enabled flag\n    const equityFlag = remoteFlags?.perpsHip3Enabled;\n    // Use type guard to validate before calling - validatedVersionGatedFeatureFlag also\n    // handles invalid flags internally, but proper typing requires the guard\n    const validatedEquity = isVersionGatedFeatureFlag(equityFlag)\n      ? this.#deps.featureFlags.validateVersionGated(equityFlag)\n      : undefined;\n\n    this.#deps.debugLogger.log(\n      'PerpsController: HIP-3 equity flag validation',\n      {\n        equityFlag,\n        validatedEquity,\n        willUse: validatedEquity === undefined ? 'fallback' : 'remote',\n      },\n    );\n\n    // Extract and validate remote HIP-3 market lists\n    const validatedAllowlistMarkets = hasProperty(\n      remoteFlags,\n      'perpsHip3AllowlistMarkets',\n    )\n      ? this.#validateMarketList(\n          remoteFlags.perpsHip3AllowlistMarkets,\n          'allowlistMarkets',\n          currentConfig.allowlistMarkets,\n        )\n      : undefined;\n\n    const validatedBlocklistMarkets = hasProperty(\n      remoteFlags,\n      'perpsHip3BlocklistMarkets',\n    )\n      ? this.#validateMarketList(\n          remoteFlags.perpsHip3BlocklistMarkets,\n          'blocklistMarkets',\n          currentConfig.blocklistMarkets,\n        )\n      : undefined;\n\n    // Detect changes (only if we have valid remote values)\n    const equityChanged =\n      validatedEquity !== undefined &&\n      validatedEquity !== currentConfig.enabled;\n    const allowlistMarketsChanged =\n      validatedAllowlistMarkets !== undefined &&\n      this.#arraysHaveDifferentValues(\n        validatedAllowlistMarkets,\n        currentConfig.allowlistMarkets,\n      );\n    const blocklistMarketsChanged =\n      validatedBlocklistMarkets !== undefined &&\n      this.#arraysHaveDifferentValues(\n        validatedBlocklistMarkets,\n        currentConfig.blocklistMarkets,\n      );\n\n    if (equityChanged || allowlistMarketsChanged || blocklistMarketsChanged) {\n      this.#deps.debugLogger.log(\n        'PerpsController: HIP-3 config changed via remote feature flags',\n        {\n          equityChanged,\n          allowlistMarketsChanged,\n          blocklistMarketsChanged,\n          oldEquity: currentConfig.enabled,\n          newEquity: validatedEquity,\n          oldAllowlistMarkets: currentConfig.allowlistMarkets,\n          newAllowlistMarkets: validatedAllowlistMarkets,\n          oldBlocklistMarkets: currentConfig.blocklistMarkets,\n          newBlocklistMarkets: validatedBlocklistMarkets,\n          source: 'remote',\n        },\n      );\n\n      // Update internal state (sticky remote - never downgrade)\n      context.setHip3Config({\n        enabled: validatedEquity,\n        allowlistMarkets: validatedAllowlistMarkets\n          ? [...validatedAllowlistMarkets]\n          : undefined,\n        blocklistMarkets: validatedBlocklistMarkets\n          ? [...validatedBlocklistMarkets]\n          : undefined,\n        source: 'remote',\n      });\n\n      // Increment version to trigger ConnectionManager reconnection and cache clearing\n      const newVersion = context.incrementHip3ConfigVersion();\n\n      this.#deps.debugLogger.log(\n        'PerpsController: Incremented hip3ConfigVersion to trigger reconnection',\n        {\n          newVersion,\n          newHip3Enabled: validatedEquity ?? currentConfig.enabled,\n          newHip3AllowlistMarkets:\n            validatedAllowlistMarkets ?? currentConfig.allowlistMarkets,\n          newHip3BlocklistMarkets:\n            validatedBlocklistMarkets ?? currentConfig.blocklistMarkets,\n        },\n      );\n\n      // Note: ConnectionManager will handle:\n      // 1. Detecting hip3ConfigVersion change via Redux monitoring\n      // 2. Clearing all StreamManager caches\n      // 3. Calling reconnectWithNewContext() -> initializeProviders()\n      // 4. Provider reinitialization will read the new HIP-3 config below\n    }\n  }\n\n  /**\n   * Respond to RemoteFeatureFlagController state changes\n   * Refreshes user eligibility based on geo-blocked regions defined in remote feature flag.\n   * Uses fallback configuration when remote feature flag is undefined.\n   * Note: Initial eligibility is set in the constructor if fallback regions are provided.\n   *\n   * @param options - Configuration object\n   * @param options.remoteFeatureFlagControllerState - Remote feature flag state\n   * @param options.context - ServiceContext providing callbacks\n   */\n  refreshEligibility(options: {\n    remoteFeatureFlagControllerState: PerpsRemoteFeatureFlagState;\n    context: ServiceContext;\n  }): void {\n    const { remoteFeatureFlagControllerState, context } = options;\n\n    const perpsGeoBlockedRegionsFeatureFlag =\n      // NOTE: Do not use perpsPerpTradingGeoBlockedCountries as it is deprecated.\n      remoteFeatureFlagControllerState.remoteFeatureFlags\n        ?.perpsPerpTradingGeoBlockedCountriesV2;\n\n    const remoteBlockedRegions = (\n      perpsGeoBlockedRegionsFeatureFlag as { blockedRegions?: string[] }\n    )?.blockedRegions;\n\n    if (Array.isArray(remoteBlockedRegions)) {\n      this.setBlockedRegions({\n        list: remoteBlockedRegions,\n        source: 'remote',\n        context,\n      });\n    }\n\n    // Also check for HIP-3 config changes\n    this.refreshHip3Config({ remoteFeatureFlagControllerState, context });\n  }\n\n  /**\n   * Set blocked region list with \"never downgrade\" pattern enforcement\n   * Updates the blocked region list and triggers eligibility refresh.\n   * Implements \"sticky remote\": once remote regions are set, never downgrade to fallback.\n   *\n   * @param options - Configuration object\n   * @param options.list - Array of blocked region codes\n   * @param options.source - Source of the list ('remote' or 'fallback')\n   * @param options.context - ServiceContext providing callbacks\n   */\n  setBlockedRegions(options: {\n    list: string[];\n    source: 'remote' | 'fallback';\n    context: ServiceContext;\n  }): void {\n    const { list, source, context } = options;\n\n    if (\n      !context.getBlockedRegionList ||\n      !context.setBlockedRegionList ||\n      !context.refreshEligibility\n    ) {\n      throw new Error(\n        'Required blocked region callbacks not available in ServiceContext',\n      );\n    }\n\n    const currentList = context.getBlockedRegionList();\n\n    // Never downgrade from remote to fallback\n    if (source === 'fallback' && currentList.source === 'remote') {\n      return;\n    }\n\n    if (Array.isArray(list)) {\n      context.setBlockedRegionList(list, source);\n    }\n\n    context.refreshEligibility().catch((error) => {\n      this.#deps.logger.error(\n        ensureError(error, 'FeatureFlagConfigurationService.setBlockedRegions'),\n        {\n          tags: { feature: PERPS_CONSTANTS.FeatureName },\n          context: {\n            name: 'FeatureFlagConfigurationService.setBlockedRegions',\n            data: { source },\n          },\n        },\n      );\n    });\n  }\n}\n"]}