Разработка HD-кошелька

Разработка HD-кошелька

HD-кошелёк (Hierarchical Deterministic wallet) позволяет из одной seed phrase генерировать неограниченное дерево ключевых пар. Стандарт BIP-32/BIP-39/BIP-44 — это основа всех современных кошельков: MetaMask, Ledger, Trust Wallet, Phantom. Разработка собственного HD-кошелька требует точной реализации стандартов, иначе пользователи не смогут восстановить средства в других кошельках.

Стандарты и спецификации

BIP-39: генерация мнемонической фразы (12/24 слова) из энтропии и конвертация в binary seed через PBKDF2.

BIP-32: derivation дерева ключей из master seed. Определяет child key derivation функцию (CKD) для normal и hardened ключей.

BIP-44: стандартная схема путей деривации: m / purpose' / coin_type' / account' / change / index. Например, первый Ethereum адрес: m/44'/60'/0'/0/0.

EIP-55: checksum кодирование Ethereum адресов (смешанный регистр).

Генерация ключей: BIP-39 и BIP-32

Мнемоника и seed

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

// Генерация 12-словной мнемоники (128 бит энтропии)
// Или 24 слова для 256 бит — рекомендуется для cold storage
function generateMnemonic(strength: 128 | 256 = 128): string {
  return bip39.generateMnemonic(strength);
  // Пример: "abandon abandon abandon abandon abandon abandon
  //          abandon abandon abandon abandon abandon about"
}

// Конвертация мнемоники в binary seed через PBKDF2
async function mnemonicToSeed(
  mnemonic: string,
  passphrase: string = ""
): Promise<Uint8Array> {
  if (!bip39.validateMnemonic(mnemonic)) {
    throw new Error("Invalid mnemonic");
  }
  // PBKDF2-HMAC-SHA512, 2048 итераций, 64 байта
  return bip39.mnemonicToSeed(mnemonic, passphrase);
}

Derivation дерева ключей

interface DerivedAccount {
  path: string;
  privateKey: Uint8Array;
  publicKey: Uint8Array;
  address: string;
  xpub: string;  // расширенный публичный ключ для 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 путь: m/44'/coinType'/account'/change/index
  // Апостроф = hardened derivation (защита: нельзя вычислить private key из 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 {
  // Убираем prefix байт (0x04 для uncompressed)
  const pubKeyWithoutPrefix = publicKey.slice(1);
  const hash = keccak256(pubKeyWithoutPrefix);
  // Берём последние 20 байт
  const addressBytes = hash.slice(-20);
  return toChecksumAddress("0x" + Buffer.from(addressBytes).toString("hex"));
}

// EIP-55 checksum адрес
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("");
}

Безопасное хранение ключей

Шифрование через Web Crypto API (browser)

// Шифрование keystore по стандарту EIP-55 / Web3 Secret Storage
async function encryptKeystore(
  privateKey: Uint8Array,
  password: string
): Promise<EncryptedKeystore> {
  const salt = crypto.getRandomValues(new Uint8Array(32));
  const iv = crypto.getRandomValues(new Uint8Array(16));

  // Деривация ключа из пароля: PBKDF2, 600000 итераций (NIST рекомендация 2023)
  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: "" // вычисляется отдельно для integrity check
    }
  };
}

Хранение в мобильном приложении

Для React Native — Secure Enclave (iOS) или Android Keystore:

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

// Сохранение mnemonic в Secure Enclave / Android Keystore
// Ключи защищены биометрией устройства
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 и watch-only режим

HD-кошелёк поддерживает несколько accounts (разные BIP-44 account индексы) и watch-only режим через xpub:

class HDWalletManager {
  private hdKey: HDKey;

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

  // Получить аккаунт по индексу
  getAccount(accountIndex: number): DerivedAccount {
    return deriveAccount(
      // seed уже в hdKey
      new Uint8Array(64), // placeholder
      accountIndex
    );
  }

  // xpub для watch-only кошелька — показывает баланс без private key
  getAccountXpub(accountIndex: number): string {
    const accountKey = this.hdKey.derive(`m/44'/60'/${accountIndex}'`);
    return accountKey.publicExtendedKey;
  }

  // Генерация адресов из xpub без private key (для 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 режим позволяет импортировать только xpub — кошелёк показывает все адреса и балансы, но не может подписывать транзакции. Используется для мониторинга cold wallet.

Подписание транзакций

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;
}

Совместимость и тестирование

Перед релизом обязательна проверка совместимости с другими кошельками:

Официальные test vectors для BIP-39 и BIP-32 находятся в репозиториях trezor/python-mnemonic и bitcoin/bips. Прогон всех тест-векторов — обязательный шаг перед production деплоем.