removed docs/ai added not necessary
This commit is contained in:
@@ -1,178 +0,0 @@
|
|||||||
# Wallet Connections
|
|
||||||
|
|
||||||
Wallet Connections is a Hub-managed Sovran_SystemsOS feature that lets members create isolated Lightning app connections and reusable Lightning Addresses backed by a local LND node via Alby Hub.
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
Wallet management 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) shown with prominent warning:
|
|
||||||
**Keep the NWC string and QR private. The NWC connection secret cannot be displayed again.**
|
|
||||||
4. **Wallet list state**: per-wallet actions for verify/test, drain, and delete.
|
|
||||||
|
|
||||||
Pairing URI and QR data are cleared when:
|
|
||||||
- "I Saved This Secret" is clicked
|
|
||||||
- the service modal X is closed
|
|
||||||
- the overlay closes the modal
|
|
||||||
- navigation otherwise leaves the secret view
|
|
||||||
|
|
||||||
Guardrails:
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
Authenticated Hub management API
|
|
||||||
-> local Alby Hub (port 18080, loopback only)
|
|
||||||
-> local LND
|
|
||||||
|
|
||||||
Public Lightning Address
|
|
||||||
-> local Caddy on 80/443
|
|
||||||
-> loopback nwc-lnurl service (port 8181)
|
|
||||||
-> local Alby Hub invoice API with isolated appId
|
|
||||||
-> local LND
|
|
||||||
```
|
|
||||||
|
|
||||||
Security invariants:
|
|
||||||
|
|
||||||
- Alby Hub management port (18080) is never opened to the public firewall.
|
|
||||||
- Dedicated LNURL service port (8181) is never opened to the public firewall.
|
|
||||||
- LNURL callback and 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 and are never stored.
|
|
||||||
- Pairing secret QR data is generated only for create responses and is not rehydrated via wallet list APIs.
|
|
||||||
- Invoice attribution enforces wallet isolation via numeric appId on every LNURL callback.
|
|
||||||
- Wallet Connections state (Alby Hub database) is never exposed as a plain JSON file.
|
|
||||||
|
|
||||||
## Domain and runtime files
|
|
||||||
|
|
||||||
- Domain key: `lightning`
|
|
||||||
- Runtime domain file: `/var/lib/domains/lightning`
|
|
||||||
- Alby Hub state: `/var/lib/albyhub/` (restrictive permissions, secret-bearing)
|
|
||||||
- Alby Hub database: `/var/lib/albyhub/nwc.db`
|
|
||||||
- Alby Hub unlock password: `/var/lib/albyhub/unlock-password` (generated once, mode 0600)
|
|
||||||
- LND macaroon for Alby Hub: `/run/lnd/albyhub.macaroon` (restricted permissions)
|
|
||||||
|
|
||||||
## Alby Hub package and patches
|
|
||||||
|
|
||||||
Wallet Connections uses `pkgs.albyhub` from the repository's pinned `nixpkgs` input and applies three conventional patches via `overrideAttrs`:
|
|
||||||
|
|
||||||
1. **Private route hints** (`packages/albyhub/0001-private-route-hints.patch`): changes regular LND invoice creation from `Private: !hasPublicChannels` to `Private: true` and leaves hold-invoice logic unchanged.
|
|
||||||
2. **Invoice app attribution** (`packages/albyhub/0002-isolated-invoice-app-id.patch`): updates `api/models.go`, `api/transactions.go`, `http/http_service.go`, and `wails/wails_handlers.go` so invoice creation accepts and forwards optional `appId`.
|
|
||||||
3. **Loopback bind host** (`packages/albyhub/0003-loopback-bind-host.patch`): adds `HOST` to config and binds Echo to `HOST:PORT` instead of `:PORT`.
|
|
||||||
|
|
||||||
No placeholder source/vendor hashes are used in the Wallet Connections module.
|
|
||||||
|
|
||||||
## Services
|
|
||||||
|
|
||||||
| Service | User | Description |
|
|
||||||
|---|---|---|
|
|
||||||
| `albyhub.service` | `albyhub` | Headless Alby Hub NWC wallet server |
|
|
||||||
| `nwc-lnurl.service` | `albyhub` | Dedicated LNURL discovery and callback service |
|
|
||||||
| `albyhub-init.service` | `root` (oneshot) | Generates `unlock-password` once on first boot |
|
|
||||||
|
|
||||||
`nwc-lnurl.service` runs as `albyhub` so it can traverse `/var/lib/albyhub` (0700) and read `/var/lib/albyhub/unlock-password` (0600) without weakening permissions.
|
|
||||||
|
|
||||||
## Wallet Connections icon asset
|
|
||||||
|
|
||||||
- Hub service icon identifier: `nwc` (feature name remains **Wallet Connections**)
|
|
||||||
- Asset path in this repository: `app/icons/nwc.svg`
|
|
||||||
- Official source: `https://raw.githubusercontent.com/getAlby/nostr-wallet-connect/5fb6831739c7e6b089cd7205e11910ef542432ad/public/images/nwc-logo.svg`
|
|
||||||
- Upstream repository: `https://github.com/getAlby/nostr-wallet-connect`
|
|
||||||
- Upstream license: Apache-2.0 (`https://github.com/getAlby/nostr-wallet-connect/blob/5fb6831739c7e6b089cd7205e11910ef542432ad/LICENSE`)
|
|
||||||
- Attribution/redistribution note: Apache-2.0 permits redistribution; preserve upstream license notices in distributions.
|
|
||||||
|
|
||||||
## API
|
|
||||||
|
|
||||||
Management (authenticated):
|
|
||||||
|
|
||||||
- `GET /api/nwc/wallets` — list all managed wallets (no secrets)
|
|
||||||
- `POST /api/nwc/wallets` — create a wallet; returns `pairing_uri` exactly once
|
|
||||||
- `DELETE /api/nwc/wallets/{id-or-pubkey}` — drain and delete
|
|
||||||
- `POST /api/nwc/wallets/{id-or-pubkey}/drain` — transfer funds to primary wallet
|
|
||||||
- `POST /api/nwc/addresses/{alias}/test` — verify public LNURL endpoint
|
|
||||||
|
|
||||||
Exact Hub setup/auth flow used by the manager:
|
|
||||||
|
|
||||||
- `GET /api/info`
|
|
||||||
- If `setupCompleted == false`: `POST /api/setup` with `backendType`, `unlockPassword`, `lndAddress`, `lndCertFile`, `lndMacaroonFile`
|
|
||||||
- `GET /api/info` again
|
|
||||||
- If `running == false`: `POST /api/start` with `unlockPassword`
|
|
||||||
- If `running == true`: `POST /api/unlock` with `unlockPassword` and `permission: "full"`
|
|
||||||
- Poll authenticated `GET /api/node/status` until `isReady == true`
|
|
||||||
- Cached bearer token is refreshed once on 401/403
|
|
||||||
|
|
||||||
Exact app/transaction usage:
|
|
||||||
|
|
||||||
- `GET /api/apps?limit=<N>&offset=<N>&order_by=created_at` (full pagination using `totalCount`)
|
|
||||||
- `GET /api/v2/apps/{id}` for app-by-id fetches
|
|
||||||
- `GET /api/transactions?appId={id}&limit=<N>&offset=<N>` (full pagination using `totalCount`)
|
|
||||||
- Wallet metadata uses `appPubkey` and `balanceMsat` (`balance_sats = balanceMsat / 1000`, `dust_msat = balanceMsat % 1000`)
|
|
||||||
- Limited-wallet initial funding uses `POST /api/transfers` with `toAppId`, `amountSat`, `description`
|
|
||||||
- Drain uses `PATCH /api/apps/{appPubkey}`, transfer with `fromAppId` + `amountMsat`, and enforces final dust equality
|
|
||||||
- Delete uses `DELETE /api/apps/{appPubkey}` after pending/drain checks
|
|
||||||
|
|
||||||
Public LNURL (served by dedicated `nwc-lnurl` service via Caddy):
|
|
||||||
|
|
||||||
- `GET /.well-known/lnurlp/{alias}` — LNURL-pay discovery
|
|
||||||
- `GET /lnurlp/{alias}/callback?amount=<msat>` — invoice creation via Alby Hub
|
|
||||||
|
|
||||||
## Recovery CLI
|
|
||||||
|
|
||||||
`nwc-wallet` is included with the Hub package and calls the real Alby Hub manager:
|
|
||||||
|
|
||||||
- `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`
|
|
||||||
|
|
||||||
A CLI `create` command prints the real NWC pairing secret once. Keep it private.
|
|
||||||
|
|
||||||
## Backup and restore
|
|
||||||
|
|
||||||
`/var/lib/albyhub` is the authoritative Alby Hub state directory. It contains:
|
|
||||||
- The SQLite database (`nwc.db`) with all wallet app records.
|
|
||||||
- The unlock password (`unlock-password`).
|
|
||||||
|
|
||||||
This directory **must be treated as secret-bearing wallet material**. Backups containing it must be encrypted and access-controlled.
|
|
||||||
|
|
||||||
To back up while the service is running, use SQLite online backup (`VACUUM INTO`) or a controlled brief service stop rather than a live `cp`. A brief stop of `albyhub.service` before copying `nwc.db` is the safest approach.
|
|
||||||
|
|
||||||
Disabling Wallet Connections stops `albyhub.service` and `nwc-lnurl.service` and removes the Caddy exposure, while preserving `/var/lib/albyhub`. Re-enabling and rebuilding restores all existing connections — no secrets need to be regenerated.
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
**Alby Hub service not starting:**
|
|
||||||
- Check `journalctl -u albyhub.service` for errors.
|
|
||||||
- Verify `/var/lib/albyhub/unlock-password` exists and is readable by `albyhub`.
|
|
||||||
- Verify `/run/lnd/albyhub.macaroon` exists (LND must be running and the macaroon generated).
|
|
||||||
|
|
||||||
**LNURL discovery returning 503:**
|
|
||||||
- Check that `albyhub.service` is running.
|
|
||||||
- Check that `/var/lib/domains/lightning` contains the correct domain.
|
|
||||||
- Check `journalctl -u nwc-lnurl.service`.
|
|
||||||
|
|
||||||
**Invoice creation failing:**
|
|
||||||
- Verify LND has sufficient inbound liquidity on channels with route hints.
|
|
||||||
- Check `journalctl -u albyhub.service` for LND RPC errors.
|
|
||||||
|
|
||||||
**Wallet creation partial failure (funding not transferred):**
|
|
||||||
- The wallet was created and the NWC connection secret was shown. Save it.
|
|
||||||
- Do not create another wallet for the same alias.
|
|
||||||
- Fund the isolated wallet manually via Alby Hub's internal transfer API.
|
|
||||||
Reference in New Issue
Block a user