lnaddrd is a simple Lightning Address server that allows users to register Lightning Addresses (e.g., user@lnaddr.org) which forward incoming payments to the user's LNURL. This makes it easy to provide your own domains to users without also being their LNURL provider.
You can see a demo at https://lnaddr.org.
- Self-hosted Lightning Address server written in Rust
- User registration for Lightning Addresses
- Configurable domains (serve multiple domains)
- Embedded SQLite database backend
- Encrypted Nostr backups recoverable from one stable root secret
- Optional LUD-21-verified registration pricing by username length
- Resettable local administration UI with reserved-name controls
- Nostr service announcements and domain verification
- Environment variable configuration
- Nix/NixOS native deployment
To enter a development shell with all dependencies:
nix developThis provides Rust, Diesel CLI, SQLite, and other tools.
The dev shell comes with a range of useful just commands. Run just to see all of them.
The SQLite database is created and migrated automatically:
cargo run -- \
--domains localhost \
--database-path lnaddrd.sqlite3 \
--root-secret-file root-secret \
--admin-password-file admin-password \
--nostr-relays wss://your-relay.example \
initialize-empty
cargo run -- \
--domains localhost \
--database-path lnaddrd.sqlite3 \
--root-secret-file root-secret \
--admin-password-file admin-password \
--nostr-relays wss://your-relay.exampleFor the full list of config options see cargo run -- --help:
Usage: lnaddrd [OPTIONS]
Options:
--domains <DOMAINS>... One or more domain names to serve. Specify multiple times for multiple domains [env: LNADDRD_DOMAINS=]
--bind <BIND> The address to bind the server to [env: LNADDRD_BIND=] [default: 127.0.0.1:8080]
--database-path <DATABASE_PATH> Path to the SQLite database [env: LNADDRD_DATABASE_PATH=] [default: lnaddrd.sqlite3]
--root-secret-file <ROOT_SECRET_FILE> Stable service root secret [env: LNADDRD_ROOT_SECRET_FILE=]
--admin-password-file <ADMIN_PASSWORD_FILE> Resettable admin password [env: LNADDRD_ADMIN_PASSWORD_FILE=]
--nostr-relays <NOSTR_RELAYS>... Nostr backup relays [env: LNADDRD_NOSTR_RELAYS=]
--public-base-url <PUBLIC_BASE_URL> Canonical HTTPS announcement origin [env: LNADDRD_PUBLIC_BASE_URL=]
--service-name <SERVICE_NAME> Public announcement name [env: LNADDRD_SERVICE_NAME=]
--warning <WARNING> Warning displayed on registration page [env: LNADDRD_WARNING=]
-h, --help Print help
You can run lnaddrd using Docker. First, build the image (or pull from your registry if available):
docker build -t lnaddrd .Or pull from GitHub Container Registry (if published):
docker pull ghcr.io/<your-username-or-org>/lnaddrd:latestThen run the container, passing the required environment variables:
docker run -p 8080:8080 \
-e LNADDRD_DOMAINS="yourdomain.com" \
-e LNADDRD_BIND="0.0.0.0:8080" \
-e LNADDRD_DATABASE_PATH="/var/lib/lnaddrd/lnaddrd.sqlite3" \
-e LNADDRD_ADMIN_PASSWORD_FILE="/var/lib/lnaddrd/admin-password" \
-e LNADDRD_NOSTR_RELAYS="wss://your-relay.example" \
-e LNADDRD_PUBLIC_BASE_URL="https://yourdomain.com" \
-v lnaddrd-data:/var/lib/lnaddrd \
ghcr.io/<your-username-or-org>/lnaddrd:latestLNADDRD_DOMAINS: Comma-separated list of domains to serve (e.g.,lnaddr.org,lnaddr.net)LNADDRD_BIND: Address to bind the server to (default:0.0.0.0:8080for Docker)LNADDRD_DATABASE_PATH: SQLite database pathLNADDRD_ROOT_SECRET_FILE: Stable root-secret file; this is the critical backup materialLNADDRD_ADMIN_PASSWORD_FILE: Resettable administrator-password fileLNADDRD_NOSTR_RELAYS: Comma-separated Nostr backup relaysLNADDRD_PUBLIC_BASE_URL: Canonical HTTPS origin; enables public service announcementsLNADDRD_SERVICE_NAME: Human-readable name in announcementsLNADDRD_WARNING: (Optional) Warning message for the registration page
Persist /var/lib/lnaddrd so the SQLite database survives container replacement.
See docker-compose.yml for an example.
lnaddrd comes with a NixOS module for easy deployment. Example configuration:
let
domains = [ "lnaddr.org" ]
in
{
services.lnaddrd = {
enable = true;
domains = domains;
databasePath = "/var/lib/lnaddrd/lnaddrd.sqlite3";
nostrRelays = [ "wss://your-relay.example" ];
};
# Example NGINX reverse proxy
services.nginx = {
enable = true;
recommendedTlsSettings = true;
virtualHosts = builtins.listToAttrs (lib.map (domain: {
name = domain;
value = {
forceSSL = true;
enableACME = true;
locations."/" = {
# Default bind address, can be changed if it collides
proxyPass = "http://127.0.0.1:8080";
};
};
}) domains)
};
networking.firewall.allowedTCPPorts = [ 80 443 ];
}LNADDRD_DOMAINS: Comma-separated list of domains to serve (e.g.,lnaddr.org,lnaddr.net)LNADDRD_BIND: Address to bind the server to (default:127.0.0.1:8080)LNADDRD_DATABASE_PATH: SQLite database path (default:lnaddrd.sqlite3)LNADDRD_ROOT_SECRET_FILE: Root-secret path (default:/var/lib/lnaddrd/root-secret)LNADDRD_ADMIN_PASSWORD_FILE: Resettable admin-password path (default:/var/lib/lnaddrd/admin-password)LNADDRD_NOSTR_RELAYS: Comma-separated backup relay URLsLNADDRD_PUBLIC_BASE_URL: Canonical public HTTPS originLNADDRD_SERVICE_NAME: Public service name (default:lnaddrd)LNADDRD_WARNING: Optional warning message for the registration page
lnaddrd uses SQLite. The database file and migrations are created automatically.
On an uninitialized database the HTTP server exposes only /health/live and
the authenticated setup pages below /admin; Lightning Address and public
registration routes remain unavailable. Log in and either generate a fresh
root seed or enter an existing seed to validate and restore its Nostr backup.
After setup succeeds, the process switches to normal service mode automatically.
The root-secret file is the only irreplaceable application state. Back it up
separately and keep it mode 0600. The admin-password file is intentionally
resettable: remove or replace it and restart to invalidate existing sessions
without changing addresses or the Nostr identity.
# Inspect remote records without changing the target database
lnaddrd --domains yourdomain.com --database-path recovered.sqlite3 \
--root-secret-file root-secret --nostr-relays wss://relay.example \
restore --dry-run
# Rebuild an uninitialized SQLite file
lnaddrd --domains yourdomain.com --database-path recovered.sqlite3 \
--root-secret-file root-secret --nostr-relays wss://relay.example restoreNormal resolution reads SQLite and remains available during a relay outage. New mutations stay non-active until at least one relay acknowledges their encrypted backup.
Open /admin, using the password stored at LNADDRD_ADMIN_PASSWORD_FILE.
If that file does not exist, lnaddrd creates it with mode 0600; the default
location is /var/lib/lnaddrd/admin-password. Set the environment variable to
use another password file. The password is the only credential required to
enter first-run setup. It is resettable and is not recovery material.
On a running service, Root seed backup requires the current administrator
password again and downloads the 64-character seed as a no-store attachment.
Keep that export offline: possession of it controls the service identity and
decrypts all backed-up address metadata.
The UI configures exact reserved names and optional max_length=price_msat
tiers. A paid recipient must be an LNURL or Lightning Address supporting
LUD-21. Saving a policy requests an unpaid test invoice and validates its
unsettled verification response.
New services visibly reserve _, admin, administrator, api, help,
info, lnurl, root, security, support, and www; every entry can be
removed in the admin UI.
Paid attempts expire after 15 minutes. Settlement is checked server-side; the browser cannot provide a receipt. If Nostr publication fails after payment, the exact signed record remains queued and no second invoice is requested.
With LNADDRD_PUBLIC_BASE_URL set, the server publishes a signed NIP-78
announcement and serves /.well-known/lnaddrd.json. Discover candidates from
an explicitly selected relay set with:
lnaddrd --nostr-relays wss://relay.example discover
lnaddrd --nostr-relays wss://relay.example discover --jsonDiscovery is not federation or failover. The command verifies current domain control, but operators still require an independent trust policy.
Alongside the HTML registration UI, lnaddrd exposes a JSON API under
/api/v1 (plus legacy management routes under /lnaddress), fully specified
in the registration API microstandard:
GET /api/v1/register/quote— price a domain/username without reserving it.POST /api/v1/register— register a free name immediately.POST /api/v1/register/start— start a paid registration and receive a BOLT11 invoice.GET /api/v1/register/:id— poll a paid registration attempt's status.GET /api/v1/addresses— list addresses owned by a NIP-98-authenticated pubkey.PUT /lnaddress/update/DELETE /lnaddress/remove— legacy management, by bearer token or NIP-98.POST /lnaddress/register— legacy token-only free registration.
Several /api/v1 endpoints accept a NIP-98 Authorization header to bind a
registration to a Nostr public key or to prove address ownership; support is
advertised via the registration-api-v1 and nostr-auth announcement
capabilities. NIP-98 handling differs per endpoint (optional, required, or
unused) — see doc 03 for the exact rules.
The NIP-98 replay guard and the per-IP rate limits are both in-memory and per-process: a multi-replica deployment behind a load balancer does not share either state across replicas, so a client can bypass a rate limit or replay an event by landing on a different replica.
marketplace/ is a static, single-page client that discovers operators over
Nostr and lets a Nostr identity register and manage a Lightning Address
without visiting any one operator's site first. It has no build step and no
backend of its own: it talks directly to relays (for discovery) and to
whichever operator's HTTP API hosts the address (for
registration and management).
The app is Nostr-identity-only: a NIP-07 browser extension is required both to register an address and to manage one afterward, and every registration and management request it sends is NIP-98-signed with that identity. The app never displays or asks for a Lightning Address management token — there is no token-fallback form. An operator's own hosted HTML registration flow is a separate thing this app does not touch; it still issues tokens there for wallet-less users who register directly with that operator instead of through the marketplace.
The canonical deployment lives at https://mkt.lnaddr.org, published by the
marketplace.yml GitHub Actions workflow: every push to master that touches
marketplace/ runs the JS tests and deploys the directory as-is to GitHub
Pages. But it is not special — host it on any static file server: GitHub
Pages, a CDN, python3 -m http.server, or anything else that serves plain
files over HTTPS. For local development:
just marketplace-serve # http://localhost:8081The discovery relay set is entirely client-side: append ?relays= with a
comma-separated list of wss:// relay URLs to override the built-in
defaults, e.g. ?relays=wss://relay.damus.io,wss://nos.lol. There is no
server-side configuration for the marketplace at all.
The page is stateless by design: all of its state (selected relays, which
tab is active) lives in the URL or in memory, and it persists nothing to
localStorage, sessionStorage, or cookies. A NIP-07 browser extension
supplies the user's Nostr key on demand (to connect an identity and to sign
NIP-98 requests); the key material itself never leaves the extension. See the
service announcement and
registration API microstandards for
the discovery and API contracts the marketplace implements against.
Each domain row's "users" figure comes from one of two sources, in order of
preference. If the operator's announcement self-reports a per-domain active
address count (the users field described in the
service announcement
microstandard), the marketplace shows that number as-is, badged "Self-reported
by the operator" — it's an operator claim, not independently verified. If the
operator didn't announce a usable count for a domain, and it didn't announce
one for any of its other domains either, the marketplace falls back to
scanning: a per-operator count of that operator's encrypted
backup records on the discovery
relays — one record per registered address, regardless of which of the
operator's domains it belongs to. It's a public-Nostr-data proxy for "how many
addresses has this operator registered," not a live database query: it may
include addresses that were later deleted (a backup record isn't necessarily
removed on deletion) and, if the source relays hold more matching records than
a single query returns, the app shows "N+" rather than an exact figure. An
operator that self-reports a count for at least one domain is never scanned at
all; any of its other domains lacking their own announced entry simply show no
figure, rather than a stale scan-derived one.
Build the one-time importer with --features postgres-import. Stop the old
service, initialize the new SQLite service, run a dry run, then import:
cargo run --features postgres-import -- \
--domains yourdomain.com --database-path lnaddrd.sqlite3 \
--root-secret-file root-secret --nostr-relays wss://relay.example \
import-postgres --database-url "$LNADDRD_DATABASE_URL" --dry-runLegacy installations with invalid empty usernames or case-colliding names may
opt in to --skip-empty-usernames and --prefer-newest-duplicates. The latter
selects the greatest updated_at (then created_at) and reports every skipped
or superseded row in the signed import report.
--canonicalize-usernames explicitly lowercases, trims, and replaces runs of
legacy username whitespace with -; every changed username is also counted in
the report. The same normalization is applied only to backing Lightning Address
destinations that otherwise fail validation, and those changes are counted
separately; encoded LNURLs are never rewritten.
The importer reads but never mutates PostgreSQL, validates every row before writing, hashes legacy management tokens with Argon2id, waits for relay acknowledgement, and prints a signed redacted report. Keep PostgreSQL untouched until the imported service has been checked; reruns skip already staged names.
The Nostr-recoverable SQLite architecture, optional LUD-21 payment gate, administration model, and service-discovery protocol are documented in the design specification, with an incremental implementation plan. The companion protocol documents define encrypted backup records and public service announcements.
MIT

