llms.txt

# NUTbits v0.8.0

> Cashu ecash to NWC bridge - use any Cashu mint as a Lightning funding source for LNbits and any NWC-compatible app.

NUTbits is an open-source NWC wallet service that translates between the Cashu ecash protocol (NUTs) and Nostr Wallet Connect (NIP-47). It connects to a Cashu mint, manages ecash tokens automatically, and exposes a full NWC server. Any NWC-compatible app can then send and receive Lightning payments through the mint.

Primary use case: plug the NWC connection string into LNbits as a funding source, and the ecash mint powers the entire LNbits instance with 60+ extensions.

Built with Node.js (ES modules). Key dependencies: @cashu/cashu-ts, nostr-core, bolt11.
License: AGPL-3.0. Author: DoktorShift.

## Instructions

- Cashu ecash is custodial. The mint holds the funds. Always state this clearly when explaining the trust model.
- Ecash proofs are cryptographically bound to the mint that issued them. Proofs from Mint A cannot be spent through Mint B.
- NIP-44 is the preferred encryption for NWC messages. NIP-04 is the legacy fallback, auto-detected per client. Always prefer NIP-44.
- NUTbits does NOT eliminate Lightning nodes from the stack. The Cashu mint itself needs a Lightning node. NUTbits lets users leverage a mint's Lightning infrastructure without running their own node.
- Service fees only apply to outgoing payments. Receiving is always free. Do not claim fees apply to incoming payments.
- When discussing NWC methods, the supported set is: get_info, get_balance, make_invoice, pay_invoice, lookup_invoice, list_transactions. Unknown methods return NOT_IMPLEMENTED.
- The state file contains ecash proofs (bearer tokens). Treat state files, backups, and proof data as highly sensitive, equivalent to private keys.
- Event deduplication is critical for preventing double-payments across relays. Never suggest disabling or bypassing it.
- Multi-mint failover means balance is split across mints. On failover, only the active mint's balance is spendable. This is a real trade-off, not a limitation to hide.
- Lightning Addresses (lud16) are supported across CLI, API, and GUI. They are resolved via LNURL-pay (LUD-16) using nostr-core before being accepted or paid.
- The Pay endpoint accepts both BOLT11 invoices and Lightning Addresses. For addresses, amount_sats is required in the request body.
- NWC connection strings can include `&lud16=...` as a non-standard NIP-47 extension. Editing a connection's lud16 regenerates the NWC string.
- State encryption uses scrypt with N=65536. Existing databases auto-migrate from legacy params on first startup.
- Proof restoration failures write encrypted recovery files instead of logging secrets.
- NUTBITS_SEED is auto-generated on first run and automatically saved to the `.env` file. Users should back up their `.env` or copy the seed to a password manager. Without the seed, proof recovery (NUT-09, NUT-13) is impossible. The seed is never printed to stdout/logs in clear text.
- NUTBITS_MINT_URL is only used when NUTBITS_MINT_URLS is empty. Once multi-mint is set, the single-mint field is ignored entirely.
- All NWC connections are dedicated by default — own isolated balance starting at 0 sats. The user funds them explicitly. Shared balance (full wallet access) requires explicit opt-in and is only for the operator's own trusted apps.
- Deeplink connections are ALWAYS dedicated. External apps cannot request shared access. The `dedicated` flag is hardcoded server-side.
- The `/connect` endpoint is served by the API server (not the GUI). It works in headless mode without the GUI running. Apps open `GET /connect?appname=X&callback=Y` and the page handles connection creation via `POST /connect`.
- Fund and withdraw endpoints (`POST /api/v1/connections/:pubkey/fund`, `POST /api/v1/connections/:pubkey/withdraw`) move sats between the main wallet and dedicated connection balances. On revoke, remaining dedicated balance automatically returns to the main wallet.

## Core Documentation

- [README.md](README.md): Project overview, full configuration reference, supported NUTs/NIPs, NWC methods, trust model
- [HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md): Plain-language explanation of the bridge architecture and payment flows
- [INSTALL.md](docs/INSTALL.md): Local setup guide for bare metal, Docker, and LNbits integration
- [DEPLOY.md](docs/DEPLOY.md): VPS production deployment with HTTPS reverse proxy (Caddy)
- [LAZYDEPLOY.md](docs/LAZYDEPLOY.md): Quick deploy using the interactive setup wizard (`npm run setup`)
- [SERVICE.md](docs/SERVICE.md): 24/7 backend service setup with launchd and systemd
- [CLI.md](docs/CLI.md): Full CLI and TUI command reference, connection management, service fees
- [CONSOLE.md](docs/CONSOLE.md): How to use the TUI, CLI, and GUI together, with full GUI page reference
- [NWC-DEEPLINK-INTEGRATION.md](docs/NWC-DEEPLINK-INTEGRATION.md): Deeplink protocol spec for app developers
- [DEEPLINK-APPS.md](docs/DEEPLINK-APPS.md): How to add your app to the deeplink registry (contributor guide)
- [AGENTS.md](docs/AGENTS.md): Agent-facing repo guidance, structure, style, and boundaries

