chore(runway): cherry-pick fix(card): update feature flag listener on CardController (#29376)

- fix(card): update feature flag listener on CardController (#29350)

<!--
Please submit this PR as a draft initially.

Do not mark it as "Ready for review" until this PR meets the canonical
Definition of Ready For Review in `docs/readme/ready-for-review.md`.

In short: the template must be materially complete (not just section
titles
present), all status checks must be currently passing, and the only
expected
follow-up commits must be reviewer-driven.
-->

## **Description**

This branch refreshes **card home data and Baanx configuration** when
**remote card feature flags** change, and fixes a **race** where a slow
**unauthenticated** `fetchCardHomeData` could overwrite state **after**
successful **submitCredentials**.

**Feature flags**

-

[`app/selectors/featureFlagController/card/index.ts`](app/selectors/featureFlagController/card/index.ts):
exports **`defaultCardFeatureFlag`** and **`resolveCardFeatureFlag`**
(empty remote payload → defaults). **`selectCardFeatureFlag`** now uses
**`resolveCardFeatureFlag`** so the same resolution rules apply in Redux
selectors and Engine.

**BaanxProvider / init**

-

[`BaanxProvider.ts`](app/core/Engine/controllers/card-controller/providers/BaanxProvider.ts):
accepts optional **`getCardFeatureFlag`** (lazy) in addition to legacy
**`cardFeatureFlag`**. A private getter resolves **`cardFeatureFlag`**
on each read so URLs/constants track the latest remote flags without
recreating the provider.
-

[`card-controller/index.ts`](app/core/Engine/controllers/card-controller/index.ts):
passes **`getCardFeatureFlag`** from
**`RemoteFeatureFlagController:getState`** +
**`resolveCardFeatureFlag`** into **`BaanxProvider`**.

**CardController**

- Subscribes to **`RemoteFeatureFlagController:stateChange`** with a
**selector** that serializes **`remoteFeatureFlags.cardFeature`** so
only meaningful card-flag updates run the handler.
- **`#handleCardFeatureFlagChange`**: if an EVM address is selected,
**`invalidateFetch()`**, clears **`cardHomeData`** / sets
**`cardHomeDataStatus`** to **`idle`**, then refetches card home data.
- **`#fetchCardHomeDataWithLogging`**: centralizes
**`fetchCardHomeData`** + **`Logger.error`** for account switch,
feature-flag refresh, **`submitCredentials`**, and
**`validateAndRefreshSession`**.
- **`#triggerCardholderCheck`** (accounts API URL path): uses
**`resolveCardFeatureFlag`** instead of ad-hoc casting.
- **`submitCredentials`**: sets **`cardHomeData`** to **`null`** and
status **`idle`**, calls **`invalidateFetch()`**, then fetches—so
in-flight unauthenticated responses cannot win over authenticated data.

**Messenger / types**

-

[`card-controller-messenger/index.ts`](app/core/Engine/messengers/card-controller-messenger/index.ts):
allows event **`RemoteFeatureFlagController:stateChange`**.
- [`types.ts`](app/core/Engine/controllers/card-controller/types.ts):
**`CardControllerAllowedEvents`** includes
**`RemoteFeatureFlagControllerStateChangeEvent`**.

**Tests**

-

[`CardController.test.ts`](app/core/Engine/controllers/card-controller/CardController.test.ts):
subscription to remote feature-flag state; handler clears state and
refetches; **`drops in-flight unauthenticated card home data after
successful auth`**.
-

[`BaanxProvider.test.ts`](app/core/Engine/controllers/card-controller/providers/BaanxProvider.test.ts):
**`getCardFeatureFlag`** read **lazily** during **`getOnChainAssets`**.

## **Changelog**

CHANGELOG entry: Card — **`CardController`** listens for
**`RemoteFeatureFlagController:stateChange`** and refetches card home
data when **`cardFeature`** changes; **`BaanxProvider`** resolves card
feature flags lazily; shared **`resolveCardFeatureFlag`**;
**`submitCredentials`** invalidates in-flight fetches and resets card
home state to avoid stale unauthenticated data after login.

## **Related issues**

Fixes: #29348

<!-- Add GitHub issue link when available, e.g. Fixes #12345 -->

## **Manual testing steps**

```gherkin
Feature: Card home and Baanx flags stay in sync with remote card feature flags

  Scenario: Remote card feature flag updates while card tab is open
    Given the user is on an EVM account with card session and card home loaded
    When remote `cardFeature` changes (e.g. rollout or config update)
    Then card home data is cleared to idle and refetched
    And Baanx-backed calls use the updated flag-derived config on subsequent requests

  Scenario: Login while an unauthenticated card home fetch is still in flight
    Given an unauthenticated card home fetch has not completed
    When the user completes submitCredentials successfully
    Then authenticated card home data wins and a late unauthenticated response does not overwrite it

  Scenario: Card feature flag change with no selected EVM address
    When RemoteFeatureFlagController emits a card-related change but no EVM address is selected
    Then the handler returns early without refetch errors
```

## **Screenshots/Recordings**

<!-- Optional: behavior is mostly data-layer; attach if you verify on
device after a forced remote flag change. -->

### **Before**

<!-- Card home could stay stale until manual refresh; rare stale data
after fast login during slow unauthenticated fetch. -->

### **After**

<!-- Card home refetches when `cardFeature` changes; submitCredentials
path drops stale in-flight unauthenticated results. -->

## **Pre-merge author checklist**

<!--
Every checklist item must be consciously assessed before marking this PR
as
"Ready for review". A checked box means you deliberately considered that
responsibility, not that you literally performed every action listed.

Unchecked boxes are ambiguous: they are not an implicit "N/A" and they
are not
a silent "skip". See `docs/readme/ready-for-review.md` for the full
checklist
semantics.
-->

- [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**

<!--
Reviewer checklist items follow the same semantics as the author
checklist: an
unchecked box means the reviewer consciously assessed that
responsibility. See
`docs/readme/ready-for-review.md`.
-->

- [ ] 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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Updates card state refresh triggers and fetch invalidation logic
around auth and feature-flag changes; risk is moderate due to new event
subscriptions and potential for extra network calls or missed updates if
selectors are wrong.
> 
> **Overview**
> **Card home data now refreshes when remote `cardFeature` flags
change.** `CardController` subscribes to
`RemoteFeatureFlagController:stateChange`, clears `cardHomeData`/status
back to `idle`, invalidates any in-flight fetch, and refetches.
> 
> **Fixes a race where slow unauthenticated fetches could overwrite
authenticated state.** After successful `submitCredentials`, the
controller resets home data, bumps the fetch generation, and refetches
via a shared `#fetchCardHomeDataWithLogging` helper (also used by
account-switch and session refresh paths).
> 
> **Feature-flag resolution and consumption were tightened.** Adds
`resolveCardFeatureFlag` (and exports `defaultCardFeatureFlag`) to
normalize empty remote payloads to defaults; `BaanxProvider` can now
read flags lazily via a `getCardFeatureFlag` callback wired in
`cardControllerInit`, and the card-controller messenger/types allow the
new remote-flag stateChange event.
> 
> Tests add coverage for the new subscription behavior, the stale-fetch
drop after auth, and lazy flag reads in `BaanxProvider`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
0d9863b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
[890ac4a](890ac4a)

Co-authored-by: Bruno Nascimento <brunonascimentodev@gmail.com>

Author: runway-github[bot]

app/core/Engine/controllers/card-controller/CardController.test.ts

@@ -24,6 +24,12 @@ jest.mock('../../../../util/Logger');
 
 const mockTokenStore = CardTokenStore as jest.Mocked<typeof CardTokenStore>;
 
+async function flushPromises(times = 5): Promise<void> {
+  for (let i = 0; i < times; i++) {
+    await Promise.resolve();
+  }
+}
+
 function buildMessenger() {
   return new Messenger<
     'CardController',
@@ -314,6 +320,71 @@ describe('CardController — auth methods', () => {
       expect(result.done).toBe(true);
     });
 
+    it('drops in-flight unauthenticated card home data after successful auth', async () => {
+      const staleAsset = { ...mockAsset, symbol: 'STALE' };
+      const staleHomeData = {
+        ...mockCardHomeData,
+        primaryFundingAsset: staleAsset,
+        fundingAssets: [staleAsset],
+      };
+      const authenticatedAsset = { ...mockAsset, symbol: 'AUTH' };
+      const authenticatedHomeData = {
+        ...mockCardHomeData,
+        primaryFundingAsset: authenticatedAsset,
+        fundingAssets: [authenticatedAsset],
+      };
+      let resolveStaleFetch: (data: CardHomeData) => void = () => undefined;
+
+      const provider = buildMockProvider();
+      const getOnChainAssetsMock =
+        provider.getOnChainAssets as jest.MockedFunction<
+          NonNullable<ICardProvider['getOnChainAssets']>
+        >;
+      provider.initiateAuth.mockResolvedValue(mockSession);
+      provider.submitCredentials.mockResolvedValue({
+        done: true,
+        tokenSet: mockTokenSet,
+      });
+      getOnChainAssetsMock.mockReturnValue(
+        new Promise<CardHomeData>((resolve) => {
+          resolveStaleFetch = resolve;
+        }),
+      );
+      provider.validateTokens.mockReturnValue('valid');
+      provider.getCardHomeData.mockResolvedValue(authenticatedHomeData);
+      mockTokenStore.get
+        .mockResolvedValueOnce(null)
+        .mockResolvedValue(mockTokenSet);
+      mockTokenStore.set.mockResolvedValue(true);
+
+      const { controller } = buildControllerWithMockMessenger(provider);
+      const staleFetchPromise = controller.fetchCardHomeData();
+      await flushPromises();
+
+      expect(getOnChainAssetsMock).toHaveBeenCalledTimes(1);
+
+      await controller.initiateAuth('US');
+      await controller.submitCredentials({
+        type: 'email_password',
+        email: 'a@b.com',
+        password: 'pass',
+      });
+      await flushPromises();
+
+      expect(provider.getCardHomeData).toHaveBeenCalledTimes(1);
+      expect(controller.state.cardHomeData).toStrictEqual(
+        authenticatedHomeData,
+      );
+
+      resolveStaleFetch(staleHomeData);
+      await staleFetchPromise;
+      await flushPromises();
+
+      expect(controller.state.cardHomeData).toStrictEqual(
+        authenticatedHomeData,
+      );
+    });
+
     it('still sets isAuthenticated when token store write fails', async () => {
       const provider = buildMockProvider();
       provider.initiateAuth.mockResolvedValue(mockSession);
@@ -646,6 +717,46 @@ describe('CardController — event subscriptions', () => {
     );
   });
 
+  it('subscribes to RemoteFeatureFlagController:stateChange on construction', () => {
+    const mockMessenger = buildMockMessenger();
+    new CardController({
+      messenger: mockMessenger,
+      providers: {},
+    });
+
+    expect(mockMessenger.subscribe).toHaveBeenCalledWith(
+      'RemoteFeatureFlagController:stateChange',
+      expect.any(Function),
+      expect.any(Function),
+    );
+  });
+
+  it('clears and refetches card home data when the card feature flag changes', () => {
+    const provider = buildMockProvider();
+    const { controller, messenger } = buildControllerWithMockMessenger(
+      provider,
+      {
+        cardHomeData: mockCardHomeData as unknown as Record<string, null>,
+        cardHomeDataStatus: 'success',
+      },
+    );
+    const fetchSpy = jest
+      .spyOn(controller, 'fetchCardHomeData')
+      .mockResolvedValue();
+
+    const remoteFeatureFlagHandler = (
+      messenger.subscribe as jest.Mock
+    ).mock.calls.find(
+      ([event]) => event === 'RemoteFeatureFlagController:stateChange',
+    )?.[1];
+
+    remoteFeatureFlagHandler?.('{}');
+
+    expect(controller.state.cardHomeData).toBeNull();
+    expect(controller.state.cardHomeDataStatus).toBe('idle');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
   it('calls validateAndRefreshSession on KeyringController:unlock', async () => {
     const provider = buildMockProvider();
     mockTokenStore.get.mockResolvedValue(null);

app/core/Engine/controllers/card-controller/CardController.ts

@@ -37,6 +37,10 @@ import {
 import { CardTokenStore } from './CardTokenStore';
 import { isEthAccount } from '../../../Multichain/utils';
 import { pickPrimaryFromReordered, reorderAssets } from './utils/assetPriority';
+import {
+  resolveCardFeatureFlag,
+  type CardFeatureFlag,
+} from '../../../../selectors/featureFlagController/card';
 
 const CARDHOLDER_BATCH_SIZE = 50;
 const CARDHOLDER_MAX_BATCHES = 3;
@@ -170,6 +174,26 @@ export class CardController extends BaseController<
           .sort()
           .join(','),
     );
+
+    this.messenger.subscribe(
+      'RemoteFeatureFlagController:stateChange',
+      (_cardFeatureKey: string) => {
+        this.#handleCardFeatureFlagChange();
+      },
+      (state) => JSON.stringify(state.remoteFeatureFlags?.cardFeature ?? {}),
+    );
+  }
+
+  #fetchCardHomeDataWithLogging(method: string): void {
+    this.fetchCardHomeData().catch((error) =>
+      Logger.error(error as Error, {
+        tags: { feature: 'card' },
+        context: {
+          name: 'CardController',
+          data: { method },
+        },
+      }),
+    );
   }
 
   #handleAccountSwitch(): void {
@@ -182,18 +206,22 @@ export class CardController extends BaseController<
         s.cardHomeData = null;
         s.cardHomeDataStatus = 'idle';
       });
-      this.fetchCardHomeData().catch((error) =>
-        Logger.error(error as Error, {
-          tags: { feature: 'card' },
-          context: {
-            name: 'CardController',
-            data: { method: '#handleAccountSwitch' },
-          },
-        }),
-      );
+      this.#fetchCardHomeDataWithLogging('#handleAccountSwitch');
     }
   }
 
+  #handleCardFeatureFlagChange(): void {
+    const currentAddress = this.#getSelectedEvmAddress();
+    if (!currentAddress) return;
+
+    this.invalidateFetch();
+    this.update((s) => {
+      s.cardHomeData = null;
+      s.cardHomeDataStatus = 'idle';
+    });
+    this.#fetchCardHomeDataWithLogging('#handleCardFeatureFlagChange');
+  }
+
   #triggerCardholderCheck(): void {
     // Debounce: coalesce rapid consecutive triggers (e.g. KeyringController:unlock
     // and AccountTreeController:stateChange both fire on wallet unlock) into a
@@ -220,9 +248,11 @@ export class CardController extends BaseController<
       const featureState = this.messenger.call(
         'RemoteFeatureFlagController:getState',
       );
-      const cardFeature = featureState.remoteFeatureFlags?.cardFeature as
-        | { constants?: { accountsApiUrl?: string } }
-        | undefined;
+      const cardFeature = resolveCardFeatureFlag(
+        featureState.remoteFeatureFlags?.cardFeature as
+          | CardFeatureFlag
+          | undefined,
+      );
       const accountsApiUrl = cardFeature?.constants?.accountsApiUrl;
       if (!accountsApiUrl) return;
 
@@ -475,19 +505,14 @@ export class CardController extends BaseController<
       }
       this.update((s) => {
         s.isAuthenticated = true;
+        s.cardHomeData = null;
+        s.cardHomeDataStatus = 'idle';
         (s.providerData as unknown as Record<string, Record<string, string>>)[
           pid
         ] = { location: tokenSet.location };
       });
-      this.fetchCardHomeData().catch((error) =>
-        Logger.error(error as Error, {
-          tags: { feature: 'card' },
-          context: {
-            name: 'CardController',
-            data: { method: 'submitCredentials/fetchCardHomeData' },
-          },
-        }),
-      );
+      this.invalidateFetch();
+      this.#fetchCardHomeDataWithLogging('submitCredentials/fetchCardHomeData');
     }
 
     return result;
