feat(hw): add executeHardwareWalletOperation utility (#29085)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

Add shared utility that runs hardware wallet operations behind the
standard readiness + awaiting-confirmation flow. Includes foundation
helpers (getDeviceIdForAddress, normalizeReplacementGasFeeParams) as
prerequisites.

<!--
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?
-->

## **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: null

## **Related issues**

Related to: https://consensyssoftware.atlassian.net/browse/MUL-1741

## **Manual testing steps**

This can only be tested via
#29087

## **Screenshots/Recordings**

Not applicable

## **Pre-merge author checklist**

- [ ] 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).
- [ ] 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](https://jsdoc.app/) format
if applicable
- [ ] 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)

- [ ] 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](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
- [ ] 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**

- [ ] 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]
> **Medium Risk**
> Touches the hardware wallet provider’s wallet-type resolution and
introduces a new shared signing wrapper; mistakes could lead to
incorrect adapter selection or confirmation/error UI behavior during
signing.
> 
> **Overview**
> Adds a shared `executeHardwareWalletOperation` helper to standardize
hardware-wallet operations: it resolves device id from address, gates on
`ensureDeviceReady`, shows/hides the awaiting-confirmation UI, and
centralizes rejection + error handling (including user-cancel
suppression), with unit coverage.
> 
> Updates `HardwareWalletProvider`/context to support a new
`setPendingOperationAddress` hook and to *auto-derive* the effective
wallet type from the in-flight operation address (via
`getHardwareWalletTypeForAddress`) when no explicit `targetWalletType`
is set. Also tightens the `setTargetWalletType` context type and updates
affected tests/mocks.
> 
> Separately introduces a `ReplacementGasFeeValues` type alias and
reuses it in replacement gas normalization/repricing helpers (no
functional behavior change).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
3db6970. 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/components/Views/LedgerSelectAccount/index.test.tsx

@@ -163,6 +163,7 @@ const defaultHardwareWalletValues = {
   },
   ensureDeviceReady: mockEnsureDeviceReady,
   setTargetWalletType: mockSetTargetWalletType,
+  setPendingOperationAddress: jest.fn(),
   showHardwareWalletError: mockShowHardwareWalletError,
   showAwaitingConfirmation: mockShowAwaitingConfirmation,
   hideAwaitingConfirmation: mockHideAwaitingConfirmation,

app/core/HardwareWallet/HardwareWalletProvider.tsx

