feat(perps): integrate MetaMask Points rewards and fee discounts for Perps trading (#19808)

## **Description**

This PR implements MetaMask Points rewards integration for Perps
trading, including tier-based fee discounts and points estimation
display. Users now see their estimated points earnings and receive fee
discounts based on their MetaMask Points tier before executing trades.

### What is the reason for the change?
- TAT-1221: Users need tier-based MetaMask builder fee discounts (Tier
1-3: 10bps, Tier 4-5: 5bps, Tier 6-7: 3.5bps)
- TAT-1223: Users need to see estimated points earnings before trading

### What is the improvement/solution?
- Integrated RewardsController for fee discount and points estimation
- Added RewardPointsDisplay component with fox icon animation states
- Implemented fee discount visualization with fox icon in fee row
- Added comprehensive error handling with tooltips
- Supports development simulation with magic numbers (41, 42, 43)

## **Changelog**

CHANGELOG entry: Added MetaMask Points rewards integration to Perps
trading with tier-based fee discounts and points estimation display

## **Related issues**

Fixes: 
- [TAT-1221](https://consensyssoftware.atlassian.net/browse/TAT-1221)
- [TAT-1223](https://consensyssoftware.atlassian.net/browse/TAT-1223)
- [TAT-1226](https://consensyssoftware.atlassian.net/browse/TAT-1426)

## **Manual testing steps**

```gherkin
Feature: MetaMask Points Rewards Integration

  Scenario: User sees fee discount for their tier
    Given user has MetaMask Points tier 4-5
    And user is on Perps order view with valid order amount
    When user enters order details
    Then user sees orange fox icon with "-X%" discount in fee row
    And total fee reflects the discount amount

  Scenario: User sees estimated points for trade
    Given user has opted into rewards program
    And user is on Perps order view
    When user enters valid order amount and leverage
    Then user sees orange fox icon with estimated points number
    And points animate on value changes (refresh state)

  Scenario: User sees error state handling
    Given rewards API is unavailable
    When user attempts to view rewards information
    Then user sees greyed out fox icon with "Couldn't load" text
    And user can tap info icon to see error details

  Scenario: Development simulation testing
    Given __DEV__ mode is enabled
    When user enters amount "41"
    Then user sees simulated 20% fee discount
    When user enters amount "42"
    Then user sees error state
    When user enters amount "43"
    Then user sees loading state
```

## **Screenshots/Recordings**

### **Before**
- No rewards integration
- Standard fees without discounts
- No points estimation

### **After**
- Fee discount displayed with fox icon and percentage
- Points estimation with animated fox icon
- Error states with tooltips
- Proper alignment and design system compliance



https://github.com/user-attachments/assets/6101166d-0565-4859-b37b-6d1569bc0afd



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

---


[TAT-1221]:
https://consensyssoftware.atlassian.net/browse/TAT-1221?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

---------

Co-authored-by: Rik Van Gulck <vangulckrik@gmail.com>

Author: abretonc7s

app/components/UI/Bridge/hooks/useRewardsIconAnimation/useRewardsIconAnimation.test.ts

@@ -399,4 +399,146 @@ describe('useRewardsIconAnimation', () => {
       expect(mockFireState).toHaveBeenCalledWith('State Machine 1', 'Disable');
     });
   });
+
+  describe('refresh animation trigger', () => {
+    it('triggers Refresh when isRefresh is true and has positive points', () => {
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          isRefresh: true,
+          estimatedPoints: 100,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).toHaveBeenCalledWith('State Machine 1', 'Refresh');
+    });
+
+    it('does not trigger Refresh when estimatedPoints is 0', () => {
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          isRefresh: true,
+          estimatedPoints: 0,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).not.toHaveBeenCalled();
+    });
+
+    it('does not trigger Refresh when estimatedPoints is null', () => {
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          isRefresh: true,
+          estimatedPoints: null,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).not.toHaveBeenCalled();
+    });
+
+    it('prioritizes loading state over refresh', () => {
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          isRewardsLoading: true,
+          isRefresh: true,
+          estimatedPoints: 100,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).toHaveBeenCalledWith('State Machine 1', 'Disable');
+    });
+
+    it('prioritizes error state over refresh', () => {
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          hasRewardsError: true,
+          isRefresh: true,
+          estimatedPoints: 100,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).toHaveBeenCalledWith('State Machine 1', 'Disable');
+    });
+  });
+
+  describe('additional edge cases for complete coverage', () => {
+    it('handles when shouldShowRewardsRow is false with refresh state', () => {
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          shouldShowRewardsRow: false,
+          isRefresh: true,
+          estimatedPoints: 100,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).not.toHaveBeenCalled();
+    });
+
+    it('handles points change from 0 to positive value', () => {
+      // Arrange
+      mockPreviousPointsRef.current = 0 as any;
+
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          estimatedPoints: 50,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).toHaveBeenCalledWith('State Machine 1', 'Start');
+      expect(mockPreviousPointsRef.current).toBe(50);
+    });
+
+    it('handles points change from positive to 0', () => {
+      // Arrange
+      mockPreviousPointsRef.current = 100 as any;
+
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          estimatedPoints: 0,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).not.toHaveBeenCalled();
+      expect(mockPreviousPointsRef.current).toBe(0);
+    });
+
+    it('handles points change from null to positive', () => {
+      // Arrange
+      mockPreviousPointsRef.current = null as any;
+
+      // Act
+      renderHookWithProvider(() =>
+        useRewardsIconAnimation({
+          ...defaultParams,
+          estimatedPoints: 75,
+        }),
+      );
+
+      // Assert
+      expect(mockFireState).toHaveBeenCalledWith('State Machine 1', 'Start');
+      expect(mockPreviousPointsRef.current).toBe(75);
+    });
+  });
 });

