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