chore: update version gated feature flag docs (#32159)

asalsys · cursoragent · web-flow · commit 35328c8759a3 · 2026-06-23T23:08:09.000Z
## **Description**  Version-gated remote feature flags are evaluated in many places across the codebase, but guidance was scattered across team-specific docs and there was no single canonical pattern for agents and contributors to follow. This PR centralizes that guidance: 1. **New canonical guide** — `docs/readme/version-gated-feature-flags.md` documents the SSOT (`app/util/remoteFeatureFlag`), the required selector pattern using `validatedVersionGatedFeatureFlag`, non-standard flag shapes, and forbidden duplicate helpers. 2. **Cursor agent rule** — `.cursor/rules/version-gated-feature-flags.mdc` enforces the same patterns for AI-assisted edits under `app/**/*.{ts,tsx}`. 3. **Cross-doc updates** — Perps, Predict, mUSD, and Compliance docs now link to the canonical guide and show correct import/usage examples instead of implying ad-hoc version checks. 4. **Repo hygiene** — `.gitignore` is updated to track `*.mdc` Cursor rules (matching the existing carve-out pattern for other IDE config), and `AGENTS.md` references the new guide in the development guidelines table and quick reference. No runtime or selector code changes — documentation and agent guidance only. ## **Changelog**  CHANGELOG entry: null ## **Related issues**  Refs: fixes: [MCWP-653](https://consensyssoftware.atlassian.net/browse/MCWP-653) ## **Manual testing steps**  N/A — documentation-only change. Verified by reading rendered markdown links and confirming `.cursor/rules/version-gated-feature-flags.mdc` is tracked after the `.gitignore` carve-out. ## **Screenshots/Recordings**  N/A — no UI changes. ### **Before** N/A ### **After** N/A ## **Pre-merge author checklist**  - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile Coding Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md). - [x] I've completed the PR template to the best of my ability - [x] I've included tests if applicable - [x] I've documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [x] I've applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. #### Performance checks (if applicable) - [ ] I've tested on Android - Ideally on a mid-range device; emulator is acceptable - [ ] I've tested with a power user scenario - Use these [power-user SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93) to import wallets with many accounts and tokens - [ ] I've instrumented key operations with Sentry traces for production performance metrics - See [`trace()`](/app/util/trace.ts) for usage and [`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274) for an example For performance guidelines and tooling, see the [Performance Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers). ## **Pre-merge reviewer checklist**  - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. [MCWP-653]: https://consensyssoftware.atlassian.net/browse/MCWP-653?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ  --- > [!NOTE] > **Low Risk** > Docs and agent guidance only; no runtime, selector, or feature-flag behavior changes. > > **Overview** > Adds a **canonical guide** at `docs/readme/version-gated-feature-flags.md` and a matching **Cursor rule** (`.cursor/rules/version-gated-feature-flags.mdc`) so contributors and agents use `validatedVersionGatedFeatureFlag` from `app/util/remoteFeatureFlag` in selectors instead of duplicating version checks. > > **Cross-links and examples** in Perps, Predict, mUSD, and Compliance docs now point at that guide and show the shared import pattern. **`AGENTS.md`** adds the guide to the dev guidelines table and quick reference. > > **`.gitignore`** is adjusted so tracked `*.mdc` rules under `.cursor/rules/` can be committed (carve-out for IDE config). No app or selector code changes. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 0388626. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Cursor <cursoragent@cursor.com>
diff --git a/.cursor/rules/version-gated-feature-flags.mdc b/.cursor/rules/version-gated-feature-flags.mdc
@@ -0,0 +1,97 @@
+---
+description: Use shared version-gated feature flag helpers; never duplicate hasMinimumRequiredVersion or validatedVersionGatedFeatureFlag
+globs: app/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# Version-Gated Feature Flags
+
+> Canonical human guide: [`docs/readme/version-gated-feature-flags.md`](../../docs/readme/version-gated-feature-flags.md)
+
+## Canonical source (SSOT)
+
+All version-gated feature flag logic lives in `app/util/remoteFeatureFlag/index.ts`:
+
+- `validatedVersionGatedFeatureFlag` — preferred for remote flags shaped as `{ enabled, minimumVersion }` (or progressive-rollout wrappers)
+- `hasMinimumRequiredVersion` — version comparison only; import when needed, never redefine
+
+## Required patterns
+
+### ✅ Use `validatedVersionGatedFeatureFlag` in selectors
+
+```typescript
+import { validatedVersionGatedFeatureFlag, VersionGatedFeatureFlag } from '../../../util/remoteFeatureFlag';
+
+export const selectMyFeatureEnabled = createSelector(
+  selectRemoteFeatureFlags,
+  (remoteFeatureFlags) => {
+    const remoteFlag = remoteFeatureFlags?.myFeature as unknown as VersionGatedFeatureFlag;
+    return validatedVersionGatedFeatureFlag(remoteFlag) ?? false;
+  },
+);
+```
+
+### ✅ Non-standard flag shapes — map, don't duplicate
+
+Configs that use `active` instead of `enabled` (e.g. `depositConfig`) must map to the canonical shape and call the shared helper:
+
+```typescript
+import { validatedVersionGatedFeatureFlag } from '../../../util/remoteFeatureFlag';
+
+return (
+  validatedVersionGatedFeatureFlag({
+    enabled: depositConfig.active ?? false,
+    minimumVersion: depositConfig.minimumVersion ?? '',
+  }) ?? false
+);
+```
+
+### ✅ Import `hasMinimumRequiredVersion` only from the util
+
+```typescript
+import { hasMinimumRequiredVersion } from '../../../util/remoteFeatureFlag';
+```
+
+Never copy the `compare-versions` + `getVersion` pattern into feature modules.
+
+## Forbidden patterns
+
+### ❌ Do not define local version-gating helpers
+
+```typescript
+// FORBIDDEN — duplicate of app/util/remoteFeatureFlag
+function hasMinimumRequiredVersion(minVersion: string) { ... }
+const validatedVersionGatedFeatureFlag = (flag: unknown) => { ... }
+```
+
+### ❌ Do not inline version checks for feature flags
+
+```typescript
+// FORBIDDEN
+import { getVersion } from 'react-native-device-info';
+import compareVersions from 'compare-versions';
+
+const ok = compareVersions.compare(getVersion(), flag.minimumVersion, '>=');
+```
+
+### ❌ Do not add duplicate utils under feature folders
+
+Do not create files like:
+
+- `app/components/UI/**/utils/hasMinimumRequiredVersion.ts`
+- `app/core/redux/slices/**/hasMinimumRequiredVersion.ts`
+
+## Where logic belongs
+
+| Layer | Responsibility |
+|-------|----------------|
+| `RemoteFeatureFlagController` | Fetch/store raw flags — **no** client version gating |
+| `app/util/remoteFeatureFlag` | Version comparison + `validatedVersionGatedFeatureFlag` |
+| Selectors (`featureFlagController`, `**/selectors/featureFlags`) | Call shared helpers; return `boolean` |
+| Hooks / components | `useSelector(selectXEnabled)` — not local version math |
+
+## Enforcement
+
+- **REJECT** new local definitions of `hasMinimumRequiredVersion` or `validatedVersionGatedFeatureFlag`
+- **REJECT** new `compare-versions` + `getVersion` usage for feature-flag gating outside `app/util/remoteFeatureFlag`
+- **REQUIRE** imports from `app/util/remoteFeatureFlag` for all version-gated flag checks
diff --git a/.gitignore b/.gitignore
@@ -220,10 +220,12 @@ release-signoffs.json
 .claude/skills/
 .claude/commands/
 .agents/skills/
-.cursor/rules/
+.cursor/rules/*
+!.cursor/rules/*.mdc
 .cursor/skills/
 .cursor/commands/
 # Carve-outs: IDE/bugbot config that must stay tracked
+!.cursor/rules/*.mdc
 !.cursor/BUGBOT.md
 !.cursor/hooks.json
 !.cursor/worktrees.json
diff --git a/AGENTS.md b/AGENTS.md
@@ -101,11 +101,12 @@ scripts/                  # Build and automation scripts
 
 **Detailed guidelines are in `docs/testing/`** (canonical, in-repo) and the `mms-*` skill set installed via `yarn skills` (Cursor / Codex / Claude harnesses):
 
-| Guide                                                                          | Scope                                             |
-| ------------------------------------------------------------------------------ | ------------------------------------------------- |
-| [`docs/testing/unit-testing.md`](docs/testing/unit-testing.md)                 | `*.test.*` files — test patterns, mocking, AAA    |
-| [`docs/testing/e2e-testing.md`](docs/testing/e2e-testing.md)                   | Detox smoke/regression — Page Objects, gestures   |
-| [`docs/testing/component-view-tests.md`](docs/testing/component-view-tests.md) | `*.view.test.tsx` — framework, presets, renderers |
+| Guide                                                                                      | Scope                                                                        |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| [`docs/testing/unit-testing.md`](docs/testing/unit-testing.md)                             | `*.test.*` files — test patterns, mocking, AAA                               |
+| [`docs/testing/e2e-testing.md`](docs/testing/e2e-testing.md)                               | Detox smoke/regression — Page Objects, gestures                              |
+| [`docs/testing/component-view-tests.md`](docs/testing/component-view-tests.md)             | `*.view.test.tsx` — framework, presets, renderers                            |
+| [`docs/readme/version-gated-feature-flags.md`](docs/readme/version-gated-feature-flags.md) | Version-gated remote flags — `validatedVersionGatedFeatureFlag` in selectors |
 
 General coding, UI, deeplink-handler, and PR-creation guidance now lives in the centralized `mms-*` skill set installed via `yarn skills` (see `.agents/skills/mms-*` after sync).
 
@@ -115,6 +116,7 @@ General coding, UI, deeplink-handler, and PR-creation guidance now lives in the
 - **Components**: Design system first → `component-library` second → custom last
 - **Styling**: Use `useTailwind()` hook, `Box`/`Text` components, design tokens
 - **Testing**: Mandatory for all code, AAA pattern, mock everything external
+- **Version-gated feature flags**: Use `validatedVersionGatedFeatureFlag` from `app/util/remoteFeatureFlag` in selectors — see [`docs/readme/version-gated-feature-flags.md`](docs/readme/version-gated-feature-flags.md) and [`.cursor/rules/version-gated-feature-flags.mdc`](.cursor/rules/version-gated-feature-flags.mdc)
 - **Commands**: ONLY use yarn (never npm/npx)
 
 ## Environment Setup
diff --git a/docs/compliance.md b/docs/compliance.md
@@ -50,7 +50,7 @@ To enable compliance:
 1. Set `complianceEnabled: true` in LaunchDarkly (or via the local feature flag override screen in dev builds).
 2. Compliance status will be fetched per-address whenever a gated action is triggered.
 
-> **Version gating:** The feature flag uses `validatedVersionGatedFeatureFlag`, which compares against the **native binary version** reported by `react-native-device-info`'s `getVersion()` — not `package.json`. If your device has a stale build installed, the version check may fail even if the flag is enabled. Do a clean native rebuild to pick up the correct version.
+> **Version gating:** The feature flag uses `validatedVersionGatedFeatureFlag` in `selectComplianceEnabled`, which compares against the **native binary version** reported by `react-native-device-info`'s `getVersion()` — not `package.json`. If your device has a stale build installed, the version check may fail even if the flag is enabled. Do a clean native rebuild to pick up the correct version.
 
 ### Feature flag selector
 
@@ -60,6 +60,8 @@ import { selectComplianceEnabled } from 'app/selectors/featureFlagController/com
 const isEnabled = useSelector(selectComplianceEnabled);
 ```
 
+The selector resolves the remote `{ enabled, minimumVersion }` payload via `validatedVersionGatedFeatureFlag`. See [`docs/readme/version-gated-feature-flags.md`](./readme/version-gated-feature-flags.md).
+
 ## Usage in Flows
 
 ### Option 1: `gate()` from `useComplianceGate` (recommended for action guards)
diff --git a/docs/musd/musd-convert-list.md b/docs/musd/musd-convert-list.md
@@ -461,9 +461,14 @@ export const selectMusdConversionStatuses = createSelector(
 
 **Path:** `app/components/UI/Earn/selectors/featureFlags/index.ts`
 
-Add new version-gated flag with local fallback (following the same pattern as other mUSD flags):
+Add new version-gated flag with local fallback (see [`docs/readme/version-gated-feature-flags.md`](../../readme/version-gated-feature-flags.md)):
 
 ```typescript
+import {
+  validatedVersionGatedFeatureFlag,
+  type VersionGatedFeatureFlag,
+} from '../../../../util/remoteFeatureFlag';
+
 export const selectMusdQuickConvertEnabledFlag = createSelector(
   selectRemoteFeatureFlags,
   (remoteFeatureFlags) => {
diff --git a/docs/perps/perps-feature-flags.md b/docs/perps/perps-feature-flags.md
@@ -7,7 +7,7 @@ Framework for controlling Perps feature availability through LaunchDarkly with l
 **Key Design Principles:**
 
 - LaunchDarkly is the single source of truth for feature enablement
-- Version-gated flags ensure features only activate on compatible app versions
+- Version-gated flags use `validatedVersionGatedFeatureFlag` from `app/util/remoteFeatureFlag` (see [Version-gated feature flags](../readme/version-gated-feature-flags.md))
 - Local environment variables provide development/testing fallback
 - Graceful degradation when LaunchDarkly is unavailable
 
@@ -74,6 +74,11 @@ See [Perps A/B Testing Framework](./perps-ab-testing.md) for variant-based flags
 **File:** `app/components/UI/Perps/selectors/featureFlags/index.ts`
 
 ```typescript
+import {
+  validatedVersionGatedFeatureFlag,
+  type VersionGatedFeatureFlag,
+} from '../../../../util/remoteFeatureFlag';
+
 /**
  * Selector for My Feature flag
  * Controls visibility of My Feature in the UI
@@ -230,12 +235,14 @@ These flags are managed via `FeatureFlagConfigurationService` and control runtim
 
 ### Version Gating
 
-The `minimumVersion` field ensures features only activate on compatible app versions:
+The `minimumVersion` field ensures features only activate on compatible app versions. **Do not** compare versions in selectors or components — use `validatedVersionGatedFeatureFlag`:
 
-- **Format:** Semantic version string (e.g., `"7.60.0"`)
-- **Comparison:** Uses `compare-versions` library with `>=` operator
+- **Format:** Semantic version string (e.g. `"7.60.0"`)
+- **Evaluation:** `validatedVersionGatedFeatureFlag(remoteFlag)` returns `true` only when `enabled` is true **and** the native app version is `>= minimumVersion`
 - **Use case:** Prevent feature activation on older app versions that lack required code
 
+See [`docs/readme/version-gated-feature-flags.md`](../readme/version-gated-feature-flags.md) for the full pattern and non-standard flag shapes.
+
 ---
 
 ## Troubleshooting
@@ -249,8 +256,8 @@ The `minimumVersion` field ensures features only activate on compatible app vers
 ### Version Gating Not Working
 
 1. **Verify `minimumVersion` format:** Must be valid semver string
-2. **Check app version:** `getVersion()` from `react-native-device-info`
-3. **Check comparison:** Uses `>=` operator
+2. **Check native app version:** `getVersion()` from `react-native-device-info` (used inside `validatedVersionGatedFeatureFlag`) — not `package.json`
+3. **Confirm selector uses the helper:** `validatedVersionGatedFeatureFlag(remoteFlag) ?? localFallback` — not inline `compare-versions`
 
 ### Local Flag Not Overriding
 
@@ -265,8 +272,9 @@ The `minimumVersion` field ensures features only activate on compatible app vers
 - **Selectors:** `app/components/UI/Perps/selectors/featureFlags/index.ts`
 - **Mocks:** `app/components/UI/Perps/mocks/remoteFeatureFlagMocks.ts`
 - **Tests:** `app/components/UI/Perps/selectors/featureFlags/index.test.ts`
-- **Version validation:** `app/util/remoteFeatureFlag/index.ts`
-- **Controller init:** `app/core/Engine/wallet-init/instance-options/remote-feature-flag-controller.ts` (RFFC instance options) and `app/core/Engine/wallet-init/initialization.ts` (constructed via `@metamask/wallet`)
+- **Version validation:** `app/util/remoteFeatureFlag/index.ts` (`validatedVersionGatedFeatureFlag`)
+- **Version-gated flags guide:** `docs/readme/version-gated-feature-flags.md`
+- **Controller init:** `app/core/Engine/controllers/remote-feature-flag-controller-init.ts`
 - **Configuration service:** `app/controllers/perps/services/FeatureFlagConfigurationService.ts`
 
 ---
diff --git a/docs/predict/live-nfl-architecture.md b/docs/predict/live-nfl-architecture.md
@@ -8,10 +8,15 @@ The Live NFL feature introduces real-time sports betting functionality with WebS
 
 ## Feature Flag
 
-The feature is gated behind `predictLiveNflEnabled`:
+The feature is gated behind `predictLiveNflEnabled` using `validatedVersionGatedFeatureFlag` (see [`docs/readme/version-gated-feature-flags.md`](../readme/version-gated-feature-flags.md)):
 
 ```typescript
 // app/components/UI/Predict/selectors/featureFlags/index.ts
+import {
+  validatedVersionGatedFeatureFlag,
+  type VersionGatedFeatureFlag,
+} from '../../../../util/remoteFeatureFlag';
+
 export const selectPredictLiveNflEnabled = createSelector(
   selectRemoteFeatureFlags,
   (remoteFeatureFlags) => {
diff --git a/docs/predict/tasks/00-feature-flag-and-types.md b/docs/predict/tasks/00-feature-flag-and-types.md
@@ -27,6 +27,11 @@ Set up the feature flag for Live NFL and define all necessary TypeScript types f
 Create/update `app/components/UI/Predict/selectors/featureFlags/index.ts`:
 
 ```typescript
+import {
+  validatedVersionGatedFeatureFlag,
+  type VersionGatedFeatureFlag,
+} from '../../../../util/remoteFeatureFlag';
+
 /**
  * Selector for Predict Live NFL feature enablement
  */
diff --git a/docs/readme/version-gated-feature-flags.md b/docs/readme/version-gated-feature-flags.md
@@ -0,0 +1,97 @@
+# Version-Gated Feature Flags
+
+Canonical guide for evaluating remote feature flags that include a minimum app version. Applies to all teams (Ramp, Perps, Money, Predict, platform selectors, etc.).
+
+## SSOT
+
+| Concern                              | Location                                                                               |
+| ------------------------------------ | -------------------------------------------------------------------------------------- |
+| Version comparison + flag validation | [`app/util/remoteFeatureFlag/index.ts`](../../app/util/remoteFeatureFlag/index.ts)     |
+| Raw flag storage                     | `RemoteFeatureFlagController.remoteFeatureFlags` (no client version gating)            |
+| Boolean for UI / hooks               | Selectors under `app/selectors/featureFlagController/` or `**/selectors/featureFlags/` |
+
+**Always use** `validatedVersionGatedFeatureFlag` in selectors. **Never** duplicate `hasMinimumRequiredVersion` or `validatedVersionGatedFeatureFlag` in feature modules.
+
+`hasMinimumRequiredVersion` is a lower-level helper used inside `validatedVersionGatedFeatureFlag`. Import it from the util only when you need a standalone version check — do not reimplement it.
+
+## Flag shapes
+
+### Standard (preferred)
+
+LaunchDarkly JSON:
+
+```json
+{
+  "enabled": true,
+  "minimumVersion": "7.65.0"
+}
+```
+
+Progressive-rollout wrappers (`{ name, value: { enabled, minimumVersion } }`) are normalized automatically.
+
+### Non-standard configs
+
+Some flags use different property names (e.g. `depositConfig` uses `active` instead of `enabled`). **Map** to the canonical shape before calling the helper:
+
+```typescript
+validatedVersionGatedFeatureFlag({
+  enabled: depositConfig.active ?? false,
+  minimumVersion: depositConfig.minimumVersion ?? '',
+}) ?? false;
+```
+
+### Multi-version flags (controller-processed)
+
+`RemoteFeatureFlagController` resolves flags shaped as `{ versions: { "7.53.0": value, "7.60.0": value } }` at fetch time using `clientVersion`. Consumers read the **processed** value from state — no `validatedVersionGatedFeatureFlag` call needed for that shape.
+
+## Implementation pattern
+
+### 1. Selector (required)
+
+```typescript
+import { createSelector } from 'reselect';
+import { selectRemoteFeatureFlags } from '../index'; // adjust path
+import {
+  validatedVersionGatedFeatureFlag,
+  type VersionGatedFeatureFlag,
+} from '../../../util/remoteFeatureFlag';
+
+export const selectMyFeatureEnabled = createSelector(
+  selectRemoteFeatureFlags,
+  (remoteFeatureFlags) => {
+    const localFlag = process.env.MM_MY_FEATURE_ENABLED === 'true';
+    const remoteFlag =
+      remoteFeatureFlags?.myFeature as unknown as VersionGatedFeatureFlag;
+
+    return validatedVersionGatedFeatureFlag(remoteFlag) ?? localFlag;
+  },
+);
+```
+
+- Remote flag wins when valid; `undefined` from the helper triggers env/local fallback.
+- When `OVERRIDE_REMOTE_FEATURE_FLAGS=true`, the helper returns `undefined` so local overrides apply.
+
+### 2. Hook or component
+
+```typescript
+const isEnabled = useSelector(selectMyFeatureEnabled);
+```
+
+Do not call `getVersion()`, `compare-versions`, or local version helpers in hooks/components.
+
+## Version source
+
+`validatedVersionGatedFeatureFlag` compares against the **native binary version** from `react-native-device-info`'s `getVersion()` — not `package.json`. After a version bump, do a clean native rebuild if gating behaves unexpectedly.
+
+## Forbidden
+
+- Local `function hasMinimumRequiredVersion(...)` copies
+- Inline `compareVersions.compare(getVersion(), minimumVersion, '>=')` for feature flags
+- Duplicate util files under `app/components/UI/**/utils/` or `app/core/redux/slices/**/`
+
+## Related
+
+- [Perps feature flags](../perps/perps-feature-flags.md) — team-specific examples
+- [Compliance OFAC gating](../compliance.md#feature-flag) — real selector using this pattern
+- [`.cursor/rules/version-gated-feature-flags.mdc`](../../.cursor/rules/version-gated-feature-flags.mdc) — Cursor agent rule
+- External: [MetaMask remote feature flags](https://github.com/MetaMask/contributor-docs/blob/main/docs/remote-feature-flags.md)
