Cómo alojar un servidor Lightning Address en un nodo LND propio

¿Qué es una Lightning Address?¶

Una Lightning Address es un identificador con formato similar al correo electrónico (usuario@dominio.com) que permite recibir pagos en Bitcoin a través de la red Lightning sin necesidad de generar una factura manualmente. Cuando alguien envía fondos, tu servidor genera automáticamente una factura válida y la presenta al pagador. Esto es posible gracias al protocolo LNURL-pay, especificado en el LUD-06.

Requisitos previos¶

Un nodo LND funcionando (con lnd instalado y sincronizado) y con la API REST habilitada.
Liquidez entrante suficiente en el nodo (canales abiertos con capacidad para recibir).
Un dominio propio apuntando a la IP pública del servidor.
Certificado TLS válido (por ejemplo, de Let's Encrypt) para el dominio o subdominio.
Un servidor con acceso a Internet (VPS o máquina local con IP fija) donde se ejecutará el software.
Nginx instalado (para proxy inverso y TLS).
Docker o go (comandos de compilación), según el software elegido.

Paso 1: elegir un software de Lightning Address server¶

Existen múltiples implementaciones. Aquí se usa Ligess (Lightning Address Server), una opción ligera que se compila a un binario y se conecta con LND a través de su API REST.

Alternativas: - satdress (escrito en Go, muy sencillo). - LNURL-pay server (Node.js).

En este tutorial se documenta Ligess por su simplicidad.

Paso 2: compilar Ligess (o descargar binario)¶

# Clonar repositorio
git clone https://github.com/fiatjaf/ligess.git
cd ligess

# Compilar (requiere Go instalado)
go build -o ligess .

Alternativamente, descargar un binario precompilado desde la sección de releases del repositorio.

Paso 3: configurar el archivo .env o variables de entorno¶

Crea un archivo .env en el mismo directorio de ligess:

LND_REST_HOST=localhost:8080
LND_MACAROON_PATH=/ruta/a/admin.macaroon
LND_TLS_CERT_PATH=/ruta/a/tls.cert
BASE_URL=https://pago.tudominio.com
LN_ADDRESS_DOMAIN=tudominio.com
PORT=3441

LND_REST_HOST: puerto de la API REST de LND (por defecto 8080).
LND_MACAROON_PATH: ruta al archivo .macaroon con permisos para generar facturas (usar admin.macaroon).
LND_TLS_CERT_PATH: ruta al certificado TLS de LND (suele estar en ~/.lnd/tls.cert).
BASE_URL: URL pública (con https) que apuntará al servidor.
LN_ADDRESS_DOMAIN: tu dominio (sin el usuario).
PORT: puerto interno donde escuchará Ligess.

Paso 4: probar el servidor localmente¶

Ejecutar Ligess:

./ligess

Debería mostrar algo como:

Listening on :3441

Comprobar que responde correctamente:

curl http://localhost:3441/.well-known/lnurlp/usuario

Si devuelve JSON con tag: "payRequest", está funcionando.

Paso 5: configurar Nginx como proxy inverso con SSL¶

a) Crear un archivo de configuración en `/etc/nginx/sites-available/lightning-address`¶

server {
    listen 80;
    server_name pago.tudominio.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name pago.tudominio.com;

    ssl_certificate /etc/letsencrypt/live/pago.tudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pago.tudominio.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3441;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

b) Activar el sitio y recargar Nginx¶

sudo ln -s /etc/nginx/sites-available/lightning-address /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

c) Obtener certificados SSL con Let's Encrypt (si no se tienen)¶

sudo certbot --nginx -d pago.tudominio.com

Paso 6: ejecutar Ligess como servicio systemd (recomendado)¶

Crear archivo /etc/systemd/system/ligess.service:

[Unit]
Description=Lightning Address Server (Ligess)
After=network.target lnd.service

[Service]
ExecStart=/home/tuusuario/ligess/ligess
WorkingDirectory=/home/tuusuario/ligess
User=tuusuario
Restart=always
EnvironmentFile=/home/tuusuario/ligess/.env

[Install]
WantedBy=multi-user.target

Habilitar e iniciar:

sudo systemctl daemon-reload
sudo systemctl enable ligess
sudo systemctl start ligess

Paso 7: crear usuarios (direcciones lightning)¶

Una vez que el servidor está corriendo, para añadir una lightning address como yo@pago.tudominio.com se debe escribir en la base de datos del servidor. Ligess utiliza un archivo JSON simple.

Detener el servicio temporalmente y editar el archivo data.json (se generará automáticamente al ejecutar por primera vez) para añadir un usuario:

{
  "usuarios": {
    "yo": {
      "min": 1,
      "max": 10000000,
      "comment": "Donaciones generales",
      "comment_chars": 120,
      "currency": "BTC"
    }
  }
}

Reiniciar el servicio. La dirección será yo@pago.tudominio.com (dependerá del LN_ADDRESS_DOMAIN y del nombre de usuario elegido).

Paso 8: testear con una wallet Lightning¶

Abrir una wallet que soporte Lightning Address (por ejemplo, Wallet of Satoshi, Zeus, Blixt, Phoenix). Ingresar la dirección yo@pago.tudominio.com, especificar una cantidad (en satoshis o euros, la wallet convertirá) y enviar el pago. Confirmar que el servidor recibe la petición y LND genera una factura correctamente.

Posibles problemas y soluciones¶

Error missing lnurlp query: la wallet no recibió el JSON esperado. Verificar que Nginx esté reenviando correctamente y que BASE_URL coincida con la URL del proxy.
invoice creation failed: insufficient local balance: el nodo LND no tiene liquidez entrante suficiente para recibir el monto solicitado. Abrir canales con más capacidad.
Error de CORS: añadir en la configuración de Nginx la cabecera Access-Control-Allow-Origin: *.
Macaroons inválidos: asegurar que el archivo .macaroon utilizado tenga permiso para invoice:generate.

Notas finales¶

La seguridad del nodo LND es responsabilidad del operador. Nunca exponer la API REST de LND directamente a Internet sin autenticación fuerte.
Este método permite recibir pagos directamente a la cartera del nodo, sin pasar por custodios.
Existen servicios que alojan la Lightning Address por ti (como lnpay.co o getAlby), pero este tutorial cubre la opción completamente autogestionada.