CLIP is a proposed protocol and CLI tool for publishing and discovering verifiable Lightning Network node information over Nostr. It aims to enable Lightning node operators to share extended metadata about their nodes (contact information, policies, requirements, etc.) in a decentralized manner.
For the full protocol specification, see CLIP.md.
Lightning Network nodes currently have limited ways to share operational information beyond what's available in the gossip protocol. Node operators may want to:
- Share contact information (Nostr, email, other channels), which also works in case the node is offline.
- Announce operational policies (acceptance criteria, closing policies, maintenance schedules).
- Provide arbitrary information useful for the other nodes.
While it's already possible to share such information via Nostr or centralized directories, there is no standardized way to cryptographically verify that the information actually originates from the operator of a specific Lightning node. CLIP addresses this verification challenge by linking Lightning node signatures with Nostr identities.
# Clone the repository
git clone https://github.com/feelancer21/clip.git
cd clip
# Install the CLI tool
make installclip-cli requires a Nostr private key (nsec) to sign events. You can either:
-
Generate a new key:
clip-cli generatekey
This creates a new key and saves it to
~/.config/clip/key -
Use an existing key: If you already have a Nostr key, save it to the key file:
echo "nsec1your_private_key_here" > ~/.config/clip/key chmod 600 ~/.config/clip/key
Note: You can use any Nostr private key. It doesn't have to be generated by clip-cli. However, keep in mind that this key will be permanently associated with your Lightning node via the Node Announcement.
Create a configuration file at ~/.config/clip/config.yaml:
mkdir -p ~/.config/clip
nano ~/.config/clip/config.yamlSee Example Configuration below for a complete configuration template.
NAME:
clip-cli - CLIP (Common Lightning-node Information Payloader) - Sending and receiving verifiable Lightning node information over Nostr.
USAGE:
clip-cli [global options] command [command options]
COMMANDS:
getinfo Returns basic information about the connected Lightning node.
generatekey Generates a new private key for Nostr.
listnodeannouncements, lna Fetches all node announcement events from the configured Nostr relays and displays them.
listnodeinfo, lni Fetches all node information from the configured Nostr relays and displays it.
pubnodeannounce, pna Publishes a node announcement event to the configured Nostr relays.
pubnodeinfo, pni Publishes the node information specified in the config to the configured Nostr relays.
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--config value name of the config file (default ~/.config/clip/config.yaml)
--help, -h show help
--version, -v print the version
First, publish a Node Announcement to link your Lightning node to your Nostr identity:
clip-cli pubnodeannounce
# or
clip-cli pnaThis command:
- Creates a Node Announcement event
- Signs it with your Lightning node's identity key
- Signs it with your Nostr key
- Publishes it to the configured relays
After the announcement, you can publish your node's metadata:
clip-cli pubnodeinfo
# or
clip-cli pniThis publishes the node_info section from your configuration file to the relays.
Node Info events do not require a Lightning signature. They only need to be signed by the Nostr key that was bound in the Node Announcement.
# List all node announcements
clip-cli listnodeannouncements
# or
clip-cli lna
# List announcements from the last 7 days (default: 60 days)
clip-cli lna --since 168h
# List for a specific Lightning node (default: all nodes)
clip-cli lna --pubkey 03abc...def# List all node info
clip-cli listnodeinfo
# or
clip-cli lni
# Filter by time and node
clip-cli lni --since 24h --pubkey 03abc...def
Connects directly to an LND node via gRPC for automated signing.
lnclient: "lnd"
lnd:
host: "localhost"
port: 10009
tls_cert_path: "/path/to/your/tls.cert"
macaroon_path: "/path/to/your/macaroon.macaroon"The provided macaroon must have permissions for lnrpc.SignMessage, lnrpc.GetInfo and lnrpc.GetNodeInfo. An admin.macaroon is not strictly required but is the most convenient option.
Prompts for manual signing, making it compatible with any Lightning implementation (e.g., LND, CLN, Eclair).
lnclient: "interactive"
interactive:
network: "mainnet"
pub_key: "03abc...def"Use lncli signmessage or another API to sign the message prompted by the CLI.
A complete example configuration file can be found in config.example.yaml. You can copy this file to ~/.config/clip/config.yaml and edit it to your needs.
-
Relay URLs: Choose a mix of well-known relays for reliability.
-
Privacy: Be mindful of the information you share publicly. Only include what you are comfortable making available to anyone on the internet. For enhanced privacy, consider running your communication with Nostr relays through a VPN to obfuscate your IP address.
-
Node Info Fields: All fields under
node_infoare optional. Only include information you want to make public. -
Contact Info: You can have multiple contact methods. Set
primary: trueon your preferred method (only one contact can be primary). -
Security: The Nostr key is stored as plain text. Keep your key file (
key_store_path) secure with appropriate file permissions (600). Back up your Nostr private key securely, as it allows you to publish information even when your Lightning node is down.
See LICENSE file for details.