Lightning Network Setup Guide¶
Overview¶
Lightning Network enables instant, low-fee Bitcoin payments for Research Relay's e-commerce store. This document covers implementation selection, channel strategy, liquidity management, and cost estimates.
1. Implementation Selection: Core Lightning (CLN)¶
Decision: CLN over LND¶
| Factor | CLN | LND |
|---|---|---|
| BTCPay recommendation | Officially recommended | Supported but not preferred |
| Pruned node support | Yes | No (requires full node) |
| Resource usage | Lower (C/C++) | Higher (Go) |
| Disk savings | ~500GB+ with pruned node | Requires 700GB+ full node |
| Plugin ecosystem | Extensive (CLBOSS, etc.) | Limited built-in |
| Seed backup | Manual (hsm_secret file) |
Built-in (12-word seed) |
| GUI tools | RTL | RTL, Thunderhub, Alby Hub |
| nix-bitcoin support | First-class | Supported |
| Payment routing | Good | Slightly better success rate |
Why CLN for Research Relay:
1. Pruned node support — saves 500GB+ disk on shops-btc-01
2. CLBOSS plugin — automated channel management critical for a solo operator
3. Lower resource usage — leaves server resources for Medusa, PostgreSQL, etc.
4. nix-bitcoin integration — CLN is the default Lightning implementation in nix-bitcoin
5. Plugin architecture — easy to extend with rebalancing, monitoring, etc.
Trade-off accepted: LND has slightly better payment routing success rates and more GUI options. For a merchant primarily receiving payments (not routing), this matters less. RTL works with both implementations and is sufficient for management.
CLN Configuration via nix-bitcoin¶
services.clightning = {
enable = true;
# CLBOSS for automated channel and liquidity management
plugins.clboss.enable = true;
# Additional useful plugins
plugins.summary.enable = true; # Node summary stats
extraConfig = ''
# Allow channels larger than default
large-channels
# Experimental dual-funding (useful for negotiating channels)
experimental-dual-fund
# Fee policy — start with defaults, CLBOSS will adjust
fee-base=1000
fee-per-satoshi=10
# Min channel size (avoid dust channels)
min-capacity-sat=100000
# HTLC limits
max-concurrent-htlcs=30
'';
};
2. Channel Strategy for a Small Merchant¶
Initial Channel Setup¶
As a merchant primarily receiving payments, the key challenge is inbound liquidity — customers need to be able to send payments to you, which requires channel capacity on the remote (peer) side.
Phase 1: First 3 Channels (Week 1)¶
Open 3 channels with well-connected nodes to establish network presence:
| Channel | Target Peer Type | Size | Purpose |
|---|---|---|---|
| 1 | Major LSP (ACINQ, Voltage) | 500K-1M sats | Connectivity to broad network |
| 2 | Well-connected routing node | 500K-1M sats | Redundant path |
| 3 | Merchant-friendly node (Bitrefill, OpenNode) | 500K sats | Payment reliability |
Total initial funding needed: ~2M sats (~$800 at current rates)
On-chain fees for 3 channel opens at ~10 sat/vbyte: ~3,000-5,000 sats (~$2)
Phase 2: Acquire Inbound Liquidity (Week 1-2)¶
Outbound channels alone do not allow receiving payments. Options for inbound liquidity:
- CLBOSS automated (recommended) — CLBOSS monitors your node and automatically:
- Opens channels to well-connected peers
- Buys inbound liquidity via Boltz submarine swaps when inbound is too low
- Adjusts fees to attract routing through your channels
-
Rebalances channels that become one-sided
-
LSP channel request — Ask an LSP to open a channel to you (see LSP section below)
-
Lightning Pool (LND only, not applicable with CLN)
-
Manual swap — Spend outbound capacity via Boltz exchange to get on-chain BTC back, creating inbound capacity in the process
Phase 3: Steady State (Ongoing)¶
As customers pay via Lightning, your inbound capacity converts to local (outbound) balance. Over time: - Channels fill up on your side - You need to periodically move funds out (submarine swap to on-chain, or spend via Lightning) - CLBOSS handles most of this automatically
Peer Selection Criteria¶
When manually choosing channel peers (beyond CLBOSS automation):
- Uptime >99% — check on 1ML.com or Amboss.space
- Well-connected — 50+ channels, high capacity
- Low fee rates — indicates cooperative routing node
- Geographically distributed — reduces correlated failures
- Known entities preferred — ACINQ, Voltage, Bitrefill, WalletOfSatoshi (routing node), LNBig
3. Liquidity Management¶
Inbound Liquidity Strategies¶
Inbound liquidity is the amount your channel peers can send to you. Without it, customers cannot pay.
Strategy 1: CLBOSS Automated Management (Primary)¶
CLBOSS is an automated liquidity manager for CLN that handles:
- Channel opens: Detects when more connectivity is needed, opens channels to well-connected peers
- Inbound acquisition: Uses Boltz submarine swaps to convert outbound to inbound when your inbound drops below threshold
- Fee adjustment: Dynamically adjusts routing fees based on channel balance (low balance = higher fee to reduce outflow, high balance = lower fee to attract inflow)
- Rebalancing: Circular self-payments to redistribute liquidity across channels
CLBOSS configuration is mostly automatic. Fund the node's on-chain wallet with BTC and CLBOSS handles the rest. For a small merchant, CLBOSS is the single best tool — it removes the need for manual channel management.
Strategy 2: LSP Services¶
| LSP | Services | CLN Compatible | Cost |
|---|---|---|---|
| Voltage Flow | Instant inbound/outbound, JIT channels | Yes (LND, CLN, LDK) | Volume-based pricing |
| Boltz | Submarine swaps (on-chain ↔ Lightning) | Yes | ~0.1-0.5% swap fee |
| LNBIG | Large channel opens to your node | Yes | Free or low-cost |
| Magma | Liquidity marketplace on Amboss | Yes | Market rates |
Recommendation: Let CLBOSS handle liquidity via Boltz swaps. If you need a large channel quickly, request one from LNBIG (often free for well-connected nodes).
Strategy 3: Spend to Create Inbound¶
Every sat you spend via Lightning creates inbound capacity: - Pay suppliers via Lightning if possible - Use Lightning to buy gift cards (Bitrefill) - Submarine swap to on-chain (Boltz) when local balance is too high
Channel Capacity Planning¶
For a store expecting $500-2,000/month in BTC sales:
| Metric | Estimate |
|---|---|
| Average order size | $50-200 |
| Monthly BTC orders | 10-40 |
| Daily peak | 2-5 orders |
| Required inbound/day | ~500K sats |
| Target total inbound | 2M-5M sats |
| Target total channels | 3-5 |
| Target total capacity | 5M-10M sats |
These are conservative starting estimates. Scale up if volume exceeds expectations.
4. Lightning Service Providers (LSPs)¶
What LSPs Do¶
LSPs deploy capital in the Lightning Network on your behalf: - Open channels to your node (providing inbound liquidity) - Manage JIT (Just-In-Time) channels — open a channel on-demand when a payment arrives - Handle submarine swaps between on-chain and Lightning - Some offer hosted channel management
Recommended LSPs for Research Relay¶
Tier 1: Automated via CLBOSS¶
- Boltz Exchange — CLBOSS uses Boltz for automated submarine swaps. No manual setup needed.
- Swap fees: ~0.1-0.5% depending on direction and amount
- Supports CLN natively
- Non-custodial (atomic swaps)
Tier 2: Manual Channel Requests (if needed)¶
- LNBIG — One of the largest Lightning liquidity providers. Often opens channels for free to well-connected nodes. Request via their website or Telegram.
- Voltage Flow — Professional LSP service. Supports CLN. Provides instant inbound liquidity with usage-based pricing.
Tier 3: Marketplace¶
- Amboss Magma — Peer-to-peer liquidity marketplace. Browse offers from other node operators willing to open channels to you. Prices vary by market conditions.
JIT Channels¶
Just-In-Time channels are opened automatically when an incoming payment arrives and you lack sufficient inbound capacity. The LSP: 1. Intercepts the incoming HTLC 2. Opens a 0-conf channel to your node 3. Forwards the payment through the new channel 4. Deducts their fee from the payment
This is standardized in the LSPS2 specification. CLBOSS does not implement JIT directly but achieves a similar result by proactively maintaining inbound liquidity.
5. Cost Estimates¶
Initial Setup Costs¶
| Item | Cost (sats) | Cost (USD est.) |
|---|---|---|
| Initial channel funding (3 channels) | 2,000,000 | ~$800 |
| On-chain fees for channel opens (3 tx) | 5,000 | ~$2 |
| Total initial | ~2,005,000 | ~$802 |
Monthly Operating Costs¶
| Item | Cost (sats/month) | Cost (USD est.) |
|---|---|---|
| CLBOSS submarine swap fees | 5,000-20,000 | $2-8 |
| On-chain fees (sweeps, rebalancing) | 2,000-10,000 | $1-4 |
| Channel force-close reserve | Variable | Variable |
| Server (already running) | 0 | $0 |
| Total monthly | ~10,000-30,000 | ~$4-12 |
Cost Comparison: Lightning vs. Card Processing¶
| Method | Per-transaction cost | Monthly fixed |
|---|---|---|
| Lightning (self-hosted) | ~0 sats (receiving) | ~$4-12 (liquidity) |
| Stripe ACH | 0.8% ($0.40-1.60 per order) | $0 |
| Stripe Card | 2.9% + $0.30 ($1.75-6.10 per order) | $0 |
| Third-party BTC processor | 1% ($0.50-2.00 per order) | $0-30 |
Lightning is the cheapest option for receiving payments, especially at moderate volume. The fixed costs (liquidity management) are amortized across all transactions.
6. Operational Considerations¶
Lightning Node Uptime Requirements¶
- Lightning nodes must be online 24/7 to receive payments and monitor channels
- If your node goes offline, customers cannot pay via Lightning (on-chain still works)
- Channel peers may force-close channels if your node is offline for extended periods (typically >2 weeks, but varies by peer)
Force-Close Scenarios¶
A force-close happens when a channel is closed unilaterally (by you or your peer). This: - Locks your funds in a timelock (typically 144 blocks / ~24 hours for the non-initiating party, up to 2016 blocks / ~2 weeks for the initiator) - Costs on-chain fees at the fee rate set when the channel was last updated - Permanently closes the channel — you must open a new one
Prevention: - Maintain high uptime (nix-bitcoin services restart automatically) - Don't run out of disk space (prune properly) - Keep CLN and bitcoind updated - Monitor with alerts (see Runbook)
Watchtowers¶
A watchtower monitors the blockchain for cheating attempts (old channel states being broadcast). CLN has built-in penalty transaction logic, but only while your node is online.
For a merchant node with high uptime on a dedicated server, watchtowers are low priority. If your node runs on a laptop or has unreliable connectivity, consider the watchtower-client plugin for CLN.
Lightning Payment Limits¶
- Maximum single payment: Limited by channel capacity and HTLC limits. With 1M sat channels, maximum single payment is ~990K sats (~$400). For larger orders, customers can pay on-chain.
- MPP (Multi-Part Payments): CLN supports receiving multi-part payments, allowing payments larger than any single channel's capacity (split across multiple channels).
- Minimum payment: 1 sat (but practically, channel reserve and fees mean ~1000 sats minimum is sensible)
Privacy Considerations¶
- BTCPay Server on nix-bitcoin runs Tor by default for Bitcoin and Lightning P2P connections
- BTCPay currently fetches exchange rates without Tor proxying (IP correlation risk)
- Public Lightning node: your node's pubkey, channels, and capacity are visible on the public Lightning graph
- Consider running a private/unannounced node if privacy is paramount (trade-off: fewer routing peers)