HD Wallet (Hierarchical Deterministic) Development

HD Wallet Development

HD wallet (Hierarchical Deterministic wallet) allows generating unlimited tree of key pairs from one seed phrase. BIP-32/BIP-39/BIP-44 standard is foundation of all modern wallets: MetaMask, Ledger, Trust Wallet, Phantom. Developing own HD wallet requires precise standard implementation, otherwise users can't recover funds in other wallets.

Standards and Specifications

BIP-39: generating mnemonic phrase (12/24 words) from entropy and converting to binary seed via PBKDF2.

BIP-32: deriving key tree from master seed. Defines child key derivation function (CKD) for normal and hardened keys.

BIP-44: standard derivation path scheme: m / purpose' / coin_type' / account' / change / index. E.g., first Ethereum address: m/44'/60'/0'/0/0.

EIP-55: checksum encoding for Ethereum addresses (mixed case).

Key Generation: BIP-39 and BIP-32

Mnemonic and Seed

import * as bip39 from "bip39";
import { HDKey } from "@scure/bip32";
import { keccak256 } from "ethereum-cryptography/keccak";
import { secp256k1 } from "ethereum-cryptography/secp256k1";

// Generate 12-word mnemonic (128 bits entropy)
// Or 24 words for 256 bits — recommended for cold storage
function generateMnemonic(strength: 128 | 256 = 128): string {
  return bip39.generateMnemonic(strength);
}

// Convert mnemonic to binary seed via PBKDF2
async function mnemonicToSeed(
  mnemonic: string,
  passphrase: string = ""
): Promise<Uint8Array> {
  if (!bip39.validateMnemonic(mnemonic)) {
    throw new Error("Invalid mnemonic");
  }
  // PBKDF2-HMAC-SHA512, 2048 iterations, 64 bytes
  return bip39.mnemonicToSeed(mnemonic, passphrase);
}

Key Tree Derivation

interface DerivedAccount {
  path: string;
  privateKey: Uint8Array;
  publicKey: Uint8Array;
  address: string;
  xpub: string;  // extended public key for watch-only
}

function deriveAccount(
  seed: Uint8Array,
  accountIndex: number = 0,
  addressIndex: number = 0,
  coinType: number = 60  // 60 = Ethereum, 0 = Bitcoin, 501 = Solana
): DerivedAccount {
  const hdKey = HDKey.fromMasterSeed(seed);

  // BIP-44 path: m/44'/coinType'/account'/change/index
  // Apostrophe = hardened derivation (protection: can't compute private key from public)
  const path = `m/44'/${coinType}'/${accountIndex}'/0/${addressIndex}`;

  const derived = hdKey.derive(path);

  if (!derived.privateKey) {
    throw new Error("Failed to derive private key");
  }

  const publicKey = secp256k1.getPublicKey(derived.privateKey, false);
  const address = publicKeyToAddress(publicKey);

  return {
    path,
    privateKey: derived.privateKey,
    publicKey,
    address,
    xpub: derived.publicExtendedKey
  };
}

function publicKeyToAddress(publicKey: Uint8Array): string {
  // Remove prefix byte (0x04 for uncompressed)
  const pubKeyWithoutPrefix = publicKey.slice(1);
  const hash = keccak256(pubKeyWithoutPrefix);
  // Take last 20 bytes
  const addressBytes = hash.slice(-20);
  return toChecksumAddress("0x" + Buffer.from(addressBytes).toString("hex"));
}

// EIP-55 checksum address
function toChecksumAddress(address: string): string {
  const addr = address.toLowerCase().replace("0x", "");
  const hash = Buffer.from(keccak256(Buffer.from(addr))).toString("hex");

  return "0x" + addr
    .split("")
    .map((char, i) => (parseInt(hash[i], 16) >= 8 ? char.toUpperCase() : char))
    .join("");
}

Secure Key Storage

Encryption via Web Crypto API (Browser)

