80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
# Wallet Connections
|
|
|
|
Wallet Connections is a Hub-managed Sovran_SystemsOS feature that lets members create isolated Lightning app connections and reusable Lightning Addresses.
|
|
|
|
## Enablement flow
|
|
|
|
Use the existing Hub service tile flow:
|
|
|
|
1. Open **Wallet Connections** in Bitcoin Apps.
|
|
2. Enable feature.
|
|
3. Complete existing port/domain/DDNS/rebuild flow (80/TCP and 443/TCP).
|
|
4. Reopen tile and manage connections.
|
|
|
|
## Service-detail modal UX (implemented)
|
|
|
|
Wallet management now runs inside the existing **Wallet Connections** service-detail modal with dedicated states:
|
|
|
|
1. **Empty state**: no wallets yet, with create action.
|
|
2. **Create form**: name, alias, access preset, optional spend limit.
|
|
3. **Created/secret state**: one-time pairing secret (URI + QR when available) shown with explicit "save now" warning.
|
|
4. **Wallet list state**: per-wallet actions for verify/test, drain, and delete.
|
|
|
|
Guardrails in modal flow:
|
|
|
|
- Action buttons are disabled while API requests are in flight.
|
|
- Destructive actions (drain/delete) require user confirmation.
|
|
- API errors are surfaced inline in the modal state.
|
|
|
|
Node role behavior is unchanged: Node onboarding still skips global domain/port setup, and the `lightning` domain is configured on demand through feature enablement.
|
|
|
|
## Architecture
|
|
|
|
Public path:
|
|
|
|
`Internet -> DNS/DDNS -> router 80/443 -> Caddy -> LNURL endpoints -> Hub NWC backend -> local LND stack`
|
|
|
|
Security invariants:
|
|
|
|
- Alby/NWC management remains local to the host.
|
|
- LNURL callback/discovery are exposed only through Caddy on 80/443.
|
|
- Management APIs are authenticated and remain under `/api/nwc/`.
|
|
- Pairing secrets are returned only on create responses.
|
|
- Pairing secret QR data is generated only for create responses and is not rehydrated via wallet list APIs.
|
|
- Invoice attribution enforces wallet isolation with app-id checks.
|
|
|
|
## Domain and runtime files
|
|
|
|
- Domain key: `lightning`
|
|
- Runtime domain file: `/var/lib/domains/lightning`
|
|
- Wallet state: `/var/lib/nwc-wallets/state.json`
|
|
|
|
## API
|
|
|
|
- `GET /api/nwc/wallets`
|
|
- `POST /api/nwc/wallets`
|
|
- `DELETE /api/nwc/wallets/{id-or-pubkey}`
|
|
- `POST /api/nwc/wallets/{id-or-pubkey}/drain`
|
|
- `POST /api/nwc/addresses/{alias}/test`
|
|
|
|
Public LNURL:
|
|
|
|
- `GET /.well-known/lnurlp/{alias}`
|
|
- `GET /lnurlp/{alias}/callback?amount=<msat>`
|
|
|
|
## Recovery CLI
|
|
|
|
`nwc-wallet` is included with Hub package:
|
|
|
|
- `nwc-wallet create <name> <alias> --receive-only`
|
|
- `nwc-wallet create <name> <alias> --limit-sats <amount>`
|
|
- `nwc-wallet list`
|
|
- `nwc-wallet drain <wallet>`
|
|
- `nwc-wallet delete <wallet>`
|
|
- `nwc-wallet address show <alias>`
|
|
- `nwc-wallet health`
|
|
|
|
## Backup and restore
|
|
|
|
Wallet Connections state is stored in `/var/lib/nwc-wallets` and is included with `/var/lib` backups. Backups contain sensitive wallet-connection material and must be protected.
|