app/components/UI/Bridge/hooks/useRewardsIconAnimation/useRewardsIconAnimation.ts

@@ -14,6 +14,7 @@ interface UseRewardsIconAnimationParams {
   estimatedPoints: number | null;
   hasRewardsError: boolean;
   shouldShowRewardsRow: boolean;
+  isRefresh?: boolean;
 }
 
 interface UseRewardsIconAnimationResult {
@@ -25,6 +26,7 @@ export const useRewardsIconAnimation = ({
   estimatedPoints,
   hasRewardsError,
   shouldShowRewardsRow,
+  isRefresh = false,
 }: UseRewardsIconAnimationParams): UseRewardsIconAnimationResult => {
   const riveRef = useRef<RiveRef>(null);
   const previousPointsRef = useRef<number | null>(null);
@@ -53,6 +55,15 @@ export const useRewardsIconAnimation = ({
         return;
       }
 
+      if (isRefresh && currentPoints && currentPoints > 0) {
+        // Refresh state - trigger spin animation
+        riveRef.current.fireState(
+          STATE_MACHINE_NAME,
+          RewardsIconTriggers.Refresh,
+        );
+        return;
+      }
+
       if (currentPoints && currentPoints > 0) {
         // Has points - trigger Start
         riveRef.current.fireState(
@@ -71,6 +82,7 @@ export const useRewardsIconAnimation = ({
     hasRewardsError,
     isRewardsLoading,
     shouldShowRewardsRow,
+    isRefresh,
   ]);
 
   return {

app/components/UI/Perps/Views/PerpsClosePositionView/PerpsClosePositionView.test.tsx

@@ -13,6 +13,7 @@ import {
   defaultPerpsClosePositionMock,
   defaultPerpsEventTrackingMock,
   defaultMinimumOrderAmountMock,
+  defaultPerpsRewardsMock,
 } from '../../__mocks__/perpsHooksMocks';
 import { strings } from '../../../../../../locales/i18n';
 import {
@@ -36,6 +37,7 @@ jest.mock('../../hooks', () => ({
   usePerpsClosePosition: jest.fn(),
   usePerpsMarketData: jest.fn(),
   usePerpsToasts: jest.fn(),
+  usePerpsRewards: jest.fn(),
 }));
 
 jest.mock('../../hooks/stream', () => ({
@@ -127,6 +129,7 @@ describe('PerpsClosePositionView', () => {
   const usePerpsMarketDataMock =
     jest.requireMock('../../hooks').usePerpsMarketData;
   const usePerpsToastsMock = jest.requireMock('../../hooks').usePerpsToasts;
+  const usePerpsRewardsMock = jest.requireMock('../../hooks').usePerpsRewards;
 
   beforeEach(() => {
     jest.resetAllMocks();
@@ -161,6 +164,9 @@ describe('PerpsClosePositionView', () => {
 
     // Setup usePerpsToasts mock
     usePerpsToastsMock.mockReturnValue(defaultPerpsToastsMock);
+
+    // Setup usePerpsRewards mock
+    usePerpsRewardsMock.mockReturnValue(defaultPerpsRewardsMock);
   });
 
   describe('Component Rendering', () => {

app/components/UI/Perps/Views/PerpsClosePositionView/PerpsClosePositionView.tsx

@@ -38,6 +38,7 @@ import {
   usePerpsClosePositionValidation,
   usePerpsClosePosition,
   usePerpsToasts,
+  usePerpsRewards,
 } from '../../hooks';
 import { usePerpsLivePrices } from '../../hooks/stream';
 import { formatPositionSize, formatPrice } from '../../utils/formatUtils';
@@ -68,6 +69,7 @@ import ListItemColumn, {
   WidthType,
 } from '../../../../../component-library/components/List/ListItemColumn';
 import PerpsOrderHeader from '../../components/PerpsOrderHeader';
+import PerpsFeesDisplay from '../../components/PerpsFeesDisplay';
 
 const PerpsClosePositionView: React.FC = () => {
   const theme = useTheme();
@@ -178,6 +180,19 @@ const PerpsClosePositionView: React.FC = () => {
     orderType,
     amount: closingValue.toString(),
     isMaker: false, // Closing positions are typically taker orders
+    coin: position.coin,
+    isClosing: true, // This is a position closing operation
+  });
+
+  // Simple boolean calculation for rewards state
+  const hasValidAmount = closePercentage > 0 && closingValue > 0;
+
+  // Get rewards state using the new hook
+  const rewardsState = usePerpsRewards({
+    feeResults,
+    hasValidAmount,
+    isFeesLoading: feeResults.isLoadingMetamaskFee,
+    orderAmount: closingValue.toString(),
   });
 
   // Calculate what user will receive (initial margin + P&L at effective price - fees)
@@ -469,9 +484,13 @@ const PerpsClosePositionView: React.FC = () => {
           </TouchableOpacity>
         </View>
         <View style={styles.summaryValue}>
-          <Text variant={TextVariant.BodyMD}>
-            -{formatPrice(feeResults.totalFee, { maximumDecimals: 2 })}
-          </Text>
+          <PerpsFeesDisplay
+            feeDiscountPercentage={rewardsState.feeDiscountPercentage}
+            formatFeeText={`-${formatPrice(feeResults.totalFee, {
+              maximumDecimals: 2,
+            })}`}
+            variant={TextVariant.BodyMD}
+          />
         </View>
       </View>
 
@@ -744,6 +763,8 @@ const PerpsClosePositionView: React.FC = () => {
                 data: {
                   metamaskFeeRate: feeResults.metamaskFeeRate,
                   protocolFeeRate: feeResults.protocolFeeRate,
+                  originalMetamaskFeeRate: feeResults.originalMetamaskFeeRate,
+                  feeDiscountPercentage: feeResults.feeDiscountPercentage,
                 },
               }
             : {})}

app/components/UI/Perps/Views/PerpsOrderView/PerpsOrderView.styles.ts

@@ -100,5 +100,8 @@ const createStyles = (colors: Colors) =>
       paddingHorizontal: 16,
       backgroundColor: colors.background.default,
     },
+    pointsRightContainer: {
+      alignItems: 'flex-end',
+    },
   });
 export default createStyles;