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

docs: update README for dev.sh workflow and LNURL-withdraw

Browse source 
- 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 2026-02-15 14:23:39 -05:00
commit bf8f9c3a22
1 changed files with 74 additions and 72 deletions
Download patch file Download diff file Expand all files Collapse all files

144
README.md
View file

@ -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)
```bash
./docker/dev.sh <command> [options]
```
| Command | Description |
| ------- | ------------------------- |
| `dev` | Start development servers |
| `build` | Build all packages |
| `test` | Run unit tests |
| ------------- | ---------------------------------------------- |
| `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 |
### Infrastructure
### pnpm Scripts
| 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 dev` | Start machine app (Vite + Electron) |
| `pnpm build` | Build all packages |
| `pnpm test` | Run unit tests |
### Bitcoin/Lightning
### Machine App
| 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 |
```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