Інтеграція з Lightning Labs API

Інтеграція з Lightning Labs API

Lightning Network — це не просто «швидкий Bitcoin». Це окремий протокольний рівень зі своєю моделлю ліквідності, маршрутизацією платежів та специфічними відмовами, які не зустрічаються у on-chain розробці. Команди, що мають досвід Ethereum або Bitcoin RPC, часто недооцінюють складність: перший платіж надіслати легко, зробити з цього production-систему — уже ні.

Lightning Labs підтримує два основних демони — LND (Go) та LDK (Rust/бібліотека). У них різні API, різна філософія. LND надає gRPC та REST; LDK — це embedded бібліотека, яку потрібно інтегрувати в власний процес. Для більшості сервісних інтеграцій йдеться саме про LND через його gRPC API або через LNC (Lightning Node Connect) — протокол поверх WebSocket для браузерного доступу.

Де інтеграція нетривіальна

Управління каналами та ліквідність

Відкриття каналу — on-chain транзакція. Це значить: комісії, час очікування, необхідність тримати UTXO. Але головна проблема — inbound liquidity. Коли відкриваєш канал, вся ліквідність на твоїй стороні. Приймати платежі ти не можеш, поки контрагент не отримає середства через канал.

Для комерційних вузлів є кілька рішень:

• Loop Out (Lightning Labs Loop) — submarine swap: виводиш середства з каналу on-chain, звільняючи inbound capacity
• Pool — ринок аренди ліквідності; можна купити lease на вхідну ліквідність
• Circular rebalancing через router.SendToRoute — переміщаєш liquidity по кільцевому маршруту через сторонні вузли

// Приклад: перевірка баланса каналів перед платежом
channels, err := client.ListChannels(ctx, &lnrpc.ListChannelsRequest{
    ActiveOnly: true,
})
for _, ch := range channels.Channels {
    localRatio := float64(ch.LocalBalance) / float64(ch.Capacity)
    if localRatio < 0.1 {
        // канал почти пустий — потрібна rebalance
        triggerRebalance(ch.ChanId)
    }
}

Обробка платежів: підписки та вебхуки

LND не має вбудованих вебхуків. Стандартний паттерн — підписка на SubscribeInvoices gRPC stream. Проблема: стріми рвуться при переподключенні, і якщо reconnect обробляється неакуратно — платежі теряються.

Правильний підхід: після reconnect викликати ListInvoices з index_offset — отримати всі інвойси, створені після останнього обробленого. Це ідемпотентний catch-up.

stream, err := invoiceClient.SubscribeInvoices(ctx, &invoicesrpc.SubscribeInvoicesRequest{
    AddIndex:    lastProcessedAddIndex,
    SettleIndex: lastProcessedSettleIndex,
})
for {
    invoice, err := stream.Recv()
    if err != nil {
        // reconnect logic з backoff
        reconnect()
        continue
    }
    if invoice.State == lnrpc.Invoice_SETTLED {
        processPayment(invoice)
    }
}

LSAT / L402: токен-аутентифікація через Lightning

L402 (раніше LSAT) — це HTTP 402 + macaroon. Клієнт отримує WWW-Authenticate: L402 macaroon=..., invoice=..., оплачує invoice, відправляє Authorization: L402 <macaroon>:<preimage>. Сервер верифікує: preimage відповідає payment hash інвойса — доступ відкрито.

Це нативний спосіб монетизації API на Lightning без аккаунтів та підписок. Lightning Labs надає бібліотеку aperture як reverse proxy з підтримкою L402.

Що входить в інтеграцію

• Розгортання та налаштування LND-ноди (включаючи Tor, TLS, macaroon-політики)
• gRPC/REST клієнт під потрібний стек (Go, Node.js, Python — у LND є protobuf definitions)
• Управління інвойсами: створення, відслідковування, закінчення ваги
• Обробка сбоїв платежів: FAILED_NO_ROUTE, FAILED_INSUFFICIENT_BALANCE, таймаути
• Loop/Pool інтеграція для управління ліквідністю
• Мониторинг ноди: Prometheus метрики через lnd-exporter, алерти на закриття каналів

Типові проблеми в production

Інтеграція з Lightning — це робота з state machine платіжних каналів, а не просто HTTP-клієнт до ноди. Для продакшену потрібно розуміти життєвий цикл HTLC, модель помилок та операційку ноди.