Интеграция с CLN (Core Lightning)

Интеграция с CLN (Core Lightning)

Core Lightning (CLN, ранее c-lightning) — Lightning Network нода от Blockstream, написанная на C + Python. Если LND — это "batteries included" с богатым REST API, то CLN — это минималистичный core с плагинной архитектурой. Интеграция с CLN отличается от LND: здесь Unix socket, JSON-RPC 2.0 и мощная система плагинов. Разберём как это работает на практике.

Архитектура CLN: плагины и RPC

CLN экспонирует Unix domain socket (по умолчанию ~/.lightning/bitcoin/lightning-rpc) через который работает JSON-RPC 2.0. REST API не встроен — это либо плагин clnrest, либо сторонний прокси.

Плагины — ключевая особенность CLN. Плагин — отдельный процесс (любой язык) который общается с CLN через stdio. Плагины могут:

• Добавлять новые RPC методы
• Подписываться на события (новые платежи, блоки, подключения)
• Перехватывать хуки (pre-payment, peer connection)
• Модифицировать поведение ноды

Это принципиально отличается от LND где расширение возможно только через gRPC.

Подключение к CLN

Прямой JSON-RPC через Unix socket

import socket
import json
import struct
from pathlib import Path

class CLNSocket:
    def __init__(self, socket_path: str = "~/.lightning/bitcoin/lightning-rpc"):
        self.path = str(Path(socket_path).expanduser())
        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        self.sock.connect(self.path)
        self._id = 0

    def call(self, method: str, params: dict | list = None) -> dict:
        self._id += 1
        request = {
            "jsonrpc": "2.0",
            "id": self._id,
            "method": method,
            "params": params or {},
        }
        data = json.dumps(request).encode()
        # CLN использует newline-delimited JSON
        self.sock.sendall(data + b"\n\n")

        # Читаем ответ
        buffer = b""
        while True:
            chunk = self.sock.recv(4096)
            buffer += chunk
            try:
                response = json.loads(buffer)
                if "error" in response:
                    raise CLNError(response["error"]["message"], response["error"]["code"])
                return response["result"]
            except json.JSONDecodeError:
                continue  # ждём ещё данных

# Использование
cln = CLNSocket()
info = cln.call("getinfo")
print(f"Node ID: {info['id']}")
print(f"Alias: {info['alias']}")
print(f"Blockheight: {info['blockheight']}")

pyln-client: официальная Python библиотека

from pyln.client import LightningRpc

rpc = LightningRpc("/path/to/lightning-rpc")

# Информация о ноде
info = rpc.getinfo()

# Создание инвойса
invoice = rpc.invoice(
    msatoshi=100000,          # 100 sat в миллисатоши
    label="order-12345",      # уникальный label
    description="Payment for order 12345",
    expiry=3600,              # 1 час
)
print(invoice["bolt11"])      # BOLT11 инвойс для QR-кода
print(invoice["payment_hash"])

# Ожидание платежа с timeout
result = rpc.waitinvoice(label="order-12345")
# result["status"] == "paid" или timeout

clnrest плагин: REST/WebSocket API

Если нужен HTTP API вместо Unix socket (например, для web-приложения):

# Устанавливаем плагин clnrest
pip install pyln-client pyln-testing

# Добавляем в config ~/.lightning/config
plugin=/path/to/clnrest.py
clnrest-port=3010
clnrest-host=127.0.0.1
clnrest-certs=/path/to/certs  # TLS для production

После этого доступен REST API:

curl http://localhost:3010/v1/getinfo \
  -H "Rune: YOUR_RUNE_TOKEN"

Rune — система авторизации CLN (альтернатива macaroons из LND). Создание rune с ограниченными правами:

# Rune только для чтения инвойсов (только listinvoices + waitinvoice)
lightning-cli createrune restrictions='["method^listinvoices|method=waitinvoice"]'

Платёжный flow: приём платежей

import asyncio
from pyln.client import LightningRpc

