Интеграция с 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 library, которую нужно интегрировать в собственный процесс. Для большинства сервисных интеграций речь идёт именно об 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, модель ошибок и операционку ноды.