Setup

LNS runs as a single Go binary in a 32 MB Docker image. It requires network access to a Lethean main chain daemon (for alias discovery) and an HSD sidechain node (for DNS record resolution).

Docker (Recommended)

docker compose up -d

Or pull the pre-built image:

docker run -d \
  --name lthn-lns \
  --network host \
  -e LNS_MODE=light \
  -e DAEMON_URL=http://127.0.0.1:46941 \
  -e HSD_URL=http://127.0.0.1:14037 \
  -e HSD_API_KEY=testkey \
  -e DNS_PORT=5354 \
  -e HTTP_PORT=5553 \
  lthn/lns:testnet

Native Build

GOWORK=off go build -o lns ./cmd/lns
DAEMON_URL=http://127.0.0.1:46941 HSD_URL=http://127.0.0.1:14037 ./lns

Environment Variables

Variable	Default	Description
`LNS_MODE`	`light`	Operating mode (light queries remote HSD RPC)
`DAEMON_URL`	`http://127.0.0.1:46941`	Main chain daemon RPC URL (alias discovery)
`HSD_URL`	`http://127.0.0.1:14037`	HSD sidechain RPC URL (name resolution)
`HSD_API_KEY`	`testkey`	API key for HSD authentication
`DNS_PORT`	`5354`	DNS server port (UDP + TCP)
`HTTP_PORT`	`5553`	HTTP API port
`CHECK_INTERVAL`	`15`	Seconds between tree root checks

Ports

Port	Protocol	Service
5354	UDP + TCP	DNS server (authoritative for `lthn.` zone)
5553	TCP	HTTP API (JSON)

Dependencies

LNS depends on two backend services:

Lethean main chain daemon (letheand) -- provides alias data via get_all_alias_details JSON-RPC. Default port: 46941 (testnet).
HSD sidechain node -- provides DNS records via getnameresource JSON-RPC. Default port: 14037.

Both must be running and accessible before LNS starts. If the main chain is unreachable, LNS falls back to a hardcoded list of known names.

Docker Compose

The repository includes a docker-compose.yml for local development:

services:
  lns:
    build: .
    container_name: lthn-lns
    network_mode: host
    environment:
      LNS_MODE: light
      DAEMON_URL: http://127.0.0.1:46941
      HSD_URL: http://127.0.0.1:14037
      HSD_API_KEY: testkey
      DNS_PORT: "53"
      HTTP_PORT: "5553"
    restart: unless-stopped

The compose file uses network_mode: host so LNS can bind directly to the host's network interfaces. Adjust DNS_PORT if port 53 conflicts with an existing resolver.

Verifying the Installation

# Check health
curl http://localhost:5553/health

# Query a name via DNS
dig @localhost -p 5354 charon.lthn A

# Query a name via HTTP
curl http://localhost:5553/resolve?name=charon

A healthy response looks like:

{"mode":"light","names":14,"status":"ok","tree_root":"abc123..."}

If status is "degraded" (HTTP 503), the cache is empty or the tree root has not been fetched yet. Check that the daemon and HSD are reachable.