chore(runway): cherry-pick feat: Clear stuck pending perps withdraws from app state cp-7.62.0 (#24596)

- feat: Clear stuck pending perps withdraws from app state cp-7.62.0
(#24449)

## **Description**

This PR addresses multiple scenarios where Perps withdrawal requests
could get stuck in a "pending" or "bridging" state, causing stuck
loading indicators in the UI.

**Problem**
1. Users upgrading to a new app version may have stuck pending
withdrawals from before the withdrawal flow fixes
2. The updatedWithdrawalIdsRef in useWithdrawalRequests was not cleared
on account switch, potentially causing stale updates if withdrawal IDs
overlap across accounts
3. Users had no way to manually clear stuck pending transactions

**Solution**
1. Migration 110: Automatically clears pending/bridging withdrawal
requests during app upgrade, preserving completed/failed ones for
transaction history
2. Account switch cleanup: Added effect to clear the
updatedWithdrawalIdsRef when selectedAddress changes
3. Reset Account integration: Added clearPendingTransactionRequests()
method to PerpsController, exposed via usePerpsFirstTimeUser hook, and
integrated into the Reset Account flow in Advanced Settings

## **Changelog**

CHANGELOG entry: Fixed stuck pending withdrawal indicators in Perps
trading by clearing stale transaction requests on app upgrade and
account switch

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/TAT-2365

## **Manual testing steps**

```gherkin
Feature: Clear stuck pending Perps withdrawals

  Scenario: User upgrades app with stuck pending withdrawals
    Given user has pending withdrawal requests stuck from previous app version

    When user upgrades to new app version
    Then pending/bridging withdrawal requests are cleared
    And completed/failed withdrawal requests are preserved

  Scenario: User switches accounts with pending withdrawals
    Given user has account A with pending withdrawals
    And user switches to account B

    When user views Perps withdrawal status
    Then account B withdrawals are processed correctly
    And account A withdrawal IDs don't interfere with account B

  Scenario: User manually resets account
    Given user has stuck pending Perps transactions
    And user navigates to Settings > Advanced

    When user taps "Reset Account" and confirms
    Then pending/bridging Perps transactions are cleared
    And Perps first-time user state is reset
 ```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **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.

## **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.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Resolve stuck Perps transaction indicators and improve state handling**
> 
> - **Adds `clearPendingTransactionRequests` to `PerpsController`**: filters out `pending`/`bridging` entries from `withdrawalRequests` and `depositRequests`, and resets `withdrawalProgress`; exposes as `PerpsController:clearPendingTransactionRequests` action. Includes comprehensive unit tests.
> - **Migration 112**: on upgrade, cleans `PerpsController.withdrawalRequests` by removing `pending`/`bridging` (and invalid) entries and resets `withdrawalProgress`; preserves `completed`/`failed`. Registered in `migrations/index.ts` with extensive tests.
> - **UI integration**: `usePerpsFirstTimeUser` now exposes `clearPendingTransactionRequests`; `ResetAccountModal` invokes it during account reset to clear stuck Perps transactions. Hook tests updated to cover new method and undefined controller safety.
> - **Withdrawal UX/logging**: `useWithdrawalRequests` refactored to use `useStableArray`, track previous states, log only meaningful changes (initialized/status updates), and clear `updatedWithdrawalIdsRef` on account switch. Tests updated accordingly.
> 
> <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 9016f92. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

 [2b417ee](2b417ee)

Co-authored-by: Nick Gambino <35090461+gambinish@users.noreply.github.com>

Author: runway-github[bot]

app/components/UI/Perps/controllers/PerpsController.test.ts

@@ -2909,6 +2909,131 @@ describe('PerpsController', () => {
     });
   });
 
