feat(hw): add QR scan error handling by montelaidev · Pull Request #29388 · MetaMask/metamask-mobile

montelaidev · 2026-04-28T01:57:45Z

Description

Adds shared QR hardware scan error types and updates the animated QR scanner to classify non-UR payloads, decode failures, wrong UR types, and scan exceptions. This gives QR hardware flows user-facing retry/learn-more states and structured analytics instead of falling back to generic unknown QR errors.

This is PR 1 of 2. PR 2 stacks on this branch and wires the scanner errors into the connection/signing flows.

Changelog

CHANGELOG entry: Improved QR hardware wallet scan error messages and retry handling

Related issues

Refs: MUL-1665

Manual testing steps

Feature: QR hardware scan errors

  Scenario: user scans an unsupported QR code while pairing
    Given the user is pairing a QR-based hardware wallet
    When the user scans a QR code that is not in UR format
    Then the scanner shows a QR hardware scan error with Learn more and Try again actions

Screenshots/Recordings

Before

N/A

After

N/A

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.

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 to import wallets with many accounts and tokens
I've instrumented key operations with Sentry traces for production performance metrics
- See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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.

Made with Cursor

Note

Medium Risk
Updates QR hardware scanning flow to gate scanning on UR format and introduces new error types/UI states; bugs here could block pairing/signing scans or skew hardware wallet error analytics.

Overview
Adds structured QR hardware scan errors and inline recovery UI. AnimatedQRScanner now classifies non-UR payloads, UR decode failures, wrong UR types, and scan exceptions into QRHardwareScanError objects, shows a dedicated error screen with Learn more and Try again, and prevents repeated error handling until reset (with optional onQRHardwareScanError and onModalHideComplete callbacks).

Improves analytics and error plumbing. Hardware wallet error metrics now include is_ur_format plus error_category/received_ur_type where relevant, adds new localized copy for QR scan errors and camera-permission-denied mapping (RecoveryAction.OPEN_SETTINGS), and introduces getReplacementGasFeeParams to normalize replacement transaction gas params (legacy vs EIP-1559) with tests.

^{Reviewed by Cursor Bugbot for commit c49a680. Bugbot is set up for automated code reviews on this repo. Configure here.}

Made-with: Cursor

github-actions · 2026-04-28T01:57:53Z

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.

cursor

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

There are 2 total unresolved issues (including 1 from previous review).

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

^{Reviewed by Cursor Bugbot for commit 77c9162. Configure here.}

Co-authored-by: Monte Lai <montelaidev@users.noreply.github.com>

ccharly

LGTM! I left 2 comments about "error anylitics/metrics" cause I'm not sure I understood quite well this part. Though, some tests were already named that way, so that might be ok but if you can double-check that's better 😄

github-actions · 2026-05-04T12:07:14Z

🔍 Smart E2E Test Selection

Selected E2E tags: SmokeAccounts
Selected Performance tags: None (no tests recommended)
Risk Level: medium
AI Confidence: 72%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes are focused on QR Hardware Wallet error handling and the AnimatedQRScanner UI component:

New QR scan error infrastructure (qrScan.ts, qrHardwareScanError.ts, qrScan.types.ts): New error types and factory functions for QR hardware wallet scanning flows. These are new files with no existing E2E test coverage found.
AnimatedQRScanner.tsx: Significant UI refactor - the scanner now shows inline error states with 'Learn more' and 'Try again' buttons instead of just calling onScanError. New props added (onQRHardwareScanError, onModalHideComplete). This changes the UX flow for QR hardware wallet pairing and signing.
Error mappings update: Added PermissionCameraDenied error with new OPEN_SETTINGS recovery action.
transactionReplacementParams.ts: New utility for gas fee normalization in hardware wallet transaction replacement - currently only referenced in its test file.
Localization: New strings for QR scan errors and camera permission.

SmokeAccounts is selected because its description explicitly covers 'adding QR-based hardware wallet accounts', which is the primary user flow affected by the AnimatedQRScanner changes. The QR scanner is used during the hardware wallet pairing flow (ConnectQRHardware) and signing flow (QRSigningDetails), both of which are part of the hardware wallet account management experience.

