feat(keyring-api): add bip44:derive-index-range (#451)

Add new `bip44:derive-index-range` constructor.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Public API/types are extended and `KeyringCapabilities.bip44` now
requires a new `deriveIndexRange` boolean, which may force downstream
keyring implementations to update their declared capabilities.
> 
> **Overview**
> Adds support for a new account-creation mode
`bip44:derive-index-range` by introducing
`AccountCreationType.Bip44DeriveIndexRange` plus
`CreateAccountBip44DeriveIndexRangeOptions`/superstruct validation, and
wiring it into the `CreateAccountOptionsStruct` selective union.
> 
> Extends `KeyringCapabilities.bip44` with a required `deriveIndexRange`
boolean and updates type tests and Ethereum keyring wrappers
(HD/Ledger/QR/Trezor) to explicitly report `deriveIndexRange: false`,
along with changelog entries across affected packages.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
714aa5c. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: ccharly

packages/keyring-api/CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add support for account derivations using range of indices in `KeyringV2` ([#451](https://github.com/MetaMask/accounts/pull/451))
+  - Add `bip44:derive-index-range` capability to `KeyringCapabilities`.
+  - Add `AccountCreationType.Bip44DeriveIndexRange` and `CreateAccountBip44DeriveIndexRangeOptions`.
 - Add support for custom capabilities and entropy types in `KeyringV2` ([#415](https://github.com/MetaMask/accounts/pull/415))
   - Add `custom` capability to `KeyringCapabilities` for keyrings with non-standard `createAccounts` method.
   - Add `KeyringAccountEntropyTypeOption.Custom` for custom/opaque entropy sources.

packages/keyring-api/src/api/v2/create-account/bip44.ts

@@ -88,3 +88,43 @@ export const CreateAccountBip44DiscoverOptionsStruct = object({
 export type CreateAccountBip44DiscoverOptions = Infer<
   typeof CreateAccountBip44DiscoverOptionsStruct
 >;
+
+/**
+ * Struct for {@link CreateAccountBip44DeriveIndexRangeOptions}.
+ */
+export const CreateAccountBip44DeriveIndexRangeOptionsStruct = object({
+  /**
+   * The type of the options.
+   */
+  type: literal('bip44:derive-index-range'),
+  /**
+   * ID of the entropy source to be used to derive the accounts.
+   */
+  entropySource: string(),
+  /**
+   * The range of account group indices to derive (inclusive on both ends).
+   */
+  range: object({
+    /**
+     * The starting index of the account group range (inclusive).
+     */
+    from: number(),
+    /**
+     * The ending index of the account group range (inclusive).
+     */
+    to: number(),
+  }),
+});
+
+/**
+ * Options for creating accounts by deriving a range of BIP-44 account indices.
+ *
+ * The range is inclusive on both ends, meaning range.from=0 and range.to=5
+ * will create accounts for group indices 0, 1, 2, 3, 4, and 5.
+ *
+ * Note that the keyring can support non-standard BIP-44 paths for
+ * compatibility with other wallets.
+ */
+export type CreateAccountBip44DeriveIndexRangeOptions = Infer<
+  typeof CreateAccountBip44DeriveIndexRangeOptionsStruct
+>;

packages/keyring-api/src/api/v2/create-account/index.ts

@@ -4,6 +4,7 @@ import { type Infer } from '@metamask/superstruct';
 import {
   CreateAccountBip44DiscoverOptionsStruct,
   CreateAccountBip44DeriveIndexOptionsStruct,
+  CreateAccountBip44DeriveIndexRangeOptionsStruct,
   CreateAccountBip44DerivePathOptionsStruct,
 } from './bip44';
 import { CreateAccountCustomOptionsStruct } from './custom';
@@ -31,6 +32,15 @@ export enum AccountCreationType {
    */
   Bip44DeriveIndex = 'bip44:derive-index',
 
+  /**
+   * Represents accounts created by deriving a range of BIP-44 account indices.
+   *
+   * More than one account can be created per index, for example, the keyring
+   * can create multiple account types (e.g., P2PKH, P2TR, P2WPKH) for each
+   * account index in the range.
+   */
+  Bip44DeriveIndexRange = 'bip44:derive-index-range',
+
   /**
    * Represents accounts created through BIP-44 account discovery.
    *
@@ -64,6 +74,8 @@ export const CreateAccountOptionsStruct = selectiveUnion((value: any) => {
       return CreateAccountBip44DerivePathOptionsStruct;
     case AccountCreationType.Bip44DeriveIndex:
       return CreateAccountBip44DeriveIndexOptionsStruct;
+    case AccountCreationType.Bip44DeriveIndexRange:
+      return CreateAccountBip44DeriveIndexRangeOptionsStruct;
     case AccountCreationType.Bip44Discover:
       return CreateAccountBip44DiscoverOptionsStruct;
     case AccountCreationType.PrivateKeyImport:

packages/keyring-api/src/api/v2/keyring-capabilities.ts

@@ -35,6 +35,10 @@ export const KeyringCapabilitiesStruct = object({
        * Whether the keyring supports deriving accounts from a BIP-44 account index.
        */
       deriveIndex: boolean(),
+      /**
+       * Whether the keyring supports deriving accounts from a range of BIP-44 account indices.
+       */
+      deriveIndexRange: boolean(),
       /**
        * Whether the keyring supports BIP-44 account discovery.
        */
@@ -82,6 +86,7 @@ export const KeyringCapabilitiesStruct = object({
  *   bip44: {
  *     derivePath: true,
  *     deriveIndex: true,
+ *     deriveIndexRange: true,
  *     discover: true,
  *   },
  *   privateKey: {

packages/keyring-api/src/api/v2/keyring.test-d.ts

@@ -63,6 +63,7 @@ expectAssignable<KeyringCapabilities>({
   bip44: {
     derivePath: true,
     deriveIndex: true,
+    deriveIndexRange: true,
     discover: false,
   },
 });

packages/keyring-eth-hd/CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Add `HdKeyringV2` class implementing `KeyringV2` interface ([#398](https://github.com/MetaMask/accounts/pull/398)), ([#404](https://github.com/MetaMask/accounts/pull/404)), ([#410](https://github.com/MetaMask/accounts/pull/410)), ([#413](https://github.com/MetaMask/accounts/pull/413))
+- Add `HdKeyringV2` class implementing `KeyringV2` interface ([#398](https://github.com/MetaMask/accounts/pull/398)), ([#404](https://github.com/MetaMask/accounts/pull/404)), ([#410](https://github.com/MetaMask/accounts/pull/410)), ([#413](https://github.com/MetaMask/accounts/pull/413)), ([#451](https://github.com/MetaMask/accounts/pull/451))
   - Wraps legacy `HdKeyring` to expose accounts via the unified `KeyringV2` API and the `KeyringAccount` type.
   - Extends `EthKeyringWrapper` for common Ethereum logic.
 

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

@@ -67,6 +67,7 @@ describe('HdKeyringV2', () => {
       expect(wrapper.capabilities.scopes).toStrictEqual([EthScope.Eoa]);
       expect(wrapper.capabilities.bip44?.deriveIndex).toBe(true);
       expect(wrapper.capabilities.bip44?.derivePath).toBe(false);
+      expect(wrapper.capabilities.bip44?.deriveIndexRange).toBe(false);
       expect(wrapper.capabilities.bip44?.discover).toBe(false);
     });
   });

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

@@ -43,6 +43,7 @@ const hdKeyringV2Capabilities: KeyringCapabilities = {
   bip44: {
     deriveIndex: true,
     derivePath: false,
+    deriveIndexRange: false,
     discover: false,
   },
   privateKey: {

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

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Add `LedgerKeyringV2` class implementing `KeyringV2` interface ([#416](https://github.com/MetaMask/accounts/pull/416))
+- Add `LedgerKeyringV2` class implementing `KeyringV2` interface ([#416](https://github.com/MetaMask/accounts/pull/416)), ([#451](https://github.com/MetaMask/accounts/pull/451))
   - Wraps legacy `LedgerKeyring` to expose accounts via the unified `KeyringV2` API and the `KeyringAccount` type.
   - Extends `EthKeyringWrapper` for common Ethereum logic.
 

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

@@ -252,6 +252,7 @@ describe('LedgerKeyringV2', () => {
         bip44: {
           deriveIndex: true,
           derivePath: true,
+          deriveIndexRange: false,
           discover: false,
         },
       });