chore: implement rewards version guard

[sophieqgu]

Description

https://consensyssoftware.atlassian.net/browse/RWDS-1119
Fetch minimum required client versions from backend and prompt user to update if app version is not met

Changelog

CHANGELOG entry: null

Related issues

Fixes:

Manual testing steps

Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]

Screenshots/Recordings

Before

After

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

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.

---

Note

Medium Risk
Adds a backend-driven minimum-version check that can block entry into the Rewards flow and introduces new API/messenger wiring plus Redux state to support it. Risk is moderate because it changes navigation behavior and introduces a new network call/caching path in the Rewards controller/data service.

Overview
Adds a Rewards version guard: the app fetches minimum client version requirements from a new public Rewards API endpoint and stores them in Redux, then uses selectIsRewardsVersionBlocked to determine if the current app version is allowed.

When blocked, RewardsNavigator now short-circuits normal navigation/rendering and shows a new RewardsUpdateRequired screen with an update CTA (App Store/Play Store) and new MetaMetrics events for view/click tracking.

Extends the Rewards engine stack (data service + controller + messenger + types) with getClientVersionRequirements, adds version-guard reducers/selectors and tests, and refactors candidate subscription ID reset logic to preserve the new version-guard fields (plus other non-subscription-scoped state).

^{Written by Cursor Bugbot for commit 3c9d911. This will update automatically on new commits. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokePerps, SmokeWalletPlatform, SmokeTrade, SmokeConfirmations
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 72%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes introduce a new "version guard" feature for the Rewards system. Key changes include:

1. RewardsController - New getClientVersionRequirements action that fetches minimum app version from the backend API (cached per session)
2. RewardsDataService - New API endpoint call to /public/client-version-requirements
3. RewardsNavigator - Now conditionally renders RewardsUpdateRequired component when the app version is below the minimum required, blocking access to Rewards
4. useRewardsVersionGuard - New hook that fires on screen focus to fetch version requirements
5. Redux reducer - New version guard state fields added; also refactored the setCandidateSubscriptionId reset logic using Object.assign (potential regression risk)
6. New selectors - selectIsRewardsVersionBlocked using hasMinimumRequiredVersion utility
7. Analytics - Two new events: REWARDS_VERSION_GUARD_VIEWED and REWARDS_VERSION_GUARD_UPDATE_CLICKED

Tag Selection Rationale:

• SmokePerps: Rewards is directly related to the Perps feature area; the Perps tag description explicitly mentions Rewards-related flows and the RewardsNavigator is the entry point
• SmokeWalletPlatform: Rewards/Trending tab integration - the Rewards feature is embedded in the Trending tab which is tested under SmokeWalletPlatform; the reducer refactoring could affect state management across the platform
• SmokeTrade: The TradeWalletActions menu provides entry points to Rewards-adjacent features; the reducer changes could affect trade-related state
• SmokeConfirmations: Required as a dependent tag when selecting SmokePerps (per tag description: "When selecting SmokePerps, also select SmokeWalletPlatform and SmokeConfirmations")

No E2E tests specifically for Rewards were found in the test directories, so these tags cover the closest related test suites. The risk is medium because the changes are additive but include a refactoring of the Redux reset logic that could introduce regressions in state management.

Performance Test Selection:
The changes add a new lightweight API call (getClientVersionRequirements) that is cached in memory after the first fetch per session. This is a simple GET request to a public endpoint and is unlikely to impact any performance metrics. The UI changes (RewardsUpdateRequired component) are a simple static screen that only renders when the version is blocked. No changes to account lists, asset loading, login flows, or other performance-sensitive areas were made.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[cursor]

Rehydration sets campaigns to undefined for upgrading users

High Severity

The persist/REHYDRATE handler now explicitly assigns campaigns and campaignParticipantStatuses from the persisted payload. For users upgrading from an older app version where these fields were never persisted, action.payload.rewards.campaigns will be undefined. Since explicit undefined values override spread defaults, the resulting state will have campaigns: undefined instead of campaigns: [] (from ...initialState). Any downstream code calling .map(), .length, or iterating over campaigns will throw a runtime error.

 

[cursor]

Subscription ID change now resets previously preserved state fields

Medium Severity

The setCandidateSubscriptionId reducer was refactored from a whitelist (reset specific fields) to a blacklist (Object.assign with initialState, preserve listed fields). This silently changes behavior: campaigns, campaignParticipantStatuses, seasonStatusLoading, seasonStatusError, and several other loading/error fields are now reset on subscription change when they were previously preserved. Notably, campaigns is likely not subscription-scoped, so clearing it causes unnecessary data loss and potential UI flicker.

 

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
15 value mismatches detected (expected — fixture represents an existing user).
View details

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud