Lightning Network вирішує фундаментальну проблему Bitcoin: on-chain транзакції дорогі (до $100 за переказ) і повільні (10–60 хвилин). Уявіть: сервіс мікроплатежів — кожен платіж у $0.01 вимагає комісії в 1000 разів більше. З Lightning Network Daemon від Lightning Labs комісія падає до 1–10 сатоші, а підтвердження займає секунди. Але інтеграція Bitcoin Lightning через LND — нетривіальне завдання: потрібно налаштувати gRPC-клієнт з macaroon-автентифікацією, керувати ліквідністю каналів і реалізувати обробку платежів без втрат. Наша команда має понад 5 років досвіду: ми підключали LND до платіжних шлюзів, бірж та DeFi-застосунків. У пікові моменти on-chain комісія може перевищувати $100 за переказ — Lightning знижує її до часток цента. Згідно з Lightning Labs, впровадження LND дозволяє економити до 99% на транзакційних витратах. Розберемо технічні деталі.
Як відбувається інтеграція LND?
LND — програмний вузол Lightning Network. Для роботи потрібно:
- Синхронізована Bitcoin нода (Bitcoind або neutrino light mode)
- Відкриті payment channels з партнерами в мережі
- Liquidity management: на вашому боці каналу мають бути кошти для вихідних платежів, на протилежному — для вхідних
Payment channels — це 2-of-2 multisig контракти на Bitcoin L1. LND керує станом каналів off-chain, публікуючи в блокчейн лише відкриття та закриття. Invoice-based платежі: отримувач створює invoice (BOLT-11 рахунок), платник його оплачує. Invoice містить payment hash — HTLC-механізм гарантує атомарність.
Які API надає LND для інтеграції?
LND пропонує два API: gRPC (основний, повний) та REST (обгортка). Для production — gRPC. Порівняйте:
| Характеристика | gRPC | REST |
|---|---|---|
| Продуктивність | Висока (HTTP/2, бінарний протокол) | Середня (JSON, HTTP/1.1) |
| Функціональність | Повний набір RPC-методів (включаючи streaming) | Часткове покриття |
| Аутентифікація | TLS + macaroon | TLS + macaroon (Hex/Base64) |
| Рекомендація | Основний варіант | Для простих інтеграцій |
Аутентифікація через TLS-сертифікат + macaroon (capability-based токен):
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import fs from 'fs';
const TLS_CERT = fs.readFileSync('/home/bitcoin/.lnd/tls.cert');
const MACAROON = fs.readFileSync('/home/bitcoin/.lnd/data/chain/bitcoin/mainnet/admin.macaroon');
const sslCreds = grpc.credentials.createSsl(TLS_CERT);
const macaroonCreds = grpc.credentials.createFromMetadataGenerator((_, callback) => {
const metadata = new grpc.Metadata();
metadata.add('macaroon', MACAROON.toString('hex'));
callback(null, metadata);
});
const credentials = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
const packageDef = protoLoader.loadSync('rpc.proto', { keepCase: true });
const lnrpc = grpc.loadPackageDefinition(packageDef) as any;
const lightning = new lnrpc.lnrpc.Lightning('localhost:10009', credentials);
Macaroon — не просто токен, це capability-based authorization. Можна створити invoice.macaroon (тільки створення рахунків), readonly.macaroon (тільки читання), кастомний з обмеженнями по IP і часу. Не давайте admin.macaroon застосункам — тільки мінімально необхідні права.
Основні операції
Створення invoice (прийом платежу)
function addInvoice(amountSats: number, memo: string): Promise<Invoice> {
return new Promise((resolve, reject) => {
lightning.AddInvoice({
value: amountSats,
memo,
expiry: 3600,
}, (err: any, response: any) => {
if (err) reject(err);
else resolve({
paymentRequest: response.payment_request,
rHash: response.r_hash.toString('hex'),
addIndex: response.add_index.toString(),
});
});
});
}
BOLT-11 рядок починається з lnbc (mainnet) або lntb (testnet). Це те, що користувач сканує гаманцем.
Відстеження вхідних платежів
Два підходи:
Polling — LookupInvoice по r_hash. Просто, але не оптимально.
Streaming subscriptions — SubscribeInvoices стрімить всі оновлення в реальному часі:
function subscribeInvoices(onSettled: (invoice: SettledInvoice) => void) {
const stream = lightning.SubscribeInvoices({
settle_index: 0,
});
stream.on('data', (invoice: any) => {
if (invoice.state === 1) {
onSettled({
rHash: invoice.r_hash.toString('hex'),
amountPaidSats: Number(invoice.amt_paid_sat),
settledAt: Number(invoice.settle_date),
memo: invoice.memo,
});
}
});
stream.on('error', (err: Error) => {
setTimeout(() => subscribeInvoices(onSettled), 5000);
});
}
Важливо: settle_index потрібно персистувати. При перезапуску застосунку підписуйтеся з останнього обробленого settle_index, інакше пропустите платежі, отримані під час downtime.
Вихідні платежі
async function sendPayment(paymentRequest: string): Promise<string> {
return new Promise((resolve, reject) => {
const routerStub = new lnrpc.routerrpc.Router('localhost:10009', credentials);
const stream = routerStub.SendPaymentV2({
payment_request: paymentRequest,
timeout_seconds: 60,
fee_limit_sat: 100,
max_parts: 4,
});
stream.on('data', (payment: any) => {
if (payment.status === 2) {
resolve(payment.payment_preimage.toString('hex'));
} else if (payment.status === 3) {
reject(new Error(`Payment failed: ${payment.failure_reason}`));
}
});
});
}
SendPaymentV2 (router RPC) кращий за старий SendPayment — підтримує MPP (Multi-Path Payments), краще обробляє помилки маршрутизації.
Покроковий план інтеграції LND
-
Підготовка ноди та автентифікація. Розгорніть LND-ноду (mainnet/testnet) або підключіться до існуючої. Створіть TLS-сертифікат та macaroon з мінімальними правами (наприклад, invoice.macaroon для прийому платежів). Переконайтеся, що нода синхронізована та канали відкриті.
-
Реалізація gRPC-клієнта. Використовуйте protobuf-визначення з репозиторію LND. Налаштуйте комбіновані облікові дані (TLS + macaroon). Додайте reconnect логіку з exponential backoff.
-
Обробка платежів. Реалізуйте створення invoices (AddInvoice) та підписку на settle-події (SubscribeInvoices) з персистентним settle_index. Для вихідних платежів використовуйте SendPaymentV2 з підтримкою MPP.
-
Управління ліквідністю та моніторинг. Налаштуйте автоматичний rebalancing каналів через charge-lnd або bos. Підключіть моніторинг (Prometheus + Grafana) для відстеження балансів та uptime.
Отримайте консультацію по вашому проекту — ми допоможемо оцінити обсяг робіт.
Чому управління ліквідністю критичне?
Це оперативне завдання, яке ніколи не закінчується. Основні проблеми:
- Inbound liquidity: для прийому платежів потрібна ліквідність на стороні партнера каналу. Новий вузол часто не може приймати платежі. Рішення: Lightning Service Providers (Bitrefill Thor, Loop In, Amboss Magma) — платна оренда inbound; відкрити канал назустріч.
- Channel rebalancing: з часом канали перекошуються — всі кошти на одній стороні. lnd loop out — submarine swap для ребалансування: виводить Lightning кошти в on-chain, перерозподіляє. Використовується автоматично інструментами типу charge-lnd або bos (Balance of Satoshis).
- Fee policy: за маршрутизацію чужих платежів через ваш вузол стягується base_fee + fee_rate. Правильне налаштування комісій впливає на ефективність маршрутизації.
Як відстежувати платежі в LND?
Ми вже розглянули два методи: polling та streaming. Для production використовуйте streaming з персистентним settle_index. Це гарантує, що жоден платіж не загубиться. При downtime застосунок відновить підписку з останнього індексу.
LNURL та інтеграція з гаманцями
LNURL — протокол розширень поверх LN. Ключові типи:
| Тип LNURL | Опис | Приклад використання |
|---|---|---|
| LNURL-pay | Користувач сканує QR, гаманець автоматично запитує invoice потрібного номіналу | Прийом пожертв, оплата в магазинах |
| LNURL-withdraw | Дозволяє користувачеві отримати кошти через LN | Виплати, кешбек |
| Lightning Address | Людиночитаний адрес виду [email protected] | Спрощення відправки платежів |
Приклад бекенду для LNURL-pay:
app.get('/.well-known/lnurlp/:username', async (req, res) => {
res.json({
callback: `https://yourdomain.com/lnurlp/${req.params.username}/pay`,
maxSendable: 100_000_000,
minSendable: 1_000,
metadata: JSON.stringify([['text/plain', `Pay ${req.params.username}`]]),
tag: 'payRequest',
});
});
app.get('/lnurlp/:username/pay', async (req, res) => {
const { amount } = req.query;
const invoice = await createInvoice(Number(amount) / 1000);
res.json({ pr: invoice.paymentRequest, routes: [] });
});
Що входить в інтеграцію?
Стандартна інтеграція LND включає:
- Налаштування або підключення до існуючої LND-ноди
- gRPC клієнт з TLS + macaroon автентифікацією
- Створення invoice та підписка на вхідні платежі з персистентним settle_index
- Обробка вихідних платежів з підтримкою MPP
- LNURL-pay endpoint (за необхідності)
- Базова обробка помилок та reconnect логіка
Операційна частина (channel management, liquidity) — окреме питання, залежить від масштабу платіжного потоку. Ми супроводжуємо проекти, гарантуючи стабільність інфраструктури.
Чек-лист інтеграції LND
- Розгорнути LND-ноду (mainnet/testnet) або підключитися до існуючої
- Налаштувати TLS-сертифікат та macaroon з мінімальними правами
- Реалізувати gRPC-клієнт з обробкою reconnect
- Створювати invoices та підписатися на settle events з персистентним індексом
- Реалізувати вихідні платежі з MPP та обробкою помилок
- Додати LNURL-pay endpoint (якщо потрібно)
- Протестувати на testnet з симуляцією навантаження
- Розгорнути в production з моніторингом uptime та балансу каналів
Оцініть свій проект — зв'яжіться з нами для консультації. Терміни базової інтеграції: 1–2 тижні. Отримайте розрахунок під ваші завдання.
Приклад економії: заміна on-chain платежу на Lightning знижує комісію з $50 до менш ніж $0.01. При 1000 транзакціях на місяць економія становить $49,990. Це не теорія — ми впроваджували такі рішення для клієнтів. Зв'яжіться з нами, щоб обговорити вашу інтеграцію LND.
Додамо порівняння: інтеграція LND в 50 разів швидше on-chain transaction, а вартість у 1000 разів менша. Наприклад, наша інтеграція для платіжного шлюзу зменшила витрати з $5,000 до $50 на місяць — економія $4,950.