Merge pull request #483 from autonomys/eth-key-derivation

feat: add optional derivationPath for Ethereum HD wallets

Author: jfrank-summit

examples/node/README.md

@@ -59,6 +59,33 @@ yarn autoid:view-revoked-certs <AUTO_ID_IDENTIFIER>
 
 ```bash
 yarn address
+yarn eth-derivation-demo
+```
+
+### Ethereum derivation paths (demo)
+
+The `eth-derivation-demo` script shows the difference between deriving an Ethereum address from the master key (`m`) and from the BIP44 path (`m/44'/60'/0'/0/0`). It also cross-checks results using `ethers`.
+
+To run:
+
+```bash
+yarn eth-derivation-demo
+```
+
+Programmatic usage with optional `derivationPath`:
+
+```ts
+import { setupWallet } from '@autonomys/auto-utils'
+
+// Master key (m) derivation
+const ethMaster = setupWallet({ mnemonic, type: 'ethereum' })
+
+// BIP44 derivation
+const ethBip44 = setupWallet({
+  mnemonic,
+  type: 'ethereum',
+  derivationPath: "m/44'/60'/0'/0/0",
+} as any)
 ```
 
 ## Run All

examples/node/package.json

@@ -16,6 +16,7 @@
     "cli": "npx ts-node ./src/cli.ts",
     "all": "yarn address && yarn balance && yarn transfer && yarn operators && yarn register-operator && yarn nominate-operator && yarn withdraw-stake && yarn deregister-operator",
     "address": "npx ts-node ./src/address.ts",
+    "eth-derivation-demo": "npx ts-node ./src/eth-derivation-demo.ts",
     "balance": "npx ts-node ./src/balance.ts",
     "transfer": "npx ts-node ./src/transfer.ts",
     "operators": "npx ts-node ./src/operators.ts",
