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

feat(docker): add dev.sh with auto-funding and ATM app setup

Browse source 
- Add dev.sh script for managing regtest development environment
- Implement cmd_fund to fund ATM app owner via Lightning.Pub API
- Add --fund flag to cmd_up for automatic funding on startup
- Update setup_atm_app to write VITE_APP_ID to machine .env
- Fix Electron IPC to pass appId and extensionApiUrl to renderer
- Restructure repo from nested lamassu-next/ to root

The dev.sh script now supports:
- ./dev.sh up --fund  # Start regtest and auto-fund ATM
- ./dev.sh fund       # Fund existing ATM app
- ./dev.sh status     # Show environment status
- ./dev.sh reset      # Clean restart

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan 2026-02-15 14:19:16 -05:00
commit c98f126ba7
180 changed files with 2695 additions and 9587 deletions
Download patch file Download diff file Expand all files Collapse all files

169
README.md Normal file
View file

@ -0,0 +1,169 @@
# Lamassu Next
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
- [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
## 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.
## License
MIT