Payment Layer

l402-kit Bitcoin Lightning भुगतान कैसे प्रोसेस करता है — BOLT11, L402 प्रोटोकॉल, और क्रिप्टोग्राफ़िक सत्यापन।

Payment Layer

l402-kit एक soberano middleware है जो किसी भी HTTP endpoint में 3 लाइन कोड में Bitcoin Lightning paywall जोड़ता है। आप अपना Lightning provider लाते हैं — फंड सीधे आपके wallet में जाते हैं, कोई intermediary की आवश्यकता नहीं।

---

प्रोटोकॉल: L402

L402 एक open standard है जो HTTP/1.1 को एक native payment handshake के साथ विस्तारित करता है:

Client → GET /api/data
Server ← 402 Payment Required
         WWW-Authenticate: L402 <macaroon>, invoice="<BOLT11>"

Client pays invoice via Lightning wallet
Client → GET /api/data
         Authorization: L402 <macaroon>:<preimage>
Server ← 200 OK + data

macaroon एक capability token है जो invoice के paymentHash से बंधा होता है। preimage वह क्रिप्टोग्राफ़िक secret है जो Lightning node द्वारा भुगतान settle होने पर जारी किया जाता है। सर्वर सत्यापित करता है:

SHA256(preimage) == paymentHash ✓

कोई account नहीं, कोई session नहीं, कोई JWT नहीं — preimage ही भुगतान का प्रमाण है।

---

Invoice निर्माण प्रवाह

Your API receives a request without valid Authorization
     │
     ▼
l402-kit middleware calls lightning.createInvoice(priceSats)
     │  (your provider: Blink, Alby, OpenNode, BTCPay, LNbits…)
     ▼
Provider returns BOLT11 invoice + paymentHash
     │
     ▼
Middleware builds macaroon: base64({ hash: paymentHash, exp: now+1h })
     │
     ▼
Your API returns 402 + invoice + macaroon to client

---

Payment सत्यापन प्रवाह

Client pays BOLT11 invoice via any Lightning wallet
     │
     ▼
Lightning node releases preimage (32-byte secret)
     │
     ▼
Client sends Authorization: L402 <macaroon>:<preimage>
     │
     ▼
Middleware verifies locally — no network call:
  1. Decode macaroon (base64 → JSON { hash, exp })
  2. Check exp > now()
  3. SHA256(preimage) === hash ✓
     │
     ▼
Request passes through to your API handler → 200 OK

सत्यापन O(1) है — शुद्ध क्रिप्टोग्राफ़ी, hot path पर कोई database lookup नहीं। Replay protection (Supabase payment_hash logging) असynchronously चलता है और request को block नहीं करता।

Macaroon format

l402-kit एक lightweight custom macaroon उपयोग करता है — libmacaroon नहीं। Token एक base64url-encoded JSON object है:

{ "hash": "<paymentHash hex>", "exp": <unix timestamp> }

यह सरल है और किसी external library के बिना auditable है। Authorization header format है:

Authorization: L402 <base64url-macaroon>:<preimage-hex>

---

Fee मॉडल

मोड	शुल्क	सेटअप
Soberano (कोई भी provider)	0% — आप 100% रखते हैं	अपने provider credentials लाएं
Managed (ManagedProvider)	l402kit.com को 0.3%	कोई Lightning node नहीं — तुरंत काम करता है

Soberano mode डिफ़ॉल्ट है। Managed mode एक explicit opt-in है:

// Soberano — 0% fee, you keep 100%
import { AlbyProvider } from 'l402-kit';
const lightning = new AlbyProvider(process.env.ALBY_TOKEN!);

// Managed — 0.3% fee, no Lightning node needed
import { ManagedProvider } from 'l402-kit';
const lightning = ManagedProvider.fromAddress('[e-mail]');

---

डेटा संग्रहण (वैकल्पिक — Supabase)

भुगतान स्वचालित रूप से log करने के लिए SUPABASE_URL + SUPABASE_ANON_KEY सेट करें:

create table payments (
  id            uuid primary key default gen_random_uuid(),
  payment_hash  text unique not null,  -- SHA256(preimage) — safe to store
  endpoint      text,
  amount_sats   integer,
  paid_at       timestamptz default now()
);

preimage की जगह payment_hash क्यों? payment_hash पहले से ही हर BOLT11 invoice में embedded होता है — यह design के अनुसार public है। केवल preimage secret है। hash संग्रहीत करने से बिना किसी अतिरिक्त exposure के replay protection मिलती है।

---

Lightning Providers

l402-kit provider-agnostic है। कोई भी backend जो LightningProvider implement करता है वह काम करता है:

Provider	नोट्स
Alby Hub	Self-custodial, 0% शुल्क
Blink	निःशुल्क custodial, छोटी राशि के लिए कोई KYC नहीं
BTCPay Server	Self-hosted, पूर्ण soberanoty
OpenNode	Custodial, कोई सेटअप नहीं
LNbits	Self-hosted या cloud

Provider सेटअप के लिए TypeScript SDK या Python SDK देखें।

---

सुरक्षा गारंटी

खतरा	समाधान
Replay attack	पहले सत्यापन के बाद Preimage को उपयोग किया हुआ चिह्नित किया जाता है — in-memory या Redis adapter
नकली preimage	SHA256(preimage) === paymentHash क्रिप्टोग्राफ़िक रूप से अजेय है
Token expiry	Macaroon में exp timestamp embedded है — प्रत्येक request पर सत्यापित
Webhook spoofing	प्रोसेस करने से पहले HMAC-SHA256(secret, body) सत्यापित किया जाता है