Інтеграція LND: gRPC/API, ліквідність, LNURL

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. Порівняйте:

Аутентифікація через 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

1. Підготовка ноди та автентифікація. Розгорніть LND-ноду (mainnet/testnet) або підключіться до існуючої. Створіть TLS-сертифікат та macaroon з мінімальними правами (наприклад, invoice.macaroon для прийому платежів). Переконайтеся, що нода синхронізована та канали відкриті.

2. Реалізація gRPC-клієнта. Використовуйте protobuf-визначення з репозиторію LND. Налаштуйте комбіновані облікові дані (TLS + macaroon). Додайте reconnect логіку з exponential backoff.

3. Обробка платежів. Реалізуйте створення invoices (AddInvoice) та підписку на settle-події (SubscribeInvoices) з персистентним settle_index. Для вихідних платежів використовуйте SendPaymentV2 з підтримкою MPP.

4. Управління ліквідністю та моніторинг. Налаштуйте автоматичний 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-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) — окреме питання, залежить від масштабу платіжного потоку. Ми супроводжуємо проекти, гарантуючи стабільність інфраструктури.