@@ -8,6 +8,7 @@ import React, {
 
 import HardwareWalletContext from './contexts/HardwareWalletContext';
 import { HardwareWalletBottomSheet } from './components';
+import { getHardwareWalletTypeForAddress } from './helpers';
 import {
   useHardwareWalletStateManager,
   useDeviceEventHandlers,
@@ -42,7 +43,16 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
   const { state, refs, setters } = useHardwareWalletStateManager();
   const { connectionState, deviceId, walletType, targetWalletType } = state;
 
-  const effectiveWalletType = targetWalletType ?? walletType;
+  const [pendingOperationAddress, setPendingOperationAddress] = useState<
+    string | null
+  >(null);
+
+  const walletTypeFromPendingAddress = pendingOperationAddress
+    ? (getHardwareWalletTypeForAddress(pendingOperationAddress) ?? null)
+    : null;
+
+  const effectiveWalletType =
+    targetWalletType ?? walletTypeFromPendingAddress ?? walletType;
 
   const { handleDeviceEvent, handleError, updateConnectionState } =
     useDeviceEventHandlers({
@@ -189,6 +199,7 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
       deviceSelection,
       ensureDeviceReady,
       setTargetWalletType: setters.setTargetWalletType,
+      setPendingOperationAddress,
       showHardwareWalletError,
       showAwaitingConfirmation,
       hideAwaitingConfirmation,
@@ -200,6 +211,7 @@ export const HardwareWalletProvider: React.FC<HardwareWalletProviderProps> = ({
       deviceSelection,
       ensureDeviceReady,
       setters.setTargetWalletType,
+      setPendingOperationAddress,
       showHardwareWalletError,
       showAwaitingConfirmation,
       hideAwaitingConfirmation,

app/core/HardwareWallet/contexts/HardwareWalletContext.test.tsx

@@ -27,6 +27,7 @@ const createMockContextValue = (
   deviceSelection: defaultDeviceSelection,
   ensureDeviceReady: asyncFalse,
   setTargetWalletType: noop,
+  setPendingOperationAddress: noop,
   showHardwareWalletError: noop,
   showAwaitingConfirmation: noop,
   hideAwaitingConfirmation: noop,

app/core/HardwareWallet/contexts/HardwareWalletContext.tsx

@@ -22,7 +22,9 @@ export interface HardwareWalletContextValue {
    */
   ensureDeviceReady: (deviceId?: string | null) => Promise<boolean>;
   /** Set the target wallet type for "Add Hardware Wallet" flows (no account yet). */
-  setTargetWalletType: (walletType: HardwareWalletType | null) => void;
+  setTargetWalletType: (walletType: HardwareWalletType) => void;
+  /** Set the pending operation address so the provider can auto-derive the wallet type during signing. */
+  setPendingOperationAddress: (address: string | null) => void;
   /** Show a hardware wallet error in the bottom sheet. Use after ensureDeviceReady succeeds. */
   showHardwareWalletError: (error: unknown) => void;
   /** Show "awaiting confirmation" bottom sheet. */

app/core/HardwareWallet/executeHardwareWalletOperation.test.ts

@@ -0,0 +1,238 @@
+import { executeHardwareWalletOperation } from './executeHardwareWalletOperation';
+
+const mockGetDeviceIdForAddress = jest.fn();
+const mockIsUserCancellation = jest.fn().mockReturnValue(false);
+
+jest.mock('./helpers', () => ({
+  getDeviceIdForAddress: (...args: unknown[]) =>
+    mockGetDeviceIdForAddress(...args),
+}));
+
+jest.mock('./errors', () => ({
+  isUserCancellation: (...args: unknown[]) => mockIsUserCancellation(...args),
+}));
+
+describe('executeHardwareWalletOperation', () => {
+  const ensureDeviceReady = jest.fn();
+  const showAwaitingConfirmation = jest.fn();
+  const hideAwaitingConfirmation = jest.fn();
+  const showHardwareWalletError = jest.fn();
+  const setPendingOperationAddress = jest.fn();
+  const execute = jest.fn();
+  const onError = jest.fn();
+  const onRejected = jest.fn();
+
+  const baseOptions = {
+    address: '0x123',
+    operationType: 'transaction' as const,
+    ensureDeviceReady,
+    setPendingOperationAddress,
+    showAwaitingConfirmation,
+    hideAwaitingConfirmation,
+    showHardwareWalletError,
+    onError,
+    execute,
+    onRejected,
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockGetDeviceIdForAddress.mockResolvedValue('device-123');
+    ensureDeviceReady.mockResolvedValue(true);
+    execute.mockResolvedValue(undefined);
+    onError.mockResolvedValue(false);
+  });
+
+  it('resolves the device id before checking readiness', async () => {
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      true,
+    );
+
+    expect(mockGetDeviceIdForAddress).toHaveBeenCalledWith('0x123');
+    expect(ensureDeviceReady).toHaveBeenCalledWith('device-123');
+  });
+
+  it('sets the pending operation address at the start and clears it in the finally block', async () => {
+    await executeHardwareWalletOperation(baseOptions);
+
+    expect(setPendingOperationAddress).toHaveBeenNthCalledWith(1, '0x123');
+    expect(setPendingOperationAddress).toHaveBeenLastCalledWith(null);
+  });
+
+  it('shows awaiting confirmation while executing the operation', async () => {
+    await executeHardwareWalletOperation(baseOptions);
+
+    expect(showAwaitingConfirmation).toHaveBeenCalledWith(
+      'transaction',
+      expect.any(Function),
+    );
+    expect(execute).toHaveBeenCalledTimes(1);
+    expect(hideAwaitingConfirmation).toHaveBeenCalledTimes(1);
+    expect(onRejected).not.toHaveBeenCalled();
+  });
+
+  it('rejects when the device is not ready', async () => {
+    ensureDeviceReady.mockResolvedValue(false);
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(showAwaitingConfirmation).not.toHaveBeenCalled();
+    expect(execute).not.toHaveBeenCalled();
+    expect(onRejected).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows the hardware wallet error for unexpected operation errors', async () => {
+    const error = new Error('signing failed');
+    execute.mockRejectedValueOnce(error);
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(hideAwaitingConfirmation).toHaveBeenCalledTimes(1);
+    expect(showHardwareWalletError).toHaveBeenCalledWith(error);
+    expect(onRejected).toHaveBeenCalledTimes(1);
+  });
+
+  it('lets callers handle non-user cancellations without showing the shared hardware wallet error', async () => {
+    const error = new Error('keystone cancelled');
+    execute.mockRejectedValueOnce(error);
+    onError.mockResolvedValueOnce(true);
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(onError).toHaveBeenCalledWith(error);
+    expect(showHardwareWalletError).not.toHaveBeenCalled();
+    expect(onRejected).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not show hardware wallet errors for user cancellations', async () => {
+    const error = new Error('User rejected');
+    execute.mockRejectedValueOnce(error);
+    mockIsUserCancellation.mockReturnValueOnce(true);
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(showHardwareWalletError).not.toHaveBeenCalled();
+    expect(onRejected).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects only once when the awaiting confirmation cancel callback fires after an error', async () => {
+    let cancelCallback: (() => void) | undefined;
+    showAwaitingConfirmation.mockImplementation(
+      (_operationType: string, onReject?: () => void) => {
+        cancelCallback = onReject;
+      },
+    );
+    execute.mockRejectedValueOnce(new Error('fail'));
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+    cancelCallback?.();
+
+    expect(onRejected).toHaveBeenCalledTimes(1);
+  });
+
+  it('works without setPendingOperationAddress provided', async () => {
+    const { setPendingOperationAddress: _, ...optionsWithoutSetter } =
+      baseOptions;
+
+    await expect(
+      executeHardwareWalletOperation(optionsWithoutSetter),
+    ).resolves.toBe(true);
+
+    expect(execute).toHaveBeenCalledTimes(1);
+  });
+
+  it('works without onRejected provided', async () => {
+    const { onRejected: _, ...optionsWithoutReject } = baseOptions;
+
+    await expect(
+      executeHardwareWalletOperation(optionsWithoutReject),
+    ).resolves.toBe(true);
+  });
+
+  it('passes message operationType to showAwaitingConfirmation', async () => {
+    await expect(
+      executeHardwareWalletOperation({
+        ...baseOptions,
+        operationType: 'message',
+      }),
+    ).resolves.toBe(true);
+
+    expect(showAwaitingConfirmation).toHaveBeenCalledWith(
+      'message',
+      expect.any(Function),
+    );
+  });
+
+  it('skips hardware wallet error when cancel callback fires before execute throws', async () => {
+    let cancelCallback: (() => void) | undefined;
+    showAwaitingConfirmation.mockImplementation(
+      (_operationType: string, onReject?: () => void) => {
+        cancelCallback = onReject;
+      },
+    );
+    execute.mockImplementation(async () => {
+      cancelCallback?.();
+      throw new Error('fail');
+    });
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(showHardwareWalletError).not.toHaveBeenCalled();
+    expect(onRejected).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows the hardware wallet error when device id lookup fails', async () => {
+    const error = new Error('device lookup failed');
+    mockGetDeviceIdForAddress.mockRejectedValueOnce(error);
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(showHardwareWalletError).toHaveBeenCalledWith(error);
+    expect(execute).not.toHaveBeenCalled();
+  });
+
+  it('does not call hideAwaitingConfirmation when the error occurs before showAwaitingConfirmation', async () => {
+    const error = new Error('device lookup failed');
+    mockGetDeviceIdForAddress.mockRejectedValueOnce(error);
+
+    await executeHardwareWalletOperation(baseOptions);
+
+    expect(showAwaitingConfirmation).not.toHaveBeenCalled();
+    expect(hideAwaitingConfirmation).not.toHaveBeenCalled();
+  });
+
+  it('does not call hideAwaitingConfirmation when ensureDeviceReady throws before showAwaitingConfirmation', async () => {
+    const error = new Error('BLE connection failed');
+    ensureDeviceReady.mockRejectedValueOnce(error);
+
+    await executeHardwareWalletOperation(baseOptions);
+
+    expect(showAwaitingConfirmation).not.toHaveBeenCalled();
+    expect(hideAwaitingConfirmation).not.toHaveBeenCalled();
+  });
+
+  it('clears pending operation address in finally block even on error', async () => {
+    execute.mockRejectedValueOnce(new Error('fail'));
+
+    await expect(executeHardwareWalletOperation(baseOptions)).resolves.toBe(
+      false,
+    );
+
+    expect(setPendingOperationAddress).toHaveBeenNthCalledWith(1, '0x123');
+    expect(setPendingOperationAddress).toHaveBeenLastCalledWith(null);
+  });
+});