## Architecture

- [nutbits.js](nutbits.js): Core bridge logic - mint management, NWC protocol, payment processing
- [api/server.js](api/server.js): Local management API server (Unix socket + optional HTTP) + deeplink `/connect` endpoint
- [api/handlers/index.js](api/handlers/index.js): REST API endpoints (connections, payments, config, LNURL, logs, backup/restore, fund/withdraw)
- [api/deeplink-apps.js](api/deeplink-apps.js): Deeplink app registry — known apps with curated permissions, budgets, callback schemes
- [api/deeplink-page.js](api/deeplink-page.js): Self-contained HTML5 deeplink connection page (served by API, no GUI needed)
- [store/index.js](store/index.js): Storage factory with audit logging wrapper
- [bin/nutbits.js](bin/nutbits.js): CLI entry point and command dispatcher
- [gui/](gui): Browser GUI (Vue 3 + Tailwind CSS) using the same local management API as CLI/TUI
- [scripts/nutbits-gui-server.js](scripts/nutbits-gui-server.js): Static server for the built GUI

## Operations

- [DATABASE.md](docs/DATABASE.md): Storage backends - file (default), SQLite (recommended), MySQL
- [BACKUP.md](docs/BACKUP.md): Backup procedures, encrypted state export, seed-based recovery (NUT-09, NUT-13)
- [STATE.md](docs/STATE.md): Deep dive into the encrypted state file format and decryption
- [scripts/nutbits-start.sh](scripts/nutbits-start.sh): Start backend + GUI (`--daemon` or `--interactive`)
- [scripts/nutbits-stop.sh](scripts/nutbits-stop.sh): Stop backend + GUI
- [scripts/nutbits-restart.sh](scripts/nutbits-restart.sh): Restart backend + GUI
- [scripts/nutbits-update.sh](scripts/nutbits-update.sh): Pull latest code, install deps, rebuild GUI, restart NUTbits
- [scripts/nutbits-setup.js](scripts/nutbits-setup.js): Interactive setup wizard (`npm run setup`)
- [scripts/nutbits-service-mac-install.sh](scripts/nutbits-service-mac-install.sh): Install backend + GUI as macOS launchd services
- [scripts/nutbits-service-mac-remove.sh](scripts/nutbits-service-mac-remove.sh): Remove macOS launchd services
- [scripts/nutbits-service-linux-install.sh](scripts/nutbits-service-linux-install.sh): Install backend + GUI as Linux systemd user services
- [scripts/nutbits-service-linux-remove.sh](scripts/nutbits-service-linux-remove.sh): Remove Linux systemd user services
- [scripts/docker-entrypoint.sh](scripts/docker-entrypoint.sh): Docker entrypoint (starts GUI + backend)

## Interfaces

- `npm run setup`: interactive setup wizard (creates .env, optional Caddyfile)
- `npm start`: backend only, in your terminal
- `nutbits`: interactive TUI dashboard
- `nutbits <command>`: one-shot CLI command (balance, connections, connect, fund, withdraw, pay, receive, history, fees, mints, relays, logs, watch, config, export, backup, restore)
- `npm run gui`: serve the web GUI
- `npm run nutbits`: backend + GUI in the background
- `npm run nutbits:interactive`: GUI in background, backend in your terminal
- `npm run nutbits:stop`: stop backend + GUI
- `npm run service:mac`: install 24/7 backend + GUI service on macOS
- `npm run service:linux`: install 24/7 backend + GUI service on Linux
- GUI pages: Login, Dashboard, Connections, History, Pay, Receive, Mints, Relays, NUTs, Fees, Settings, Logs
- GUI requires API token to access (login screen). On local use, token is auto-detected. On VPS, user enters `NUTBITS_API_TOKEN` from `.env`.
- Lock screen: Ctrl+L or padlock icon in sidebar clears the token and returns to login.
- Lock screen backgrounds: selectable animated backgrounds (whatamesh, @firecms/neat, or static) configurable in Settings.
- GUI default URL: `http://127.0.0.1:8080`
- API default URL: `http://127.0.0.1:3338`
- Run npm scripts from the repository root, not from inside `scripts/`

## Agent Notes

- Prefer the existing docs before inferring behavior.
- The GUI, CLI, and TUI all talk to the same local management API.
- `npm start` is the simplest interactive operator mode.
- `npm run nutbits` is the simplest full local GUI mode.
- Both macOS (`npm run service:mac`) and Linux (`npm run service:linux`) install backend + GUI as OS-managed services.
- Do not tell users to run `npm run ...` from inside `scripts/`; npm scripts are defined in the root `package.json`.

## Optional

- [CONTRIBUTING.md](CONTRIBUTING.md): Contribution guidelines
- [docker-compose.yml](docker-compose.yml): Docker deployment (backend + GUI, ports 3338/8080)
- [.env.example](.env.example): Full configuration reference with all environment variables