feat: add Claim button for empty cash section by PatrykLucka · Pull Request #27909 · MetaMask/metamask-mobile

PatrykLucka · 2026-03-25T11:22:36Z

Description

Reason: Users with no mUSD balance but a claimable Merkl bonus only saw the claim flow after drilling into the aggregated mUSD row / asset overview. The home Cash empty state did not surface a claim action, and claim failures could occur with little feedback.

Solution:

CashGetMusdEmptyState (homepage Cash section and Cash full view empty state): wires useMerklBonusClaim with shared LINEA_MUSD_ASSET_FOR_MERKL, shows a full-width secondary Claim CTA when there is a claimable reward and no pending claim.
Button copy uses earn.claim_bonus_with_fiat so the label includes the amount formatted with formatWithThreshold + getLocaleLanguageCode(), converting Merkl’s USD amount with the same USD → selected fiat basis as the mUSD price row (oneUsdInUserFiat from mainnet currency rates).
Errors from useMerklClaimTransaction are surfaced via useMerklBonusClaim as error and a plain toast on the empty state when a claim attempt fails.
useMerklClaimTransaction: if the first Merkl fetch returns no reward data, clears the in-memory Merkl cache and retries once to avoid stale empty cache vs. display.
MusdAggregatedRow: reuses LINEA_MUSD_ASSET_FOR_MERKL from constants; row press always navigates to Mainnet mUSD asset details (no longer branches to Cash full view when the user has mUSD).
Tests for CashGetMusdEmptyState, useMerklBonusClaim, useMerklClaimTransaction, and Homepage mocks updated as needed.
Locales: claim_bonus_with_fiat (and aligned keys where added) for the new string.

Changelog

CHANGELOG entry: Added a Claim bonus action on the home Cash section when users have no mUSD but have a claimable Merkl bonus, with the amount shown in the selected fiat currency.

Related issues

Fixes:

Manual testing steps

Feature: Cash section claim bonus when wallet has no mUSD

  Scenario: User with no mUSD and claimable Merkl bonus sees claim CTA on home
    Given mUSD conversion Cash is enabled and the user is geo-eligible
    And the user has no mUSD balance on supported chains
    And Merkl reports a claimable mUSD bonus above the minimum threshold
    When the user views the Wallet home screen
    Then the Cash section shows the empty "Get mUSD" state
    And a secondary button is shown whose label starts with "Claim" and includes a formatted fiat amount

  Scenario: User taps Claim bonus from Cash empty state
    Given the Claim bonus button is visible on the Cash empty state
    When the user taps the Claim bonus button
    Then the wallet proceeds with the Merkl claim flow (e.g. transaction confirmation) when reward data is available
    Or a toast appears with an error message when the claim cannot be completed

  Scenario: Cash full view empty state
    Given the user opens the Cash token list full view with no mUSD balance
    And a claimable bonus exists
    Then the same Claim bonus control is available with consistent labeling

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 new claim path in the Cash empty-state UI and changes Merkl claim fetching to clear cache and retry, which could affect user flows and network/API behavior but is limited to the mUSD/Merkl feature area.

Overview
Adds a secondary “Claim bonus” CTA to the Cash (mUSD) empty state (homepage + full view) when a Merkl bonus is claimable, including fiat-formatted amount labeling and analytics tracking; claim failures now surface as a toast.

Extends useMerklBonusClaim to expose an error from useMerklClaimTransaction, and updates useMerklClaimTransaction to clear the Merkl in-memory cache and retry once when the initial rewards fetch returns no data.

Refactors Cash mUSD components to share a LINEA_MUSD_ASSET_FOR_MERKL constant and adjusts MusdAggregatedRow navigation to always open mainnet mUSD asset details; updates tests, mocks, locale string (earn.claim_bonus_with_fiat), and API-mocking defaults for Merkl rewards.

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

github-actions · 2026-03-25T11:22:46Z

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.

…th error handling

…rrect navigation source

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

…etaMask/metamask-mobile into add-claim-bonus-for-empty-cash-section

github-actions · 2026-03-27T14:23:28Z

🔍 Smart E2E Test Selection

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

click to see 🤖 AI reasoning details

E2E Test Selection:

The changes in this PR are focused on:

Merkl bonus claim improvements (useMerklBonusClaim, useMerklClaimTransaction): Adding error state propagation and a cache-clearing retry mechanism for stale reward data. These hooks are used in the Earn/mUSD staking flow.
Homepage Cash section UI (CashGetMusdEmptyState, MusdAggregatedRow): Adding a "Claim bonus" button with fiat amount display to the empty state when a user has a claimable Merkl bonus but no mUSD balance. This is a new UI feature on the Homepage Cash section.
API mock update (rewards.ts): Adding a Merkl API mock to the global default mocks. This is a critical change as it affects ALL E2E tests that use the default mock setup — it prevents real Merkl API calls from failing tests that render the Homepage Cash section.
Localization: Adding claim_bonus_with_fiat string.

Tag selection rationale:

SmokeTrade: The stake action smoke test (stake-action-smoke.spec.ts) uses SmokeTrade and directly tests the Earn/staking flow. The Merkl claim transaction changes could affect staking confirmation flows. Per tag description, staking flows are covered under SmokeTrade.
SmokeConfirmations: Per SmokeTrade tag description, "When selecting SmokeTrade for swap/bridge, also select SmokeConfirmations." The Merkl claim executes an on-chain transaction (claim rewards), which goes through the confirmation flow.
SmokeWalletPlatform: The Homepage Cash section (CashGetMusdEmptyState, MusdAggregatedRow) is part of the wallet homepage. The new Merkl API mock in default mocks could affect any test that renders the homepage. SmokeWalletPlatform covers wallet platform features including homepage sections.

