Lethean Name Server

(LNS)

LNS resolves .lthn domain names to network addresses. It reads alias data from the Lethean main chain, resolves DNS records from the HSD sidechain, and serves them over both DNS (UDP/TCP) and an HTTP API.

Quick Links

Setup — Docker deployment
DNS Guide — Query .lthn names
API — HTTP endpoints
Architecture — How LNS works
Using Aliases — Register and manage .lthn names
Alias RPC Reference — Daemon and wallet RPC methods for aliases

What It Does

Discovers registered aliases from the main chain daemon via get_all_alias_details RPC
Resolves each alias to DNS records (A, AAAA, TXT, NS) from the HSD sidechain via getnameresource RPC
Caches resolved records in memory, re-syncing every 15 seconds when the tree root changes
Serves DNS on port 5354 (UDP + TCP) -- query .lthn names with standard DNS tools
Serves HTTP on port 5553 -- JSON API for name resolution, listing, and health checks

Data Flow

Main chain (aliases) --> Discovery --> HSD sidechain (records) --> Cache --> DNS + HTTP

LNS queries the main chain for all registered aliases
Each alias maps to an HNS name on the sidechain (alias comment hns=X.lthn overrides the name)
LNS resolves each HNS name to DNS records via the sidechain RPC
Records are cached and served over DNS and HTTP until the tree root changes

Key Properties

32 MB Docker image -- Alpine-based, statically compiled Go binary
No chain sync required -- light mode queries remote RPC endpoints
Sidechain is the sole source of truth -- LNS never invents records
Fallback list -- if the main chain is unreachable, a hardcoded list of known names is used
Dual protocol -- DNS (RFC-compliant, authoritative for lthn. zone) and HTTP (JSON API)

Quick Links

Setup -- Docker deployment, environment variables, ports
DNS Guide -- Querying .lthn names, supported record types, resolver configuration
API -- HTTP endpoints for name resolution and health
Architecture -- Modes, discovery, caching, and the hash-derived cache system