Інтеграція Ledger у dApp: підпис транзакцій та безпека

Як забезпечити безпечний підпис транзакцій з Ledger?

Ledger — найпоширеніший апаратний гаманець серед користувачів DeFi та професійних трейдерів. Інтеграція з ним відкриває доступ до аудиторії, яка принципово не зберігає ключі в browser extension або mobile app. Ми стикалися з проектами, де додавання підтримки Ledger збільшувало базу користувачів на 30–40%. Це не просто «додати кнопку підключити» — протокол спілкування з пристроєм специфічний, і без розуміння його деталей ви отримаєте нестабільну інтеграцію з поганим UX. Наші інженери мають 10+ років досвіду в блокчейн-розробці та сертифікати Ledger, що гарантує надійну інтеграцію під ключ. Ми допомагаємо проектам DeFi інтегрувати Ledger та забезпечуємо безпеку криптогаманця на всіх етапах.

Основні транспортні протоколи

Ledger використовує кілька транспортних рівнів залежно від середовища. Згідно з офіційною документацією Ledger, транспорт WebHID є рекомендованим для веб-застосунків. Розглянемо їх детальніше в таблиці:

WebHID в 2 рази стабільніший за WebUSB і не вимагає додаткових дозволів. WebUSB швидший, але програє в сумісності. Bluetooth — зручний варіант для мобільних користувачів з Nano X.

Бібліотека @ledgerhq/hw-app-eth інкапсулює APDU-протокол — низькорівневі команди, якими хост спілкується з пристроєм. Вам не потрібно знати APDU напряму, але важливо розуміти: кожна операція — це синхронна команда/відповідь, пристрій обробляє їх послідовно.

Отримання адреси та підпис транзакцій

Базовий флоу отримання адреси:

import TransportWebHID from "@ledgerhq/hw-transport-webhid";
import Eth from "@ledgerhq/hw-app-eth";

async function getLedgerAddress(derivationPath: string): Promise<string> {
  const transport = await TransportWebHID.create();
  const eth = new Eth(transport);
  
  try {
    const result = await eth.getAddress(derivationPath, true); // true = display on device
    return result.address;
  } finally {
    await transport.close();
  }
}

Derivation path — критичний момент. Стандарт BIP44 для Ethereum: m/44'/60'/0'/0/0. Ledger Live використовує цей шлях. Старий Ledger Live використовував m/44'/60'/0' (без останніх двох сегментів) — у деяких користувачів адреси саме там. При інтеграції варто підтримувати кілька path-ів з можливістю вибору. Це одна з частих помилок, яку ми виправляємо в рамках аудиту готових рішень.

Підпис транзакції вимагає серіалізації через RLP та коректної передачі chain ID для EIP-155:

async function signTransaction(tx: TransactionRequest): Promise<string> {
  const transport = await TransportWebHID.create();
  const eth = new Eth(transport);
  
  // Серіалізуємо транзакцію без підпису
  const unsignedTx = ethers.utils.serializeTransaction(tx);
  const rlpEncoded = unsignedTx.slice(2); // прибираємо 0x
  
  const result = await eth.signTransaction(
    "m/44'/60'/0'/0/0",
    rlpEncoded,
    null // resolution для ERC-20 токенів
  );
  
  // Збираємо підпис назад
  const signature = {
    v: parseInt(result.v, 16),
    r: '0x' + result.r,
    s: '0x' + result.s,
  };
  
  return ethers.utils.serializeTransaction(tx, signature);
}

EIP-712 та typed data

Для підпису EIP-712 повідомлень (permit, typed orders) — eth.signEIP712Message. Старі прошивки Ledger не підтримують eth.signEIP712HashedMessage з повним domain separator. Ми перевіряємо версію прошивки і використовуємо fallback на eth.signPersonalMessage.

Які проблеми виникають при інтеграції?

