feat: add new hardware wallet signing qr code (#29737)

## **Description**

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

Wires the QR scan errors from PR 1 into pairing and signing flows. QR
scan failures now surface through the hardware wallet bottom sheet with
retry support, signing confirmations can reopen the scanner from the
error CTA, and replacement transaction gas params are normalized through
the shared helper.

This is PR 2 of 3 and is stacked on #29388.

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: Improved retry behavior when QR hardware wallet signing
scans fail

## **Related issues**

Refs: MUL-1665

## **Manual testing steps**

```gherkin
Feature: QR hardware signing retry

  Scenario: user retries a failed QR signing scan
    Given the user is signing with a QR-based hardware wallet
    When the user scans an invalid QR code
    Then the hardware wallet bottom sheet displays the QR scan error
    When the user taps Try again
    Then the QR scanner reopens for another signing scan
```

## **Screenshots/Recordings**

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

### **Before**

N/A

### **After**

N/A

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

- [x] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [x] 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
- [x] 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 is ambiguous, a checked 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.

Made with [Cursor](https://cursor.com)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Moderate risk because it changes the hardware-wallet bottom-sheet
recovery flow and retry behavior for QR signing, which could affect
signing UX/state transitions. Adds new analytics properties for QR scan
failures; incorrect classification could skew metrics but not funds.
> 
> **Overview**
> **Improves QR hardware wallet scan-failure recovery during
pairing/signing.** QR scan errors now route through the hardware wallet
bottom sheet with a dedicated retry path that can reopen the QR scanner
for signing retries, plus a provider-level
`setQrScanRetryHandler`/`onRetryQrScan` mechanism to coordinate retries
outside provider-managed flows.
> 
> **Adds QR scan error-specific UI + analytics.** `ErrorContent` treats
QR scan errors specially (custom title, *Try again* + *Learn more*, no
generic icon) and supports `OPEN_SETTINGS` recovery;
`useHardwareWalletAnalytics` now attaches QR scan metadata
(`error_category`, `is_ur_format`, optional `received_ur_type`) to
recovery viewed/CTA/success events.
> 
> Includes supporting refactors and tests (QR adapter no longer emits
`AppOpened` on `ensureDeviceReady`, new `isQRHardwareScanError`,
`useQrScanErrorForwarding`, `useIsConfirmationFromQrAccount`, and
`useQrConfirm`).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
31443d4. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: montelaidev

app/core/HardwareWallet/HardwareWalletProvider.tsx

@@ -88,6 +88,7 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
 
   const awaitingConfirmationRejectRef = useRef<(() => void) | null>(null);
   const operationTypeRef = useRef<'transaction' | 'message' | null>(null);
+  const qrScanRetryHandlerRef = useRef<(() => void) | null>(null);
 
   const [analyticsFlow, setAnalyticsFlow] = useState(
     HardwareWalletAnalyticsFlow.Connection,
@@ -136,6 +137,10 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
     [handleError],
   );
 
+  const setQrScanRetryHandler = useCallback((handler: (() => void) | null) => {
+    qrScanRetryHandlerRef.current = handler;
+  }, []);
+
   const showAwaitingConfirmation = useCallback(
     (operationType: 'transaction' | 'message', onReject?: () => void) => {
       DevLogger.log(
@@ -187,6 +192,26 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
     }
     await retryEnsureDeviceReady();
   }, [handleCloseFlow, retryEnsureDeviceReady]);
+
+  const handleRetryQrScan = useCallback(() => {
+    if (operationTypeRef.current !== null) {
+      updateConnectionState({
+        status: ConnectionStatus.AwaitingConfirmation,
+        deviceId: deviceId ?? 'unknown',
+        operationType: operationTypeRef.current,
+      });
+      return;
+    }
+
+    const retryQrScan = qrScanRetryHandlerRef.current;
+    updateConnectionState({ status: ConnectionStatus.Disconnected });
+    if (!retryQrScan) {
+      return;
+    }
+
+    retryQrScan();
+  }, [deviceId, updateConnectionState]);
+
   const handleAwaitingConfirmationCancel = useCallback(() => {
     DevLogger.log('[HardwareWallet] handleAwaitingConfirmationCancel');
     const onReject = awaitingConfirmationRejectRef.current;
@@ -248,6 +273,7 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
       setTargetWalletType: setters.setTargetWalletType,
       setPendingOperationAddress,
       showHardwareWalletError,
+      setQrScanRetryHandler,
       showAwaitingConfirmation,
       hideAwaitingConfirmation,
       qr: qrSigningValue,
@@ -261,6 +287,7 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
       setters.setTargetWalletType,
       setPendingOperationAddress,
       showHardwareWalletError,
+      setQrScanRetryHandler,
       showAwaitingConfirmation,
       hideAwaitingConfirmation,
       qrSigningValue,
@@ -282,6 +309,7 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
         onAwaitingConfirmationCancel={handleAwaitingConfirmationCancel}
         onConnectionSuccess={handleBottomSheetConnectionSuccess}
         onCTAClicked={trackCTAClicked}
+        onRetryQrScan={handleRetryQrScan}
       />
     </HardwareWalletContext.Provider>
   );

app/core/HardwareWallet/adapters/QRWalletAdapter.test.ts

@@ -128,13 +128,11 @@ describe('QRWalletAdapter', () => {
       ).rejects.toThrow('Adapter has been destroyed');
     });
 
-    it('returns true and emits AppOpened (QR wallets are always ready)', async () => {
+    it('returns true when camera permission is granted (QR wallets are always ready)', async () => {
       const result = await adapter.ensureDeviceReady('qr-account-address');
 
       expect(result).toBe(true);
-      expect(onDeviceEvent).toHaveBeenCalledWith({
-        event: DeviceEvent.AppOpened,
-      });
+      expect(onDeviceEvent).not.toHaveBeenCalled();
     });
 
     it('stores device ID', async () => {
@@ -150,6 +148,7 @@ describe('QRWalletAdapter', () => {
       const result = await adapter.ensureDeviceReady('qr-account-address');
 
       expect(result).toBe(false);
+      expect(mockRequestCameraPermission).not.toHaveBeenCalled();
       expect(adapter.getConnectedDeviceId()).toBeNull();
       expect(adapter.isConnected()).toBe(false);
       expect(onDeviceEvent).toHaveBeenCalledWith({

app/core/HardwareWallet/adapters/QRWalletAdapter.ts

@@ -114,12 +114,6 @@ export class QRWalletAdapter implements HardwareWalletAdapter {
 
     DevLogger.log('[QRWalletAdapter] Device is ready');
 
-    // For QR wallets, we consider the "app" to always be open
-    // since there's no app concept like on Ledger
-    this.#emitEvent({
-      event: DeviceEvent.AppOpened,
-    });
-
     return true;
   }
 
@@ -271,12 +265,8 @@ export class QRWalletAdapter implements HardwareWalletAdapter {
         if (newStatus === 'granted') {
           return true;
         }
-
-        this.#emitCameraPermissionDenied();
-        return false;
       }
 
-      // status === 'denied' - emit error event
       this.#emitCameraPermissionDenied();
       return false;
     } catch (error) {

app/core/HardwareWallet/analytics/helpers.test.ts

@@ -16,7 +16,10 @@ import {
   getAnalyticsDeviceType,
   getErrorDetails,
   getAnalyticsFlowFromApproval,
+  getQrHardwareScanErrorAnalyticsProperties,
 } from './helpers';
+import { createQRHardwareScanError, QRHardwareScanErrorType } from '../errors';
+import { QrScanRequestType } from '@metamask/eth-qr-keyring';
 
 describe('analytics helpers', () => {
   describe('getAnalyticsErrorType', () => {
@@ -362,4 +365,105 @@ describe('analytics helpers', () => {
       );
     });
   });
+
+  describe('getQrHardwareScanErrorAnalyticsProperties', () => {
+    it('returns empty object for non-ErrorState', () => {
+      const state: HardwareWalletConnectionState = {
+        status: ConnectionStatus.Disconnected,
+      };
+
+      expect(getQrHardwareScanErrorAnalyticsProperties(state)).toEqual({});
+    });
+
+    it('returns empty object for ErrorState with non-QR error', () => {
+      const error = new HardwareWalletError('Test', {
+        code: ErrorCode.Unknown,
+        severity: Severity.Err,
+        category: Category.Connection,
+        userMessage: 'Test',
+      });
+
+      const state: HardwareWalletConnectionState = {
+        status: ConnectionStatus.ErrorState,
+        error,
+      };
+
+      expect(getQrHardwareScanErrorAnalyticsProperties(state)).toEqual({});
+    });
+
+    it('returns QR scan properties for non-UR QR scanned error', () => {
+      const qrError = createQRHardwareScanError({
+        errorType: QRHardwareScanErrorType.NonURQrScanned,
+        purpose: QrScanRequestType.SIGN,
+        isUrFormat: false,
+      });
+
+      const state: HardwareWalletConnectionState = {
+        status: ConnectionStatus.ErrorState,
+        error: qrError,
+      };
+
+      const result = getQrHardwareScanErrorAnalyticsProperties(state);
+      expect(result).toEqual({
+        error_category: 'non_ur_qr_scanned',
+        is_ur_format: false,
+      });
+    });
+
+    it('returns received_ur_type for wrong UR type error', () => {
+      const qrError = createQRHardwareScanError({
+        errorType: QRHardwareScanErrorType.WrongURType,
+        purpose: QrScanRequestType.SIGN,
+        receivedUrType: 'crypto-account',
+        isUrFormat: true,
+      });
+
+      const state: HardwareWalletConnectionState = {
+        status: ConnectionStatus.ErrorState,
+        error: qrError,
+      };
+
+      const result = getQrHardwareScanErrorAnalyticsProperties(state);
+      expect(result).toEqual({
+        error_category: 'wrong_ur_type',
+        is_ur_format: true,
+        received_ur_type: 'crypto-account',
+      });
+    });
+
+    it('returns empty string for received_ur_type when not provided', () => {
+      const qrError = createQRHardwareScanError({
+        errorType: QRHardwareScanErrorType.WrongURType,
+        purpose: QrScanRequestType.PAIR,
+        isUrFormat: true,
+      });
+
+      const state: HardwareWalletConnectionState = {
+        status: ConnectionStatus.ErrorState,
+        error: qrError,
+      };
+
+      const result = getQrHardwareScanErrorAnalyticsProperties(state);
+      expect(result.received_ur_type).toBe('');
+    });
+
+    it('returns QR scan properties for UR decode error', () => {
+      const qrError = createQRHardwareScanError({
+        errorType: QRHardwareScanErrorType.URDecodeError,
+        purpose: QrScanRequestType.SIGN,
+        isUrFormat: true,
+      });
+
+      const state: HardwareWalletConnectionState = {
+        status: ConnectionStatus.ErrorState,
+        error: qrError,
+      };
+
+      const result = getQrHardwareScanErrorAnalyticsProperties(state);
+      expect(result).toEqual({
+        error_category: 'ur_decode_error',
+        is_ur_format: true,
+      });
+    });
+  });
 });

app/core/HardwareWallet/analytics/helpers.ts

@@ -4,6 +4,7 @@ import {
   HardwareWalletConnectionState,
   ConnectionStatus,
 } from '@metamask/hw-wallet-sdk';
+import { isQRHardwareScanError, QRHardwareScanErrorType } from '../errors';
 import { ApprovalType } from '@metamask/controller-utils';
 import { TransactionType } from '@metamask/transaction-controller';
 
@@ -186,3 +187,31 @@ export function getErrorDetails(
   }
   return { error_code: '', error_message: '' };
 }
+
+/**
+ * Segment/MetaMetrics properties for QR hardware camera scan failures
+ * (`Hardware Wallet Connection Failed` / recovery UI), when the connection
+ * {@link ConnectionStatus.ErrorState} error is a {@link isQRHardwareScanError}.
+ */
+export function getQrHardwareScanErrorAnalyticsProperties(
+  connectionState: HardwareWalletConnectionState,
+): Record<string, string | boolean> {
+  if (connectionState.status !== ConnectionStatus.ErrorState) {
+    return {};
+  }
+  const { error } = connectionState;
+  if (!isQRHardwareScanError(error)) {
+    return {};
+  }
+  const metadata = error.metadata;
+  const payload: Record<string, string | boolean> = {
+    error_category: metadata.qrHardwareScanErrorType,
+    is_ur_format: metadata.isUrFormat,
+  };
+  if (
+    metadata.qrHardwareScanErrorType === QRHardwareScanErrorType.WrongURType
+  ) {
+    payload.received_ur_type = metadata.receivedUrType ?? '';
+  }
+  return payload;
+}

app/core/HardwareWallet/analytics/index.ts

@@ -6,6 +6,7 @@ export {
   getErrorTypeFromConnectionState,
   getAnalyticsDeviceType,
   getErrorDetails,
+  getQrHardwareScanErrorAnalyticsProperties,
 } from './helpers';
 
 export { useHardwareWalletAnalytics } from './useHardwareWalletAnalytics';

app/core/HardwareWallet/analytics/useHardwareWalletAnalytics.test.ts

@@ -14,6 +14,8 @@ import {
   HardwareWalletAnalyticsFlow,
 } from './helpers';
 import { MetaMetricsEvents } from '../../Analytics';
+import { createQRHardwareScanError, QRHardwareScanErrorType } from '../errors';
+import { QrScanRequestType } from '@metamask/eth-qr-keyring';
 
 const mockTrackEvent = jest.fn();
 const mockBuild = jest.fn().mockReturnValue({ name: 'built-event' });
@@ -86,6 +88,67 @@ describe('useHardwareWalletAnalytics', () => {
       expect(mockTrackEvent).toHaveBeenCalled();
     });
 
+    it('includes QR scan analytics when error is a QR hardware scan failure', () => {
+      const { rerender } = renderHook(
+        (props) => useHardwareWalletAnalytics(props),
+        { initialProps: defaultOptions },
+      );
+
+      const qrError = createQRHardwareScanError({
+        errorType: QRHardwareScanErrorType.NonURQrScanned,
+        purpose: QrScanRequestType.PAIR,
+        isUrFormat: false,
+      });
+
+      rerender({
+        ...defaultOptions,
+        walletType: HardwareWalletType.Qr,
+        connectionState: {
+          status: ConnectionStatus.ErrorState,
+          error: qrError,
+        },
+      });
+
+      expect(mockAddProperties).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error_type: HardwareWalletAnalyticsErrorType.GenericError,
+          error_category: 'non_ur_qr_scanned',
+          is_ur_format: false,
+        }),
+      );
+    });
+
+    it('includes received_ur_type for wrong UR type QR scan errors', () => {
+      const { rerender } = renderHook(
+        (props) => useHardwareWalletAnalytics(props),
+        { initialProps: defaultOptions },
+      );
+
+      const qrError = createQRHardwareScanError({
+        errorType: QRHardwareScanErrorType.WrongURType,
+        purpose: QrScanRequestType.SIGN,
+        receivedUrType: 'eth-signature',
+        isUrFormat: true,
+      });
+
+      rerender({
+        ...defaultOptions,
+        walletType: HardwareWalletType.Qr,
+        connectionState: {
+          status: ConnectionStatus.ErrorState,
+          error: qrError,
+        },
+      });
+
+      expect(mockAddProperties).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error_category: 'wrong_ur_type',
+          is_ur_format: true,
+          received_ur_type: 'eth-signature',
+        }),
+      );
+    });
+
     it('fires when transitioning to AwaitingApp', () => {
       const { rerender } = renderHook(
         (props) => useHardwareWalletAnalytics(props),