aiolabs/bitspire
9
0
Fork 0
Code Issues 52 Pull requests 2 Projects Releases Packages Wiki Activity Actions

Add KYC-free Lightning-first architecture review

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan 2026-01-22 15:16:53 -05:00
commit 528c2d6fa8
2 changed files with 672 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

671
docs/architecture-review.md Normal file
View file

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

1
docs/modernization-plan.md
View file

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