Интеграция с LND (Lightning Network Daemon)

Интеграция с LND (Lightning Network Daemon)

Lightning Network решает конкретную проблему Bitcoin: on-chain транзакции стоят денег и требуют подтверждений. LND (Lightning Network Daemon от Lightning Labs) — самая распространённая реализация LN-ноды. Интеграция с LND нужна когда хотят принимать моментальные Bitcoin-платежи с комиссией в несколько сатоши, или строить приложение поверх Lightning. Это не «подключить API» — это запустить и поддерживать платёжную инфраструктуру.

Что такое 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-механизм гарантирует атомарность.

Подключение к LND: gRPC vs REST

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');

// Создаём channel с TLS + 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,  // BOLT-11 строка
        rHash: response.r_hash.toString('hex'),     // payment hash
        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,  // с начала, или с конкретного индекса для catch-up
  });

  stream.on('data', (invoice: any) => {
    if (invoice.state === 1) {  // SETTLED = оплачен
      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) => {
    // Reconnect logic
    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,        // MPP: разбить на несколько частей если нужно
    });
    
    stream.on('data', (payment: any) => {
      if (payment.status === 2) {  // SUCCEEDED
        resolve(payment.payment_preimage.toString('hex'));
      } else if (payment.status === 3) {  // FAILED
        reject(new Error(`Payment failed: ${payment.failure_reason}`));
      }
    });
  });
}

SendPaymentV2 (router RPC) предпочтительнее старого SendPayment — поддерживает MPP (Multi-Path Payments), лучше обрабатывает ошибки маршрутизации.

Liquidity management

Это оперативная задача которая никогда не заканчивается. Проблемы:

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. Правильная настройка комиссий влияет на эффективность маршрутизации.

LNURL и интеграция с кошельками

LNURL — протокол расширений поверх LN. Ключевые типы:

LNURL-pay — пользователь сканирует QR, кошелёк автоматически запрашивает invoice нужного номинала. Не нужно заранее знать сумму:

// Backend endpoint для 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,  // msats
    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;  // в msats
  const invoice = await createInvoice(Number(amount) / 1000);
  res.json({ pr: invoice.paymentRequest, routes: [] });
});

Lightning Address — human-readable адрес вида [email protected]. Реализуется через LNURL-pay endpoint на /.well-known/lnurlp/{username}.

LNURL-withdraw — позволяет пользователю получить средства через LN. Применение: выплаты, кешбэк.

Что входит в интеграцию

Стандартная интеграция с LND: настройка или подключение к существующей LND-ноде, gRPC клиент с TLS + macaroon аутентификацией, создание invoice, подписка на входящие платежи с персистентным settle_index, обработка исходящих платежей, LNURL-pay endpoint (по необходимости), базовая обработка ошибок и reconnect логика.

Операционная часть (channel management, liquidity) — отдельный вопрос, зависит от масштаба платёжного потока.

Сроки: 1-2 недели для backend интеграции в существующее приложение.