clnaddress

A CLN plugin that runs an lnurl server so you can receive via lnurl (LUD-06) or ln-addresses (LUD-16) with optional Zap (NIP-57) support.

Check out payany if you want to be able to pay to an LNURL or ln-address from the CLI.

• Installation
• Building
• Options
• Methods
• Documentation

Installation

For general plugin installation instructions see the plugins repo README.md

Release binaries for

• x86_64-linux
• armv7-linux (Raspberry Pi 32bit)
• aarch64-linux (Raspberry Pi 64bit)
• universal-apple-darwin (macOS)

can be found on the release page. If you are unsure about your architecture you can run uname -m.

Building

You can build the plugin yourself instead of using the release binaries. First clone the repo:

git clone https://github.com/daywalker90/clnaddress.git

Install a recent rust version (rustup is recommended) and in the clnaddress folder run:

cargo build --release

After that the binary will be here: target/release/clnaddress

Note: Release binaries are built using cross and the optimized profile.

Options

• clnaddress-min-receivable: Minimum receivable amount in msat, defaults to 0 (any amount allowed)
• clnaddress-max-receivable: Maximum receivable amount in msat, defaults to 100000000000
• clnaddress-description: Description shown in wallets, defaults to Thank you :)
• clnaddress-listen: Listen address for the LNURL web server. Use [::] to bind to everything. Defaults to localhost:9797
• clnaddress-base-url: Base URL of you lnaddress service, e.g. https://sub.domaster.org/path/, no default and must be set
• clnaddress-nostr-privkey: Nostr private key for signing zap receipts, no default and optional, but required for zap support. It is recommended to create another key for this and not use your usual nostr key. Deprecated: on startup the key is automatically stored in a file (<lightning_dir>/clnaddress/nostr-secret-key) with chmod 600 permissions, so you can remove this option and the plugin keeps reading the key from the file.
• clnaddress-nostr-privkey-file: Path to a file containing the Nostr private key for signing zap receipts (preferred over clnaddress-nostr-privkey). Use this to avoid exposing the key in your config file and via listconfigs. Restrict permissions on the file, e.g. chmod 600. When both options are set, the file takes precedence and clnaddress-nostr-privkey is ignored.

Methods

• clnaddress-adduser user [is_email] [description]
  • adds a user for your ln-address server
  • user: username part of the lightning address
  • is_email: optional boolean if the lightning address is also an email, which would change the metadata slightly, defaults to false
  • description: optional user-specific description, defaults to the description from the clnaddress-description option
• clnaddress-deluser user
  • deletes a previously added user
  • user: username part of the lightning address
• clnaddress-listuser [user]
  • lists previously added user(s)
  • user: optional username part of the lightning address

Documentation

Reverse Proxy

For any of this to work you must configure your reverse proxy to point to the lnurl web server hosted under clnaddress-listen

With nginx:

For LNURL you can choose any location e.g. lnurl:

location /lnurl/ {
        proxy_pass http://localhost:9797/;
        add_header 'Access-Control-Allow-Origin' '*';
}

To support all ln-address users you add another location like this:

location ~* ^/\.well-known/lnurlp/([^/]+) {
        proxy_pass http://localhost:9797$request_uri;
        add_header 'Access-Control-Allow-Origin' '*';
}

Make sure to use the correct proxy_pass address, usually it's just http:// + clnaddress-listen + /

Rate limiting, request timeouts and similar DoS protection are expected to be handled by your reverse proxy (e.g. with limit_req and the various *_timeout directives in nginx).

LNURL

Your LNURL gets printed to log on plugin start, watch out for the line starting with LNURL:

LN-Addresses

clnaddress supports multiple ln-addresses at the same time and you can add or remove users with the clnaddress-adduser and clnaddress-deluser methods.

Nostr

In order for zap receipts to be send you must specify a nostr private key that will sign the receipts. It is recommended to create another key for this and not use your usual nostr key. Point clnaddress-nostr-privkey-file at a file (permissions chmod 600) containing the key so it is not exposed in the config or listconfigs. If you only set the deprecated clnaddress-nostr-privkey option, the key is automatically migrated to <lightning_dir>/clnaddress/nostr-secret-key on startup, so you can remove the option afterwards without losing zap support.