From 528c2d6fa8e17760ecbb2fe37cedfeaa48d12842 Mon Sep 17 00:00:00 2001 From: Patrick Mulligan Date: Thu, 22 Jan 2026 15:16:53 -0500 Subject: [PATCH] Add KYC-free Lightning-first architecture review Comprehensive rethinking of the project vision: Core Principles: - KYC-free: No identity collection - Lightning-native: Security through protocol - Self-custodial: Operator and user control keys - Privacy by default: Minimize data retention - Autonomous machines: Reduce server dependency Key Technical Decisions: - LNbits as primary Lightning backend - Cashu ecash for offline capability and privacy - LNURL-withdraw/pay for user-friendly flows - BOLT12 offers for static payment codes - NFC BOLT cards for tap-to-withdraw - Fedimint option for community custody Architecture Options: - A: Lean Server (recommended starting point) - B: Serverless Machine (maximum autonomy) - C: Fedimint Community Model Assessment: 60%+ of existing lamassu-server is compliance code. Recommendation: Rebuild core, reuse hardware drivers. Co-Authored-By: Claude Opus 4.5 --- docs/architecture-review.md | 671 ++++++++++++++++++++++++++++++++++++ docs/modernization-plan.md | 1 + 2 files changed, 672 insertions(+) create mode 100644 docs/architecture-review.md diff --git a/docs/architecture-review.md b/docs/architecture-review.md new file mode 100644 index 0000000..6844b73 --- /dev/null +++ b/docs/architecture-review.md @@ -0,0 +1,671 @@ +--- +title: Architecture Review - KYC-Free Lightning-First Vision +created: 2026-01-22 +updated: 2026-01-22 +tags: + - architecture + - lightning + - kyc-free + - redesign + - vision +status: active +priority: critical +--- + +# Architecture Review: KYC-Free Lightning-First Vision + +> [!abstract] Summary +> A comprehensive review of our project architecture, reimagining Lamassu from scratch as a **KYC-free, open-source, Lightning-native** Bitcoin ATM ecosystem. We have complete freedom to redesign - no backward compatibility concerns. + +## Quick Links + +- [[#Vision Statement]] +- [[#Current State Analysis]] +- [[#Proposed Architecture]] +- [[#Lightning Backend Options]] +- [[#Privacy Technologies]] +- [[#Critical Decisions]] + +--- + +## Vision Statement + +> [!important] Core Principles +> 1. **KYC-Free** - No identity collection, no compliance theater +> 2. **Open-Source First** - Every component auditable and forkable +> 3. **Lightning-Native** - Security through protocol, not policy +> 4. **Self-Custodial** - Operator and user control their own keys +> 5. **Privacy by Default** - Minimize data collection and retention +> 6. **Autonomous Machines** - Reduce server dependency + +### What We're Building + +The **ultimate Bitcoin Lightning ATM** with a wallet ecosystem that: +- Converts cash ↔ Lightning instantly +- Requires no identity verification +- Operates with minimal infrastructure +- Can function offline with ecash +- Supports NFC tap-to-pay +- Enables operator sovereignty + +--- + +## Current State Analysis + +### Lamassu Codebase Issues + +The existing Lamassu codebase carries significant baggage: + +| Component | Problem | Impact | +|-----------|---------|--------| +| `lib/compliance/` | KYC/AML workflows | 40% of server code | +| `lib/customers/` | Identity management | Database bloat | +| `lib/sanctions/` | OFAC screening | External dependencies | +| `lib/sms/` | Phone verification | Privacy violation | +| `lib/id-scan/` | Document verification | Third-party APIs | +| `lib/blacklist/` | User blocking | Centralized control | +| Multi-coin | Altcoin support | Code complexity | + +> [!warning] Assessment +> **60%+ of lamassu-server code is compliance-related.** Rather than removing it surgically, a clean rebuild may be more efficient. + +### Current LNbits Integration (As Documented) + +Our current docs treat LNbits as a simple payment backend: + +``` +Machine → Server → LNbits → Lightning Network +``` + +**Problems with this approach:** +1. Server is still a bottleneck +2. Single point of failure +3. Not utilizing LNbits' full potential +4. Missing privacy technologies (Cashu, Fedimint) +5. Still designed around on-chain model + +--- + +## Proposed Architecture + +### Option A: Lean Server (Recommended) + +```mermaid +graph TB + subgraph "ATM Machine" + tauri[Tauri + Vue 3] + ldk[LDK-Node / Phoenixd] + hal[Rust HAL] + end + + subgraph "Minimal Coordinator" + api[Fastify API] + db[(SQLite/PostgreSQL)] + end + + subgraph "Lightning Layer" + lnbits[LNbits] + cashu[Cashu Mint] + fedimint[Fedimint Gateway] + end + + tauri -->|LNURL/BOLT12| lnbits + tauri -->|ecash| cashu + tauri -->|Optional| api + api --> db + lnbits --> fedimint + hal --> hardware[Hardware] +``` + +**Key Changes:** +- Machine can operate independently with embedded Lightning +- Server becomes optional coordinator (fleet management, analytics) +- Multiple Lightning backends supported +- Ecash for offline capability + +### Option B: Serverless Machine + +```mermaid +graph TB + subgraph "Autonomous ATM" + ui[Vue 3 UI] + xstate[XState v5] + ldk[LDK-Node] + cashu[Cashu Wallet] + hal[Rust HAL] + end + + ldk -->|Direct| ln[Lightning Network] + cashu -->|Swap| mint[Cashu Mint] + hal --> hw[Hardware] + + admin[Admin Phone App] -->|Bluetooth/Local| ui +``` + +**Extreme autonomy:** +- No central server at all +- Machine runs its own Lightning node +- Admin via local connection (phone app) +- Perfect for single-operator deployments + +### Option C: Fedimint Community Model + +```mermaid +graph TB + subgraph "Community Federation" + g1[Guardian 1] + g2[Guardian 2] + g3[Guardian 3] + g4[Guardian 4] + end + + subgraph "ATMs" + atm1[Machine 1] + atm2[Machine 2] + atm3[Machine 3] + end + + subgraph "Gateway" + gw[Lightning Gateway] + end + + atm1 --> g1 + atm2 --> g2 + atm3 --> g3 + g1 --> gw + g2 --> gw + g3 --> gw + g4 --> gw + gw --> ln[Lightning Network] +``` + +**Community custody:** +- Multiple guardians share custody +- No single operator can rug +- Built-in ecash for privacy +- Ideal for community/coop deployments + +--- + +## Lightning Backend Options + +### Comparison Matrix + +| Backend | Self-Custodial | Complexity | Offline | Privacy | Best For | +|---------|---------------|------------|---------|---------|----------| +| **LDK-Node** | Yes | High | No | Good | Embedded in machine | +| **Phoenixd** | Yes | Low | No | Good | Simple server setup | +| **LNbits** | Depends | Medium | Via Cashu | Good | Multi-wallet, extensions | +| **Cashu** | No (mint) | Low | Yes | Excellent | Offline, privacy | +| **Fedimint** | Federated | High | Yes | Excellent | Community custody | +| **Breez SDK** | Yes | Medium | No | Good | Mobile-first | + +### Recommendation: Layered Approach + +``` +┌─────────────────────────────────────────────┐ +│ Layer 3: User-Facing Protocols │ +│ LNURL-withdraw, LNURL-pay, BOLT12, NFC │ +├─────────────────────────────────────────────┤ +│ Layer 2: Privacy & Offline │ +│ Cashu ecash, Fedimint e-cash │ +├─────────────────────────────────────────────┤ +│ Layer 1: Lightning Backends │ +│ LNbits (primary), Phoenixd, LDK-Node │ +└─────────────────────────────────────────────┘ +``` + +**Use each layer for its strengths:** +- **LNbits** - Backend abstraction, multi-wallet, extensions +- **Cashu** - Offline payments, instant settlement, privacy +- **LNURL** - User experience (scan QR to receive) +- **BOLT12** - Static payment codes, privacy + +--- + +## Privacy Technologies + +### Cashu Integration + +> [!decision] Cashu for Offline & Privacy +> Cashu ecash enables offline ATM operation and enhanced privacy. + +**How it works for ATM:** + +```mermaid +sequenceDiagram + participant User + participant ATM + participant Mint as Cashu Mint + participant LN as Lightning + + User->>ATM: Insert $20 cash + ATM->>Mint: Request ecash tokens + Mint->>ATM: Issue 20,000 sat tokens + ATM->>User: Display QR (Cashu tokens) + User->>User: Scan with Cashu wallet + + Note over User,LN: Later, user can... + User->>Mint: Redeem tokens + Mint->>LN: Pay Lightning invoice +``` + +**Benefits:** +- ATM doesn't need to know user's Lightning wallet +- User receives ecash, redeems whenever +- ATM can operate offline (pre-loaded tokens) +- Perfect privacy (blinded signatures) + +**Cashu Libraries:** +- `cashu-ts` - TypeScript SDK +- `cashu-rs` - Rust implementation +- `nutshell` - Python reference + +### Fedimint Integration + +> [!note] Fedimint for Community Operations +> When multiple operators want shared custody without single points of failure. + +**Architecture:** +```typescript +// Federation of 4 guardians (3-of-4 threshold) +const federation = { + guardians: [ + 'operator1.onion', + 'operator2.onion', + 'operator3.onion', + 'operator4.onion', + ], + threshold: 3, + modules: ['wallet', 'mint', 'ln'], +} +``` + +**Use Cases:** +- Bitcoin circular economy communities +- Cooperative ATM networks +- Regions with unstable operators + +--- + +## Protocol Stack + +### LNURL for ATM UX + +> [!tip] LNURL-withdraw is Perfect for ATMs +> User scans QR from ATM screen to pull sats to their wallet. + +**Cash-In Flow (User buys Bitcoin):** +```mermaid +sequenceDiagram + participant User + participant ATM + participant LNbits + + User->>ATM: Insert $50 cash + ATM->>LNbits: Create LNURL-withdraw + LNbits->>ATM: lnurl1dp68gurn8ghj7... + ATM->>ATM: Display QR code + User->>User: Scan with any LN wallet + User->>LNbits: Request invoice (via LNURL) + LNbits->>User: Pay invoice to user's wallet + ATM->>ATM: Transaction complete +``` + +**Benefits:** +- Works with ANY Lightning wallet +- No camera needed on ATM +- User controls destination +- Privacy preserved + +**Cash-Out Flow (User sells Bitcoin):** +```mermaid +sequenceDiagram + participant User + participant ATM + participant LNbits + + User->>ATM: Select "Sell Bitcoin" + ATM->>LNbits: Create invoice + LNbits->>ATM: BOLT11 invoice + ATM->>ATM: Display QR code + User->>User: Scan & pay invoice + LNbits->>ATM: Payment confirmed + ATM->>User: Dispense cash +``` + +### BOLT12 Offers + +> [!decision] BOLT12 for Static Payment Codes +> Reusable payment requests without LNURL server dependency. + +```typescript +// ATM publishes static offer +const atmOffer = 'lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrc2q...' + +// User's wallet fetches invoice via onion message +// No HTTP server needed! +``` + +**Benefits:** +- No additional server infrastructure +- Native Lightning protocol +- Built-in privacy (blinded paths) +- Supports refunds + +### NFC BOLT Cards + +> [!tip] Tap-to-Withdraw with NFC +> Pre-programmed NFC cards for instant cash withdrawal. + +**How BOLT Cards work:** +1. NFC card contains LNURL-withdraw with rotating auth +2. User taps card on ATM +3. ATM reads LNURL, requests invoice +4. Card's backing service pays invoice +5. ATM dispenses cash + +**Implementation:** +- Cards use NXP NTAG 424 DNA (secure element) +- Each tap generates unique auth code +- Supports spending limits per tap/day +- Compatible with: Coinos, LNbits, BTCPay + +```typescript +// LNbits BoltCards extension +const card = { + uid: '04:E1:5F:...', + cardName: 'ATM Withdrawal Card', + maxWithdrawPerTap: 50000, // sats + dailyLimit: 200000, // sats +} +``` + +--- + +## Simplified Transaction Flows + +### Cash → Lightning (Buy) + +``` +┌─────────────────────────────────────────────────────────────┐ +│ SIMPLIFIED BUY FLOW │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ 1. User inserts cash [$20, $50, $100] │ +│ │ +│ 2. ATM displays QR [LNURL-withdraw] │ +│ "Scan to receive Bitcoin" │ +│ │ +│ 3. User scans with ANY [Phoenix, Zeus, Wallet of │ +│ Lightning wallet Satoshi, Breez, etc.] │ +│ │ +│ 4. Sats arrive instantly [~2 seconds] │ +│ │ +│ Done. No account. No KYC. No email. No phone. │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Lightning → Cash (Sell) + +``` +┌─────────────────────────────────────────────────────────────┐ +│ SIMPLIFIED SELL FLOW │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ Option A: Pay Invoice │ +│ 1. Select amount to withdraw [$20, $50, $100] │ +│ 2. ATM shows Lightning invoice QR │ +│ 3. User pays from any wallet │ +│ 4. Cash dispensed │ +│ │ +│ Option B: NFC Tap (BOLT Card) │ +│ 1. User taps NFC card │ +│ 2. ATM reads LNURL-withdraw │ +│ 3. Cash dispensed │ +│ [Single tap, ~3 seconds total] │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Offline Mode (Cashu) + +``` +┌─────────────────────────────────────────────────────────────┐ +│ OFFLINE CASH-IN FLOW │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ATM has pre-loaded Cashu tokens from mint │ +│ │ +│ 1. User inserts $50 cash │ +│ │ +│ 2. ATM displays Cashu token QR │ +│ (No internet required!) │ +│ │ +│ 3. User scans with Cashu wallet │ +│ [Minibits, Nutstash, eNuts] │ +│ │ +│ 4. User can later swap ecash → Lightning │ +│ when they have connectivity │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Revised Component Architecture + +### What We Keep from Lamassu + +| Component | Keep? | Notes | +|-----------|-------|-------| +| Hardware drivers | Yes | Port to Rust HAL | +| Bill validator protocols | Yes | ID003, eSSP, ccTalk | +| Bill dispenser drivers | Yes | Puloon, Fujitsu | +| Brain state machine | Rewrite | Simplify with XState v5 | +| Admin UI | Partial | Rebuild in Vue 3 | +| Server API | Minimal | Strip compliance code | + +### What We Remove + +| Component | Why Remove | +|-----------|------------| +| `lib/compliance/` | No KYC | +| `lib/customers/` | No identity storage | +| `lib/sanctions/` | No OFAC screening | +| `lib/sms/` | No phone verification | +| `lib/id-scan/` | No document scanning | +| `lib/blacklist/` | No user blocking | +| Multi-coin support | Bitcoin only | +| Fiat exchange rates | Lightning is the unit | + +### New Components to Build + +| Component | Purpose | Technology | +|-----------|---------|------------| +| `lightning-service` | Backend abstraction | LNbits + Cashu + Fedimint | +| `lnurl-server` | LNURL-withdraw/pay | Fastify + LNbits | +| `bolt12-handler` | Static offers | LDK | +| `cashu-bridge` | Offline capability | cashu-ts | +| `nfc-handler` | BOLT card support | libnfc + Rust | +| `admin-app` | Operator mobile app | Vue 3 + Capacitor | + +--- + +## Revised Tech Stack + +### Server (Coordinator) + +```yaml +Runtime: Node.js 22 LTS +Language: TypeScript (strict) +Framework: Fastify +API: tRPC (admin), LNURL (public) +Database: SQLite (single) / PostgreSQL (fleet) +ORM: Drizzle +Lightning: LNbits API +Ecash: Cashu client +``` + +### Machine + +```yaml +Shell: Tauri 2.x (Rust) +UI: Vue 3 + Pinia + shadcn-vue +State: XState v5 +Hardware: Rust HAL + napi-rs +Lightning: LDK-Node or Phoenixd (optional) +Ecash: Cashu wallet +NFC: libnfc bindings +``` + +### Mobile Admin App + +```yaml +Framework: Vue 3 + Ionic/Capacitor +Connectivity: Bluetooth LE, Local WiFi +Features: Machine pairing, balance check, settings +``` + +--- + +## Critical Decisions Needed + +### Decision 1: Server Model + +| Option | Pros | Cons | +|--------|------|------| +| **A: Lean Server** | Fleet management, familiar model | Single point of failure | +| **B: Serverless** | Maximum autonomy | Complex admin | +| **C: Fedimint** | Community custody | Requires federation | + +> [!question] Recommendation +> Start with **Option A (Lean Server)** for faster development, design for Option B compatibility. + +### Decision 2: Primary Lightning Backend + +| Option | Pros | Cons | +|--------|------|------| +| **LNbits** | Extensions, multi-wallet | Requires server | +| **Phoenixd** | Simple, self-custodial | ACINQ dependency | +| **LDK-Node** | Embedded, maximum control | Complex | + +> [!question] Recommendation +> **LNbits** as primary (proven, extensible), with **Cashu** for offline mode. + +### Decision 3: Ecash Strategy + +| Option | Pros | Cons | +|--------|------|------| +| **Cashu** | Simple, growing ecosystem | Single mint trust | +| **Fedimint** | Federated trust | Complex setup | +| **Both** | Maximum flexibility | Maintenance burden | + +> [!question] Recommendation +> **Cashu** first (simpler), add Fedimint support later. + +### Decision 4: Rebuild vs Refactor + +| Option | Effort | Risk | Result | +|--------|--------|------|--------| +| **Rebuild** | 6-12 months | Medium | Clean architecture | +| **Refactor** | 12-18 months | High | Frankenstein code | + +> [!question] Recommendation +> **Rebuild** the core, reuse hardware drivers. + +--- + +## Implementation Roadmap + +### Phase 1: Foundation + +- [ ] Create new monorepo structure +- [ ] Set up devenv.nix for development +- [ ] Port hardware drivers to Rust HAL +- [ ] Implement LNURL-withdraw flow +- [ ] Basic Vue 3 machine UI + +### Phase 2: Lightning Integration + +- [ ] LNbits integration (simplified from current docs) +- [ ] LNURL-pay for cash-out +- [ ] Cashu ecash support +- [ ] NFC BOLT card support + +### Phase 3: Operator Tools + +- [ ] Minimal admin API +- [ ] Vue 3 admin dashboard +- [ ] Mobile admin app +- [ ] Fleet management (optional) + +### Phase 4: Advanced Features + +- [ ] BOLT12 offers +- [ ] Fedimint integration +- [ ] LDK-Node embedded option +- [ ] Offline-first mode + +--- + +## Comparison: Old vs New + +| Aspect | Old Lamassu | New Vision | +|--------|-------------|------------| +| Identity | KYC/AML required | None collected | +| Compliance | 60% of codebase | 0% | +| Coins | 30+ altcoins | Bitcoin only | +| On-chain | Primary | Emergency fallback | +| Lightning | Secondary | Primary | +| Privacy | Minimal | Maximum (Cashu) | +| Server | Required | Optional | +| Offline | Not possible | Cashu ecash | +| NFC | Not supported | BOLT cards | +| Custody | Operator holds | User self-custody | + +--- + +## Open Questions + +1. **Exchange rate source?** - Do we quote BTC/fiat or operate in sats-only mode? +2. **Minimum viable admin?** - What's the smallest admin surface needed? +3. **Machine authentication?** - How do machines auth to coordinator without certs? +4. **Liquidity management?** - How do operators manage Lightning liquidity? +5. **Regulatory reality?** - What jurisdictions can this operate in? + +--- + +## Related Notes + +- [[modernization-plan]] - Original tech stack decisions +- [[lnbits-integration]] - Current LNbits docs (to be revised) +- [[membership-lightning-integration]] - Membership feature (simplify) +- [[hardware-recommendations]] - Hardware choices +- [[machine-ui-modernization]] - Vue 3 UI migration + +--- + +## References + +### Lightning +- [LDK Documentation](https://lightningdevkit.org/) +- [Phoenixd](https://github.com/ACINQ/phoenixd) +- [LNbits](https://lnbits.com/) +- [LNURL Specifications](https://github.com/lnurl/luds) +- [BOLT12](https://bolt12.org/) + +### Privacy/Ecash +- [Cashu Protocol](https://cashu.space/) +- [Fedimint](https://fedimint.org/) +- [Cashu TypeScript SDK](https://github.com/cashubtc/cashu-ts) + +### NFC +- [BOLT Cards](https://bolt.cards/) +- [LNbits BoltCards Extension](https://github.com/lnbits/lnbits/tree/main/lnbits/extensions/boltcards) + +### Reference Implementations +- [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 diff --git a/docs/modernization-plan.md b/docs/modernization-plan.md index 879fd40..dbf85a6 100644 --- a/docs/modernization-plan.md +++ b/docs/modernization-plan.md @@ -513,6 +513,7 @@ test('user can complete transaction', async ({ page }) => { ## Related Notes +- [[architecture-review]] - **KYC-free Lightning-first architecture review** - [[CLAUDE]] - Claude Code guidance - [[admin-ui-modernization]] - Vue 3 migration for admin dashboard - [[machine-ui-modernization]] - Vue 3 migration for kiosk UI