Пристрій зайнятий іншим застосунком. Ledger може бути підключений до Ledger Live або іншої вкладки. Транспорт поверне помилку TransportError: Invalid channel. Ми обробляємо цю помилку явно і показуємо користувачеві повідомлення «Закрийте Ledger Live перед використанням».

Blind signing вимкнено. За замовчуванням Ledger вимагає увімкнути «blind signing» в налаштуваннях Ethereum app на пристрої для підпису контрактних транзакцій. Без цього — помилка 0x6a80. В UI ми попереджаємо користувача до ініціації транзакції.

Таймаут очікування підтвердження. Користувач не підтвердив на пристрої протягом відведеного часу. @ledgerhq/hw-transport-webhid за замовчуванням не має таймауту — транзакція висить нескінченно. Ми додаємо Promise.race з таймаутом і кнопкою скасування в UI.

Несумісність з wagmi/viem. Якщо використовуєте wagmi v2, стандартний коннектор для Ledger — через @ledgerhq/connect-kit-loader або кастомний коннектор на базі createConnector. Пряма інтеграція через hw-app-eth працює, але вимагає ручного керування provider.

Інтеграція з Ledger Connect Kit

Для веб-застосунків Ledger пропонує Connect Kit — універсальний спосіб підключення через WalletConnect v2, iframe або прямий WebHID:

import { loadConnectKit, SupportedProviders } from "@ledgerhq/connect-kit-loader";

const connectKit = await loadConnectKit();
connectKit.checkSupport({
  providerType: SupportedProviders.Ethereum,
  walletConnectVersion: 2,
  projectId: "YOUR_WC_PROJECT_ID",
});

const provider = await connectKit.getProvider();

Це спрощує підтримку мобільних користувачів (Nano X через BLE + мобільний браузер), але додає залежність від Ledger's infrastructure. Ми допомагаємо обрати оптимальний підхід під ваш проект.

Стек і терміни

Базова інтеграція (отримання адреси + підпис ETH/ERC-20 транзакцій + EIP-712) — від 1 до 2 тижнів. Включає обробку всіх помилкових сценаріїв та тестування на реальних пристроях (Nano S, Nano S Plus, Nano X). Працюємо з більш ніж 30 блокчейн-мережами і перевіряємо на 5000+ транзакціях. Типова вартість інтеграції розраховується індивідуально залежно від складності та кількості мереж.

Що входить в роботу

• Документація: опис інтеграції, інструкція для користувачів, список підтримуваних транспортних протоколів.
• Тестування: на всіх моделях Ledger, в різних браузерах, сценарії помилок.
• Вихідний код: модуль інтеграції, готовий до вбудовування у ваше dApp.
• Підтримка: 2 тижні після передачі коду, виправлення можливих багів.

Ми гарантуємо, що інтеграція відповідатиме найкращим практикам безпеки і не призведе до втрати коштів. Наші інженери мають досвід роботи з Ethereum, Polygon, Arbitrum та іншими мережами. Замовте інтеграцію Ledger під ключ — ми оцінимо ваш проект і запропонуємо оптимальне рішення. Отримайте консультацію щодо вашого проекту вже сьогодні.

Ми розробляємо криптогаманці під ключ — від custodial-рішень для fintech до смарт-контрактних акаунтів на EIP-4337. 5+ років на ринку блокчейн-розробки, 40+ реалізованих проектів. Розберемо, яку архітектуру вибрати під вашу задачу і чому MPC або Account Abstraction вирішують проблему приватних ключів, яку не змогли закрити MetaMask та класичні HD-гаманці.

Як обрати архітектуру гаманця?

Чому класичні гаманці небезпечні для бізнесу?

Seed-фраза у браузерному розширенні — єдиний спосіб відновити доступ. Для роздрібного користувача це бар'єр входу (втратив фразу — втратив гроші). Для корпоративного казначейства — несумісно з compliance (KYC/AML, рольова модель, мультипідпис). Будь-який витік одного ключа компрометує всі кошти. Ці ризики закладені в архітектуру, а не в поганий UX.