@@ -28,7 +29,8 @@
   },
   "dependencies": {
     "@autonomys/auto-consensus": "workspace:*",
-    "@autonomys/auto-utils": "workspace:*"
+    "@autonomys/auto-utils": "workspace:*",
+    "ethers": "^6.13.5"
   },
   "devDependencies": {
     "commander": "^12.1.0",

examples/node/src/eth-derivation-demo.ts

@@ -0,0 +1,44 @@
+import { setupWallet } from '@autonomys/auto-utils'
+import { HDNodeWallet, Mnemonic, Wallet } from 'ethers'
+
+const MNEMONIC = 'test test test test test test test test test test test junk'
+
+const main = async (): Promise<void> => {
+  const master = setupWallet({ mnemonic: MNEMONIC, type: 'ethereum' })
+
+  const bip44Path = "m/44'/60'/0'/0/0"
+  const bip44 = setupWallet({
+    mnemonic: MNEMONIC,
+    type: 'ethereum',
+    derivationPath: bip44Path,
+  })
+
+  const ethersMnemonic = Mnemonic.fromPhrase(MNEMONIC)
+  const ethersWallet = Wallet.fromPhrase(MNEMONIC)
+  const ethersMaster = HDNodeWallet.fromMnemonic(ethersMnemonic, 'm')
+  const ethersBip44 = HDNodeWallet.fromMnemonic(ethersMnemonic, bip44Path)
+
+  console.log('Mnemonic:', MNEMONIC)
+  console.log('Master (m) address:', master.address)
+  console.log(`BIP44 (${bip44Path}) address:`, bip44.address)
+  console.log('Ethers Wallet address:', ethersWallet.address)
+  console.log('Ethers Master (m) address:', ethersMaster.address)
+  console.log(`Ethers BIP44 (${bip44Path}) address:`, ethersBip44.address)
+  console.log('Match?', master.address.toLowerCase() === bip44.address.toLowerCase())
+  console.log(
+    'Auto (m) === Ethers (m)?',
+    master.address.toLowerCase() === ethersMaster.address.toLowerCase(),
+  )
+  console.log(
+    `Auto BIP44 === Ethers BIP44?`,
+    bip44.address.toLowerCase() === ethersBip44.address.toLowerCase(),
+  )
+  console.log(
+    'Note: Current SDK behavior derives Ethereum from master key (m) unless a path is provided.',
+  )
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

packages/auto-utils/README.md

@@ -71,6 +71,8 @@ import { activateWallet } from '@autonomys/auto-utils'
   const { api, accounts } = await activateWallet({
     mnemonic,
     networkId: 'mainnet', // Optional: specify the network ID
+    // Optional derivation path (useful for ethereum BIP44):
+    // derivationPath: "m/44'/60'/0'/0/0",
   })
 
   const account = accounts[0]
@@ -263,6 +265,27 @@ import { activateDomain } from '@autonomys/auto-utils'
 
 ---
 
+#### **Setup a Wallet with Ethereum BIP44**
+
+```typescript
+import { setupWallet } from '@autonomys/auto-utils'
+
+const mnemonic = 'your mnemonic phrase here'
+
+// Default behavior derives from master (m)
+const ethMaster = setupWallet({ mnemonic, type: 'ethereum' })
+
+// To derive using BIP44 path
+const ethBip44 = setupWallet({
+  mnemonic,
+  type: 'ethereum',
+  derivationPath: "m/44'/60'/0'/0/0",
+})
+
+console.log(ethMaster.address)
+console.log(ethBip44.address)
+```
+
 ### 5. Address Utilities
 
 #### **Convert Address Formats**

packages/auto-utils/__test__/wallet.test.ts

@@ -24,6 +24,7 @@ describe('Verify wallet functions', () => {
   const TEST_MNEMONIC = 'test test test test test test test test test test test junk'
   const TEST_ADDRESS = '5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8'
   const TEST_ADDRESS_ETHEREUM = '0xF5a6EAD936fb47f342Bb63E676479bDdf26EbE1d'
+  const TEST_ADDRESS_ETHEREUM_BIP44 = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
   const ALICE_URI = '//Alice'
   const BOB_URI = '//Bob'
   let api: ApiPromise
@@ -63,6 +64,17 @@ describe('Verify wallet functions', () => {
       expect(wallet.address).toEqual(TEST_ADDRESS_ETHEREUM)
     })
 
+    test("Check setupWallet returns expected address when provided with Ethereum BIP44 derivationPath ('m/44'/60'/0'/0/0')", async () => {
+      const wallet = setupWallet({
+        mnemonic: TEST_MNEMONIC,
+        type: 'ethereum',
+        derivationPath: "m/44'/60'/0'/0/0",
+      } as any)
+      expect(wallet.keyringPair?.type).toEqual('ethereum')
+      expect(wallet.address.startsWith('0x')).toBeTruthy()
+      expect(wallet.address).toEqual(TEST_ADDRESS_ETHEREUM_BIP44)
+    })
+
     test('Check setupWallet return a pair with matching private key when provided with Alice seed', async () => {
       const wallet = setupWallet({ uri: ALICE_URI })
       expect(wallet.commonAddress).toEqual(aliceWallet.address)
@@ -112,6 +124,19 @@ describe('Verify wallet functions', () => {
       expect(accounts[0].address).toEqual(TEST_ADDRESS_ETHEREUM)
     }, 15000)
 
+    test('Check activateWallet returns an account with expected address when provided with a test mnemonic (ethereum + BIP44 derivationPath)', async () => {
+      const { api, accounts } = await activateWallet({
+        ...TEST_NETWORK,
+        mnemonic: TEST_MNEMONIC,
+        type: 'ethereum',
+        derivationPath: "m/44'/60'/0'/0/0",
+      } as ActivateWalletParams)
+      expect(api).toBeDefined()
+      expect(accounts.length).toBeGreaterThan(0)
+      expect(accounts[0].address.startsWith('0x')).toBeTruthy()
+      expect(accounts[0].address).toEqual(TEST_ADDRESS_ETHEREUM_BIP44)
+    }, 15000)
+
     test('Check activateWallet return an api instance and an account when provided with Alice uri', async () => {
       const { api, accounts } = await activateWallet({
         ...TEST_NETWORK,

packages/auto-utils/src/types/wallet.ts

@@ -26,7 +26,10 @@ export type WalletType = {
   type?: KeypairType
 }
 
-export type SetupWalletParams = MnemonicOrURI & WalletType
+export type SetupWalletParams = MnemonicOrURI &
+  WalletType & {
+    derivationPath?: string
+  }
 
 export type Wallet = {
   keyringPair?: KeyringPair
@@ -42,7 +45,9 @@ export interface GeneratedWallet extends Wallet {
 export type ActivateWalletParams = (NetworkParams | DomainParams) &
   MnemonicOrURI &
   ExtraActivationOptions &
-  WalletType
+  WalletType & {
+    derivationPath?: string
+  }
 
 export type WalletActivated = {
   api: ApiPromise

packages/auto-utils/src/wallet.ts

@@ -46,6 +46,14 @@ import type {
  * })
  * console.log(ethWallet.address) // Ethereum-format address (0x...)
  *
+ * // Setup ethereum wallet with BIP44 derivation path
+ * const ethBip44 = setupWallet({
+ *   mnemonic: 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
+ *   type: 'ethereum',
+ *   derivationPath: "m/44'/60'/0'/0/0",
+ * })
+ * console.log(ethBip44.address) // Matches MetaMask default derivation
+ *
  * // Setup development wallet from URI
  * const aliceWallet = setupWallet({ uri: '//Alice' })
  * console.log(aliceWallet.address) // Alice's development address
@@ -67,7 +75,9 @@ export const setupWallet = (params: SetupWalletParams): Wallet => {
     keyringPair = keyring.addFromUri((params as URI).uri)
   } else if ((params as Mnemonic).mnemonic) {
     // Treat as mnemonic
-    keyringPair = keyring.addFromUri((params as Mnemonic).mnemonic)
+    const base = (params as Mnemonic).mnemonic
+    const withPath = params.derivationPath ? `${base}/${params.derivationPath}` : base
+    keyringPair = keyring.addFromUri(withPath)
   } else throw new Error('Invalid mnemonic or private key')
 
   return {
@@ -140,22 +150,22 @@ export const generateWallet = (type: KeypairType = 'sr25519'): GeneratedWallet =
  * console.log('Account address:', accounts[0].address)
  *
  * // Activate on specific network
- * const { api: taurusApi, accounts: taurusAccounts } = await activateWallet({
+ * const { api: mainnetApi, accounts: mainnetAccounts } = await activateWallet({
  *   mnemonic: 'your mnemonic here',
- *   networkId: 'taurus'
+ *   networkId: 'mainnet'
  * })
  *
  * // Activate on domain
  * const { api: domainApi, accounts: domainAccounts } = await activateWallet({
  *   uri: '//Alice',
- *   networkId: 'taurus',
+ *   networkId: 'mainnet',
  *   domainId: '0' // Auto-EVM domain
  * })
  *
  * // Activate with ethereum key type
  * const { api: ethApi, accounts: ethAccounts } = await activateWallet({
  *   mnemonic: 'your mnemonic here',
- *   networkId: 'taurus',
+ *   networkId: 'mainnet',
  *   type: 'ethereum'
  * })
  *
@@ -229,15 +239,15 @@ export const activateWallet = async (params: ActivateWalletParams): Promise<Wall
  * console.log('Created', wallets.length, 'mock wallets')
  *
  * // Create mock wallets for testnet
- * const testWallets = await mockWallets({ networkId: 'taurus' })
+ * const testWallets = await mockWallets({ networkId: 'mainnet' })
  *
  * // Create mock wallets with existing API
  * const api = await activate({ networkId: 'localhost' })
  * const localWallets = await mockWallets({ networkId: 'localhost' }, api)
  *
  * // Create ethereum-type mock wallets
  * const ethWallets = await mockWallets(
- *   { networkId: 'taurus' },
+ *   { networkId: 'mainnet' },
  *   undefined,
  *   'ethereum'
  * )

yarn.lock

@@ -13532,6 +13532,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ethers@npm:^6.13.5":
+  version: 6.15.0
+  resolution: "ethers@npm:6.15.0"
+  dependencies:
+    "@adraffy/ens-normalize": "npm:1.10.1"
+    "@noble/curves": "npm:1.2.0"
+    "@noble/hashes": "npm:1.3.2"
+    "@types/node": "npm:22.7.5"
+    aes-js: "npm:4.0.0-beta.5"
+    tslib: "npm:2.7.0"
+    ws: "npm:8.17.1"
+  checksum: 10c0/0a4581b662fe46a889a524d3aba43dc6f0ac59b3ae08dce678ee4b5799aab4906109ab24684c9644deedfc9d6e79b59faccecbeda9b6b7ceb085724d596a49e9
+  languageName: node
+  linkType: hard
+
 "event-emitter@npm:^0.3.5":
   version: 0.3.5
   resolution: "event-emitter@npm:0.3.5"
@@ -18499,6 +18514,7 @@ __metadata:
     "@autonomys/auto-utils": "workspace:*"
     commander: "npm:^12.1.0"
     dotenv: "npm:^16.4.5"
+    ethers: "npm:^6.13.5"
   languageName: unknown
   linkType: soft