Руководство по миграции

Переход с Managed на Soberano режим, обновление между версиями или смена Lightning провайдеров — без простоев.

Managed → Soberano (0% комиссия, полное хранение)

Вы начали с ManagedProvider, потому что это самый быстрый способ начать работу. Когда вы будете готовы к полному хранению и 0% комиссии, миграция займёт одну строку.

1. Настройте ваш Lightning провайдер

   Выберите soberano провайдера. Blink — бесплатно, без KYC, мгновенная настройка.

   # Blink: создайте аккаунт → API Keys → скопируйте ключ + wallet ID
   BLINK_API_KEY=blink_xxxxxxxxxxxxxxxxxxxxxxxx
   BLINK_WALLET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
2. Замените провайдер — одна строка

   // Before
   import { ManagedProvider } from 'l402-kit';
   const lightning = ManagedProvider.fromAddress('[e-mail]');
   
   // After
   import { BlinkProvider } from 'l402-kit';
   const lightning = new BlinkProvider(
     process.env.BLINK_API_KEY!,
     process.env.BLINK_WALLET_ID!,
   );
   

   # Before
   from l402kit import ManagedProvider
   lightning = ManagedProvider.from_address("[e-mail]")
   
   # After
   from l402kit.providers.blink import BlinkProvider
   lightning = BlinkProvider(
       api_key=os.environ["BLINK_API_KEY"],
       wallet_id=os.environ["BLINK_WALLET_ID"],
   )
   

   Всё остальное — настройка middleware, верификация токенов, код эндпоинтов — остаётся точно таким же.

3. Деплой

   Токены, выпущенные managed провайдером, продолжают работать после миграции. Верификация — это чистая криптография (SHA256(preimage) == paymentHash) — она не зависит от того, какой провайдер создал инвойс.

   Нет окна миграции, нет простоев, нет базы данных для обновления.

Уже оплаченные токены, выпущенные через ManagedProvider, остаются действительными после смены провайдера. macaroon содержит только хэш и срок действия — никаких данных, специфичных для провайдера.

---

Смена между soberano провайдерами

Та же схема — меняете экземпляр провайдера, больше ничего не изменяется.

// Blink → LNbits
import { LNbitsProvider } from 'l402-kit';
const lightning = new LNbitsProvider(
  process.env.LNBITS_KEY!,
  process.env.LNBITS_URL ?? 'https://legend.lnbits.com',
);

// Blink → OpenNode
import { OpenNodeProvider } from 'l402-kit';
const lightning = new OpenNodeProvider(process.env.OPENNODE_KEY!, false);

---

v1.x → v1.8 (текущая)

Нет критических изменений. SDK развивается аддитивно — новые провайдеры, новые утилиты для агентов, новые адаптеры воспроизведения. Обновите с помощью:

npm install l402-kit@latest
pip install --upgrade l402kit
cargo update l402kit
go get github.com/shinydapps/l402-kit/go@latest

Если вы зафиксировали конкретную версию, проверьте changelog, чтобы узнать, что нового.

---

Миграция фреймворков

Express → Fastify

// Express
app.get('/api', l402({ priceSats: 10, lightning }), handler);

// Fastify
import { l402Fastify } from 'l402-kit/fastify';

fastify.get('/api', {
  preHandler: l402Fastify({ priceSats: 10, lightning }),
}, handler);

Express → Hono (Cloudflare Workers)

import { Hono } from 'hono';
import { l402Hono } from 'l402-kit/hono';

const app = new Hono();
app.use('/api/*', l402Hono({ priceSats: 10, lightning }));
app.get('/api/data', (c) => c.json({ data: 'paid' }));

Flask → FastAPI

# Flask
from l402kit.flask import l402_required

@app.route('/api')
@l402_required(price_sats=10, lightning=provider)
def handler():
    return jsonify({'data': 'paid'})

# FastAPI
from l402kit import l402_required

@app.get('/api')
@l402_required(price_sats=10, lightning=provider)
async def handler():
    return {'data': 'paid'}

---

Миграция хранилища воспроизведения

In-memory → Supabase

Задайте переменные окружения — middleware автоматически определит и переключится:

SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=your_anon_key

Существующие активные токены продолжают работать. Хранилище Supabase начинает запись с момента активации — исторические данные мигрировать не нужно.

In-memory → Redis

import { Redis } from 'ioredis';
import { RedisReplayAdapter } from 'l402-kit';

const redis = new Redis(process.env.REDIS_URL!);

app.get('/api', l402({
  priceSats: 10,
  lightning,
  replayAdapter: new RedisReplayAdapter(redis),
}), handler);

Провайдеры

Все варианты провайдеров и их настройка

Руководство по продакшену

Чеклист деплоя