@@ -541,14 +566,8 @@ export class CardController extends BaseController<
 
     // Always fetch card home data regardless of auth state: authenticated users
     // get full card data, unauthenticated users get on-chain asset state.
-    this.fetchCardHomeData().catch((error) =>
-      Logger.error(error as Error, {
-        tags: { feature: 'card' },
-        context: {
-          name: 'CardController',
-          data: { method: 'validateAndRefreshSession/fetchCardHomeData' },
-        },
-      }),
+    this.#fetchCardHomeDataWithLogging(
+      'validateAndRefreshSession/fetchCardHomeData',
     );
 
     if (!tokens) return { isAuthenticated: false };

app/core/Engine/controllers/card-controller/index.ts

@@ -4,7 +4,10 @@ import type { CardControllerMessenger } from './types';
 import { BaanxService } from './services/BaanxService';
 import { BaanxProvider } from './providers/BaanxProvider';
 import { resolveBaanxConfig } from './services/baanx-config';
-import type { CardFeatureFlag } from '../../../../selectors/featureFlagController/card';
+import {
+  resolveCardFeatureFlag,
+  type CardFeatureFlag,
+} from '../../../../selectors/featureFlagController/card';
 
 /**
  * Initialize the CardController.
@@ -18,17 +21,21 @@ export const cardControllerInit: MessengerClientInitFunction<
 > = (request) => {
   const { controllerMessenger, persistedState } = request;
 
-  const featureState = controllerMessenger.call(
-    'RemoteFeatureFlagController:getState',
-  );
-  const cardFeatureFlag = featureState.remoteFeatureFlags?.cardFeature as
-    | CardFeatureFlag
-    | undefined;
+  const getCardFeatureFlag = () => {
+    const featureState = controllerMessenger.call(
+      'RemoteFeatureFlagController:getState',
+    );
+    return resolveCardFeatureFlag(
+      featureState.remoteFeatureFlags?.cardFeature as
+        | CardFeatureFlag
+        | undefined,
+    );
+  };
 
   const baanxConfig = resolveBaanxConfig();
   const baanxProvider = new BaanxProvider({
     service: new BaanxService(baanxConfig),
-    cardFeatureFlag,
+    getCardFeatureFlag,
   });
 
   const controller = new CardController({

app/core/Engine/controllers/card-controller/providers/BaanxProvider.test.ts

@@ -688,6 +688,27 @@ describe('BaanxProvider', () => {
       );
     });
 
+    it('reads card feature flags lazily when checking on-chain assets', async () => {
+      spendersMock.mockResolvedValue([limitedTuple('50'), limitedTuple('0')]);
+      let currentCardFeatureFlag: CardFeatureFlag | null = null;
+
+      const p = new BaanxProvider({
+        service,
+        getCardFeatureFlag: () => currentCardFeatureFlag,
+      });
+      currentCardFeatureFlag = cardFeatureFlag;
+
+      const result = await p.getOnChainAssets(ownerAddr);
+
+      expect(spendersMock).toHaveBeenCalledWith(
+        ownerAddr,
+        [tokenA, tokenB],
+        expect.any(Array),
+      );
+      expect(result.primaryFundingAsset?.symbol).toBe('USDC');
+      expect(result.primaryFundingAsset?.address).toBe(tokenA);
+    });
+
     it('uses #findLastApprovedToken when multiple tokens have non-zero allowance and prefers latest Approval log', async () => {
       spendersMock.mockResolvedValue([limitedTuple('10'), limitedTuple('20')]);
 

app/core/Engine/controllers/card-controller/providers/BaanxProvider.ts

@@ -247,17 +247,24 @@ export class BaanxProvider implements ICardProvider {
   }
 
   private readonly service: BaanxService;
-  private readonly cardFeatureFlag: CardFeatureFlag | null;
+  private readonly getCardFeatureFlag: () => CardFeatureFlag | null;
 
   constructor({
     service,
     cardFeatureFlag,
+    getCardFeatureFlag,
   }: {
     service: BaanxService;
     cardFeatureFlag?: CardFeatureFlag;
+    getCardFeatureFlag?: () => CardFeatureFlag | null | undefined;
   }) {
     this.service = service;
-    this.cardFeatureFlag = cardFeatureFlag ?? null;
+    this.getCardFeatureFlag = () =>
+      getCardFeatureFlag?.() ?? cardFeatureFlag ?? null;
+  }
+
+  private get cardFeatureFlag(): CardFeatureFlag | null {
+    return this.getCardFeatureFlag();
   }
 
   // -- Auth --

app/core/Engine/controllers/card-controller/types.ts

@@ -13,7 +13,10 @@ import type {
   KeyringControllerUnlockEvent,
   KeyringControllerSignPersonalMessageAction,
 } from '@metamask/keyring-controller';
-import type { RemoteFeatureFlagControllerGetStateAction } from '@metamask/remote-feature-flag-controller';
+import type {
+  RemoteFeatureFlagControllerGetStateAction,
+  RemoteFeatureFlagControllerStateChangeEvent,
+} from '@metamask/remote-feature-flag-controller';
 import type { NetworkControllerFindNetworkClientIdByChainIdAction } from '@metamask/network-controller';
 import type { TransactionControllerAddTransactionAction } from '@metamask/transaction-controller';
 import type { CardHomeData } from './provider-types';
@@ -71,6 +74,7 @@ type CardControllerAllowedActions =
 
 type CardControllerAllowedEvents =
   | AccountTreeControllerStateChangeEvent
+  | RemoteFeatureFlagControllerStateChangeEvent
   | KeyringControllerUnlockEvent;
 
 export type CardControllerMessenger = Messenger<

app/core/Engine/messengers/card-controller-messenger/index.ts

@@ -35,7 +35,11 @@ export function getCardControllerMessenger(
       'NetworkController:findNetworkClientIdByChainId',
       'TransactionController:addTransaction',
     ],
-    events: ['AccountTreeController:stateChange', 'KeyringController:unlock'],
+    events: [
+      'AccountTreeController:stateChange',
+      'RemoteFeatureFlagController:stateChange',
+      'KeyringController:unlock',
+    ],
   });
 
   return messenger;