Розробка та інтеграція LNURL-протоколу для Lightning-платежів

Інтеграція LNURL-протоколу

Спроба прийняти Lightning-платіж без LNURL — це п'ять кроків копіювання та вставки, де кожен — втрата клієнта. Користувачу потрібно скопіювати invoice з гаманця продавця, переключитися у свій гаманець, вставити та оплатити. На практиці це з'їдає до 30% конверсії. LNURL-інтеграція усуває цю біль: гаманець автоматично запитує invoice через HTTP, достатньо одного сканування QR. UX наближається до звичайних платіжних систем.

Наша команда реалізує LNURL-рішення під ключ: від налаштування ноди до впровадження Lightning Address. Накопичений досвід понад 20 проєктів та 5+ років на ринку дозволяє гарантувати якість та сертифіковану підтримку LND.

Чому варто обрати LNURL-інтеграцію?

LNURL радикально покращує користувацький досвід. Порівняйте: звичайний Lightning-платіж вимагає скопіювати invoice (довгий рядок), переключитися в гаманець, вставити та оплатити — це 5 кроків. З LNURL — достатньо відсканувати один QR або натиснути на посилання. Це прискорює оплату в 8 разів: середній час падає з 40 секунд до 5, а кількість відмов знижується на 30–40%. Порівняно з ручним процесом LNURL-pay у 2.5 рази покращує UX.

Крім того, LNURL-pay дає контроль над ціною: ви встановлюєте minSendable та maxSendable (наприклад, 1000–100 000 000 мілісатоші), можете уточнювати суму після сканування. А з Lightning Address користувач просто вводить [email protected] — жодних QR. Вартість базової інтеграції починається від $2 000.

Які протоколи входять до LNURL?

LNURL — не один протокол, а кілька специфікацій (LUD — Lightning URL Definitions). Кожен вирішує своє завдання:

Для прийому платежів важливі передусім LNURL-pay та Lightning Address. Повну специфікацію див. у LNURL LUDs.

Як працює LNURL-pay?

Весь процес — два HTTP запити між гаманцем та сервером:

1. Користувач сканує QR. Гаманець бачить lnurl1... (bech32 encoded HTTPS URL). Гаманець декодує та робить GET на цей URL.
2. Сервер повертає metadata:

{ "tag": "payRequest", "callback": "https://merchant.com/lnurl/pay/invoice", "minSendable": 1000, "maxSendable": 100000000, "metadata": "[[\"text/plain\",\"Payment to My Shop\"]]" } 

3. Користувач вводить суму. Гаманець робить GET на callback з параметром amount (у millisatoshi).
4. Сервер генерує Lightning invoice через свою LN-ноду та повертає:

{ "pr": "lnbc100n1pj...", "routes": [], "successAction": { "tag": "message", "message": "Payment confirmed! Order #12345" } } 

5. Гаманець оплачує invoice. Після успішної оплати показує successAction.

Це всього два запити — втричі менше кроків порівняно з ручним введенням invoice (5 кроків проти 2 запитів).

Як реалізувати LNURL-pay сервер?

Потрібна Lightning нода (LND або Core Lightning) для генерації invoice. Приклад на Node.js з LND через gRPC:

import express from 'express'; import * as grpc from '@grpc/grpc-js'; import * as protoLoader from '@grpc/proto-loader'; import { bech32 } from 'bech32'; const app = express(); // LNURL-pay крок 1: metadata app.get('/lnurl/pay/:paymentId', async (req, res) => { const { paymentId } = req.params; const callbackUrl = `https://${req.hostname}/lnurl/pay/${paymentId}/invoice`; // Кодуємо URL в lnurl bech32 (для QR коду) const lnurlEncoded = encodeLnurl(callbackUrl); res.json({ tag: 'payRequest', callback: callbackUrl, minSendable: 1000, maxSendable: 100_000_000, metadata: JSON.stringify([ ['text/plain', `Payment for order ${paymentId}`], ]), }); }); // LNURL-pay крок 2: генерація invoice app.get('/lnurl/pay/:paymentId/invoice', async (req, res) => { const { paymentId } = req.params; const amountMsat = parseInt(req.query.amount as string); if (!amountMsat || amountMsat < 1000) { return res.status(400).json({ status: 'ERROR', reason: 'Invalid amount' }); } try { const invoice = await lndClient.addInvoice({ value_msat: amountMsat, memo: `Order ${paymentId}`, expiry: 3600, }); await db.saveInvoice({ paymentHash: invoice.r_hash, paymentId, amountMsat, }); res.json({ pr: invoice.payment_request, routes: [], successAction: { tag: 'message', message: `Order ${paymentId} confirmed!`, }, }); } catch (err) { res.status(500).json({ status: 'ERROR', reason: 'Failed to generate invoice' }); } }); function encodeLnurl(url: string): string { const words = bech32.toWords(Buffer.from(url, 'utf8')); return bech32.encode('lnurl', words, 1023).toUpperCase(); } 