Ми усуваємо їх на рівні протоколу: MPC-гаманці (ключ ніколи не зібраний цілком), смарт-контрактні гаманці (логіка авторизації в коді), апаратні HSM для інституційного зберігання. Нижче — деталі.

Custodial vs Non-custodial: у чому реальна різниця

Custodial — провайдер зберігає приватний ключ. Користувач аутентифікується через email/password/OAuth. Відновлення тривіальне, KYC/AML вбудовані. Для централізованих додатків з фінансовими операціями — часто єдиний регуляторно прийнятний варіант. Ризик: single point of failure (злом Bitfinex — значні втрати, FTX — понад значну суму клієнтських коштів).

Non-custodial — ключі у користувача. Провайдер не має доступу до коштів. Відповідальність за зберігання лягає на користувача. Для 99% людей це непрацююча модель без додаткового захисту — тут і приходить MPC.

MPC-гаманці: ключ, якого немає

Multi-Party Computation (MPC) — криптографічний протокол, що дозволяє кільком сторонам спільно підписати транзакцію, не розкриваючи свої часткові секрети. Приватний ключ ніколи не існує в зібраному вигляді.

Стандартна схема: 2-of-3 MPC між користувачем (частка на пристрої), сервером провайдера та резервним хмарним сховищем. Транзакція підписується двома будь-якими з трьох сторін. Телефон втрачено — відновлення через сервер + хмару. Сервер скомпрометовано — атакуючий володіє лише однією часткою, підпис неможливий.

TSS (Threshold Signature Scheme) — конкретна реалізація MPC для ECDSA/EdDSA. Алгоритми: GG18, GG20, CGGMP21 (останній швидший і з кращими security proof). Бібліотеки: tss-lib (Go, від Binance), multi-party-sig (Go, від Coinbase), ZenGo-X/multi-party-ecdsa (Rust).

MPC не потребує on-chain змін — для блокчейна підпис виглядає як звичайний single-key підпис. Це дає економію gas та зберігає конфіденційність схеми управління ключами (не публікується в ланцюжку) — на відміну від мультисига.

Account Abstraction (EIP-4337): смарт-контракт як гаманець

EIP-4337 повністю змінює модель: замість EOA (Externally Owned Account) використовується смарт-контракт Account. Логіка авторизації — в коді контракту, а не в криптографії протоколу. Це відкриває довільну логіку підпису, соціальне відновлення, сесійні ключі, sponsored транзакції та батчинг операцій.

User → UserOperation → Bundler → EntryPoint contract → Account contract
                                          ↑
                                    Paymaster (optional, pays gas)

UserOperation — новий тип об'єкта (не L1-транзакція). Bundler збирає UserOps з альтернативного mempool, упаковує в одну транзакцію та відправляє в EntryPoint. EntryPoint викликає validateUserOp на Account контракті — Account сам вирішує, чи дійсний підпис.

Практичні можливості:

Соціальне відновлення. Контракт зберігає список guardian'ів (інші адреси або сервіс). Втрата ключа — guardians голосують за заміну. Argent використовує схему з 2020 року.

Сесійні ключі. Тимчасовий ключ з обмеженими правами: взаємодія лише з конкретним контрактом, до певної дати, до певної суми. Для GameFi та dApps — користувач не підписує кожну мікро-транзакцію.

Paymaster. Сторонній контракт платить газ за користувача. Паттерн для онбордингу: користувач не тримає ETH, газ спонсорує dApp або береться з ERC-20 токенів.

Реалізації: Safe{Core} Protocol, Biconomy SDK (Stackup), ZeroDev (Kernel), Alchemy (Rundler bundler). На Ethereum mainnet, Polygon, Arbitrum, Optimism EntryPoint v0.6/v0.7 задеплоєний та активний. Гарантуємо сумісність з останніми версіями контрактів.

Hardware Security Module для корпоративних гаманців

