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

docs: add architecture comparison with traditional lamassu-server

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan 2026-01-26 15:58:01 -05:00
commit 16f5fb3cbc
3 changed files with 351 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
lamassu-next/CLAUDE.md
View file

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

11
lamassu-next/README.md
View file

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

338
lamassu-next/docs/architecture-comparison.md Normal file
View file

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