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:

Open Wallet Connections in Bitcoin Apps.
Enable feature.
Complete existing port/domain/DDNS/rebuild flow (80/TCP and 443/TCP).
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.

2.0 KiB Raw Blame History