class CLNPaymentProcessor:
    def __init__(self, rpc_path: str):
        self.rpc = LightningRpc(rpc_path)
        self.pending_invoices: dict[str, asyncio.Future] = {}

    def create_invoice(self, amount_sat: int, order_id: str, description: str) -> dict:
        label = f"order-{order_id}"
        inv = self.rpc.invoice(
            msatoshi=amount_sat * 1000,
            label=label,
            description=description,
            expiry=900,  # 15 минут
        )
        return {
            "bolt11": inv["bolt11"],
            "payment_hash": inv["payment_hash"],
            "expires_at": inv["expires_at"],
        }

    async def wait_for_payment(self, label: str, timeout: int = 900) -> bool:
        """Ожидает оплату инвойса, возвращает True при успехе"""
        loop = asyncio.get_event_loop()

        def blocking_wait():
            try:
                result = self.rpc.waitinvoice(label=label)
                return result.get("status") == "paid"
            except Exception:
                return False

        try:
            paid = await asyncio.wait_for(
                loop.run_in_executor(None, blocking_wait),
                timeout=timeout
            )
            return paid
        except asyncio.TimeoutError:
            return False

Плагины: расширение CLN

Написание плагина — главная суперсила CLN. Пример минималистичного плагина на Python, который логирует все входящие платежи:

#!/usr/bin/env python3
# payment_logger_plugin.py

from pyln.client import Plugin

plugin = Plugin()

@plugin.subscribe("invoice_payment")
def on_payment(invoice_payment, **kwargs):
    """Вызывается при каждом успешном входящем платеже"""
    label = invoice_payment.get("label")
    amount_msat = invoice_payment.get("msat")
    preimage = invoice_payment.get("preimage")

    plugin.log(f"Payment received: label={label}, amount={amount_msat}msat")

    # Здесь: webhook, запись в БД, отправка уведомления
    notify_webhook(label, amount_msat)

@plugin.method("my_custom_method")
def custom_method(plugin, some_param, **kwargs):
    """Добавляет новый RPC метод в CLN"""
    return {"result": f"Processed: {some_param}"}

plugin.run()

# Подключаем плагин (в ~/.lightning/config)
plugin=/path/to/payment_logger_plugin.py

Плагины через subscribe("invoice_payment") получают события без polling — это правильный паттерн для real-time обработки платежей.

Hook: interceptor для платежей

Для advanced случаев (rate limiting, fraud detection) — хук htlc_accepted:

@plugin.hook("htlc_accepted")
def on_htlc(onion, htlc, **kwargs):
    """Перехватывает входящий HTLC до его принятия"""
    amount = htlc.get("amount_msat")

    # Отклонить если сумма слишком маленькая (anti-spam)
    if amount < 1000:  # < 1 sat
        return {"result": "fail", "failure_message": "4100"}  # insufficient_fees

    # Принять
    return {"result": "continue"}

Маршрутизация и управление каналами

# Открытие канала
funding = rpc.fundchannel(
    id="03abc...@ip:port",
    amount=500000,         # 500k sat
    announce=True,         # публичный канал
    minconf=1,             # минимум подтверждений funding tx
)

# Список каналов с балансами
channels = rpc.listpeerchannels()
for ch in channels["channels"]:
    print(f"Channel {ch['short_channel_id']}: "
          f"local={ch['to_us_msat']}msat, "
          f"remote={ch['total_msat'] - ch['to_us_msat']}msat")

# Отправка платежа
payment = rpc.pay(bolt11="lnbc...")
print(f"Status: {payment['status']}, preimage: {payment.get('payment_preimage')}")

CLN vs LND: практическое сравнение

CLN предпочтителен если: нужны кастомные плагины с нестандартной логикой, важна минимальная footprint, или вы уже работаете с Blockstream инфраструктурой.

Разработка базовой интеграции (приём платежей + webhook) — 3-5 дней. Полный плагин с кастомной логикой маршрутизации — 1-2 недели.