Guía de Migración

Pasa de modo Managed a Soberano, actualiza entre versiones o cambia de proveedor Lightning — sin tiempo de inactividad.

Managed → Soberano (0% de comisión, custodia total)

Empezaste con ManagedProvider porque es la forma más rápida de comenzar. Cuando estés listo para la custodia total y 0% de comisión, la migración es de una sola línea.

1. Configura tu proveedor Lightning

   Elige un proveedor soberano. Blink es gratuito, sin KYC, configuración instantánea.

   # Blink: crea cuenta → API Keys → copia key + wallet ID
   BLINK_API_KEY=blink_xxxxxxxxxxxxxxxxxxxxxxxx
   BLINK_WALLET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
2. Cambia el proveedor — una sola línea

   // 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"],
   )
   

   Todo lo demás — configuración del middleware, verificación de tokens, código de endpoints — permanece exactamente igual.

3. Despliega

   Los tokens emitidos por el proveedor administrado continúan funcionando después de la migración. La verificación es criptografía pura (SHA256(preimage) == paymentHash) — no depende de qué proveedor creó la factura.

   No hay ventana de migración, no hay tiempo de inactividad, no hay base de datos que actualizar.

Los tokens ya pagados emitidos bajo ManagedProvider siguen siendo válidos después de cambiar de proveedor. El macaroon solo contiene un hash y una fecha de expiración — no contiene datos específicos del proveedor.

---

Cambiar entre proveedores soberanos

El mismo patrón — intercambia la instancia del proveedor, nada más cambia.

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

Sin cambios incompatibles. El SDK es aditivo — nuevos proveedores, nuevas utilidades para agentes, nuevos adaptadores de repetición. Actualiza con:

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

Si fijaste una versión específica, consulta el registro de cambios para ver las novedades.

---

Migración de framework

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

---

Migración del almacén de repetición

En memoria → Supabase

Configura las variables de entorno — el middleware las detecta automáticamente y cambia:

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

Los tokens en curso existentes siguen funcionando. El almacén de Supabase comienza a registrar desde el momento en que está activo — no hay datos históricos que migrar.

En memoria → 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

Todas las opciones de proveedores y su configuración

Production Guide

Lista de verificación para el despliegue