|
| 1 | +# Lightning Network Setup options |
| 2 | + |
| 3 | +As discussed in the [Lightning Network overview](./LightningNetwork.md), there are several options to set up a Lightning Network node in BTCPay Server. On this page we will give you installation instructions and/or link to the relevant documentation. |
| 4 | + |
| 5 | +Jump right to the section you are interested in: |
| 6 | +[[toc]] |
| 7 | + |
| 8 | +## Setting up your own Lightning Network node (fully self sovereign) |
| 9 | + |
| 10 | +This guide will show you how to set up your Lightning Network (LN) node in BTCPay Server and guide you through the basics. |
| 11 | + |
| 12 | +BTCPay Server currently offers these implementations of the Lightning Network: |
| 13 | + |
| 14 | +- [LND](https://github.com/lightningnetwork/lnd) |
| 15 | +- [Core Lightning (CLN)](https://github.com/ElementsProject/lightning) (formerly c-lightning) |
| 16 | +- [Eclair](https://github.com/ACINQ/eclair) |
| 17 | + |
| 18 | +::: danger |
| 19 | +Before you proceed, please understand that running LN nodes is still a bit complicated. You need to ensure to have proper backups to be able to recover funds. |
| 20 | +Using the Lightning Network can put your money at risk. Do not use more than you can afford to lose. |
| 21 | +::: |
| 22 | + |
| 23 | +Take time to familiarize yourself with the risks associated with using the Lightning Network. |
| 24 | + |
| 25 | +If you choose to run the internal Lightning Node in BTCPay Server, consider: |
| 26 | + |
| 27 | +1. Any LN node operates at two levels: **on-chain** and **off-chain**. |
| 28 | +2. The LN implementation of choice will create an on-chain hot wallet that will be used to fund the off-chain payment channels. |
| 29 | +3. Make sure you back up the **on-chain** hot wallet seed (see the instructions below for the individual implementations). |
| 30 | +4. The seed in step #3 can **only recover the on-chain funds**, although it is necessary for the off-chain operation. |
| 31 | +5. **Off-chain** funds locked in channels **cannot** be backed up using a single-seed. Read the documentation issued by your LN implementation of choice. |
| 32 | +6. **Off-chain** recovery mechanisms are under active research and development. Erasing your BTCPay Server or unsafe/unsecure operation of the computing environment (e.g Filesystem corruption, compromised keys) can lead to permanent **loss of funds**. |
| 33 | +7. Use our [backup script](./Docker/backup-restore) to regularly backup your BTCPay Server instance. This will help you recover your funds in case of a failure. |
| 34 | + |
| 35 | +As the technology matures and develops, mechanisms for proper backup will be easier to implement in BTCPay Server. |
| 36 | +As of [v1.0.3.138](https://blog.btcpayserver.org/btcpay-lnd-migration/), LND is the only Lightning Network implementation that allows for [lightning seed backups with BTCPay Server](./FAQ/LightningNetwork.md#where-can-i-find-recovery-seed-backup-for-my-lightning-network-wallet-in-btcpay-server). |
| 37 | + |
| 38 | +### Choosing the Lightning Network implementation |
| 39 | + |
| 40 | +First, read [here](./FAQ/LightningNetwork.md#can-i-use-a-pruned-node-with-ln-in-btcpay) about using pruned Bitcoin nodes with Lightning Network implementations before deploying. |
| 41 | + |
| 42 | +On the installation, you'll be able to choose the implementation. |
| 43 | + |
| 44 | +For [web-interface installations like on LunaNode](./Deployment/LunaNode.md), you can select the implementation from the drop-down menu. |
| 45 | +For other [docker](https://github.com/btcpayserver/btcpayserver-docker) based [deployment methods](./Deployment/README.md) you need to: |
| 46 | + |
| 47 | +```bash |
| 48 | +sudo su - |
| 49 | +cd btcpayserver-docker |
| 50 | +export BTCPAYGEN_LIGHTNING="implementationgoeshere" |
| 51 | +. ./btcpay-setup.sh -i |
| 52 | +``` |
| 53 | + |
| 54 | +- For **Core Lightning (CLN)** use `export BTCPAYGEN_LIGHTNING="clightning"` |
| 55 | +- For **LND** use `export BTCPAYGEN_LIGHTNING="lnd"` |
| 56 | +- For **Eclair** use `export BTCPAYGEN_LIGHTNING="eclair"` AND `export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-txindex"` |
| 57 | + |
| 58 | +Finally, to begin using LN, your blockchain needs to be fully synced. |
| 59 | + |
| 60 | +### Lightning node configuration in BTCPay Server |
| 61 | + |
| 62 | +#### Connecting your internal Lightning Node |
| 63 | + |
| 64 | +Irrespective of the LN implementation deployed, the process of connecting your internal Lightning Node in BTCPay Server is the same. |
| 65 | + |
| 66 | +1. Choose a store |
| 67 | +2. Go to "Lightning" > Select "Use internal node" |
| 68 | +3. Click "Save" > See "BTC Lightning node updated." message |
| 69 | +4. Go to "Public Node Info" > The node should appear **"Online"** |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +If the internal connection fails, confirm: |
| 74 | + |
| 75 | +1. The Bitcoin on-chain node is fully synchronized |
| 76 | +2. The Internal lightning node is "Enabled" under "Lightning" > "Settings" > "BTC Lightning Settings" |
| 77 | + |
| 78 | +If you are unable to connect to your Lightning node, try [restarting your server](./FAQ/ServerSettings.md#how-to-restart-btcpay-server) or reviewing our [troubleshooting guide](./Troubleshooting.md). You will not be able to accept lightning payments in your store until your Lightning node appears "Online". Try to test your Lightning connection by clicking the "Public Node Info" link. |
| 79 | + |
| 80 | +#### Connecting an external Lightning Node in BTCPay Server |
| 81 | + |
| 82 | +BTCPay Server offers the option to connect to an external Lightning node. To configure it: |
| 83 | + |
| 84 | +1. Go to "Lightning" > Select "Use custom node" if there is no Lightning node configured. |
| 85 | +2. Go to "Lightning" > Select "Settings" > Select "Change connection" > Select "Use custom node" to modify an existing connection |
| 86 | +3. Add the configuration details matching the lightning implementation used, click on "Test connection" |
| 87 | +4. If successful, click "Save" > See "BTC Lightning node updated." message. |
| 88 | + |
| 89 | +::: tip |
| 90 | +If you already use [AlbyHub](https://getalby.com/) you can use the LNDHub connection support to connect your BTCPay wallet directly to your Alby account. As AlbyHub supports sub-accounts, you can use it similarly to the popular but discontinued LNBank plugin. Learn more on [how to connect your BTCPay wallet to Alby](https://guides.getalby.com/user-guide/v/alby-account-and-browser-extension/alby-lightning-account/connect-your-alby-lightning-account-to-other-apps/connect-to-btcpay-server). |
| 91 | +::: |
| 92 | + |
| 93 | +### Getting started with BTCPay Server and LND |
| 94 | + |
| 95 | +#### Control your LND using Ride The Lightning (RTL) |
| 96 | + |
| 97 | +The easiest way to use LND implementation with BTCPay Server is to use the **[Ride The Lightning]https://github.com/Ride-The-Lightning/RTL)** (RTL) service. A web user interface for the Lightning Network, RTL allows you to operate your node without leaving BTCPay Server, from your browser. |
| 98 | +\ |
| 99 | +To initiate RTL in BTCPay Server, Go to Server Settings > Services > Ride The Lightning > See information. |
| 100 | + |
| 101 | +#### Control your LND using Zeus |
| 102 | + |
| 103 | +For remote control of your LN node with your mobile phone, you can use [ZEUS](https://docs.zeusln.app/for-users/remote-connections/btcpay/) |
| 104 | + |
| 105 | +#### Control your LND via the command-line: lncli |
| 106 | + |
| 107 | +LND can be accessed via the command-line using the shell script `bitcoin-lncli.sh`. |
| 108 | +\ |
| 109 | +If you're on Docker make sure you're in docker directory. |
| 110 | + |
| 111 | +```bash |
| 112 | +sudo su - |
| 113 | +cd btcpayserver-docker |
| 114 | +./bitcoin-lncli.sh $command |
| 115 | +./bitcoin-lncli.sh getinfo #show info about the node |
| 116 | +``` |
| 117 | + |
| 118 | +Run ./bitcoin-lncli.sh --help` to see a full list of commands or check the full [API documentation](https://api.lightning.community/). |
| 119 | + |
| 120 | +### Getting started with BTCPay Server and Core Lightning (CLN) |
| 121 | + |
| 122 | +#### Control your CLN using Ride The Lightning (RTL) |
| 123 | + |
| 124 | +The easiest way to use CLN implementation with BTCPay Server is to use the **[Ride The Lightning]https://github.com/Ride-The-Lightning/RTL)** (RTL) service. A web user interface for the Lightning Network, RTL allows you to operate your node without leaving BTCPay Server, from your browser. |
| 125 | +\ |
| 126 | +To initiate RTL in BTCPay Server, Go to Server Settings > Services > Ride The Lightning > See information. |
| 127 | + |
| 128 | +#### Control your LND using Zeus |
| 129 | + |
| 130 | +For remote control of your LN node with your mobile phone, you can use [ZEUS](https://docs.zeusln.app/for-users/remote-connections/btcpay/) |
| 131 | + |
| 132 | +#### Control your CLN via the command-line: lightning-cli |
| 133 | + |
| 134 | +Similar to `lncli`, CLN can be accessed via the command-line using the shell script `bitcoin-lightning-cli.sh`. |
| 135 | +\ |
| 136 | +If you're on Docker make sure you're in docker directory. |
| 137 | + |
| 138 | +```bash |
| 139 | +sudo su - |
| 140 | +cd btcpayserver-docker |
| 141 | +./bitcoin-lightning-cli.sh $command |
| 142 | +./bitcoin-lightning-cli.sh getinfo #show info about the node |
| 143 | +``` |
| 144 | + |
| 145 | +Run `./bitcoin-lightning-cli.sh help` to see a full list of commands or check the full [API documentation](https://lightning.readthedocs.io/). |
| 146 | + |
| 147 | +### Lightning node backup |
| 148 | + |
| 149 | +Before you start transacting using your new lightning node, consider backing up the **on-chain** wallet. Steps: |
| 150 | + |
| 151 | +1. **for LND**: storing a copy of the LND seed. |
| 152 | + Go to "Server Settings" > "Services" > "LND Seed Backup" and select "See information" |
| 153 | +2. **for CLN**: storing a copy of the [hsm_secret](https://lightning.readthedocs.io/BACKUP.html#hsm-secret) |
| 154 | + \ |
| 155 | + The CLN $LIGHTNINGDIR is located in `/var/lib/docker/volumes/generated_clightning_bitcoin_datadir/_data/bitcoin` |
| 156 | + |
| 157 | +Acknowledge the limitations of **off-chain** payment channel backups and associated risks. |
| 158 | +\ |
| 159 | +See [backup FAQ](./Docker/backup-restore/#lightning-channel-backup) if you are running the BTCPay Server instance with Docker. |
| 160 | + |
| 161 | +### Funding your on-chain wallet |
| 162 | + |
| 163 | +Now that your lightning node is active, before opening lightning payment channels, you will need to fund the on-chain wallet. |
| 164 | +\ |
| 165 | +The on-chain funding process can be performed in two ways: |
| 166 | + |
| 167 | +1. via the Ride The Lightning (RTL) UI interface |
| 168 | + |
| 169 | +- Select a "Store" and go to the "Lightning" section |
| 170 | +- Under "Services", select "Ride The Lightning" |
| 171 | +- In the RTL app, go to "On-chain", select "Receive" under the "On-chain Transactions" menu |
| 172 | +- Select "Generate Address" and use it as the destination for the allocated funds |
| 173 | + |
| 174 | +2. via the command-line using `bitcoin-lncli.sh` or `bitcoin-lightning-cli.sh` |
| 175 | + |
| 176 | +```bash |
| 177 | +sudo su - |
| 178 | +cd btcpayserver-docker |
| 179 | +./bitcoin-lncli.sh newaddress p2wkh #for LND |
| 180 | +./bitcoin-lightning-cli.sh newaddr #for CLN |
| 181 | +{ |
| 182 | + "address" / "bech32": "bc1..........." #use this as the destination for the allocated funds |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +Once your on-chain lightning node is funded, it's time to connect to other nodes on the network and open payment channels. |
| 187 | +\ |
| 188 | +Check out [Payment channels](./LightningNetwork_PaymentChannels.md) for recommendations on opening payment channels, liquidity management and more. |
0 commit comments