From 16f5fb3cbc7d17e0f44ee6e827e8042d1e8570e8 Mon Sep 17 00:00:00 2001 From: Patrick Mulligan Date: Mon, 26 Jan 2026 15:58:01 -0500 Subject: [PATCH] docs: add architecture comparison with traditional lamassu-server Comprehensive document comparing Nostr-native approach with traditional lamassu-server/machine for operators evaluating the transition. Covers infrastructure, security, payments, compliance, and migration path. Co-Authored-By: Claude Opus 4.5 --- lamassu-next/CLAUDE.md | 2 + lamassu-next/README.md | 11 + lamassu-next/docs/architecture-comparison.md | 338 +++++++++++++++++++ 3 files changed, 351 insertions(+) create mode 100644 lamassu-next/docs/architecture-comparison.md diff --git a/lamassu-next/CLAUDE.md b/lamassu-next/CLAUDE.md index cf100d1..04ce10b 100644 --- a/lamassu-next/CLAUDE.md +++ b/lamassu-next/CLAUDE.md @@ -292,6 +292,8 @@ When porting: ## Related Documentation +- `docs/architecture-comparison.md` - Nostr-native vs traditional lamassu-server comparison +- `docs/ndebit-cash-in-flow.md` - Technical walkthrough of cash-in implementation - `packages/lightning/TROUBLESHOOTING.md` - Lightning.Pub integration gotchas (must read!) - `.claude/skills/*.md` - Custom skill documentation diff --git a/lamassu-next/README.md b/lamassu-next/README.md index 7350f37..5132e9b 100644 --- a/lamassu-next/README.md +++ b/lamassu-next/README.md @@ -2,6 +2,8 @@ A Nostr-native Lightning ATM system. KYC-free, open source, auditable. +> **Considering adopting this approach?** See [Architecture Comparison](docs/architecture-comparison.md) for a detailed comparison with traditional lamassu-server/machine. + ## Prerequisites - [Nix](https://nixos.org/download.html) with flakes enabled @@ -149,6 +151,15 @@ mine-blocks 1 # Trigger sync - **NIP-44**: Encryption standard for private Nostr messages - **Kind 21000**: Lightning.Pub RPC events +## Documentation + +| Document | Description | +| ---------------------------------------------------------- | ----------------------------------------------- | +| [Architecture Comparison](docs/architecture-comparison.md) | Nostr-native vs traditional lamassu-server | +| [ndebit Cash-In Flow](docs/ndebit-cash-in-flow.md) | Technical walkthrough of cash-in implementation | +| [Troubleshooting](packages/lightning/TROUBLESHOOTING.md) | Lightning.Pub integration issues and solutions | +| [CLAUDE.md](CLAUDE.md) | Development guidelines and code style | + ## Contributing See `CLAUDE.md` for development guidelines and code style. diff --git a/lamassu-next/docs/architecture-comparison.md b/lamassu-next/docs/architecture-comparison.md new file mode 100644 index 0000000..d8ab489 --- /dev/null +++ b/lamassu-next/docs/architecture-comparison.md @@ -0,0 +1,338 @@ +# Architecture Comparison: Nostr-Native vs Traditional Lamassu + +This document compares the Nostr-native Lightning ATM architecture (Lamassu Next) with the traditional lamassu-server/machine implementation to help operators evaluate the transition. + +## Executive Summary + +| Aspect | Traditional (lamassu-server) | Nostr-Native (lamassu-next) | +| ------------------------ | ---------------------------- | ---------------------------------- | +| **Communication** | Custom WebSocket protocol | Nostr relay (NIP-01) | +| **Identity** | Server-issued credentials | Cryptographic keypairs (npub/nsec) | +| **Account System** | PostgreSQL + custom auth | Lightning.Pub (Nostr-native) | +| **Payment Protocol** | Direct LND RPC | CLINK protocol (kinds 21001-21003) | +| **Infrastructure** | Server + DB + Admin UI | Relay (optional self-hosted) | +| **Wallet Compatibility** | Lamassu-specific | Any CLINK-compatible wallet | + +--- + +## Traditional Architecture (lamassu-server/machine) + +### Overview + +``` +┌─────────────────┐ WebSocket ┌─────────────────────┐ +│ ATM Machine │◄─────────────────────────►│ lamassu-server │ +│ (lamassu-machine)│ │ │ +└─────────────────┘ │ ┌───────────────┐ │ + │ │ PostgreSQL │ │ +┌─────────────────┐ HTTPS │ └───────────────┘ │ +│ Admin UI │◄─────────────────────────►│ │ +│ (React SPA) │ GraphQL │ ┌───────────────┐ │ +└─────────────────┘ │ │ LND │ │ + │ └───────────────┘ │ +┌─────────────────┐ │ │ +│ Customer Wallet │◄── Lightning Invoice ─────│ ┌───────────────┐ │ +│ (any LN wallet) │ │ │ Compliance │ │ +└─────────────────┘ │ │ Services │ │ + │ └───────────────┘ │ + └─────────────────────┘ +``` + +### Components + +| Component | Description | +| ------------------- | ------------------------------------------------ | +| **lamassu-server** | Node.js Express + Apollo GraphQL backend | +| **lamassu-machine** | Node.js kiosk application with hardware drivers | +| **PostgreSQL** | Central database for transactions, users, config | +| **Admin UI** | React dashboard for fleet management | +| **LND** | Lightning Network Daemon for payments | + +### Communication Flow + +1. Machine boots and authenticates with server via client certificate +2. Server pushes configuration and state via WebSocket +3. Customer initiates transaction at machine +4. Machine requests invoice/address from server +5. Server creates invoice via LND, stores in PostgreSQL +6. Customer pays invoice +7. Server detects payment, updates database +8. Server notifies machine to dispense cash +9. Transaction logged in PostgreSQL for compliance + +### Characteristics + +- **Centralized**: All state lives in server's PostgreSQL +- **Operator-managed**: Requires significant infrastructure +- **Custom protocol**: WebSocket messages are Lamassu-specific +- **Tight coupling**: Machine depends entirely on server availability +- **Compliance-ready**: Built-in KYC/AML features + +--- + +## Nostr-Native Architecture (lamassu-next) + +### Overview + +``` +┌─────────────────┐ ┌─────────────────┐ +│ ATM Machine │ │ Customer │ +│ (npub_atm) │ │ Wallet │ +└────────┬────────┘ │ (npub_user) │ + │ └────────┬────────┘ + │ NIP-01 events │ + │ NIP-44 encrypted │ CLINK protocol + ▼ ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Nostr Relay │ +│ (strfry, nostr-rs, etc.) │ +└─────────────────────────────────────────────────────────────────┘ + │ │ + │ Kind 21000 (RPC) │ + │ Kind 21001-21003 (CLINK) │ + ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ +│ Lightning.Pub │ │ Lightning.Pub │ +│ (ATM account) │◄── Lightning Payment ─────►│ (User account) │ +└────────┬────────┘ └─────────────────┘ + │ + ▼ +┌─────────────────┐ +│ LND │ +└─────────────────┘ +``` + +### Components + +| Component | Description | +| ------------------- | ----------------------------------------------- | +| **Nostr Relay** | Message broker (strfry, nostr-rs-relay) | +| **Lightning.Pub** | Nostr-native account system wrapping LND | +| **ATM Machine** | Tauri + Vue 3 kiosk identified by npub | +| **Customer Wallet** | Any CLINK-compatible wallet (ShockWallet, etc.) | + +### Communication Flow (Cash-In Example) + +1. ATM generates ephemeral keypair or uses persistent npub +2. Customer scans QR containing `ndebit` (debit authorization) +3. Customer's wallet connects to relay, finds ATM's Lightning.Pub +4. Wallet creates invoice via Lightning.Pub RPC (kind 21000) +5. Wallet sends debit request (kind 21002) to ATM's npub +6. ATM verifies request, approves payment +7. Lightning.Pub pays invoice, returns preimage +8. ATM detects payment confirmation +9. ATM dispenses cash +10. Transaction recorded as Nostr event (optional) + +### Characteristics + +- **Decentralized**: No single server owns state +- **Interoperable**: Standard protocols (Nostr, CLINK, Lightning) +- **Keypair identity**: ATM is identified by npub, not server account +- **Loose coupling**: ATM can work with any relay/Lightning.Pub +- **Privacy-first**: No central transaction logs required + +--- + +## Detailed Comparison + +### 1. Infrastructure Requirements + +| Requirement | Traditional | Nostr-Native | +| -------------------- | ------------------------------------ | -------------------------------- | +| **Server Hardware** | Dedicated server (4+ GB RAM, SSD) | Optional (can use public relays) | +| **Database** | PostgreSQL (backup, maintenance) | None required | +| **SSL Certificates** | Required (client certs for machines) | Not required | +| **Domain Name** | Required | Optional | +| **Static IP** | Recommended | Not required | +| **Firewall Rules** | Complex (multiple ports) | Simple (outbound WebSocket only) | + +**Advantage: Nostr-Native** - Dramatically simpler infrastructure. An operator can start with public relays and self-host later. + +### 2. Security Model + +| Aspect | Traditional | Nostr-Native | +| -------------------- | ------------------------------- | ------------------------ | +| **Machine Auth** | Client certificates | Keypair (nsec) | +| **Message Security** | TLS | NIP-44 encryption | +| **Identity Theft** | Steal cert + key | Steal nsec only | +| **Compromise Scope** | All machines if server breached | Individual machine only | +| **Key Storage** | Server manages | Machine manages own keys | + +**Advantage: Nostr-Native** - Compromise of one machine doesn't affect others. No central point of failure. + +### 3. Payment Flow + +| Aspect | Traditional | Nostr-Native | +| ------------------------ | ---------------------- | ------------------------------ | +| **Invoice Creation** | Server creates via LND | Lightning.Pub via Nostr RPC | +| **Payment Detection** | Server polls LND | Subscription to payment events | +| **Wallet Compatibility** | Any Lightning wallet | CLINK-compatible wallets | +| **Offline Capability** | None | Cashu ecash (planned) | +| **Payment Protocol** | BOLT11 only | BOLT11 + CLINK + noffer | + +**Mixed**: Traditional has broader wallet compatibility today. Nostr-Native enables advanced features (ndebit, noffer) but requires CLINK wallets. + +### 4. Operator Experience + +| Aspect | Traditional | Nostr-Native | +| ----------------------- | ------------------------------- | -------------------------- | +| **Setup Time** | Hours (server, DB, certs) | Minutes (connect to relay) | +| **Maintenance** | DB backups, updates, monitoring | Minimal | +| **Fleet Management** | Admin UI (full-featured) | Dashboard (planned) | +| **Transaction History** | PostgreSQL queries | Nostr event queries | +| **Configuration** | Server-pushed | Local or relay-stored | + +**Mixed**: Traditional has mature tooling. Nostr-Native is simpler but dashboard is still in development. + +### 5. Customer Experience + +| Aspect | Traditional | Nostr-Native | +| ----------------------- | ------------------------ | ----------------------- | +| **Cash-In** | Scan invoice, pay | Scan ndebit, authorize | +| **Cash-Out** | Enter phone, receive SMS | Scan noffer, receive | +| **Wallet Requirements** | Any Lightning wallet | CLINK-compatible wallet | +| **Account Required** | Sometimes (compliance) | Never | +| **Transaction Speed** | ~10 seconds | ~5 seconds | + +**Advantage: Nostr-Native** - Faster, more private, no accounts. But requires specific wallet support. + +### 6. Compliance & Regulation + +| Aspect | Traditional | Nostr-Native | +| -------------------- | ----------------------- | --------------------- | +| **KYC Integration** | Built-in | Not included | +| **Transaction Logs** | PostgreSQL | Optional Nostr events | +| **Audit Trail** | Comprehensive | Operator-defined | +| **Reporting** | Admin UI exports | Custom tooling needed | +| **Regulatory Fit** | Designed for compliance | Privacy-first design | + +**Advantage: Traditional** - If you need KYC/AML, traditional is ready. Nostr-Native assumes jurisdictions without these requirements. + +### 7. Resilience & Availability + +| Aspect | Traditional | Nostr-Native | +| --------------------------- | ---------------------- | ------------------------- | +| **Server Down** | All machines offline | Machines continue working | +| **Network Partition** | Transactions fail | Can use multiple relays | +| **Database Corruption** | Catastrophic | No database to corrupt | +| **Recovery** | Restore from backup | Re-sync from relay | +| **Geographic Distribution** | Single server location | Relay anywhere | + +**Advantage: Nostr-Native** - No single point of failure. Machines are autonomous. + +### 8. Development & Extensibility + +| Aspect | Traditional | Nostr-Native | +| --------------------------- | ----------------- | ------------------------- | +| **Codebase** | Large monolith | Modular packages | +| **Protocol** | Proprietary | Open standards | +| **Third-party Integration** | Custom API needed | Standard Nostr/CLINK | +| **Community** | Lamassu operators | Nostr + Bitcoin ecosystem | +| **Forkability** | Complex | Straightforward | + +**Advantage: Nostr-Native** - Open protocols mean broader ecosystem participation. + +--- + +## Migration Path + +### Phase 1: Parallel Operation + +Run both systems simultaneously: + +- Existing machines continue with lamassu-server +- New machines or test units use lamassu-next +- Compare reliability and customer feedback + +### Phase 2: Hybrid Mode + +Bridge the systems: + +- lamassu-server creates Nostr events for transactions +- Dashboard reads from both PostgreSQL and relay +- Gradual feature parity validation + +### Phase 3: Full Migration + +Complete transition: + +- All machines run lamassu-next firmware +- Retire lamassu-server infrastructure +- Optional: Keep PostgreSQL as read-only archive + +### Migration Considerations + +| Consideration | Notes | +| -------------------------- | ----------------------------------------------- | +| **Hardware Compatibility** | Same bill validators/dispensers, new software | +| **Customer Education** | May need CLINK-compatible wallet guidance | +| **Operator Training** | Different mental model (events vs database) | +| **Regulatory Review** | Verify compliance in your jurisdiction | +| **Rollback Plan** | Keep lamassu-server available during transition | + +--- + +## Trade-offs & Honest Assessment + +### Where Nostr-Native Excels + +1. **Simplicity**: No server to manage, no database to backup +2. **Privacy**: No central transaction logs +3. **Resilience**: No single point of failure +4. **Interoperability**: Works with any CLINK wallet +5. **Speed**: Direct relay communication is faster +6. **Cost**: No server hosting costs (can use public relays) + +### Where Traditional May Be Better + +1. **Compliance**: Built-in KYC/AML if required by law +2. **Wallet Support**: Works with any Lightning wallet today +3. **Maturity**: Battle-tested over years of operation +4. **Tooling**: Full-featured admin dashboard exists +5. **Support**: Established support channels and documentation + +### Current Limitations of Nostr-Native + +| Limitation | Status | Mitigation | +| ---------------------- | ------------- | ---------------------------------- | +| Dashboard not complete | In progress | Use relay queries directly | +| Limited wallet support | Growing | ShockWallet, others adopting CLINK | +| No offline mode yet | Cashu planned | Requires internet currently | +| Less documentation | Improving | This document helps | + +--- + +## Conclusion + +The Nostr-native architecture represents a fundamental shift from centralized to decentralized ATM operation. It trades the comprehensive compliance features of lamassu-server for simplicity, privacy, and resilience. + +**Choose Nostr-Native if:** + +- You operate in jurisdictions without KYC requirements +- You want minimal infrastructure overhead +- You value customer privacy +- You're comfortable with emerging technology + +**Stick with Traditional if:** + +- You need built-in compliance features +- You require extensive fleet management tools today +- You need to support any Lightning wallet +- You prefer mature, battle-tested systems + +**Consider Hybrid if:** + +- You want to evaluate both approaches +- You're planning a gradual migration +- You have mixed regulatory requirements across locations + +--- + +## Further Reading + +- [CLINK Protocol Specification](https://github.com/shocknet/clink) +- [Lightning.Pub Documentation](https://github.com/shocknet/Lightning.Pub) +- [Nostr Protocol (NIP-01)](https://github.com/nostr-protocol/nips/blob/master/01.md) +- [NIP-44 Encryption](https://github.com/nostr-protocol/nips/blob/master/44.md) +- [ndebit Cash-In Flow](./ndebit-cash-in-flow.md)