Интеграция 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) — отдельный вопрос, зависит от масштаба платёжного потока. Мы сопровождаем проекты, гарантируя стабильность инфраструктуры.