Інтеграція 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 під ключ — ми оцінимо ваш проект і запропонуємо оптимальне рішення. Отримайте консультацію щодо вашого проекту вже сьогодні.