docs: update README for dev.sh workflow and LNURL-withdraw
- Replace old devenv commands with dev.sh usage - Document LNURL-withdraw as alternative cash-in method - Update architecture to reflect Electron + Vue (not Tauri) - Add HAL package to architecture overview - Update infrastructure services table with regtest nodes - Add troubleshooting for common dev.sh issues Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan
parent
c98f126ba7
commit
bf8f9c3a22
1 changed files with 74 additions and 72 deletions
146
README.md
146
README.md
|
|
@ -9,6 +9,7 @@ A Nostr-native Lightning ATM system. KYC-free, open source, auditable.
|
||||||
- [Nix](https://nixos.org/download.html) with flakes enabled
|
- [Nix](https://nixos.org/download.html) with flakes enabled
|
||||||
- [devenv](https://devenv.sh/getting-started/)
|
- [devenv](https://devenv.sh/getting-started/)
|
||||||
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
|
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
|
||||||
|
- [Lightning.Pub](https://github.com/shocknet/Lightning.Pub) cloned to `~/dev/shocknet/Lightning.Pub`
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
|
|
@ -23,133 +24,134 @@ devenv shell
|
||||||
# 3. Install dependencies
|
# 3. Install dependencies
|
||||||
pnpm install
|
pnpm install
|
||||||
|
|
||||||
# 4. Start infrastructure (bitcoind, LND, Lightning.Pub, strfry relay)
|
# 4. Start regtest infrastructure with auto-funding
|
||||||
infra-up
|
./docker/dev.sh up --fund
|
||||||
|
|
||||||
# 5. Fund the regtest wallet and set up Lightning channel
|
# 5. Check status
|
||||||
mine-blocks 101
|
./docker/dev.sh status
|
||||||
setup-channel
|
|
||||||
|
|
||||||
# 6. Validate everything is working
|
|
||||||
test-setup
|
|
||||||
```
|
```
|
||||||
|
|
||||||
If `test-setup` shows all green, you're ready to develop!
|
If status shows all services running and ATM funded, you're ready to develop!
|
||||||
|
|
||||||
## Development Commands
|
## Development Commands
|
||||||
|
|
||||||
### Core
|
### dev.sh (Regtest Environment)
|
||||||
|
|
||||||
| Command | Description |
|
```bash
|
||||||
| ------- | ------------------------- |
|
./docker/dev.sh <command> [options]
|
||||||
| `dev` | Start development servers |
|
```
|
||||||
| `build` | Build all packages |
|
|
||||||
| `test` | Run unit tests |
|
|
||||||
|
|
||||||
### Infrastructure
|
| Command | Description |
|
||||||
|
| ------------- | ---------------------------------------------- |
|
||||||
|
| `up` | Start regtest + Lightning.Pub + relay |
|
||||||
|
| `up --fund` | Start and auto-fund ATM with 100k sats |
|
||||||
|
| `down` | Stop all services |
|
||||||
|
| `status` | Show service status and ATM balance |
|
||||||
|
| `fund [sats]` | Fund ATM app owner (default: 100000) |
|
||||||
|
| `logs` | Follow service logs |
|
||||||
|
| `reset` | Stop services and clear all state |
|
||||||
|
|
||||||
| Command | Description |
|
### pnpm Scripts
|
||||||
| -------------- | ------------------------- |
|
|
||||||
| `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 |
|
||||||
|
| -------------- | -------------------------- |
|
||||||
|
| `pnpm dev` | Start machine app (Vite + Electron) |
|
||||||
|
| `pnpm build` | Build all packages |
|
||||||
|
| `pnpm test` | Run unit tests |
|
||||||
|
|
||||||
| Command | Description |
|
### Machine App
|
||||||
| --------------------- | ---------------------------------- |
|
|
||||||
| `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)
|
```bash
|
||||||
|
cd apps/machine
|
||||||
| Command | Description |
|
pnpm dev # Start Electron app with hot reload
|
||||||
| ---------------------- | -------------------------------- |
|
```
|
||||||
| `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
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
lamassu-next/
|
lamassu-next/
|
||||||
├── apps/
|
├── apps/
|
||||||
│ ├── machine/ # Tauri + Vue 3 ATM kiosk (planned)
|
│ └── machine/ # Electron + Vue 3 ATM kiosk
|
||||||
│ └── dashboard/ # Operator dashboard (planned)
|
|
||||||
├── packages/
|
├── packages/
|
||||||
│ ├── nostr-client/ # Nostr client (NIP-01, NIP-42, NIP-44)
|
│ ├── nostr-client/ # Nostr client (NIP-01, NIP-42, NIP-44)
|
||||||
│ ├── clink/ # CLINK protocol (kinds 21001-21003)
|
│ ├── clink/ # CLINK protocol (ndebit, noffer)
|
||||||
│ ├── lightning/ # Lightning.Pub RPC client
|
│ ├── lightning/ # Lightning.Pub RPC client
|
||||||
|
│ ├── hal/ # Hardware Abstraction Layer (bill validators, dispensers)
|
||||||
│ ├── state-machine/ # XState v5 ATM state machine
|
│ ├── state-machine/ # XState v5 ATM state machine
|
||||||
│ ├── cashu/ # Cashu ecash (placeholder)
|
│ ├── cashu/ # Cashu ecash (placeholder)
|
||||||
│ └── ui-shared/ # Shared Vue components (placeholder)
|
│ └── ui-shared/ # Shared Vue components (placeholder)
|
||||||
└── docker/ # Development infrastructure
|
└── docker/ # Development infrastructure (dev.sh, regtest)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Infrastructure Services
|
## Infrastructure Services
|
||||||
|
|
||||||
| Service | Container | Port | Description |
|
| Service | Port | Description |
|
||||||
| ------------- | --------------------- | ----- | --------------------- |
|
| ----------------- | ----- | ------------------------------------ |
|
||||||
| strfry | lamassu-relay | 7777 | Nostr relay |
|
| strfry | 7777 | Nostr relay (ws://localhost:7777) |
|
||||||
| bitcoind | lamassu-bitcoind | 18443 | Bitcoin (regtest) |
|
| bitcoind | 18443 | Bitcoin regtest node |
|
||||||
| LND | lamassu-lnd | 10009 | Lightning.Pub's node |
|
| lnd-1 | 10001 | Lightning.Pub's LND node |
|
||||||
| LND Alice | lamassu-lnd-alice | 10010 | Test payment source |
|
| lnd-2 | 10002 | Peer node for channel |
|
||||||
| Lightning.Pub | lamassu-lightning-pub | 1776 | Nostr-native accounts |
|
| lnd-3 | 10003 | Funding source (auto-miner rewards) |
|
||||||
| PostgreSQL | lamassu-postgres | 5432 | Database |
|
| Lightning.Pub | 1776 | Nostr-native accounts API |
|
||||||
|
| Withdraw Extension| 1777 | LNURL-withdraw for cash-in |
|
||||||
|
| PostgreSQL | 5432 | Lightning.Pub database |
|
||||||
|
|
||||||
## Testing E2E Payment Flow
|
## Testing Cash-In Flow
|
||||||
|
|
||||||
After running `test-setup`, you can test the full cash-in flow:
|
After starting the environment with `./docker/dev.sh up --fund`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Create an invoice on Alice (simulating customer wallet)
|
# Start the ATM app
|
||||||
alice-invoice 1000
|
cd apps/machine
|
||||||
|
pnpm dev
|
||||||
# Copy the invoice and test payment via Lightning.Pub
|
|
||||||
test-payment 1000
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Troubleshooting
|
1. Click "Cash In" on the ATM idle screen
|
||||||
|
2. Insert simulated bills (dev mode)
|
||||||
|
3. Click "Done Inserting"
|
||||||
|
4. Choose payment method:
|
||||||
|
- **CLINK** - Scan with Shock Wallet (ndebit protocol)
|
||||||
|
- **LNURL** - Scan with any Lightning wallet (Phoenix, Zeus, etc.)
|
||||||
|
5. Claim the withdrawal in your wallet
|
||||||
|
|
||||||
If payments hang or fail, see `packages/lightning/TROUBLESHOOTING.md` for common issues and solutions.
|
## Troubleshooting
|
||||||
|
|
||||||
### Common Issues
|
### Common Issues
|
||||||
|
|
||||||
**Services won't start:**
|
**Services won't start:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
infra-down
|
./docker/dev.sh reset
|
||||||
docker system prune -f
|
./docker/dev.sh up --fund
|
||||||
infra-up
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Channel not active:**
|
**ATM not funded / "not enough balance":**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mine-blocks 6 # Confirm pending channels
|
./docker/dev.sh fund 100000
|
||||||
node-info # Check channel status
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**LND not synced:**
|
**Port already in use:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
lncli getinfo # Check synced_to_chain
|
./docker/dev.sh down
|
||||||
mine-blocks 1 # Trigger sync
|
# Kill any orphan processes on ports 1776, 1777, 7777
|
||||||
|
./docker/dev.sh up
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**LNURL-withdraw fails:**
|
||||||
|
|
||||||
|
- Ensure withdraw extension is running (`./docker/dev.sh status`)
|
||||||
|
- Check ATM app has valid `VITE_APP_ID` in `apps/machine/.env`
|
||||||
|
- Verify app owner is funded (not just app_user balance)
|
||||||
|
|
||||||
## Key Concepts
|
## Key Concepts
|
||||||
|
|
||||||
- **CLINK**: Protocol for Lightning payments over Nostr (kinds 21001-21003)
|
- **CLINK**: Protocol for Lightning payments over Nostr (ndebit, noffer)
|
||||||
|
- **ndebit**: Customer-initiated debit authorization (cash-in primary method)
|
||||||
|
- **LNURL-withdraw**: Standard Lightning withdrawal link (cash-in alternative)
|
||||||
- **Lightning.Pub**: Nostr-native account system wrapping LND
|
- **Lightning.Pub**: Nostr-native account system wrapping LND
|
||||||
- **NIP-44**: Encryption standard for private Nostr messages
|
- **NIP-44**: Encryption standard for private Nostr messages
|
||||||
- **Kind 21000**: Lightning.Pub RPC events
|
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue