Skip to content

Commit c3abb0a

Browse files
committed
Refactor and move things around.
1 parent 077207a commit c3abb0a

File tree

3 files changed

+254
-243
lines changed

3 files changed

+254
-243
lines changed

docs/LightningNetwork-GettingStarted.md

Lines changed: 0 additions & 83 deletions
This file was deleted.

docs/LightningNetwork-Setup.md

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
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+
![LightningNetworkNodeSetupOverview](./img/lightning-node-setup/LightningNetworkNodeSetupOverview.jpg)
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

Comments
 (0)