From 108cd83d69542be90400b708d01dda53d847a869 Mon Sep 17 00:00:00 2001 From: Patrick Mulligan Date: Thu, 22 Jan 2026 15:25:34 -0500 Subject: [PATCH] Replace BOLT12 with CLINK Offers in architecture BOLT12 problems (per @justin_shocknet): - Onion messages add latency and failure probability - Every hop is a point of failure (Tor-like) - Normalizes mobile nodes (bad for Lightning) - Redundant (LND keysend already exists) - Astroturfed by NGOs with questionable motives CLINK Offers advantages: - Uses Nostr relays (commodity, trustless via NIP-44) - No HTTP callbacks, WebSockets, or onion messages - Keys decoupled from Lightning node identity - Already working: ShockWallet, Lightning.Pub, Stacker News - More traction in weeks than BOLT12 in years Updated: - Protocol stack recommendation - New components (clink-handler) - Implementation roadmap - References section Co-Authored-By: Claude Opus 4.5 --- docs/architecture-review.md | 70 ++++++++++++++++++++++++++++--------- 1 file changed, 53 insertions(+), 17 deletions(-) diff --git a/docs/architecture-review.md b/docs/architecture-review.md index 6844b73..3e0d534 100644 --- a/docs/architecture-review.md +++ b/docs/architecture-review.md @@ -205,7 +205,7 @@ graph TB ``` ┌─────────────────────────────────────────────┐ │ Layer 3: User-Facing Protocols │ -│ LNURL-withdraw, LNURL-pay, BOLT12, NFC │ +│ LNURL-withdraw, CLINK Offers, NFC │ ├─────────────────────────────────────────────┤ │ Layer 2: Privacy & Offline │ │ Cashu ecash, Fedimint e-cash │ @@ -219,7 +219,7 @@ graph TB - **LNbits** - Backend abstraction, multi-wallet, extensions - **Cashu** - Offline payments, instant settlement, privacy - **LNURL** - User experience (scan QR to receive) -- **BOLT12** - Static payment codes, privacy +- **CLINK Offers** - Static payment codes over Nostr (replaces BOLT12) --- @@ -334,24 +334,53 @@ sequenceDiagram ATM->>User: Dispense cash ``` -### BOLT12 Offers +### CLINK Offers (Replaces BOLT12) -> [!decision] BOLT12 for Static Payment Codes -> Reusable payment requests without LNURL server dependency. +> [!decision] CLINK Offers for Static Payment Codes +> Nostr-native static payment codes - superior to BOLT12. + +**Why NOT BOLT12:** + +| Problem | Impact | +|---------|--------| +| Onion messages | Tor-like routing adds latency, every hop = failure point | +| Global round-trips | Requests can circle the world multiple times | +| Mobile node normalization | Encourages unreliable always-offline nodes | +| Redundant | LND keysend already provides static payments | +| Astroturfed | NGO-pushed spec with questionable motives | + +**Why CLINK:** +- Uses Nostr relays (commodity infrastructure, trustless via NIP-44) +- No HTTP callbacks, WebSockets, or Tor-like messaging +- Keys decoupled from Lightning node identity +- Already working: ShockWallet, Lightning.Pub, Stacker News ```typescript -// ATM publishes static offer -const atmOffer = 'lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2q...' +// CLINK Offer (noffer) - static payment code +const atmOffer = 'noffer1qqs...' -// User's wallet fetches invoice via onion message -// No HTTP server needed! +// Invoice request flows through Nostr relays +// No onion message round-trips! + +// Using @shocknet/clink-sdk +import { createOffer, requestInvoice } from '@shocknet/clink-sdk' + +const offer = createOffer({ + pubkey: atmNostrPubkey, + relays: ['wss://relay.damus.io', 'wss://nos.lol'], + priceType: 'variable', // ATM calculates based on cash inserted +}) ``` -**Benefits:** -- No additional server infrastructure -- Native Lightning protocol -- Built-in privacy (blinded paths) -- Supports refunds +**CLINK Protocol:** +- **Kind 21001**: Offer Request/Response +- **Kind 21002**: Debit Request/Response +- **Kind 21003**: Management Delegation + +**References:** +- [CLINK Spec](https://github.com/shocknet/CLINK) +- [CLINK Demo](https://clinkme.dev/) +- [Lightning.Pub](https://github.com/shocknet/Lightning.Pub) ### NFC BOLT Cards @@ -486,7 +515,7 @@ const card = { |-----------|---------|------------| | `lightning-service` | Backend abstraction | LNbits + Cashu + Fedimint | | `lnurl-server` | LNURL-withdraw/pay | Fastify + LNbits | -| `bolt12-handler` | Static offers | LDK | +| `clink-handler` | Static offers via Nostr | @shocknet/clink-sdk | | `cashu-bridge` | Offline capability | cashu-ts | | `nfc-handler` | BOLT card support | libnfc + Rust | | `admin-app` | Operator mobile app | Vue 3 + Capacitor | @@ -603,7 +632,7 @@ Features: Machine pairing, balance check, settings ### Phase 4: Advanced Features -- [ ] BOLT12 offers +- [ ] CLINK Offers (Nostr-native static codes) - [ ] Fedimint integration - [ ] LDK-Node embedded option - [ ] Offline-first mode @@ -654,7 +683,13 @@ Features: Machine pairing, balance check, settings - [Phoenixd](https://github.com/ACINQ/phoenixd) - [LNbits](https://lnbits.com/) - [LNURL Specifications](https://github.com/lnurl/luds) -- [BOLT12](https://bolt12.org/) + +### CLINK (Nostr-Native Lightning) +- [CLINK Protocol Spec](https://github.com/shocknet/CLINK) +- [CLINK Demo](https://clinkme.dev/) +- [Lightning.Pub](https://github.com/shocknet/Lightning.Pub) +- [ShockWallet](https://github.com/shocknet/wallet2) +- [@shocknet/clink-sdk](https://www.npmjs.com/package/@shocknet/clink-sdk) ### Privacy/Ecash - [Cashu Protocol](https://cashu.space/) @@ -669,3 +704,4 @@ Features: Machine pairing, balance check, settings - [FOSSA ATM](https://github.com/lnbits/fossa) - LNbits Lightning ATM - [Bleskomat](https://github.com/samotari/bleskomat) - Minimal Lightning ATM - [RoboSats](https://github.com/RoboSats/robosats) - KYC-free P2P exchange +- [RoboSats](https://github.com/RoboSats/robosats) - KYC-free P2P exchange