From bf8f9c3a2203f91ce28ff431277a2c879505c52d Mon Sep 17 00:00:00 2001 From: Patrick Mulligan Date: Sun, 15 Feb 2026 14:23:39 -0500 Subject: [PATCH] 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 --- README.md | 146 +++++++++++++++++++++++++++--------------------------- 1 file changed, 74 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 5132e9b..fb5db33 100644 --- a/README.md +++ b/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 - [devenv](https://devenv.sh/getting-started/) - [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 @@ -23,133 +24,134 @@ devenv shell # 3. Install dependencies pnpm install -# 4. Start infrastructure (bitcoind, LND, Lightning.Pub, strfry relay) -infra-up +# 4. Start regtest infrastructure with auto-funding +./docker/dev.sh up --fund -# 5. Fund the regtest wallet and set up Lightning channel -mine-blocks 101 -setup-channel - -# 6. Validate everything is working -test-setup +# 5. Check status +./docker/dev.sh status ``` -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 -### Core +### dev.sh (Regtest Environment) -| Command | Description | -| ------- | ------------------------- | -| `dev` | Start development servers | -| `build` | Build all packages | -| `test` | Run unit tests | +```bash +./docker/dev.sh [options] +``` -### 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 | -| -------------- | ------------------------- | -| `infra-up` | Start all Docker services | -| `infra-down` | Stop all Docker services | -| `infra-status` | Show service status | -| `infra-logs` | Follow service logs | +### pnpm Scripts -### Bitcoin/Lightning +| Command | Description | +| -------------- | -------------------------- | +| `pnpm dev` | Start machine app (Vite + Electron) | +| `pnpm build` | Build all packages | +| `pnpm test` | Run unit tests | -| 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 ` | Pay invoice from Alice's node | +### Machine App -### 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 | +```bash +cd apps/machine +pnpm dev # Start Electron app with hot reload +``` ## Architecture ``` lamassu-next/ ├── apps/ -│ ├── machine/ # Tauri + Vue 3 ATM kiosk (planned) -│ └── dashboard/ # Operator dashboard (planned) +│ └── machine/ # Electron + Vue 3 ATM kiosk ├── packages/ │ ├── 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 +│ ├── hal/ # Hardware Abstraction Layer (bill validators, dispensers) │ ├── state-machine/ # XState v5 ATM state machine │ ├── cashu/ # Cashu ecash (placeholder) │ └── ui-shared/ # Shared Vue components (placeholder) -└── docker/ # Development infrastructure +└── docker/ # Development infrastructure (dev.sh, regtest) ``` ## 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 | +| Service | Port | Description | +| ----------------- | ----- | ------------------------------------ | +| strfry | 7777 | Nostr relay (ws://localhost:7777) | +| bitcoind | 18443 | Bitcoin regtest node | +| lnd-1 | 10001 | Lightning.Pub's LND node | +| lnd-2 | 10002 | Peer node for channel | +| lnd-3 | 10003 | Funding source (auto-miner rewards) | +| 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 -# Create an invoice on Alice (simulating customer wallet) -alice-invoice 1000 - -# Copy the invoice and test payment via Lightning.Pub -test-payment 1000 +# Start the ATM app +cd apps/machine +pnpm dev ``` -## 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 **Services won't start:** ```bash -infra-down -docker system prune -f -infra-up +./docker/dev.sh reset +./docker/dev.sh up --fund ``` -**Channel not active:** +**ATM not funded / "not enough balance":** ```bash -mine-blocks 6 # Confirm pending channels -node-info # Check channel status +./docker/dev.sh fund 100000 ``` -**LND not synced:** +**Port already in use:** ```bash -lncli getinfo # Check synced_to_chain -mine-blocks 1 # Trigger sync +./docker/dev.sh down +# 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 -- **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 - **NIP-44**: Encryption standard for private Nostr messages -- **Kind 21000**: Lightning.Pub RPC events ## Documentation