fix: expose missing methods in hardware keyrings wrappers (#551)

There's some missing methods that are needed by the clients.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Moderate risk because it adds new public surface area and changes
`forgetDevice` behavior to also clear the V2 account registry, which
could affect client state/caching around device resets.
> 
> **Overview**
> Exposes missing *device-management* APIs on the V2 wrapper keyrings so
clients can manage paired hardware devices directly via the wrapper.
> 
> `LedgerKeyring`, `QrKeyring`, and `TrezorKeyring` (and thus
`OneKeyKeyring`) now pass through getters/methods like `hdPath`,
`bridge`, paging (`getFirstPage`/`getNextPage`/`getPreviousPage`), and
device reset (`forgetDevice`), plus device-specific calls (e.g. Ledger
`get/setDeviceId`, `attemptMakeApp`, `getAppNameAndVersion`, Trezor
`getModel`, `isUnlocked`). `forgetDevice` also clears the V2 registry to
keep wrapper accounts in sync with the inner keyring, and new unit
tests/changelog entries cover these additions.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
56e782c. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: hmalik88

packages/keyring-eth-ledger-bridge/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Expose device-management pass-throughs on the V2 `LedgerKeyring` wrapper: `hdPath` (getter), `bridge` (getter), `getDeviceId`, `setDeviceId`, `setHdPath`, `getFirstPage`, `getNextPage`, `getPreviousPage`, `forgetDevice`, `isUnlocked`, `attemptMakeApp`, `getAppNameAndVersion`. `forgetDevice` additionally clears the V2 account registry to keep it in sync with the inner keyring. ([#551](https://github.com/MetaMask/accounts/pull/551))
+
 ## [12.0.3]
 
 ### Changed

packages/keyring-eth-ledger-bridge/src/v2/ledger-keyring.test.ts

@@ -852,4 +852,103 @@ describe('LedgerKeyring', () => {
       expect(accounts[1]?.options.entropy.groupIndex).toBe(2);
     });
   });
+
+  describe('device management pass-throughs', () => {
+    it('exposes the inner keyring hdPath', () => {
+      const { wrapper, inner } = createEmptyWrapper();
+
+      expect(wrapper.hdPath).toBe(inner.hdPath);
+    });
+
+    it('exposes the inner keyring bridge', () => {
+      const { wrapper, inner } = createEmptyWrapper();
+
+      expect(wrapper.bridge).toBe(inner.bridge);
+    });
+
+    it('getDeviceId delegates to the inner keyring', () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      inner.setDeviceId('device-abc');
+
+      expect(wrapper.getDeviceId()).toBe('device-abc');
+    });
+
+    it('setDeviceId delegates to the inner keyring', () => {
+      const { wrapper, inner } = createEmptyWrapper();
+
+      wrapper.setDeviceId('device-xyz');
+
+      expect(inner.getDeviceId()).toBe('device-xyz');
+    });
+
+    it('setHdPath delegates to the inner keyring', () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const setHdPathSpy = jest.spyOn(inner, 'setHdPath');
+
+      wrapper.setHdPath(`m/44'/60'/0'/0`);
+
+      expect(setHdPathSpy).toHaveBeenCalledWith(`m/44'/60'/0'/0`);
+      expect(inner.hdPath).toBe(`m/44'/60'/0'/0`);
+    });
+
+    it('getFirstPage delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const page = [{ address: EXPECTED_ACCOUNTS[0], balance: 0, index: 0 }];
+      jest.spyOn(inner, 'getFirstPage').mockResolvedValue(page);
+
+      expect(await wrapper.getFirstPage()).toStrictEqual(page);
+    });
+
+    it('getNextPage delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const page = [{ address: EXPECTED_ACCOUNTS[1], balance: 0, index: 1 }];
+      jest.spyOn(inner, 'getNextPage').mockResolvedValue(page);
+
+      expect(await wrapper.getNextPage()).toStrictEqual(page);
+    });
+
+    it('getPreviousPage delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const page = [{ address: EXPECTED_ACCOUNTS[0], balance: 0, index: 0 }];
+      jest.spyOn(inner, 'getPreviousPage').mockResolvedValue(page);
+
+      expect(await wrapper.getPreviousPage()).toStrictEqual(page);
+    });
+
+    it('forgetDevice clears inner state and the V2 registry', async () => {
+      const { wrapper, inner } = await createWrapperWithAccounts(2);
+
+      // Populate the wrapper's registry by reading accounts.
+      const accounts = await wrapper.getAccounts();
+      expect(accounts).toHaveLength(2);
+
+      await wrapper.forgetDevice();
+
+      expect(inner.accounts).toStrictEqual([]);
+      expect(inner.accountDetails).toStrictEqual({});
+      expect(await wrapper.getAccounts()).toStrictEqual([]);
+    });
+
+    it('isUnlocked delegates to the inner keyring', () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      jest.spyOn(inner, 'isUnlocked').mockReturnValue(true);
+
+      expect(wrapper.isUnlocked()).toBe(true);
+    });
+
+    it('attemptMakeApp delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      jest.spyOn(inner, 'attemptMakeApp').mockResolvedValue(true);
+
+      expect(await wrapper.attemptMakeApp()).toBe(true);
+    });
+
+    it('getAppNameAndVersion delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const response = { appName: 'Ethereum', version: '1.10.0' };
+      jest.spyOn(inner, 'getAppNameAndVersion').mockResolvedValue(response);
+
+      expect(await wrapper.getAppNameAndVersion()).toStrictEqual(response);
+    });
+  });
 });

packages/keyring-eth-ledger-bridge/src/v2/ledger-keyring.ts

@@ -17,7 +17,15 @@ import type { AccountId, EthKeyring } from '@metamask/keyring-utils';
 import { add0x, getChecksumAddress } from '@metamask/utils';
 import type { Hex } from '@metamask/utils';
 
-import type { LedgerKeyring as LegacyLedgerKeyring } from '../ledger-keyring';
+import type {
+  GetAppNameAndVersionResponse,
+  LedgerBridge,
+  LedgerBridgeOptions,
+} from '../ledger-bridge';
+import type {
+  AccountPage,
+  LedgerKeyring as LegacyLedgerKeyring,
+} from '../ledger-keyring';
 
 /**
  * Methods supported by Ledger keyring EOA accounts.
@@ -350,4 +358,106 @@ export class LedgerKeyring
       this.registry.delete(accountId);
     });
   }
+
+  /**
+   * @returns The current derivation path used by the inner keyring.
+   */
+  get hdPath(): string {
+    return this.inner.hdPath;
+  }
+
+  /**
+   * @returns The bridge instance used by the inner keyring to communicate
+   * with the device.
+   */
+  get bridge(): LedgerBridge<LedgerBridgeOptions> {
+    return this.inner.bridge;
+  }
+
+  /**
+   * @returns The device ID for the paired Ledger device.
+   */
+  getDeviceId(): string {
+    return this.inner.getDeviceId();
+  }
+
+  /**
+   * Set the device ID for the paired Ledger device.
+   *
+   * @param deviceId - The device ID to set.
+   */
+  setDeviceId(deviceId: string): void {
+    this.inner.setDeviceId(deviceId);
+  }
+
+  /**
+   * Set the derivation path on the inner keyring.
+   *
+   * @param hdPath - The derivation path to set.
+   */
+  setHdPath(hdPath: string): void {
+    this.inner.setHdPath(hdPath);
+  }
+
+  /**
+   * Fetch the first page of candidate addresses from the device.
+   *
+   * @returns The first page of accounts.
+   */
+  async getFirstPage(): Promise<AccountPage> {
+    return this.inner.getFirstPage();
+  }
+
+  /**
+   * Fetch the next page of candidate addresses from the device.
+   *
+   * @returns The next page of accounts.
+   */
+  async getNextPage(): Promise<AccountPage> {
+    return this.inner.getNextPage();
+  }
+
+  /**
+   * Fetch the previous page of candidate addresses from the device.
+   *
+   * @returns The previous page of accounts.
+   */
+  async getPreviousPage(): Promise<AccountPage> {
+    return this.inner.getPreviousPage();
+  }
+
+  /**
+   * Clear the inner keyring's device-pairing state and accounts, and reset
+   * the V2 account registry to keep them in sync.
+   */
+  async forgetDevice(): Promise<void> {
+    await this.withLock(async () => {
+      this.inner.forgetDevice();
+      this.registry.clear();
+    });
+  }
+
+  /**
+   * @returns Whether the inner keyring has an unlocked HD key.
+   */
+  isUnlocked(): boolean {
+    return this.inner.isUnlocked();
+  }
+
+  /**
+   * Attempt to open the Ethereum app on the connected Ledger device.
+   *
+   * @returns Whether the app was opened.
+   */
+  async attemptMakeApp(): Promise<boolean> {
+    return this.inner.attemptMakeApp();
+  }
+
+  /**
+   * @returns The app name and version currently running on the connected
+   * Ledger device.
+   */
+  async getAppNameAndVersion(): Promise<GetAppNameAndVersionResponse> {
+    return this.inner.getAppNameAndVersion();
+  }
 }

packages/keyring-eth-qr/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Expose device-management pass-throughs on the V2 `QrKeyring` wrapper: `getName`, `getMode`, `getFirstPage`, `getNextPage`, `getPreviousPage`, `forgetDevice`. `forgetDevice` additionally clears the V2 account registry to keep it in sync with the inner keyring. ([#551](https://github.com/MetaMask/accounts/pull/551))
+
 ### Changed
 
 - Bump `@metamask/keyring-sdk` from `^2.0.2` to `^2.1.1` ([#544](https://github.com/MetaMask/accounts/pull/544), [#546](https://github.com/MetaMask/accounts/pull/546))

packages/keyring-eth-qr/src/v2/qr-keyring.test.ts

@@ -766,4 +766,61 @@ describe('QrKeyring', () => {
       });
     });
   });
