マイグレーションガイド

Managedモードからソベラーノモードへの移行、バージョン間のアップグレード、またはLightningプロバイダーの切り替えを、ダウンタイムなしで行います。

Managed → ソベラーノ（手数料0%、フルカストディ）

ManagedProviderは最速で起動できる方法として最初に選ばれます。フルカストディと手数料0%の準備ができたら、移行は1行で完了します。

1. Lightningプロバイダーをセットアップする

   ソベラーノプロバイダーを選択します。Blinkは無料、KYC不要、即時セットアップが可能です。

   # Blink: アカウント作成 → APIキー → キーとウォレットIDをコピー
   BLINK_API_KEY=blink_xxxxxxxxxxxxxxxxxxxxxxxx
   BLINK_WALLET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
2. プロバイダーを交換する — 1行

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

   その他すべて — ミドルウェアのセットアップ、トークンの検証、エンドポイントのコード — はまったく同じままです。

3. デプロイする

   マネージドプロバイダーによって発行されたトークンは、移行後も引き続き有効です。検証は純粋な暗号処理（SHA256(preimage) == paymentHash）であり、どのプロバイダーがインボイスを作成したかには依存しません。

   移行ウィンドウも、ダウンタイムも、更新すべきデータベースも存在しません。

ManagedProvider下で発行済みの支払済みトークンは、プロバイダーを切り替えた後も有効のままです。macaroonにはハッシュと有効期限のみが含まれており、プロバイダー固有のデータは含まれていません。

---

ソベラーノプロバイダー間の切り替え

同じパターンで — プロバイダーインスタンスを交換するだけで、他は何も変更しません。

// 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

特定のバージョンを固定している場合は、変更履歴で新機能を確認してください。

---

フレームワークの移行

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

---

リプレイストアの移行

インメモリ → Supabase

環境変数を設定すると、ミドルウェアが自動検出して切り替えます：

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

処理中の既存トークンは引き続き有効です。Supabaseストアはアクティブになった時点から記録を開始します — 移行すべき過去のデータはありません。

インメモリ → 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);

プロバイダー

すべてのプロバイダーオプションとセットアップ

本番環境ガイド

デプロイメントチェックリスト