// Encrypt keystore per EIP-55 / Web3 Secret Storage standard
async function encryptKeystore(
  privateKey: Uint8Array,
  password: string
): Promise<EncryptedKeystore> {
  const salt = crypto.getRandomValues(new Uint8Array(32));
  const iv = crypto.getRandomValues(new Uint8Array(16));

  // Derive key from password: PBKDF2, 600000 iterations (NIST 2023 recommendation)
  const passwordKey = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(password),
    "PBKDF2",
    false,
    ["deriveBits", "deriveKey"]
  );

  const encryptionKey = await crypto.subtle.deriveKey(
    {
      name: "PBKDF2",
      salt,
      iterations: 600_000,
      hash: "SHA-256"
    },
    passwordKey,
    { name: "AES-GCM", length: 256 },
    false,
    ["encrypt", "decrypt"]
  );

  const encrypted = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    encryptionKey,
    privateKey
  );

  return {
    version: 3,
    crypto: {
      ciphertext: Buffer.from(encrypted).toString("hex"),
      cipher: "aes-256-gcm",
      kdf: "pbkdf2",
      kdfparams: {
        dklen: 32,
        salt: Buffer.from(salt).toString("hex"),
        c: 600_000,
        prf: "hmac-sha256"
      },
      iv: Buffer.from(iv).toString("hex"),
      mac: ""
    }
  };
}

Mobile Storage

For React Native — Secure Enclave (iOS) or Android Keystore:

import * as SecureStore from "expo-secure-store";
import * as Keychain from "react-native-keychain";

// Save mnemonic in Secure Enclave / Android Keystore
// Keys protected by device biometry
async function storeMnemonicSecurely(
  mnemonic: string,
  biometricPrompt: string
): Promise<void> {
  await Keychain.setGenericPassword(
    "hd_wallet_mnemonic",
    mnemonic,
    {
      accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
      accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET,
      authenticationType: Keychain.AUTHENTICATION_TYPE.BIOMETRICS,
      securityLevel: Keychain.SECURITY_LEVEL.SECURE_HARDWARE
    }
  );
}

async function retrieveMnemonic(prompt: string): Promise<string> {
  const credentials = await Keychain.getGenericPassword({
    authenticationPrompt: { title: prompt }
  });
  if (!credentials) throw new Error("No stored mnemonic");
  return credentials.password;
}

Multi-account and Watch-only Mode

HD wallet supports multiple accounts (different BIP-44 account indices) and watch-only mode via xpub:

class HDWalletManager {
  private hdKey: HDKey;

  constructor(seed: Uint8Array) {
    this.hdKey = HDKey.fromMasterSeed(seed);
  }

  // Get account by index
  getAccount(accountIndex: number): DerivedAccount {
    return deriveAccount(
      new Uint8Array(64), // placeholder
      accountIndex
    );
  }

  // xpub for watch-only wallet — shows balance without private key
  getAccountXpub(accountIndex: number): string {
    const accountKey = this.hdKey.derive(`m/44'/60'/${accountIndex}'`);
    return accountKey.publicExtendedKey;
  }

  // Generate addresses from xpub without private key (for hardware wallet integration)
  static deriveAddressFromXpub(
    xpub: string,
    addressIndex: number
  ): string {
    const hdKey = HDKey.fromExtendedKey(xpub);
    const derived = hdKey.derive(`m/0/${addressIndex}`);
    return publicKeyToAddress(derived.publicKey!);
  }
}

Watch-only mode allows importing only xpub — wallet shows all addresses and balances but can't sign transactions. Used for monitoring cold wallet.

Transaction Signing

import { Transaction, parseTransaction } from "viem";
import { privateKeyToAccount } from "viem/accounts";

async function signTransaction(
  privateKey: Uint8Array,
  txParams: {
    to: string;
    value: bigint;
    data: string;
    chainId: number;
    nonce: number;
    maxFeePerGas: bigint;
    maxPriorityFeePerGas: bigint;
    gas: bigint;
  }
): Promise<string> {
  const account = privateKeyToAccount(
    `0x${Buffer.from(privateKey).toString("hex")}`
  );

  const signedTx = await account.signTransaction({
    type: "eip1559",
    ...txParams
  });

  return signedTx;
}

Compatibility and Testing

Before release, mandatory compatibility check with other wallets:

Official test vectors for BIP-39 and BIP-32 found in trezor/python-mnemonic and bitcoin/bips repositories. Running all test vectors — mandatory step before production deploy.