The changes are primarily additive (new UI feature, error handling improvement, new mock) with low risk of breaking existing functionality. The mock addition is the most impactful change as it affects all tests using default mocks, but it's a safe addition (returns empty array for Merkl rewards).

Performance Test Selection:
The changes are focused on Earn/mUSD Merkl bonus claim UI and hook logic. While there are UI changes to the Homepage Cash section, they are additive (new button, error handling) and don't involve list rendering, heavy data loading, or performance-critical paths. The hook changes add a retry mechanism but this is in the claim flow (user-initiated), not in the rendering/loading path. No performance test tags are warranted.

View GitHub Actions results

github-actions · 2026-03-27T14:56:56Z

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

sonarqubecloud · 2026-03-27T15:59:06Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

PatrykLucka self-assigned this Mar 25, 2026

metamaskbot added the team-mobile-ux Mobile UX team label Mar 25, 2026

github-actions Bot added the size-M label Mar 25, 2026

PatrykLucka changed the title ~~feat: add error handling and claim bonus functionality for Merkl rewards~~ feat: add Claim button for empty cash section Mar 25, 2026

PatrykLucka force-pushed the add-claim-bonus-for-empty-cash-section branch from c00bffe to 0efc195 Compare March 25, 2026 13:01

PatrykLucka added 3 commits March 26, 2026 07:55

feat: add error handling and claim bonus functionality for Merkl rewards

696f7e4

test: enhance AssetOverviewClaimBonus and CashTokensFullView tests wi…

5d6cc2a

…th error handling

test: update MusdAggregatedRow tests to include error handling and co…

64884f4

…rrect navigation source

PatrykLucka force-pushed the add-claim-bonus-for-empty-cash-section branch from 0efc195 to 64884f4 Compare March 26, 2026 06:55

test: add mock response for Merkl bonus rewards endpoint

6c88cf9

PatrykLucka marked this pull request as ready for review March 26, 2026 10:26

PatrykLucka requested review from a team as code owners March 26, 2026 10:26

Merge branch 'main' into add-claim-bonus-for-empty-cash-section

a0a2755

github-actions Bot added the risk-medium Moderate testing recommended · Possible bug introduction risk label Mar 26, 2026

shane-t previously approved these changes Mar 26, 2026

View reviewed changes

PatrykLucka enabled auto-merge March 26, 2026 12:24

christopherferreira9 previously approved these changes Mar 27, 2026

View reviewed changes

PatrykLucka added this pull request to the merge queue Mar 27, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Mar 27, 2026

PatrykLucka added this pull request to the merge queue Mar 27, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Mar 27, 2026

PatrykLucka added this pull request to the merge queue Mar 27, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Mar 27, 2026

Merge branch 'main' into add-claim-bonus-for-empty-cash-section

f674fef

cursor Bot reviewed Mar 27, 2026

View reviewed changes

Comment thread app/components/Views/Homepage/Homepage.test.tsx Outdated

github-actions Bot added risk-medium Moderate testing recommended · Possible bug introduction risk and removed risk-medium Moderate testing recommended · Possible bug introduction risk labels Mar 27, 2026

test: Update Homepage tests to include new mock for usePerpsLiveOrders

8ce2a9b

Merge branch 'add-claim-bonus-for-empty-cash-section' of github.com:M…

550636c

…etaMask/metamask-mobile into add-claim-bonus-for-empty-cash-section

PatrykLucka dismissed stale reviews from shane-t and christopherferreira9 via 550636c March 27, 2026 14:20

github-actions Bot added risk-medium Moderate testing recommended · Possible bug introduction risk and removed risk-medium Moderate testing recommended · Possible bug introduction risk labels Mar 27, 2026

shane-t approved these changes Mar 30, 2026

View reviewed changes

christopherferreira9 approved these changes Mar 30, 2026

View reviewed changes

PatrykLucka added this pull request to the merge queue Mar 30, 2026

Merged via the queue into main with commit 5d0e19e Mar 30, 2026
193 of 199 checks passed

PatrykLucka deleted the add-claim-bonus-for-empty-cash-section branch March 30, 2026 09:41

github-actions Bot locked and limited conversation to collaborators Mar 30, 2026

metamaskbot added the release-7.73.0 Issue or pull request that will be included in release 7.73.0 label Mar 30, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add Claim button for empty cash section#27909

feat: add Claim button for empty cash section#27909
PatrykLucka merged 8 commits into
mainfrom
add-claim-bonus-for-empty-cash-section

PatrykLucka commented Mar 25, 2026 •

edited by cursor Bot

Loading

Uh oh!

github-actions Bot commented Mar 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

sonarqubecloud Bot commented Mar 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

PatrykLucka commented Mar 25, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changelog

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

github-actions Bot commented Mar 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2026

🔍 Smart E2E Test Selection

Uh oh!

github-actions Bot commented Mar 27, 2026

Uh oh!

sonarqubecloud Bot commented Mar 27, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PatrykLucka commented Mar 25, 2026 •

edited by cursor Bot

Loading