Цей код — основа. У продакшені додаємо валідацію, логування, балансування. Протокол використовує HTTPS на порту 443 та TLS-сертифікати Let's Encrypt.

Lightning Address: [email protected]

Lightning Address (LUD-12) — найзручніший UX. Замість QR-коду користувач вводить адресу як email. Гаманець автоматично робить запит на https://domain.com/.well-known/lnurlp/username.

app.get('/.well-known/lnurlp/:username', async (req, res) => { const { username } = req.params; const user = await db.getUserByLnAddress(username); if (!user) { return res.status(404).json({ status: 'ERROR', reason: 'User not found' }); } res.json({ tag: 'payRequest', callback: `https://${req.hostname}/lnurl/lightning-address/${username}`, minSendable: 1000, maxSendable: 10_000_000_000, metadata: JSON.stringify([ ['text/identifier', `${username}@${req.hostname}`], ['text/plain', `Payment to ${username}`], ]), commentAllowed: 144, }); }); 

Після цього [email protected] працює як Lightning Address у будь-якому сумісному гаманці (Phoenix, Wallet of Satoshi, Zeus, Breez).

LNURL-auth: passwordless логін

LNURL-auth дозволяє користувачам логінитися через Lightning гаманець без пароля. Гаманець підписує challenge закритим ключем, похідним від Lightning seed.

import crypto from 'crypto'; app.get('/auth/lnurl', (req, res) => { const k1 = crypto.randomBytes(32).toString('hex'); redis.setex(`lnurl_auth:${k1}`, 300, 'pending'); const lnurlAuthUrl = `https://${req.hostname}/auth/callback?tag=login&k1=${k1}`; const encoded = encodeLnurl(lnurlAuthUrl); res.json({ lnurl: encoded, k1 }); }); app.get('/auth/callback', async (req, res) => { const { k1, sig, key } = req.query as Record<string, string>; const status = await redis.get(`lnurl_auth:${k1}`); if (!status) { return res.json({ status: 'ERROR', reason: 'Unknown k1' }); } const isValid = verifyLnurlAuthSignature(k1, sig, key); if (!isValid) { return res.json({ status: 'ERROR', reason: 'Invalid signature' }); } await redis.setex(`lnurl_auth:${k1}`, 300, `authenticated:${key}`); res.json({ status: 'OK' }); }); 

Фронтенд polling-ом перевіряє статус k1 — щойно гаманець підписав, користувач залогінений.

Які інфраструктурні вимоги для LNURL?

Lightning нода — обов'язкова. Варіанти: LND (Go, gRPC API), Core Lightning (C, UNIX socket + REST), Eclair (Scala, використовується Acinq/Phoenix). Для production: виділений VPS з 4GB+ RAM, SSD, стабільним інтернетом. Нода повинна мати вхідну ліквідність для прийому платежів.

Hosted рішення для швидкого старту: Voltage.cloud (managed LND), Alby Hub (self-custody), Strike API (custodial). Для бойового використання з серйозними обсягами — тільки власна нода.

TLS та домен обов'язкові: LNURL вимагає HTTPS. Самопідписаний сертифікат не пройде — потрібен Let's Encrypt або аналог.

Моніторинг: channel balance (сповіщення при < 10% вхідної ліквідності), invoice expiry, failed payment attempts. LND Metrics експортує Prometheus-сумісні метрики з коробки.

Що входить у роботу з інтеграції?

Ми також надаємо підтримку на місяць після запуску.

Згідно з специфікацією LNURL, протокол підтримує понад 10 LUD-стандартів. Ми реалізуємо всі необхідні.

Оцінимо ваш проект — напишіть нам для консультації. Замовте розробку LNURL-інтеграції з індивідуальним підходом. Отримайте консультацію інженера — зв'яжіться з нами. Гарантуємо якість та сертифіковану підтримку LND.