Lightning.Pub

Lightning.Pub

GitHub last commit PRs Welcome Chat Xitter

Don't just run a Lightning Node, run a Lightning Pub.

"Pub" is a Nostr-native account system designed to make running Lightning infrastructure for your friends/family/customers easier than previously thought possible.

Lightning payments open the door to a new internet, but because of UX challenges with sovereignty we've seen a much slower uptake than we should for something so amazing.

It may come as a surprise that the biggest hurdle to more adoption via Family and SMB Lightning nodes hasn't been with Bitcoin/Lightning node management itself, as we've seen that liquidity is easily automated, but rather the legacy baggage of traditional Client-Server web infrastructure. Things like IP4, Reverse Proxies, DNS, Firewalls and SSL certificates, all require a personal configuration that is a hurdle for most.

Tor as a workaround has proven too slow and unreliable, and a dead-end for clearnet-web usecases.

Mobile nodes are easy to use for spending, but channels for every device is expensive and unscalable. UX suffers from the limitations of the node not being an always-online server, which also makes them largely useless for merchants and routing services that earn revenue while you sleep.

Pub solves these challenges with a P2P-like design that is also web-friendly, by implementing a full RPC that is Nostr-native. Being Nostr-native eliminates the complexity of configuring your node like a server by using commodity Nostr relays. These relays, unlike LNURL proxies, are trustless by nature of Nostr's own encryption spec (NIP44).

Additionally, support for optional services are integrated into Pub for operators seeking backward compatibility with legacy LNURLs and Lightning Addresses.

By solving the networking and programability hurdles, Pub provides Lightning with a 3rd Layer that enables node-runners, Busineses, and Uncle Jims to more easily bring their personal network into Bitcoin's permissionless economy. In doing so, Pub runners can keep the Lightning Network decentralized, with custodial scaling that is free of fiat rails, large banks, and other forms of high-time-preference shitcoinery.

Table of Contents

Features

Accounts

Connect Wallet Invite Guests

Planned Features

Dashboard Wireframe:

Pub Dashboard

Installation

One-Line Deployment

Paste one-line and have a Pub node in under 2 minutes. It uses neutrino so you can run it on a $5 VPS or old laptop.

This method installs all dependencies and creates user-level services (systemd on Linux, launchd on macOS).

Platform Support:

[!IMPORTANT] System Requirements:

[!TIP] Bundled Node: The Lightning.Pub install script provides a complete Lightning solution. You do NOT need to a full Bitcoin or other node, perfect small devices like Raspberry Pi.

To start, run the following command:

Linux:

wget -qO- https://deploy.lightning.pub | bash

macOS:

curl -fsSL https://deploy.lightning.pub | bash

It should look like this in a minute or so

One-Line Deployment

Note: The installation is now confined to user-space, meaning:

After Installation:

⚠️ Migration from Previous Versions: Previous system-wide installations (as of 8.27.2025) need some manual intervention:

  1. Stop existing services: sudo systemctl stop lnd lightning_pub
  2. Disable services: sudo systemctl disable lnd lightning_pub
  3. Remove old systemd units: sudo rm /etc/systemd/system/lnd.service /etc/systemd/system/lightning_pub.service
  4. Reload systemd: sudo systemctl daemon-reload
  5. Run the new installer: wget -qO- https://deploy.lightning.pub | bash

Please report any issues to the issue tracker.

Automatic updates

These are controversial, so we don't include them. You can however add a line to your crontab to re-run the installer on your time preference and it will gracefully handle updating:

Linux:

# Add to user's crontab (crontab -e) - runs weekly on Sunday at 2 AM
0 2 * * 0 wget -qO- https://deploy.lightning.pub | bash

macOS:

# Add to user's crontab (crontab -e) - runs weekly on Sunday at 2 AM
0 2 * * 0 curl -fsSL https://deploy.lightning.pub | bash

Note: The installer will only restart services if version checks deem necessary.

Troubleshooting

If the installation fails or services don't start properly, use these commands to diagnose:

Linux:

# Check service status
systemctl --user status lnd
systemctl --user status lightning_pub

# View logs
journalctl --user-unit lnd -f
journalctl --user-unit lightning_pub -f

# Restart services if needed
systemctl --user restart lnd
systemctl --user restart lightning_pub

macOS: After installation, run source ~/.zshrc (or source ~/.bash_profile) to enable the convenience aliases, or open a new terminal. Then use:

# Check service status
lpub-status

# View logs
lpub-log      # Lightning.Pub logs
lnd-log       # LND logs

# Control services
lpub-start    # Start both services
lpub-stop     # Stop both services
lpub-restart  # Restart both services

All Platforms:

# Retrieve admin connection string (if installation completed but you need to find it again)
cat ~/lightning_pub/admin.connect

# Reset admin access (generates new admin.connect automatically)
rm ~/lightning_pub/admin.npub
sleep 1  # Wait briefly for new admin.connect to re-generate
cat ~/lightning_pub/admin.connect