+  describe('clearPendingTransactionRequests', () => {
+    it('removes pending and bridging withdrawal requests', () => {
+      // Arrange: Add withdrawal requests with different statuses
+      controller.testUpdate((state) => {
+        state.withdrawalRequests = [
+          {
+            id: 'withdrawal-1',
+            amount: '100',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: false,
+            status: 'pending',
+          },
+          {
+            id: 'withdrawal-2',
+            amount: '200',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: false,
+            status: 'bridging',
+          },
+          {
+            id: 'withdrawal-3',
+            amount: '300',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: true,
+            status: 'completed',
+            txHash: '0xabc',
+          },
+          {
+            id: 'withdrawal-4',
+            amount: '50',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: false,
+            status: 'failed',
+          },
+        ];
+      });
+
+      controller.clearPendingTransactionRequests();
+
+      expect(controller.state.withdrawalRequests).toHaveLength(2);
+      expect(controller.state.withdrawalRequests.map((w) => w.id)).toEqual([
+        'withdrawal-3',
+        'withdrawal-4',
+      ]);
+    });
+
+    it('removes pending and bridging deposit requests', () => {
+      // Arrange: Add deposit requests with different statuses
+      controller.testUpdate((state) => {
+        state.depositRequests = [
+          {
+            id: 'deposit-1',
+            amount: '100',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: false,
+            status: 'pending',
+          },
+          {
+            id: 'deposit-2',
+            amount: '200',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: false,
+            status: 'bridging',
+          },
+          {
+            id: 'deposit-3',
+            amount: '300',
+            asset: 'USDC',
+            accountAddress: '0x123',
+            timestamp: Date.now(),
+            success: true,
+            status: 'completed',
+            txHash: '0xdef',
+          },
+        ];
+      });
+
+      controller.clearPendingTransactionRequests();
+
+      expect(controller.state.depositRequests).toHaveLength(1);
+      expect(controller.state.depositRequests[0].id).toBe('deposit-3');
+    });
+
+    it('resets withdrawal progress', () => {
+      // Arrange: Set some withdrawal progress
+      controller.testUpdate((state) => {
+        state.withdrawalProgress = {
+          progress: 50,
+          lastUpdated: Date.now() - 10000,
+          activeWithdrawalId: 'withdrawal-1',
+        };
+      });
+
+      controller.clearPendingTransactionRequests();
+
+      expect(controller.state.withdrawalProgress.progress).toBe(0);
+      expect(controller.state.withdrawalProgress.activeWithdrawalId).toBeNull();
+    });
+
+    it('handles empty arrays gracefully', () => {
+      // Arrange: Ensure arrays are empty
+      controller.testUpdate((state) => {
+        state.withdrawalRequests = [];
+        state.depositRequests = [];
+      });
+
+      controller.clearPendingTransactionRequests();
+
+      expect(controller.state.withdrawalRequests).toHaveLength(0);
+      expect(controller.state.depositRequests).toHaveLength(0);
+    });
+  });
+
   describe('trade configuration', () => {
     it('returns undefined for unsaved configuration', () => {
       const result = controller.getTradeConfiguration('ETH');

app/components/UI/Perps/controllers/PerpsController.ts

@@ -572,6 +572,10 @@ export type PerpsControllerActions =
       type: 'PerpsController:resetFirstTimeUserState';
       handler: PerpsController['resetFirstTimeUserState'];
     }
+  | {
+      type: 'PerpsController:clearPendingTransactionRequests';
+      handler: PerpsController['clearPendingTransactionRequests'];
+    }
   | {
       type: 'PerpsController:saveTradeConfiguration';
       handler: PerpsController['saveTradeConfiguration'];
@@ -2330,6 +2334,36 @@ export class PerpsController extends BaseController<
     });
   }
 
+  /**
+   * Clear pending/bridging withdrawal and deposit requests
+   * This is useful when users want to clear stuck pending indicators
+   * Called by Reset Account feature in settings
+   */
+  clearPendingTransactionRequests(): void {
+    DevLogger.log('PerpsController: Clearing pending transaction requests', {
+      timestamp: new Date().toISOString(),
+    });
+
+    this.update((state) => {
+      // Filter out pending/bridging withdrawals, keep completed/failed for history
+      state.withdrawalRequests = state.withdrawalRequests.filter(
+        (req) => req.status !== 'pending' && req.status !== 'bridging',
+      );
+
+      // Filter out pending deposits, keep completed/failed for history
+      state.depositRequests = state.depositRequests.filter(
+        (req) => req.status !== 'pending' && req.status !== 'bridging',
+      );
+
+      // Reset withdrawal progress
+      state.withdrawalProgress = {
+        progress: 0,
+        lastUpdated: Date.now(),
+        activeWithdrawalId: null,
+      };
+    });
+  }
+
   /**
    * Get saved trade configuration for a market
    */

app/components/UI/Perps/hooks/usePerpsFirstTimeUser.test.ts

@@ -16,6 +16,7 @@ jest.mock('../../../../core/Engine', () => ({
     PerpsController: {
       markTutorialCompleted: jest.fn(),
       resetFirstTimeUserState: jest.fn(),
+      clearPendingTransactionRequests: jest.fn(),
     },
   },
 }));
@@ -47,6 +48,7 @@ describe('usePerpsFirstTimeUser', () => {
       isFirstTimeUser: true,
       markTutorialCompleted: expect.any(Function),
       resetFirstTimeUserState: expect.any(Function),
+      clearPendingTransactionRequests: expect.any(Function),
     });
   });
 
@@ -68,6 +70,7 @@ describe('usePerpsFirstTimeUser', () => {
       isFirstTimeUser: false,
       markTutorialCompleted: expect.any(Function),
       resetFirstTimeUserState: expect.any(Function),
+      clearPendingTransactionRequests: expect.any(Function),
     });
   });
 
