Migrationsleitfaden

Wechsle von Managed- zu Soberano-Modus, führe Versions-Upgrades durch oder wechsle Lightning-Anbieter — ohne Ausfallzeiten.

Managed → Soberano (0% Gebühr, volle Verwahrung)

Du hast mit ManagedProvider begonnen, weil es der schnellste Weg ist, loszulegen. Wenn du bereit für volle Verwahrung und 0% Gebühr bist, besteht die Migration aus einer einzigen Zeile.

1. Richte deinen Lightning-Anbieter ein

   Wähle einen Soberano-Anbieter. Blink ist kostenlos, kein KYC, sofortige Einrichtung.

   # Blink: Konto erstellen → API Keys → Schlüssel + Wallet-ID kopieren
   BLINK_API_KEY=blink_xxxxxxxxxxxxxxxxxxxxxxxx
   BLINK_WALLET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
2. Anbieter tauschen — eine Zeile

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

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

   Alles andere — Middleware-Einrichtung, Token-Verifizierung, Endpunkt-Code — bleibt exakt gleich.

3. Deployen

   Tokens, die vom verwalteten Anbieter ausgestellt wurden, funktionieren weiterhin nach der Migration. Die Verifizierung ist reine Kryptografie (SHA256(preimage) == paymentHash) — sie hat keine Abhängigkeit davon, welcher Anbieter die Rechnung erstellt hat.

   Es gibt kein Migrationsfenster, keine Ausfallzeit, keine Datenbank zum Aktualisieren.

Bereits bezahlte Tokens, die unter ManagedProvider ausgestellt wurden, bleiben nach dem Anbieterwechsel gültig. Das macaroon enthält nur einen Hash und ein Ablaufdatum — keine anbieterspezifischen Daten.

---

Zwischen Soberano-Anbietern wechseln

Gleiches Muster — tausche die Anbieter-Instanz aus, alles andere bleibt unverändert.

// 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 (aktuell)

Keine Breaking Changes. Das SDK ist additiv aufgebaut — neue Anbieter, neue Agent-Hilfsprogramme, neue Replay-Adapter. Upgrade mit:

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

Wenn du eine bestimmte Version festgelegt hast, sieh im Changelog nach, was neu ist.

---

Framework-Migration

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'}

---

Replay-Store-Migration

In-Memory → Supabase

Setze Umgebungsvariablen — die Middleware erkennt sie automatisch und wechselt:

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

Bestehende laufende Tokens funktionieren weiterhin. Der Supabase-Store beginnt ab dem Moment der Aktivierung mit der Aufzeichnung — es gibt keine historischen Daten zum Migrieren.

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);

Providers

Alle Anbieteroptionen und Einrichtung

Production Guide

Deployment-Checkliste