Running Bitcoin & Lightning Nodes Over The Tor Network (2021 Edition)
And Connecting Your Phone to Use Lightning On-The-Go
Preface
In 2018 I made a tutorial for getting a Bitcoin full node up and running on Linux, and I provided a complete step-by-step process, along with explainers for how to use & understand the bash shell, and what certain commands and their flags did. It’s been 3 years since, and what you’re reading now is the updated and next iteration of that.
This tutorial is 1 of 3 being published in tandem. The one you’re viewing currently is the primary one, and brings the other two together to run over the Tor network, and connect your phone’s Bitcoin & Lightning wallets to it using Zap iOS over Tor (if you do not have iOS you may skip the Zap aspects of this tutorial, or use the Zap desktop client). The other two function as standalone tutorials for both Bitcoin & Lightning respectively, and they completely break down the entire node installation process for beginners.
The Bitcoin & Lightning sections in this tutorial will be simplified. If you want more detail please reference the standalone guides for each:
Primary:
- Running Bitcoin & Lightning Nodes Over The Tor Network
Standalone:
Table Of Contents
(Click on any section to jump to that part of the tutorial.)
- Introduction
- Part 1 — Installing Linux, Dependencies, And Tor
A) Downloading, Installing, And Updating Linux
B) Installing & Configuring Tor
C) Prerequisites & Dependencies - Part 2 — Installing Bitcoin & Fully Validating
A) Compile Bitcoin Core 0.21.1 From The Source Code
B) Configure The Bitcoin Software
C) Start Up The Software And Syncing The Blockchain - Part 3 — Installing Lightning & Opening Channels
A) Installing ‘Go’ & LND
B) Configuring LND & Syncing The Graph
C) Funding Your Wallet & Opening A Channel - Part 4 — Connecting Your Phone & Making Payments (Zap iOS)
A) Install ‘LND Connect’ & Connecting Zap To LND
B) Interacting With Your LND Node Via Zap
(Optional):
C) Balancing Your Channel
D) Testing Small Payments - Extra Guidance
How To Create A Transaction Index
How To Recompile/Update Bitcoin Core
How To Update LND
Introduction
This tutorial will guide you through the process of installing Linux (kind of), Tor, Bitcoin Core, and the Lightning Network Daemon (referred to as LND from here on out), and configuring the Zap mobile wallet for iOS to connect to your LND node over Tor.
I’ve made this as modular as possible so that you may skip steps where you already have the software installed. I recommend you read the intro to each step to ensure it can actually be skipped.
At minimum, please make note of the following (it will all be explained later):
- You may skip the Tor steps. Just don’t install it, and don’t include the Tor configurations during the configuration steps. (You’ll need to configure Zap yourself, or opt out of using Zap.)
- You may skip the Zap steps. You can still follow the tutorial in its entirety up until that point and you’ll still have Bitcoin & Lightning running over Tor.
- LND as we are installing it will require Bitcoin Core, and you may need to recompile Bitcoin after you install the ZeroMQ library:
$ sudo apt-get install libzmq3-dev. I’ve provided instructions for how to do this here. - LND will generally not work with a pruned node. Please make sure you have enough hard drive space for the entire Bitcoin blockchain. At the time of writing it’s about 375 GB. It will grow over time.
- LND performs better if your Bitcoin Core node has a “transaction index”. Your bitcoin.conf file should include a line that says
txindex=1. If it doesn’t, that’s fine, but when you add it to your bitcoin.conf file your node will begin building it from scratch using the old blocks. If your node is pruned you will need to resync the blockchain. I’ve provided instructions for how to do this here. - The Linux distribution we are using is Kubuntu 20.0.4.1 and it uses AMD64 architecture. There are a few steps that will need to be modified if you aren’t using an AMD64 distribution. They will be made clear, but you may also need additional dependencies (that is on you).
- The install directories we are using (
~/code/bitcoin&~/code/lnd) may be modified at your own discretion. If you’re skipping steps, like the Bitcoin Core step, please make sure the directories within the commands suit your needs. I do not recommend changing the default data directories (~/.bitcoin&~/.lnd), it may (probably will) cause issues.
Part 1 — Installing Linux, Dependencies, And Tor
Skip to installing dependencies & Tor if Linux isn’t new to you. Skip this step entirely if you already have Bitcoin & Tor installed. Skim this entire section for just the commands if you’re impatient.
1-A) Downloading, Installing, And Updating Linux
The downloading & installing step is the only step that won’t actually be a guide. I’m going to assume you have the precursor knowledge and the ability to figure out how to download & mount the ISO image I link below, boot it, and follow the default install instructions. If you don’t, you can follow Ubuntu’s official tutorial for Windows or MacOS.
Download Kubuntu ISO image
Kubuntu is Ubuntu, but shiny. The most recent LTS release is 20.04.1.
(You don’t need to use Kubuntu. Ubuntu will work with this tutorial, or any other Debian based operating system, although you may have to install other packages.)
Install ISO Image To USB Or CD
If you’ve never used Linux, it’s probably safe to assume you’re using either Windows or MacOS. Follow Ubuntu’s official tutorial for Windows or MacOS.
Install The Operating System
You’ll set up a computer name, user, and password. My username for this tutorial will be satoshi, and the computer name will be nakamoto.
Log In And Get Acquainted
After installation your desktop should look like the screenshot below:
Updating Linux
Via the command line in the terminal (Konsole), check for updates:
satoshi@nakamoto:~$ sudo apt-get-update
(See the beginners guide if this is unfamiliar to you).
1-B) Installing & Configuring Tor
The procedures in this tutorial for getting our Bitcoin & Lightning nodes running over Tor will be split across a few sections. This section will cover installing Tor, and configuring the Tor software so that when we configure Bitcoin, Lightning, and Zap to run over Tor, the Tor software will be ready. Tor Tor Tor.
First we’re going to install Tor, and then configure it to launch when the computer starts. This will not change any network behavior when you’re browsing/using the Internet, and everything you normally do will still go over the normal Internet. Starting Tor just means that the Tor software is ready to be used by other software. Starting Tor when the computer starts just means we don’t have to remember to launch it every time we start our Bitcoin & Lightning nodes.
Adding The Tor Repository
Before we can run the command to install Tor, we need to add the repository source so apt knows where to look for the Tor package, but before we add the repository we need to know our Linux distribution's codename.
If you installed Kubuntu 20.04.1, the release codename is focal.
If you are using a different Linux distribution, enter the following command to find out what to replace focal with during the step after this:
$ lsb_release -cFor example, my desktop’s Kubuntu 18 release codename is bionic:
Now let’s add the repository source:
$ sudo nano /etc/apt/sources.list.d/tor_repo.listnano will create a text file named tor_repo.list in that directory, and then open a terminal based text editor.
With the editor open, we’re going to paste the following two lines into the terminal, but before we do that note the bold text that says focal. Replace focal with your distributions codename:
deb http://deb.torproject.org/torproject.org focal main
deb-src http://deb.torproject.org/torproject.org focal mainAfter that is pasted, press CONTROL+X, then press ‘y’, and then press Enter.
Adding The Tor GPG Key & Installing Tor
Next we need to add the Tor GPG key used to sign the Tor package via the command curl, but we’ll need to install curl first if it’s not already installed:
$ sudo apt install curl(Below is a single string, not two lines.)$ curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | sudo apt-key add -
After adding the GPG key, run an update, which will update the repository index with the tor_repo.list file we created earlier, then proceed with installing Tor:
$ sudo apt-get update$ sudo apt-get install tor deb.torproject.org-keyring
(During testing for this section on my desktop, which is running an older version of Kubuntu, I ran into dependency issues with the libevent version. If you did not install the Kubuntu version provided in this tutorial, or the most recent Ubuntu equivalent, you may have a similar experience. See here for a possible resolution.)
Configuring Tor For Bitcoin & Lightning
Now that Tor is installed, we need to edit the torrc file located in /etc/tor/. Navigate to it the traditional way, open it, and add the following lines into the file at the bottom:
SOCKSPort 9050
Log notice stdout
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
HiddenServiceDir /var/lib/tor/lnd/
HiddenServicePort 8080 127.0.0.1:8080To avoid convoluting this step, do not worry about any of the other text in that file. Just scroll to the bottom and add those lines in:
Setting Tor User Permissions
Following the Tor configuration, we need to make sure that the user Bitcoin is running on (in my case: satoshi) is included in the “Tor group”.
First, let’s find out the name of the Tor group:
$ grep User /usr/share/tor/tor-service-defaults-torrc
Next, add your user to the Tor group (replace satoshi with your username):
$ sudo usermod -a -G debian-tor satoshiRestart Your Machine
At this point we need to restart the computer, or log out entirely and log back in. The user & group modifications we just made will not apply unless we do so.
Configure Tor To Start During Boot Up
With Tor installed & configured, let’s tell the operating system to start it during boot, via systemctl enable, and then manually start Tor (it runs in the background) via systemctl start:
$ sudo systemctl enable torTor will now start every time the computer boots up, but it’s not running yet, and we aren’t going to reboot again just to start Tor this one time, so let’s start it up:
$ sudo systemctl start torYour computer is now running Tor. Again, all that means is the Tor software is ready to be used by other software. Your internet traffic is still normal unless specific software tries to connect over Tor (like Bitcoin & Lightning).
1-C) Prerequisites & Dependencies
Following the updates and Tor, we’re going to install Git. It’s widely used open-source software designed for handling other open-source (and closed) projects. We’ll be using Git to access the Bitcoin repository and download its code.
Installing Git
satoshi@nakamoto:~$ sudo apt-get install git
Cloning The Bitcoin Core Repository
Make a folder called “code” within our home directory, change to that directory, and then clone the Bitcoin repository.
$ mkdir -p ~/code && cd ~/codeWe could clone Bitcoin into any folder we want, this is just the path I chose to create within the home folder. This will set us up for both this tutorial, and later for the Lightning tutorial.
Navigate to ~/code directory, then clone the repository:
$ cd ~/code$ git clone https://github.com/bitcoin/bitcoin.git
Installing Libraries
Now we need to install some libraries. In this tutorial I’ve split them into groups similar to the build documentation on Github for Ubuntu. Combining certain ones together can produce errors.
Libraries:
$ sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3 libevent-dev$ sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-test-dev libboost-thread-dev$ sudo apt-get install libsqlite3-dev$ sudo apt-get install libminiupnpc-dev$ sudo apt-get install libzmq3-dev$ sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools$ sudo apt-get install libqrencode-dev
Installing The Berkeley Database
Next we’ll install the Berkeley Database. Eventually the Berkeley Database will no longer be necessary, but it’s still required for now. There is a script included in the Bitcoin repository we cloned earlier to install it, located in /bitcoin/contrib . To run it, navigate into the /bitcoin directory, then run the script:
$ cd ~/code/bitcoin$ ./contrib/install_db4.sh `pwd`
This will install the Berkeley DB into /home/satoshi/code/bitcoin/db4 .
When that completes the output should end with the following instructions, which we will use in the next section:
That concludes the prerequisites, now onto actually installing Bitcoin.
Part 2 — Installing Bitcoin & Fully Validating
In this section we’re going to compile Bitcoin Core from the source code, edit the bitcoin.conf configuration file for the purposes of this tutorial, and then finally sync the Bitcoin blockchain over Tor.
Optionally, you may choose to sync the blockchain over the regular clearnet, and then add the Tor configurations into the bitcoin.conf file after the sync is done.
2-A) Compile Bitcoin Core 0.21.1 From The Source Code
(The version installed in this section may change with new releases.)
Navigate to the bitcoin directory we created, checkout the version tags for Bitcoin Core 0.21.1, and then run autogen.sh :
$ cd ~/code/bitcoin$ git checkout tags/v0.21.1$ ./autogen.sh
Pay attention to this step.
If your user is John, change the next line to: /home/john/code/bitcoin/db4
$ export BDB_PREFIX='/home/satoshi/code/bitcoin/db4'$ ./configure BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" BDB_CFLAGS="-I${BDB_PREFIX}/include"
Now for the install. This will take the longest time out of them all. Just let it run and complete:
$ make$ sudo make install
Once that completes you have Bitcoin Core installed!
2-B) Configure The Bitcoin Core Software
(If you’re already running Bitcoin Core you may already have a bitcoin.conf file. Yours will need to be edited to include the settings below. As a reminder, if you have a pruned node you will need to turn in off and sync the entire blockchain.)
Since the purpose of running software over Tor is privacy, we’ll want to make sure that Bitcoin is properly configured to run only over the Tor network so our IP address isn’t revealed to the world. We’ll also want the config file to include the required LND settings. Again, these things can be skipped for those not interested in every aspect of this tutorial.
Alternatively, we can configure Bitcoin to run over both Tor, and the traditional “clearnet”.
Additionally, we may be interested in performing the initial blockchain sync (IBD) over the clearnet for speed, and then switching to Tor afterwards (but before we install and run Lightning).
We’ll cover all options.
Creating The Configuration File
Since we haven’t launched the Bitcoin software yet, the Bitcoin data directory hasn’t been automatically created. It’s a hidden folder, and by default it’s created in the home directory: ~/.bitcoin
Since we need to create a bitcoin.conf file before we launch Bitcoin, we need to manually create this directory. In the terminal enter:
$ mkdir ~/.bitcoinThis folder is where all the blockchain data is stored. If you deleted it, then the next time you launched Bitcoin it would just begin to sync from the beginning, creating all of the data files stored in this directory again as it synced.
Now we’re going use the file manager. Navigate to the home directory and make sure the Hidden Files box is checked so we can see the .bitcoin folder. Then navigate into that folder, create a new text file, and save it as bitcoin.conf :
Copy and paste the following text into that bitcoin.conf file, and then save it:
# Needed for full validation
assumevalid=0# Improves LND performance
# Needs to be set now if you're going to install Lightning later
txindex=1# Allows LND to connect to the Bitcoin node via an RPC user & pass
rpcuser=PICK-A-USERNAME
rpcpassword=PICK-A-PASSWORD# Allows LND & Bitcoin Core to communicate via ZeroMQ
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333## Tor Settings
debug=tor
onlynet=onion
proxy=127.0.0.1:9050
bind=127.0.0.1
dnsseed=0
dns=0## Tor v3 Seedsaddnode=kpgvmscirrdqpekbqjsvw5teanhatztpp2gl6eee4zkowvwfxwenqaid.onion
addnode=bnx4povtqynvwnui5oqm5xcxqvat3j7yzgn6mqciuyszqawhuayvyaid.onion:8333
addnode=wyg7twmf7t3pfvfpdcfd64wvjj2pkccuui7ew34ovnqung5f623b4yyd.onion
addnode=glm52zywiqrcxuwswvgjsxr5pfeggil7uci4z5tbpvb4rjyu5hwjhtid.onion
addnode=xspiicyddsdmzxsffzw6z4f22wi2iwyyufkjcaj2qr7cznxymtft5nid.onion
addnode=nqb5q6d4nhp54ziahhm2oxopqwyyulg7nrqwrcmfvwhj7y7xasaeg7ad.onion
addnode=vp4qo7u74cpckygkfoeu4vle2yqmxh7zuxqvtkazp4nbvjnxl2s3e6id.onion
addnode=ew7x2hv76f7w7irfyektnbhd42eut27ttbfgggu7lbpxsyrlfvsujuqd.onion
addnode=qxkgr5u4rmwme5jticjuuqrecw5vfc5thcqdxvbffwbqgqkdin7s7vid.onion## Tor v2 Seedsaddnode=bitcoinostk4e4re.onion
addnode=bk7yp6epnmcllq72.onion
addnode=qg6embx5o6p4h4it.onion:8333
addnode=trjbor5uc63ghwug.onion:8333
addnode=3eznsanhteo4m2k2.onion:8333
addnode=ajjnxnxjtx6ci4cp.onion:8333
addnode=icbbaj7up3kzk4cl.onion:8333
addnode=n4n5lzeyiyi2755c.onion:8333
addnode=opw6r3lacfd4eyys.onion:8333
addnode=qdwrjk2ow3yjckne.onion:8333
addnode=wjpkhpyt2gd4jtid.onion:8333
addnode=k7ktw2e5mj4r4na5.onion:8333
addnode=zilzmq3jbzdj63md.onion:8333
addnode=4nnijtmfxeueix7s.onion:8333
addnode=s4gy4h3u5zjmpbtr.onion:8333
addnode=33vdhmzdfimfgov3.onion:8333
addnode=aipupphit3enggpj.onion:8333
Now that we have the bitcoin.conf file created, let’s review it and make sure the values are set correctly. Some of the text that was copied above is BOLD. That text needs to be catered to you.
- There is an RPC username and password you need to set. This could be anything you want it to be, but it should also not be too simple. We’ll need to put the same username and password in the LND configuration file later as well.
- The ZMQ settings tell the Bitcoin node to listen for LND (or anything using ZMQ for that matter) over ports 28332 & 28333. Since it will be listening locally (127.0.0.1 is just your own computer, and where LND will be running) so no port forwarding is necessary.
txindex=1creates a transaction index as Bitcoin syncs. This allows LND to reference the transactions it needs faster.assumevalid=0tells Bitcoin Core to validate every transaction from the Genesis block.- The Tor settings, including the .onion seeds, can be removed if you’re not going to run Bitcoin over Tor.
Explaining The Tor Configurations
debug=torwill provide additional Tor information in the logs. This will be useful if we need to diagnose an error, or simply confirm it is working. When we finally launch Bitcoin in the next section, we’ll have a separate terminal open looking for those messages. If everything is running well there should be no errors mentioning Tor after the initial startup.onlynet=onionwill restrict Bitcoin Core outbound connections (to other nodes/peers) to only be over Tor.bind=127.0.0.1will restrict Bitcoin Core inbound connections (from other nodes/peers) to only be over Tor. If you’ve never ran a node before, other peers won’t try to connect to you because they don’t know you exist, but they still could. And if you were already running a node at some point, they might. We don’t want any of that.proxy=127.0.0.1:9050tells Bitcoin Core how to communicate via Tor.127.0.0.1is your local computer, and9050is the SOCKS port that our Tor software is listening on, which we set up earlier via the torrc file.dnsseed=0anddns=0stop Bitcoin Core from trying to connect to the default DNS “seeds” (pic & link below) during bootup. Despite the inbound/outbound restrictions we set above, without these two settings our node will still try to connect to these hosts:
They’re all great people, but we’re not going to pester them!
Instead, we’re going to manually add seeds to connect to. Seeds are just other nodes that help bootstrap our node. And since we are running our node over Tor, and only over Tor, we need to add other node’s onion addresses instead of IP addresses. Once we connect to them, they send us more nodes we can connect to. Eventually our nodes will build up a long list of nodes and will no longer need the seed nodes (you can and should eventually remove them from the bitcoin.conf file).
I’ve provided a list of Tor v2 nodes my current test node is connected to, so as of this tutorial’s publication date, these nodes are up and running and should suffice. Alternatively, here is a much longer list of Tor v2 seeds.
I’ve also provided a list on Tor v3 nodes that were advertised in this Reddit thread.
(Tor v2 will be deprecated near the end of 2021. When that happens I will remove the Tor v2 seeds from this tutorial. Upgrade your node now!)
Alternative Tor Options
We’re setting up our nodes to run only over Tor, but you may want to run your node differently:
- You don’t want to run Tor at all: Just remove all Tor configurations.
- You want to run Bitcoin over the regular Internet and Tor: Remove all the Tor configurations except for
proxy=127.0.0.1:9050. This will remove all of the restrictions the other settings make, but still tell Bitcoin Core that you’re also running Tor and how to connect over it as well as the regular clearnet way. - You want to sync the blockchain over the regular Internet, and then run your node over Tor: Remove all the Tor configurations except for
proxy=127.0.0.1:9050, and then when your node is synced, add the Tor configurations back in. Leaving the proxy setting in should allow your node to grow a list of onion peers for when you do run over Tor later. If you do this, you can exclude the all of theaddnode=seeds from the bitcoin.conf file, or just remove them later.
There are other ways to configure this, but there’s no general reason for them. This covers the main ways people will want to run their Bitcoin full node.
2-C) Starting Up The Software And Syncing The Blockchain
We’re finally going to run Bitcoin, but before we do, let’s open two terminals so we can watch for Tor messages (and hopefully not errors).
In the first terminal, enter the following:
$ touch ~/.bitcoin/debug.log$ tail -f ~/.bitcoin/debug.log
In the second terminal, enter the following:
$ bitcoin-qt & tail -f ~/.bitcoin/debug.log | grep torOnce the GUI launches, you’ll see a full log output in one terminal, and Tor specific logs in the other. Your node should start syncing, and you should see .onion peers connecting in the Peers tab.
If everything was configured correctly, the Tor logs should look like this:
If your output does not look like this, something is not configured correctly. Jameson Lopp has a Tor tutorial that covers a variety of potential errors at the end of it here. If you get an error at this step, don’t hesitate to send me a message, but please review the steps first to make sure they were all followed correctly.
Notes & Anecdotes
If your Tor output matches the output above, you’re essentially done with the Bitcoin step. The node just needs to finish syncing before we move onto Lightning.
You can close the terminal that was used to look for Tor errors. I recommend leaving the other terminal with all the logs open during the sync.
My laptop downloads & syncs the entire Bitcoin blockchain in about 1 day, but over Tor it took a few days to fully sync. This seems to be the result of 2 different things:
- Tor is slower than the regular Internet. Downloading the blocks isn’t always the bottleneck for syncing, but it may be, and since Tor is slower the download may be slower.
- I seem to be having an issue where my node will drop all of the peers it is connected to. The logs will say the peers are “stalling”. This doesn’t stop the sync, but it slows it down enough to add an extra day or two. If you’re extra curious see this open issue on Github, and the comment I added.
Given that issue mentioned above, after about 10–30 minutes of syncing, close down your node and remove all the peers we added in the bitcoin.config file. Your node should have its own list of peers by now, and it should help alleviate an aspect of that issue.
One final thing that is specific to laptops: Debian based operating systems running on laptops (like Ubuntu & Kubuntu) may enter sleep mode if the laptop is left unattended too long. This will cause the sync to stop, delaying the overall time you’ll need to wait before it can finish. The Power Management settings are just a layer on top of the operating system. Those settings only let you customize additional power management functionality, they don’t turn it off at the system level. To prevent this, you’ll want to enter these commands:
$ sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target$ systemctl restart systemd-logind.service
If you’re going to be running your node nonstop you’ll want to keep this set, but to reverse these settings at any time, just enter:
$ sudo systemctl unmask sleep.target suspend.target hibernate.target hybrid-sleep.targetPart 3 — Installing Lightning & Opening Channels
(If you skipped to this section, please make sure you have ZeroMQ installed, and your Bitcoin Core node is not pruned.)
Before we move forward with this tutorial, make sure Bitcoin Core is fully synced. It might take a few days if you just completed the previous step. LND will need Bitcoin Core fully synced before starting up, and the install process takes less than 10 minutes, so just wait for the sync to finish before moving forward.
3-A) Installing ‘Go’ & LND
Installing Go
If you followed this tutorial from the beginning, the only dependency LND will need that we haven’t already installed is Go. We’re going to download the package, extract it, and then install the files into/usr/local/go.
$ wget https://dl.google.com/go/go1.15.6.linux-amd64.tar.gz$ sudo tar -C /usr/local -xzf go1.15.6.linux-amd64.tar.gz
Alternatively, for those who were already on Linux and not using AMD64 architecture, you’ll want to download the correct package from here, and edit the commands above.
Installing LND
Installing LND is simple, but first we’re going to redefine the PATH variable.
(The Lightning beginners guide explains this in detail):
$ echo "export PATH=$PATH:~/go/bin:/usr/local/go/bin" >> ~/.bashrc(If you’re already on Linux, and you’re familiar with the ~/.bashrc file, you may edit this in an alternative way if you know what your doing. Otherwise the command above should be fine.)
Go ahead and close the shell, and then open a new one so it can load the redefined PATH variable we just set.
Move to where we want our LND install directory to be, and then proceed with cloning the LND repository:
$ cd ~/code$ git clone https://github.com/lightningnetwork/lnd
Go ahead and install LND:
$ cd ~/code/lnd$ git checkout tags/v0.12.0-beta$ make install
3-B) Configuring LND & Syncing The Graph
With LND installed, we’re now going to configure it to use our Bitcoin Core node, to run over Tor, and to allow connections from the Zap mobile wallet over Tor. Then we’re going to launch Bitcoin & Lightning and allow the Lightning Graph to sync. When we launch LND we’ll be prompted to create a new wallet and write down the seed phrase before LND can start up.
Configuring The lnd.conf File
We’re going to create a lnd.conf file and copy everything below into it. Before we do that though, let’s cover the changes we’ll need to make:
## LND Settings# Lets LND know to run on top of Bitcoin (as opposed to Litecoin)
bitcoin.active=true
bitcoin.mainnet=true# Lets LND know you are running Bitcoin Core (not btcd or Neutrino)
bitcoin.node=bitcoind## Bitcoind Settings# Tells LND what User/Pass to use to RPC to the Bitcoin node
bitcoind.rpcuser=PICK-A-USERNAME
bitcoind.rpcpass=PICK-A-PASSWORD# Allows LND & Bitcoin Core to communicate via ZeroMQ
bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332
bitcoind.zmqpubrawtx=tcp://127.0.0.1:28333## Zap Settings# Enables LND's REST interface
# Zap mobile wallet will connect over Tor through this interface
restlisten=localhost:8080# Tor Settingstor.active=true
tor.v3=true
tor.streamisolation=true
listen=localhost
LND connects to Bitcoin Core via RPC
One of the ways LND will communicate with our Bitcoin Core node is via RPC, and both the lnd.conf & bitcoin.conf will need to be configured for this.
We’ve already configured the bitcoin.conf file with an RPC username & password earlier, so now we need to tell LND what that username & password is.
Replace the text next to bitcoind.rpcuser= & bitcoind.rpcpass= with the exact same credentials you chose earlier.
Zap connects to LND over Tor via REST
Depending on how Zap connects to LND, it will either use LND’s gRPC interface, or LND’s REST interface. Since this tutorial is all about Tor, we’ll be configuring LND to listen over the REST interface.
If you followed the Lightning Beginners Guide, you’ll need to change your lnd.conf file for this tutorial.
When we launch LND it’s going to create a hidden /.lnd folder where the node’s data and configurations will be placed, similar to the /.bitcoin directory.
We’re going to create that directory in advance, along with the lnd.conf file:
$ mkdir -p ~/.lnd && touch ~/.lnd/lnd.confAnd then we’re going to paste the config text above into that file:
Launching Bitcoin & LND
Launch Bitcoin if it’s not already running and make sure it’s fully synced. If you started the Bitcoin GUI using bitcoin-qt, go ahead and close out the application, and then relaunch Bitcoin using bitcoind. We don’t need or want the GUI any longer:
$ bitcoindNow that Bitcoin is running, wait about a minute (watch the log output) and then open a second terminal and launch LND via the following command:
$ lndCreating The Lightning Wallet
When launching LND for the first time, you’ll be prompted in the terminal to create a wallet before LND can proceed (highlighted at the end of the video above):
[INF] LTND: Waiting for wallet encryption password. Use `lncli create` to create a wallet, `lncli unlock` to
unlock an existing wallet, or `lncli changepassword` to change the password of an existing wallet and unlock it.We need to open a new terminal to enter the command for creating a new wallet (video below). So go ahead and open a new terminal, then enter:
$ lncli createWhen creating the wallet we’ll be prompted for a few different things:
1: Create a password for the wallet file:
Input wallet password:
Confirm password:2: Do you have a seed phrase you want to import? (We will choose ‘n’ for no.):
Do you have an existing cipher seed mnemonic you want to use? (Enter y/n): n3: Encrypt the wallet seed with a passphrase (also known as a 25th word):
Your cipher seed can optionally be encrypted.
Input your passphrase if you wish to encrypt it (or press enter to proceed without a cipher seed passphrase):Whatever you decide to do, write all of this down and keep it safe.
After the wallet is created we’ll see more output from the terminal running LND. It will begin finding other Lighting Network peers and gathering node & channel information. You now have a Lightning node!
3-C) Funding Your Wallet & Opening A Channel
With our Lightning node up and running, and the wallet created, the first thing we’re going to do is generate an address so we can send some Bitcoin to it. LND doesn’t have a GUI, so this will all be through the terminal. Later on the Zap wallet will function as our GUI. After a couple of confirmations, we’ll connect to a node and open a channel with it.
Address Generation & Funding
To generate an address enter the following into a terminal:
$ lncli newaddress np2wkh(If you want to generate a native Segwit address, use p2wkh instead.)
All you need to do now is send Bitcoin to that address displayed in the terminal and wait for a confirmation.
In the meantime, we can check the confirmation status using this command:
$ lncli walletbalanceWhen it finally confirms, you can use the following command to check for how many confirmations your transaction has, among other information:
$ lncli listunspentPicking A Node And Connecting To It
Every node has a “node ID” (a public key), including ours. When we connect with that node, a secure communication line with that node will be established, which will then allow us to securely create a channel with that node. For the purposes of this tutorial I’m going to connect to ACINQ’s Lightning node. You can choose any node you would like, although for your first channel you’ll want to pick a node with decent liquidity. ACINQ’s public key, IP address, and port number can be found on LN browser sites like 1ml.com:
To connect to ACINQ’s node over Tor, enter the following, or replace ACINQ’s public key, IP, and port with your node of choice:
$ lncli connect 03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f@of7husrflx7sforh3fw6yqlpwstee3wg5imvvmkp4bz6rbjxtg5nljad.onion:9735The command format above is [PublicKey] @ [OnionAddress] : [Port] without any spaces or brackets. After entering the command, as seen in the picture below, the LND logs will show you that the connection was established (if successful).
Opening A Channel
Once the connection is established, to open the channel we’ll need to use the command lncli openchannel, but it will require us to specify what node, and the amount. This will be done using the flags --node_key= & --local_amt=.
The following command it what I used:
$ lncli openchannel --node_key=03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f --local_amt=10000When opening a channel, the amount that we enter will specify how large the channel will be, and it will not include the fees required to open that channel. Therefor we cannot use all of the satoshis we just sent to the LN node.
The LN requires a channel’s transaction to have 3 confirmations before it can be used. After opening the channel and receiving the transaction ID, we can use LND to check the confirmation status via this command:
$ lncli pendingchannelsNow that the channel is finally opened, we can begin making payments. You have a functional non-routing LN node. Payments can be made using LND directly, but now we’re going to connect LND to the Zap wallet and use Zap’s interface instead.
Part 4 — Connecting Your Phone & Making Payments
This section will guide you through connecting the Zap mobile wallet for iOS with our LND node over Tor. If you did not install Tor earlier in this tutorial then you will not be able to do this.
The reason we will be using Zap (if you so choose to) is because this is very clearly a Tor-based tutorial, and Zap allows us to connect to our node over Tor while we are on-the-go, away from our computer.
Zap can be found on the iOS store. Just download it, launch it, and put it to the side for now. You may also use the desktop version of Zap if you’d like, but this is strictly for connecting Zap to LND remotely over Tor. Alternative methods for connecting Zap will require different configurations that will not be covered in this tutorial.
4-A) Install ‘LND Connect’ & Connecting Zap To LND
First we will need to install LND Connect, which is a small piece of software that will generate a QR code we will use to connect our Zap wallet to LND. After that we will need get our onion hostname so LND Connect can generate the QR code, and then scan that with our Zap wallet.
Installing LND Connect
To install LND Connect, just run the following commands and make sure you replace ‘satoshi’ with your username:
$ go get -d github.com/LN-Zap/lndconnect$ cd /home/satoshi/go/src/github.com/LN-Zap/lndconnect$ make
Obtain Our Onion Hostname
Since we’ll be connecting Zap to our node over Tor, we won’t need to forward any ports, but we need to tell Zap what our onion address is so it knows how to reach us.
The following command will output the hostname for the LND onion service we are running:
$ sudo cat /var/lib/tor/lnd/hostname
Connecting Zap
With LND running, in a terminal enter the following (replace the bold text with your onion address):
$ cd ~$ lndconnect --host=ONIONADDRESS --port=8080 --image
This will create a QR code image in your home directory with the name lndconnect-qr.png. From your file browser open the image, and then scan it using Zap.
Once it’s scanned Zap will attempt to connect to your node. Since it is connecting over Tor it will take a moment to fully load (see the image in the middle below). If successful you should see a screen showing your node’s current balance:
If Zap cannot connect, you need to review the LND & Tor configuration settings we made earlier.
4-B) Interacting With Your LND Node Via Zap
At this point you may consider the tutorial complete. The remainder of this tutorial will briefly cover using Zap to interact with our LND node, and interacting with the LN ecosystem, such as making payments and balancing our channels.
Using Zap To Control & View Our LND Node
Once Zap connects you’ll be displayed with a Send/Receive screen that shows our node’s total balance, which includes the send capacity of all our channels and whatever remaining Bitcoin we have in our wallet that isn’t currently in a channel.
From the Send/Receive screen, swipe right and then select the Channels menu:
This will display your current channels, their individual capacity, and how they are balanced. Since all we did so far was open a channel, our channel should only have capacity to send payments, like so:
Once you start making payments, you’ll then be able to receive payments as well, and this will be represented like so:
You can also open channels by clicking the + sign at the top right, and close channels by click on the one you want to close and then clicking ‘Close Channel’:
4-C) Balancing Your Channel
Channel balancing is the act of making sure your channels can both readily send and receive Bitcoin. There are some good explainers on the concept that can be found here, and here.
This tutorial isn’t an article on what channel balancing is, but essentially a channel has a total capacity, and the funds are distributed between both ends of that channel. When we opened our channel we funded the entire channel, therefor the capacity is completely on our end.
This means we can currently send Bitcoin, but we can’t receive until we either 1) make some payments through the channel, or 2) intentionally balance our channel.
Balancing is generally more important for routing nodes since they want to be able to actively route payments in both directions at all times, but regular users of the LN may also want to balance their channels so they can readily receive a payment from another user.
Thor from Bitrefill will open a channel to your node with the capacity of the channel on their end, which will allow you to receive payments, or begin your node’s transition to a routing node.
Pool from Lightning Labs is another service designed to help provide inbound liquidity.
Other solutions for inbound capacity may be found here:
4-D) Testing Small Payments
Once you have a channel, making payments on the LN is very easy. Wherever you go to pay, a LN ‘invoice’ will be provided to you, and you just scan or copy it to your wallet by clicking on the “Send” button. This section will simply provide you with a list of places you can make some test payments.
Lightning Websites
The following websites are interesting/unique ways you can interact with Lightning. These are not endorsements of these concepts at scale, or the kind of value they actually provide to the network. They’re just interesting ways you can test payments:
https://satoshis.place/ let’s you draw on a public wall and pay via Lightning.
https://pollofeed.com/ has a live stream of chickens that you can feed.
https://yalls.org/ lets you read posts for a small payment.
Donations
Alternatively you can make a small donation to the Human Rights Foundation over Lightning:
Extra Guidance
In the future you may want to upgrade your Bitcoin & Lightning nodes, or you may need to resync Bitcoin Core for this tutorial because you didn’t have the transaction index (txindex=1) that LND uses for performance, or you may need to recompile Bitcoin Core because you didn’t have thelibzmq3-dev dependency required for LND. The steps below will help you for these scenarios.
How To Create A Transaction Index
If you don’t have a transaction index, you’ll need your node to create one before running LND. If you didn’t have txindex=1 in your bitcoin.conf file then you don’t have a transaction index. There’s two scenarios for creating one:
- Your node is pruned, with no txindex.
- Your node is not pruned, with no txindex.
The first thing you want to do for both scenarios is follow the bitcoin.conf steps in this tutorial and make sure you have txindex=1 set in the config file. When that is complete, follow the proper steps below:
If your node is pruned: Start bitcoind with a reindex and let it resync the whole blockchain:
$ bitcoind -reindexIf your node is not pruned: Just start bitcoind normally and let it create the txindex, now that the bitcoin.conf file has the instructions for your node:
$ bitcoindHow To Recompile/Update Bitcoin Core
Recompiling Bitcoin Core and updating Bitcore Core are essentially the same procedure. We’re going to delete or rename the Bitcoin install directory, and then just reinstall Bitcoin all over again with the newer version.
We do not need to:
- re-sync or re-validate the blockchain
- create the bitcoin.conf file again
- re-install any packages or dependencies (unless you’re specifically recompiling because you did not have
libzmq3-devinstalled, then you would want to install that package first, then recompile Bitcoin Core)
If you followed this tutorial, the install directory is ~/code/bitcoin The non-hidden folder.
If you did not follow this tutorial, the install directory may be ~/bitcoin.
In contrast, the data directory is the hidden folder with the period before the word bitcoin: ~/.bitcoin . Do not delete this folder. Leaving this alone will prevent you from having to re-sync or re-validate the blockchain. Your bitcoin.conf file is there, along with your list of peers, among other things.
If you’re running and old Bitcoin client and want to follow this tutorial, I recommend renaming the install directory to something like “bitcoin-old”, and then just follow the steps from the beginning.
You can double check your client version running this command:
$ bitcoind --versionHow To Update LND
To update LND, open a terminal and enter the following commands.
- Replace satoshi with your username.
- If you followed this tutorial, Go should be installed in your home directory. If not, replace
/home/satoshi/gowith wherever you have Go installed.
$ cd /home/satoshi/go/src/github.com/lightningnetwork/lnd$ git pull$ make clean && make && make install