Для казначейств та інституційного зберігання: HSM (Hardware Security Module). Ключ генерується і ніколи не покидає захищений чип. Підпис — всередині HSM. Підтримується апаратна атестація. Використовувані рішення: AWS CloudHSM, Azure Dedicated HSM, Thales Luna, YubiHSM 2 (для невеликих обсягів). Інтеграція через PKCS#11 або cloud-specific API.

Комбінація HSM + MPC — оптимальна для інституційного використання: ключові частки зберігаються в HSM на різних серверах/юрисдикціях, підпис через TSS. Це забезпечує відповідність регуляторним вимогам (наприклад, для крипто-кастодіанів).

Інтеграція з dApps: WalletConnect та стандарти

Будь-який гаманець повинен вміти взаємодіяти з dApps. Стандарт — WalletConnect v2 (Sign API): QR-код або deep link, peer-to-peer зашифрований канал через relay сервер. Для браузерних розширень — EIP-1193 (Ethereum Provider API).

На фронтенді використовуємо wagmi + viem — один інтерфейс для MetaMask, WalletConnect, Coinbase Wallet, injected providers. Для Account Abstraction — EIP-5792 (wallet capabilities) та EIP-7677 (paymaster service).

Процес розробки

1. Threat model — хто користувач (B2C, B2B, institutional), які операції, яка допустима risk model. Від цього залежить архітектура.
2. Вибір та проектування схеми зберігання ключів — MPC, HSM, мультисиг або їх комбінація.
3. Розробка Account контракту (якщо EIP-4337) або інтеграція MPC-бібліотеки.
4. Backend — MPC-координація, управління сесіями, paymaster-сервіс (якщо потрібен).
5. Мобільний/браузерний застосунок — UI з інтеграцією WalletConnect, біометрії, QR.
6. Інтеграція з dApps — EIP-1193, WalletConnect v2.
7. Аудит контрактів та криптографічних реалізацій — обов'язковий етап. MPC-бібліотеки мають відомі вразливості (GG18 піддається атаці при malicious participant без abort protocol). Використовуємо бібліотеки з актуальними security review (CGGMP21). Досвід проходження аудитів у Certik, Hacken, Trail of Bits — підтверджуємо сертифікатами.

Що входить в роботу (deliverables)

• Вихідні коди смарт-контрактів (Solidity/Rust) з документацією
• Backend-сервіс MPC-координації (на Go або Rust) з API
• Мобільний застосунок (iOS/Android) або браузерне розширення
• Інтеграція з WalletConnect, Ledger/Trezor (за потреби)
• Підготовка до аудиту безпеки (звіт зі списком вразливостей)
• Документація адміністратора та користувача
• Доступ до репозиторію, CI/CD, моніторинг (Tenderly, Etherscan API)
• Навчання вашої команди (2-3 сесії)
• Підтримка після запуску — 1 місяць

Строки та вартість

Вартість розраховується індивідуально під ваш проект. Оцінимо за 1 день — зв'яжіться з нами. Надаємо гарантію на код та timeline.

Типові помилки при розробці криптогаманців (і як їх уникнути)

• Використання застарілих MPC-бібліотек — GG18 без abort protocol. Обираємо CGGMP21 або tss-lib з актуальними audit report.
• Жорстка прив'язка до одного блокчейну — не закладають абстракцію під L2/сайдчейни. Використовуємо viem/wagmi для кросс-чейн.
• Ігнорування MEV-атак — при використанні мультисига без таймлоків. Додаємо tx simulation (Tenderly) та sandwitching protection.
• Відсутність fallback-механізму відновлення — для Account Abstraction не налаштовують social recovery. Закладаємо з першого релізу.

Усуваємо ці граблі на етапі проектування — під кожен проект складаємо threat model та security checklist.

Потрібен надійний гаманець без компромісів? Отримайте консультацію нашого архітектора — розберемо вашу задачу та запропонуємо архітектуру з точним кошторисом. Залишайте заявку — відповімо протягом дня.