Here is a simple short guide on how to setup and operate a bitcoin and lightning node with tor. If you already are setup with Core Lightning, you can skip to the section "#Operating Core Lightning" for a simple guide on how to use Core Lightning.
Requirements: You will need a computer with linux and alot of storage space to accommodate the current size of the blockchain with consideration for future growth. A spare dedicated USB drive for the lightning channel backups. You also must know the basics on how to use a computer. If you do not know basic linux commands, learn!
Step 1 - Setup Tor a. Install the latest version of tor (tor standalone, not Tor Browser) you can install tor using your package manager, or from torproject.org b. Verify the integrity of the source code using GPG c. Configure tor, the config file by default is at ~/.tor/torrc if this does not already exist, create it. Put this in your tor config file:
d. Start tor. To stop tor you can ctrl+c in the terminal it is running in.
Step 2 - Setup a Bitcoin node a. Download the latest version of Bitcoin Core from bitcoincore.org b. Verify the integrity of the source code using GPG c. Configure your node, the config file by default is located at ~/.bitcoin/bitcoin.conf if this does not already exist, create it. Put this in your bitcoin config file
You can optionally uncomment #proxy if you want the bitcoin core to make connections through tor only.
d. start bitcoind. To stop bitcoin you can use the command bitcoin-cli stop e. Wait a long time for bitcoin to fully sync with the blockchain. You can see the status with the command bitcoin-cli -getinfo Using wifi to sync with the bitcoin network is discouraged. Wifi is often times slow or unreliable. Use a wired network connection. The time to sync will vary, for me it took around 24 hours when I did a full blockchain sync in 2023.
Step 3 - Setup Core Lightning WAIT FOR BITCOIN TO FULLY SYNC BEFORE PROCEEDING a. Download the latest version of Core Lightning from corelightning.org b. Verify the integrity of the source code using GPG c. Plug in a dedicated USB drive to use for your lightning channel backups. Keep this USB drive always plugged in and mounted when your lightning router is running. If the local channel state on your computer gets corrupted, you could lose all the money in that channel if you don't have a backup. The USB drive will maintain a mirrored and up to date backup of your local channel states, this is to protect you if your harddrive crashes. Also backup the file ~/.lightning/bitcoin/hsm_secret and the file ~/.lightning/bitcoin/accounts.sqlite3. Update the backup for the file accounts.sqlite3 everytime you open or close a channel. d. Configure your lightning node, the config file by default is located at ~/.lightning/config if this does not already exist, create it. Put this in your lightning config file. Replace the things in brackets and all caps with the appropriate entries. You can also adjust your default feerate in the section fee-base and fee-per-satoshi.
#log-level=debug
log-file=/home/[USERNAME]/.lightning/ln-log.txt
proxy=127.0.0.1:9050
bind-addr=127.0.0.1:9735
addr=statictor:127.0.0.1:9051
always-use-proxy=true
bitcoin-cli=[FILEPATH TO YOUR BITCOIN-CLI BINARY]
wallet=sqlite3:///home/[USERNAME]/.lightning/bitcoin/lightningd.sqlite3:/[FILEPATH OF YOUR BACKUP DRIVE]/lightningd.sqlite3
alias=[CHOOSE A NICKNAME FOR YOUR NODE]
fee-base=0
fee-per-satoshi=200
min-capacity-sat=100000
watchtime-blocks=500
max-locktime-blocks=2016
d. start lightningd. To stop lightning you can use the command lightning-cli stop
Now that you are setup, the procedure upon boot is to start tor, then start bitcoin, when bitcoin is caught up with blocks, start lightning. Before turning off your computer, it is the reverse, turn off lightning then bitcoin then tor. Depending on the setting you put in watchtime-blocks, and if you are using a watchtower service or not; you don't want your lightning router offline for more than a few days at a time. It is best to have your lightning router online majority of the time or always online.
#Operating Core Lightning I will now explain how to use your lightning node. This is just the basic functionality and what you will use most of the time, for more advanced functionality and options, read the manual for Core Lightning.
For viewing your open channels, node status, balances and more,you can use this tool I made https://github.com/nakoshi-satamoto/ln-term Using it is as simple as ./ln-term.sh or watch ./ln-term.sh
To view your current onchain funds: lightning-cli listfunds For onchain funds, look for entries under "outputs", not "channels".
To generate a deposit address: lightning-cli newaddr
To withdraw funds: lightning-cli withdraw [DESTINATION BTC ADDRESS] [AMOUNT IN SATOSHIS] urgent 0 Instead of a certain amount in sats, you can alternatively use 'all' to withdraw all funds. The 0 at the end means that you are telling Core Lightning it is fine to spend unconfirmed UTXOs. example: lightning-cli withdraw bc1q.notarealbitcoinaddressvftm9rlms all urgent 0
To open a chan: First connect to the peer you want to open a chan to lightning-cli connect [PEER ID]@[ADDRESS:PORT] example: lightning-cli connect 020a128145c54dec1c1d72e9bf0ec26759d1e16b9a7bba1453e1fc2b4cec6a6fbd@93.95.231.89:9735 Now you can open a channel to that peer lightning-cli fundhchannel PEER ID] [AMOUNT IN SATS] urgent example: ./lightning-cli fundchannel 038e5677dc7d1ec4e9a82bd004d524b2469fedb0867e85bd1e2f5d3352957e03b7 500000 urgent
To close a chan: lightning-cli close [PEER ID] then lightning-cli disconnect [PEER ID] For peer ID in the close command you can use the long peer ID or the channel short ID as shown in ln-term example: lightning-cli close 822500x1337x1
To pay an invoice: To decode an invoice to confirm the details before paying lightning-cli decodepay [LIGHTNING INVOICE HERE] To then pay lightning-cli pay [LIGHTNING INVOICE HERE]
To generate an invoice: lightning-cli invoice [AMOUNT IN MSATS OR SATS] [LABEL] [DESCRIPTION] The label is private and seen only by you, the description is seen by the sender. example: lightning-cli invoice 5000sats "invoice-001" "box of ammo"
To check the status of generated invoices: lightning-cli listinvoices
To update fees: lightning-cli setchannel id=[PEER ID OR SHORT CHANNEL ID] feebase=[AMOUNT] feeppm=[AMOUNT] For id, you can alternatively use 'all' to apply to all channels. examples: lightning-cli setchannel id=829535x1607x0 feebase=0 feeppm=200 lightning-cli setchannel id=03eaf4f94ad680855a7818c2f156ae4a86482dea2f396320c336989ce5f49da880 feebase=0 feeppm=200 lightning-cli setchannel id=all feebase=0 feeppm=500
If you want to use QR codes with your lightning node, you can do so with the software utilities zbarcam and qrencode. To scan a QR code: zbarcam To generate a QR code qrencode ["WHAT YOU WANT TO ENCODE"] -o [NAME OF OUTPUT FILE]
LN-term was originally announced in this post https://lightningnetwork.plus/posts/534. At the time ln-term was in testing phase, and the git repo was blocked by github in mistake. After multiple updates and improvements and testing, I no longer consider LN-term to be beta software. LN-term can be downloaded here https://github.com/nakoshi-satamoto/ln-term
LN-term is a simple shell script to serve the role as a terminal interface dashboard for Core Lightning. LN-term shows alot of useful information at a glance including a list of all channels and the balance on each side of the channels. Along with the ability to input labels in place of public IDs for nodes. LN-term has almost no dependencies, the only dependency being jq for working with json output. As such, this script does not have a software supply chain risk with massively horrendous dependency trees like python applications do. The code being a shell script, is transparent and also aims to be tiny so that it is very easy to audit easily and rapidly. The comments and documentation within the script are more than the actual lines of code itself. In fact, the actual number of lines of code in this script are around just 40 lines currently.
ln-term is a simple shell script to serve the role as a terminal interface dashboard for Core Lightning. ln-term shows alot of useful information at a glance. The most useful functionality and what I initially created this for, was to view a list of all my channels and the balance on each side of the channels. To easily identify peers, it also has the ability to program aliases in place of public keys. chan-view.png86.5 KB As an operator of Core Lightning, I wanted a way to visualize my channels, connected peers, and channel balances within the terminal. But I did not want to use one of the many available python plugins due to their heavily complex and huge dependency trees. Python applications in my opinion are a horrendous dependency nightmare with a known high risk of software supply chain compromise. If you want a frustrating challenge, try verifying the integrity of and then compiling an entire dependency tree from source for a python app. The more minimal an application is, the less vulnerable it is to supply chain attacks, and the less of an attack surface it has. When dealing with applications that handle money, security is critical. Simplicity and minimal dependencies are a desirable trait for security.
This is a simple shell script I typed together that utilizes jq for presenting information visually in the terminal for Core Lightning. The only dependency is jq for parsing json. And jq is in itself also minimal software and easy to compile from source-code if you feel the need to. With ln-term being a shell script, it also has the benefit of being transparent and does not need compiled. Making it very easy for anyone to audit and modify.
The release is signed using my nodes public key and can currently be found at my github repository I created for ln-term so that others can contribute to and improve it. https://github.com/nakoshi-satamoto/ln-term If you wish to contribute to this script or to request a copy of the latest version without using github; you can contact me.
It is my hopes that this tool I crafted can be of high benefit to other node operators.
------------------------------------ Edit (timestamp: block 832160) Github censored my account and repo without explanation. I submitted an appeal to github but it is uncertain if they will reply or even undo this action of theirs. I am seeking a freedom alternative to github. In the meantime, I can be emailed for proposed updates to this script and for the copy if needed. The initial version of this shell script can also be downloaded using these links below in the meantime while I find a git host I can use.
signature.txt: https://lightningnetwork.plus/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXI5QVE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--b63c73c4a92ef3609bd229ed0a82acaebfa559cd/signature.txt ------------------------------------ Edit (timestamp: block 833443) This repo is now unbanned by github after I submitted an appeal. One of githubs automated things did not like my account originally. I can only guess why, maybe because I signed up for github using tor. This article has the original script attached. Refer to the git repository for any future updates. ------------------------------------