@@ -90,6 +93,7 @@ describe('usePerpsFirstTimeUser', () => {
       isFirstTimeUser: true,
       markTutorialCompleted: expect.any(Function),
       resetFirstTimeUserState: expect.any(Function),
+      clearPendingTransactionRequests: expect.any(Function),
     });
   });
 
@@ -166,4 +170,50 @@ describe('usePerpsFirstTimeUser', () => {
     // Should not throw when resetFirstTimeUserState is called
     expect(() => result.current.resetFirstTimeUserState()).not.toThrow();
   });
+
+  it('calls PerpsController.clearPendingTransactionRequests when invoked', () => {
+    // Arrange
+    mockUsePerpsSelector.mockImplementation(
+      <T>(selector: (state: PerpsControllerState) => T) => {
+        expect(selector).toBe(selectIsFirstTimeUser);
+        return true as T;
+      },
+    );
+    // Restore mock for this test
+    // @ts-expect-error - Partial mock for testing
+    Engine.context.PerpsController = {
+      markTutorialCompleted: jest.fn(),
+      resetFirstTimeUserState: jest.fn(),
+      clearPendingTransactionRequests: jest.fn(),
+    };
+    const mockClearPendingTransactionRequests = Engine.context.PerpsController
+      .clearPendingTransactionRequests as jest.Mock;
+
+    // Act
+    const { result } = renderHook(() => usePerpsFirstTimeUser());
+    result.current.clearPendingTransactionRequests();
+
+    // Assert
+    expect(mockClearPendingTransactionRequests).toHaveBeenCalledWith();
+  });
+
+  it('handles PerpsController being undefined gracefully for clearPendingTransactionRequests', () => {
+    // Arrange
+    mockUsePerpsSelector.mockImplementation(
+      <T>(selector: (state: PerpsControllerState) => T) => {
+        expect(selector).toBe(selectIsFirstTimeUser);
+        return true as T;
+      },
+    );
+    // @ts-expect-error - Testing undefined case
+    Engine.context.PerpsController = undefined;
+
+    // Act
+    const { result } = renderHook(() => usePerpsFirstTimeUser());
+
+    // Should not throw when clearPendingTransactionRequests is called
+    expect(() =>
+      result.current.clearPendingTransactionRequests(),
+    ).not.toThrow();
+  });
 });

app/components/UI/Perps/hooks/usePerpsFirstTimeUser.ts

@@ -4,12 +4,13 @@ import { usePerpsSelector } from './usePerpsSelector';
 
 /**
  * Hook to check if the user is a first-time user of perps trading
- * @returns Object with isFirstTimeUser flag, markTutorialCompleted function, and resetFirstTimeUserState function
+ * @returns Object with isFirstTimeUser flag, markTutorialCompleted function, resetFirstTimeUserState function, and clearPendingTransactionRequests function
  */
 export function usePerpsFirstTimeUser(): {
   isFirstTimeUser: boolean;
   markTutorialCompleted: () => void;
   resetFirstTimeUserState: () => void;
+  clearPendingTransactionRequests: () => void;
 } {
   const isFirstTimeUser = usePerpsSelector(selectIsFirstTimeUser);
 
@@ -21,9 +22,14 @@ export function usePerpsFirstTimeUser(): {
     Engine.context.PerpsController?.resetFirstTimeUserState();
   };
 
+  const clearPendingTransactionRequests = () => {
+    Engine.context.PerpsController?.clearPendingTransactionRequests();
+  };
+
   return {
     isFirstTimeUser,
     markTutorialCompleted,
     resetFirstTimeUserState,
+    clearPendingTransactionRequests,
   };
 }

app/components/UI/Perps/hooks/useWithdrawalRequests.test.ts

@@ -1097,24 +1097,19 @@ describe('useWithdrawalRequests', () => {
   });
 
   describe('logging', () => {
-    it('logs pending withdrawals from controller state', () => {
+    it('logs when a new withdrawal is initialized', () => {
       renderHookWithProvider(() => useWithdrawalRequests(), {
         state: createMockState(),
       });
 
       expect(mockDevLogger.log).toHaveBeenCalledWith(
-        'Pending withdrawals from controller state:',
+        'Withdrawal initialized:',
         expect.objectContaining({
-          count: 2,
-          withdrawals: expect.arrayContaining([
-            expect.objectContaining({
-              id: 'withdrawal-1',
-              timestamp: expect.any(String),
-              amount: '100',
-              asset: 'USDC',
-              status: 'pending',
-            }),
-          ]),
+          id: 'withdrawal-1',
+          timestamp: expect.any(String),
+          amount: '100',
+          asset: 'USDC',
+          status: 'pending',
         }),
       );
     });