+
+  describe('device management pass-throughs', () => {
+    it('getName delegates to the inner keyring', async () => {
+      const { wrapper, inner } = await createWrapperWithAccounts(1);
+
+      expect(wrapper.getName()).toBe(inner.getName());
+    });
+
+    it('getMode delegates to the inner keyring', async () => {
+      const { wrapper, inner } = await createWrapperWithAccounts(1);
+
+      expect(wrapper.getMode()).toBe(inner.getMode());
+    });
+
+    it('getFirstPage delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const page = [{ address: EXPECTED_ACCOUNTS[0], index: 0 }] as Awaited<
+        ReturnType<LegacyQrKeyring['getFirstPage']>
+      >;
+      jest.spyOn(inner, 'getFirstPage').mockResolvedValue(page);
+
+      expect(await wrapper.getFirstPage()).toStrictEqual(page);
+    });
+
+    it('getNextPage delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const page = [{ address: EXPECTED_ACCOUNTS[1], index: 1 }] as Awaited<
+        ReturnType<LegacyQrKeyring['getNextPage']>
+      >;
+      jest.spyOn(inner, 'getNextPage').mockResolvedValue(page);
+
+      expect(await wrapper.getNextPage()).toStrictEqual(page);
+    });
+
+    it('getPreviousPage delegates to the inner keyring', async () => {
+      const { wrapper, inner } = createEmptyWrapper();
+      const page = [{ address: EXPECTED_ACCOUNTS[0], index: 0 }] as Awaited<
+        ReturnType<LegacyQrKeyring['getPreviousPage']>
+      >;
+      jest.spyOn(inner, 'getPreviousPage').mockResolvedValue(page);
+
+      expect(await wrapper.getPreviousPage()).toStrictEqual(page);
+    });
+
+    it('forgetDevice clears inner state and the V2 registry', async () => {
+      const { wrapper, inner } = await createWrapperWithAccounts(2);
+
+      // Populate the wrapper's registry by reading accounts.
+      const accounts = await wrapper.getAccounts();
+      expect(accounts).toHaveLength(2);
+
+      await wrapper.forgetDevice();
+
+      expect(await inner.getAccounts()).toStrictEqual([]);
+      expect(await wrapper.getAccounts()).toStrictEqual([]);
+    });
+  });
 });

packages/keyring-eth-qr/src/v2/qr-keyring.ts

@@ -18,6 +18,7 @@ import type { AccountId } from '@metamask/keyring-utils';
 import type { Hex } from '@metamask/utils';
 
 import { DeviceMode } from '../device';
+import type { IndexedAddress } from '../device';
 import type { QrKeyring as LegacyQrKeyring } from '../qr-keyring';
 
 /**
@@ -435,4 +436,58 @@ export class QrKeyring
       this.registry.delete(accountId);
     });
   }
+
+  /**
+   * @returns The name of the paired device, or the keyring type if no device
+   * is paired.
+   */
+  getName(): string {
+    return this.inner.getName();
+  }
+
+  /**
+   * @returns The current device mode (HD or Account), or `undefined` if no
+   * device is paired.
+   */
+  getMode(): DeviceMode | undefined {
+    return this.inner.getMode();
+  }
+
+  /**
+   * Fetch the first page of candidate addresses from the device.
+   *
+   * @returns The first page of addresses.
+   */
+  async getFirstPage(): Promise<IndexedAddress[]> {
+    return this.inner.getFirstPage();
+  }
+
+  /**
+   * Fetch the next page of candidate addresses from the device.
+   *
+   * @returns The next page of addresses.
+   */
+  async getNextPage(): Promise<IndexedAddress[]> {
+    return this.inner.getNextPage();
+  }
+
+  /**
+   * Fetch the previous page of candidate addresses from the device.
+   *
+   * @returns The previous page of addresses.
+   */
+  async getPreviousPage(): Promise<IndexedAddress[]> {
+    return this.inner.getPreviousPage();
+  }
+
+  /**
+   * Clear the inner keyring's device-pairing state and accounts, and reset
+   * the V2 account registry to keep them in sync.
+   */
+  async forgetDevice(): Promise<void> {
+    await this.withLock(async () => {
+      await this.inner.forgetDevice();
+      this.registry.clear();
+    });
+  }
 }

packages/keyring-eth-trezor/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Expose device-management pass-throughs on the V2 `TrezorKeyring` wrapper (inherited by the V2 `OneKeyKeyring`): `getModel`, `hdPath` (getter), `bridge` (getter), `setHdPath`, `getFirstPage`, `getNextPage`, `getPreviousPage`, `forgetDevice`, `isUnlocked`. `forgetDevice` additionally clears the V2 account registry to keep it in sync with the inner keyring. ([#551](https://github.com/MetaMask/accounts/pull/551))
+
 ### Changed
 
 - Bump `@metamask/keyring-sdk` from `^2.0.2` to `^2.1.1` ([#544](https://github.com/MetaMask/accounts/pull/544), [#546](https://github.com/MetaMask/accounts/pull/546))