Інтеграція з CLN (Core Lightning)

Інтеграція з Core Lightning (CLN)

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
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']}")

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

# Додаємо в ~/.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. Приклад мінімалістичного плагіну, який логує всі вхідні платежі:

#!/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 тижні.