Sovran_SystemsOS/docs/wallet-connections.md

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.