Add README with setup instructions
Complete getting started guide for new developers: - Prerequisites (Nix, devenv, Docker) - Quick start from scratch (5 commands to working env) - All available development commands - Architecture overview - Infrastructure services reference - E2E testing instructions - Troubleshooting section Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan
parent
4bf78e25dc
commit
e7f32b92f9
1 changed files with 158 additions and 0 deletions
158
lamassu-next/README.md
Normal file
158
lamassu-next/README.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
# Lamassu Next
|
||||
|
||||
A Nostr-native Lightning ATM system. KYC-free, open source, auditable.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Nix](https://nixos.org/download.html) with flakes enabled
|
||||
- [devenv](https://devenv.sh/getting-started/)
|
||||
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone ssh://forgejo@git.atitlan.io/aiolabs/lamassu-next.git
|
||||
cd lamassu-next
|
||||
|
||||
# 2. Enter the development environment
|
||||
devenv shell
|
||||
|
||||
# 3. Install dependencies
|
||||
pnpm install
|
||||
|
||||
# 4. Start infrastructure (bitcoind, LND, Lightning.Pub, strfry relay)
|
||||
infra-up
|
||||
|
||||
# 5. Fund the regtest wallet and set up Lightning channel
|
||||
mine-blocks 101
|
||||
setup-channel
|
||||
|
||||
# 6. Validate everything is working
|
||||
test-setup
|
||||
```
|
||||
|
||||
If `test-setup` shows all green, you're ready to develop!
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Core
|
||||
|
||||
| Command | Description |
|
||||
| ------- | ------------------------- |
|
||||
| `dev` | Start development servers |
|
||||
| `build` | Build all packages |
|
||||
| `test` | Run unit tests |
|
||||
|
||||
### Infrastructure
|
||||
|
||||
| Command | Description |
|
||||
| -------------- | ------------------------- |
|
||||
| `infra-up` | Start all Docker services |
|
||||
| `infra-down` | Stop all Docker services |
|
||||
| `infra-status` | Show service status |
|
||||
| `infra-logs` | Follow service logs |
|
||||
|
||||
### Bitcoin/Lightning
|
||||
|
||||
| Command | Description |
|
||||
| --------------------- | ---------------------------------- |
|
||||
| `btccli` | Bitcoin CLI (regtest) |
|
||||
| `lncli` | LND CLI (Lightning.Pub's node) |
|
||||
| `lncli-alice` | LND CLI (Alice's node) |
|
||||
| `mine-blocks [n]` | Mine regtest blocks (default: 1) |
|
||||
| `setup-channel` | Open channel between Alice and LND |
|
||||
| `alice-pay <invoice>` | Pay invoice from Alice's node |
|
||||
|
||||
### Testing (E2E)
|
||||
|
||||
| Command | Description |
|
||||
| ---------------------- | -------------------------------- |
|
||||
| `test-setup` | Validate test environment |
|
||||
| `test-payment [sats]` | Run e2e payment test |
|
||||
| `fund-atm [sats]` | Fund ATM account (default: 100k) |
|
||||
| `alice-invoice [sats]` | Create invoice on Alice's node |
|
||||
| `node-info` | Show node pubkeys and channels |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
lamassu-next/
|
||||
├── apps/
|
||||
│ ├── machine/ # Tauri + Vue 3 ATM kiosk (planned)
|
||||
│ └── dashboard/ # Operator dashboard (planned)
|
||||
├── packages/
|
||||
│ ├── nostr-client/ # Nostr client (NIP-01, NIP-42, NIP-44)
|
||||
│ ├── clink/ # CLINK protocol (kinds 21001-21003)
|
||||
│ ├── lightning/ # Lightning.Pub RPC client
|
||||
│ ├── state-machine/ # XState v5 ATM state machine
|
||||
│ ├── cashu/ # Cashu ecash (placeholder)
|
||||
│ └── ui-shared/ # Shared Vue components (placeholder)
|
||||
└── docker/ # Development infrastructure
|
||||
```
|
||||
|
||||
## Infrastructure Services
|
||||
|
||||
| Service | Container | Port | Description |
|
||||
| ------------- | --------------------- | ----- | --------------------- |
|
||||
| strfry | lamassu-relay | 7777 | Nostr relay |
|
||||
| bitcoind | lamassu-bitcoind | 18443 | Bitcoin (regtest) |
|
||||
| LND | lamassu-lnd | 10009 | Lightning.Pub's node |
|
||||
| LND Alice | lamassu-lnd-alice | 10010 | Test payment source |
|
||||
| Lightning.Pub | lamassu-lightning-pub | 1776 | Nostr-native accounts |
|
||||
| PostgreSQL | lamassu-postgres | 5432 | Database |
|
||||
|
||||
## Testing E2E Payment Flow
|
||||
|
||||
After running `test-setup`, you can test the full cash-in flow:
|
||||
|
||||
```bash
|
||||
# Create an invoice on Alice (simulating customer wallet)
|
||||
alice-invoice 1000
|
||||
|
||||
# Copy the invoice and test payment via Lightning.Pub
|
||||
test-payment 1000
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If payments hang or fail, see `packages/lightning/TROUBLESHOOTING.md` for common issues and solutions.
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Services won't start:**
|
||||
|
||||
```bash
|
||||
infra-down
|
||||
docker system prune -f
|
||||
infra-up
|
||||
```
|
||||
|
||||
**Channel not active:**
|
||||
|
||||
```bash
|
||||
mine-blocks 6 # Confirm pending channels
|
||||
node-info # Check channel status
|
||||
```
|
||||
|
||||
**LND not synced:**
|
||||
|
||||
```bash
|
||||
lncli getinfo # Check synced_to_chain
|
||||
mine-blocks 1 # Trigger sync
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **CLINK**: Protocol for Lightning payments over Nostr (kinds 21001-21003)
|
||||
- **Lightning.Pub**: Nostr-native account system wrapping LND
|
||||
- **NIP-44**: Encryption standard for private Nostr messages
|
||||
- **Kind 21000**: Lightning.Pub RPC events
|
||||
|
||||
## Contributing
|
||||
|
||||
See `CLAUDE.md` for development guidelines and code style.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Loading…
Add table
Add a link
Reference in a new issue