Docker Installation

See the Docker Installation Guide.

Manual CLI Installation

  1. Run LND if you aren't already:
./lnd --bitcoin.active --bitcoin.mainnet --bitcoin.node=neutrino --neutrino.addpeer=neutrino.shock.network --feeurl=https://nodes.lightning.computer/fees/v1/btc-fee-estimates.json
  1. Download and Install Lightning.Pub:
git clone https://github.com/shocknet/Lightning.Pub && cd Lightning.Pub && npm i
  1. Configure values in the env file:
cp env.example .env && nano .env
  1. Start the service:
npm start

Usage Notes

Connecting to ShockWallet

For Administrators:

  1. After installation, you'll see an admin connection string (format: nprofile1...:token) and a terminal QR code containing the same admin connection string
  2. Option 1: Scan the terminal QR code directly with ShockWallet's "Add Source" feature (mobile or web) to pair as administrator
  3. Option 2: Copy/paste the connection string into ShockWallet's node connection screen

For Guest Users:

[!NOTE] Connecting with wallet will create an account on the node, it will not show or have access to the full LND balance. Allocating existing funds to the admin user will be added to the operator dashboard in a future release.

Lightning Address

When you run your own Lightning Pub, obtaining a Lightning Address is fully automated in ShockWallet. The wallet automatically:

  1. Takes the CLINK offer from your Pub
  2. Enrolls it at a LNURL bridge (creates a @shockwallet.app address)
  3. This makes the Lightning Address trustless when payers support CLINK as it uses Nostr for communication instead of trusting the bridge to serve the correct invoice.

[!TIP] CLINK Integration: Your Pub's CLINK offers enable ShockWallet to connect to CLINK-compatible services, like Stacker News, allowing you to send and receive payments without additional setup.

For custom Lightning Address domains, see the Advanced Configuration section.

Advanced Configuration

Copy env.example to .env and customize settings:

cp env.example .env
nano .env  # or use your preferred editor

[!IMPORTANT] Environment variables set in .env will override any settings configured via the wizard or stored in the settings database table.

Custom Nostr Relay

By default, Lightning.Pub uses the ShockNet relay. To use your own:

# Single relay
NOSTR_RELAYS=wss://your-relay-url.com

# Multiple relays (space-separated)
NOSTR_RELAYS="wss://relay1.com wss://relay2.com wss://relay3.com"

The wizard interface (coming soon for Start9/Umbrel) will make this graphical.

Bootstrap Liquidity Provider

By default, Lightning.Pub connects to a bootstrap liquidity provider (another Pub over Nostr) for outbound routing when local LND channel liquidity is low. Pub compares rates from top LSPs and automatically requests a channel when needed.

Settings are loaded from environment variables or the admin_settings database table (env wins if both are set). The relevant keys are PROVIDER_NPROFILE and DISABLE_LIQUIDITY_PROVIDER

# Disable upstream provider checks (LND only for outbound payments)
DISABLE_LIQUIDITY_PROVIDER=true

# Optional: point at a different Pub instance (pubkey + relay are in the nprofile)
PROVIDER_NPROFILE=nprofile1qyd8wumn8ghj7um5wfn8y7fwwd5x7cmt9ehx2arhdaexkqpqwmk5tuqvafa6ckwc6zmaypyy3af3n4aeds2ql7m0ew42kzsn638q9s9z8p

Custom Lightning Address Domain

By default, ShockWallet automatically enrolls your CLINK offer at @shockwallet.app. For custom domains, you have two options:

Option 1: Run your own Bridgelet

A minimalist LNURL-P and Lightning Address bridge service that uses CLINK Offers. This gives you full control over your Lightning Address domain without trusting third-party bridges.

Option 2: Enable LNURL directly on Pub

# Configure which LNURL bridge to suggest to wallets (default: https://shockwallet.app)
BRIDGE_URL=https://your-bridge.com

# Enable LNURL callbacks directly on Pub (requires SSL reverse proxy pointing to Pub's port)
SERVICE_URL=https://yourdomain.com

Complete Reference

See env.example for complete documentation of all available settings.

For additional documentation, guides, and FAQs, visit docs.shock.network or contribute to the docs repository.

Support Development

[!IMPORTANT]
ShockWallet and Lightning.Pub are free software. If you would like to see continued development, please show your support 😊

License

Warning

[!WARNING]
While this software has been used in a high-profile production environment for several years, it should still be considered bleeding edge. Special care has been taken to mitigate the risk of drainage attacks, which is a common risk to all Lightning APIs. An integrated Watchdog service will terminate spends if it detects a discrepancy between LND and the database, for this reason IT IS NOT RECOMMENDED TO USE PUB ALONGSIDE OTHER ACCOUNT SYSTEMS such as AlbyHub, LNBits, or BTCPay - this watchdog may however be disabled. While we give the utmost care and attention to security, the internet is an adversarial environment and SECURITY/RELIABILITY ARE NOT GUARANTEED- USE AT YOUR OWN RISK.