No other tags are directly impacted - the changes are isolated to hardware wallet QR scanning infrastructure and don't touch confirmations, network management, browser, snaps, or other flows.

Confidence is moderate (72) because no dedicated E2E tests for QR hardware wallet scanning were found in the test suite, so coverage validation is limited to the broader SmokeAccounts suite.

Performance Test Selection:
The changes are focused on error handling logic and UI state management within the QR scanner modal. There are no changes to rendering-heavy components, data loading, state management controllers, or critical performance paths. The AnimatedQRScanner changes add error state rendering but this is a modal component that only appears during hardware wallet flows, not in any performance-critical paths like account list rendering, app launch, or asset loading.

View GitHub Actions results

sonarqubecloud · 2026-05-04T12:22:42Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

feat(hw): add QR scan error handling

e30d8a5

Made-with: Cursor

montelaidev self-assigned this Apr 28, 2026

metamaskbotv2 Bot added the team-accounts-framework Accounts team label Apr 28, 2026

montelaidev mentioned this pull request Apr 28, 2026

feat(hw): wire QR signing retry flow #29389

Closed

10 tasks

github-actions Bot added the size-L label Apr 28, 2026

fix: lint and add coverage

582c7fa

github-actions Bot added size-XL and removed size-L labels Apr 28, 2026

montelaidev marked this pull request as ready for review April 28, 2026 08:12

cursor Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.tsx

ccharly reviewed Apr 28, 2026

View reviewed changes

montelaidev added 2 commits April 28, 2026 20:16

fix: address comments

708ad0a

fix: re-add message

725ab69

cursor Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.tsx

montelaidev added 3 commits April 28, 2026 20:56

fix: typing and casting

6ecd266

fix: set ref when scan error is active

7be4ccb

fix: lint and add coverage

41f874a

montelaidev requested a review from ccharly April 29, 2026 09:07

montelaidev added 2 commits April 29, 2026 17:59

fix: lint

12a3f34

fix:lint

8441128

cursor Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.tsx Outdated

fix: reset error

dc5e824

ccharly reviewed Apr 29, 2026

View reviewed changes

montelaidev added 2 commits April 29, 2026 23:47

refactor: tests to be more dry

587f0da

fix: use enum

b316768

ccharly reviewed Apr 29, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.test.tsx Outdated

cursor Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.test.tsx Outdated

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.test.tsx Outdated

fix: test

77c9162

cursor Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.test.tsx Outdated

montelaidev and others added 2 commits April 30, 2026 08:23

fix: use getByTestId

2e89662

test: fix QR scanner modal reset coverage

e3bfd1a

Co-authored-by: Monte Lai <montelaidev@users.noreply.github.com>

ccharly previously approved these changes Apr 30, 2026

View reviewed changes

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.test.tsx

Comment thread app/components/UI/QRHardware/AnimatedQRScanner.test.tsx

fix: update tests

2bb8777

montelaidev dismissed ccharly’s stale review via 2bb8777 May 4, 2026 09:15

montelaidev enabled auto-merge May 4, 2026 09:16

ccharly approved these changes May 4, 2026

View reviewed changes

Merge branch 'main' into feat/mul-1665-qr-scan-errors

c49a680

montelaidev added this pull request to the merge queue May 4, 2026

Merged via the queue into main with commit abe3349 May 4, 2026
294 of 301 checks passed

montelaidev deleted the feat/mul-1665-qr-scan-errors branch May 4, 2026 14:34

github-actions Bot locked and limited conversation to collaborators May 4, 2026

metamaskbotv2 Bot added the release-7.77.0 Issue or pull request that will be included in release 7.77.0 label May 4, 2026

Uh oh!

Conversation

montelaidev commented Apr 28, 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

Performance checks (if applicable)

Pre-merge reviewer checklist

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ccharly left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 4, 2026

🔍 Smart E2E Test Selection

Uh oh!

sonarqubecloud Bot commented May 4, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

montelaidev commented Apr 28, 2026 •

edited by cursor Bot

Loading