# 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.

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.
- 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.