@metamask-previews/perps-controller 0.0.0-preview-685dbf46b → 1.0.0-preview-bc00f2c

package/dist/services/FeatureFlagConfigurationService.cjs

@@ -0,0 +1,257 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _FeatureFlagConfigurationService_instances, _FeatureFlagConfigurationService_deps, _FeatureFlagConfigurationService_validateMarketList, _FeatureFlagConfigurationService_filterValidPatterns, _FeatureFlagConfigurationService_arraysHaveDifferentValues;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagConfigurationService = void 0;
+const utils_1 = require("@metamask/utils");
+const perpsConfig_1 = require("../constants/perpsConfig.cjs");
+const types_1 = require("../types/index.cjs");
+const errorUtils_1 = require("../utils/errorUtils.cjs");
+const marketUtils_1 = require("../utils/marketUtils.cjs");
+const stringParseUtils_1 = require("../utils/stringParseUtils.cjs");
+/**
+ * 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.
+ */
+class FeatureFlagConfigurationService {
+    /**
+     * Create a new FeatureFlagConfigurationService instance
+     *
+     * @param deps - Platform dependencies for logging, metrics, etc.
+     */
+    constructor(deps) {
+        _FeatureFlagConfigurationService_instances.add(this);
+        _FeatureFlagConfigurationService_deps.set(this, void 0);
+        __classPrivateFieldSet(this, _FeatureFlagConfigurationService_deps, deps, "f");
+    }
+    /**
+     * 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 = (0, types_1.isVersionGatedFeatureFlag)(equityFlag)
+            ? __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").featureFlags.validateVersionGated(equityFlag)
+            : undefined;
+        __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").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 = (0, utils_1.hasProperty)(remoteFlags, 'perpsHip3AllowlistMarkets')
+            ? __classPrivateFieldGet(this, _FeatureFlagConfigurationService_instances, "m", _FeatureFlagConfigurationService_validateMarketList).call(this, remoteFlags.perpsHip3AllowlistMarkets, 'allowlistMarkets', currentConfig.allowlistMarkets)
+            : undefined;
+        const validatedBlocklistMarkets = (0, utils_1.hasProperty)(remoteFlags, 'perpsHip3BlocklistMarkets')
+            ? __classPrivateFieldGet(this, _FeatureFlagConfigurationService_instances, "m", _FeatureFlagConfigurationService_validateMarketList).call(this, 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 &&
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_instances, "m", _FeatureFlagConfigurationService_arraysHaveDifferentValues).call(this, validatedAllowlistMarkets, currentConfig.allowlistMarkets);
+        const blocklistMarketsChanged = validatedBlocklistMarkets !== undefined &&
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_instances, "m", _FeatureFlagConfigurationService_arraysHaveDifferentValues).call(this, validatedBlocklistMarkets, currentConfig.blocklistMarkets);
+        if (equityChanged || allowlistMarketsChanged || blocklistMarketsChanged) {
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").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();
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").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) => {
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").logger.error((0, errorUtils_1.ensureError)(error, 'FeatureFlagConfigurationService.setBlockedRegions'), {
+                tags: { feature: perpsConfig_1.PERPS_CONSTANTS.FeatureName },
+                context: {
+                    name: 'FeatureFlagConfigurationService.setBlockedRegions',
+                    data: { source },
+                },
+            });
+        });
+    }
+}
+exports.FeatureFlagConfigurationService = FeatureFlagConfigurationService;
+_FeatureFlagConfigurationService_deps = new WeakMap(), _FeatureFlagConfigurationService_instances = new WeakSet(), _FeatureFlagConfigurationService_validateMarketList = function _FeatureFlagConfigurationService_validateMarketList(remoteValue, fieldName, currentValue) {
+    __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").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 = __classPrivateFieldGet(this, _FeatureFlagConfigurationService_instances, "m", _FeatureFlagConfigurationService_filterValidPatterns).call(this, (0, stringParseUtils_1.parseCommaSeparatedString)(remoteValue).map(stringParseUtils_1.stripQuotes), fieldName);
+        if (parsed.length > 0) {
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").debugLogger.log(`PerpsController: HIP-3 ${fieldName} validated from string`, { validatedMarkets: parsed });
+            return parsed;
+        }
+        __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").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 = __classPrivateFieldGet(this, _FeatureFlagConfigurationService_instances, "m", _FeatureFlagConfigurationService_filterValidPatterns).call(this, remoteValue
+            .map((market) => (0, stringParseUtils_1.stripQuotes)(market.trim()))
+            .filter((market) => market.length > 0), fieldName);
+        if (validatedMarkets.length > 0) {
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").debugLogger.log(`PerpsController: HIP-3 ${fieldName} validated from array`, { validatedMarkets });
+            return validatedMarkets;
+        }
+        __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").debugLogger.log(`PerpsController: HIP-3 ${fieldName} array was empty after filtering`, { fallbackValue: currentValue });
+        return undefined;
+    }
+    __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").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;
+}, _FeatureFlagConfigurationService_filterValidPatterns = function _FeatureFlagConfigurationService_filterValidPatterns(patterns, fieldName) {
+    return patterns.filter((pattern) => {
+        try {
+            (0, marketUtils_1.validateMarketPattern)(pattern);
+            return true;
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _FeatureFlagConfigurationService_deps, "f").logger.error((0, errorUtils_1.ensureError)(error, `FeatureFlagConfigurationService.filterValidPatterns`), {
+                tags: { feature: perpsConfig_1.PERPS_CONSTANTS.FeatureName },
+                context: {
+                    name: 'FeatureFlagConfigurationService.filterValidPatterns',
+                    data: { fieldName, pattern },
+                },
+            });
+            return false;
+        }
+    });
+}, _FeatureFlagConfigurationService_arraysHaveDifferentValues = function _FeatureFlagConfigurationService_arraysHaveDifferentValues(a, b) {
+    return (JSON.stringify([...a].sort((itemA, itemB) => itemA.localeCompare(itemB))) !==
+        JSON.stringify([...b].sort((itemA, itemB) => itemA.localeCompare(itemB))));
+};
+//# sourceMappingURL=FeatureFlagConfigurationService.cjs.map

package/dist/services/FeatureFlagConfigurationService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureFlagConfigurationService.cjs","sourceRoot":"","sources":["../../src/services/FeatureFlagConfigurationService.ts"],"names":[],"mappings":"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","sourcesContent":["import { hasProperty } from '@metamask/utils';\n\nimport type { ServiceContext } from './ServiceContext';\nimport { PERPS_CONSTANTS } from '../constants/perpsConfig';\nimport { isVersionGatedFeatureFlag } from '../types';\nimport type {\n  PerpsPlatformDependencies,\n  PerpsRemoteFeatureFlagState,\n} from '../types';\nimport { ensureError } from '../utils/errorUtils';\nimport { validateMarketPattern } from '../utils/marketUtils';\nimport {\n  parseCommaSeparatedString,\n  stripQuotes,\n} from '../utils/stringParseUtils';\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"]}

package/dist/services/FeatureFlagConfigurationService.d.cts

@@ -0,0 +1,73 @@
+import type { ServiceContext } from "./ServiceContext.cjs";
+import type { PerpsPlatformDependencies, PerpsRemoteFeatureFlagState } from "../types/index.cjs";
+/**
+ * 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.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureFlagConfigurationService.d.cts","sourceRoot":"","sources":["../../src/services/FeatureFlagConfigurationService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,6BAAyB;AAGvD,OAAO,KAAK,EACV,yBAAyB,EACzB,2BAA2B,EAC5B,2BAAiB;AAQlB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,+BAA+B;;IAG1C;;;;OAIG;gBACS,IAAI,EAAE,yBAAyB;IAyI3C;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,gCAAgC,EAAE,2BAA2B,CAAC;QAC9D,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI;IA6HR;;;;;;;;;OASG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAC1B,gCAAgC,EAAE,2BAA2B,CAAC;QAC9D,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI;IAwBR;;;;;;;;;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;CAqCT"}

package/dist/services/FeatureFlagConfigurationService.d.mts

@@ -0,0 +1,73 @@
+import type { ServiceContext } from "./ServiceContext.mjs";
+import type { PerpsPlatformDependencies, PerpsRemoteFeatureFlagState } from "../types/index.mjs";
+/**
+ * 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.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureFlagConfigurationService.d.mts","sourceRoot":"","sources":["../../src/services/FeatureFlagConfigurationService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,6BAAyB;AAGvD,OAAO,KAAK,EACV,yBAAyB,EACzB,2BAA2B,EAC5B,2BAAiB;AAQlB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,+BAA+B;;IAG1C;;;;OAIG;gBACS,IAAI,EAAE,yBAAyB;IAyI3C;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,gCAAgC,EAAE,2BAA2B,CAAC;QAC9D,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI;IA6HR;;;;;;;;;OASG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAC1B,gCAAgC,EAAE,2BAA2B,CAAC;QAC9D,OAAO,EAAE,cAAc,CAAC;KACzB,GAAG,IAAI;IAwBR;;;;;;;;;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;CAqCT"}