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 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan
parent
e55f11ab3a
commit
528c2d6fa8
2 changed files with 672 additions and 0 deletions
671
docs/architecture-review.md
Normal file
671
docs/architecture-review.md
Normal 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
|
||||||
|
|
@ -513,6 +513,7 @@ test('user can complete transaction', async ({ page }) => {
|
||||||
|
|
||||||
## Related Notes
|
## Related Notes
|
||||||
|
|
||||||
|
- [[architecture-review]] - **KYC-free Lightning-first architecture review**
|
||||||
- [[CLAUDE]] - Claude Code guidance
|
- [[CLAUDE]] - Claude Code guidance
|
||||||
- [[admin-ui-modernization]] - Vue 3 migration for admin dashboard
|
- [[admin-ui-modernization]] - Vue 3 migration for admin dashboard
|
||||||
- [[machine-ui-modernization]] - Vue 3 migration for kiosk UI
|
- [[machine-ui-modernization]] - Vue 3 migration for kiosk UI
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue