This bot sends your lightning node's live HTLC events as they occur. By default it sends everything, which can get noisy, so it has a /filter command, to selectively filter the events you are interested in.
It also stores your HTLCs in a database file, so that it can send you reports.
e.g
It is easy to use, and thus accessible to non-developers.
As a good node operator, you'll want to keep an eye on failed HTLC events (link_fail_event). These take place when your node fails to route. Minimizing those via the proper use of balanced channels, or the proper use of fees does two things, with two broad consequences:
- It increases the likelihood of the network routing via your node.
- Thus boosts your chances to earn sats.
- It increases the overall health of the network.
- Thus increases the chances of lightning growing healthily, and ultimately succeeding.
"It appears that even after 25 retries, temporary errors are still the most common".
Exerpt from 'Understanding the Lightning Network capability to route payments' (pdf).
The first step to solving a problem is identifying it. This bot does that for you.
Run this so the bot can initiate chats with you.
Start receiving events.
Stop receiving events.
Filter the events to only the ones you're interested in.
List available commands, and get help on using them.
The /filter command takes a jq string. Examples are provided by running the /help command.
The bot has a 'plugin' ability, so other devs and technical users can write their own commands by just copying an existing plugin and modifying it. Current plugins are:
Export HTLCs as csv file and send.
Export HTLCs as excel file and send.
Generate plots of incoming and outgoing link fail event channels
Generate a bar chart of SEND forward and fail events, and send.
In Telegram, make sure you first create a bot with Bot Father, and take note of your Bot's token. Secondly, have a quick glance at the code or ask a developer to quickly audit the code before running it on your node. Don't trust, verify.
# ssh into your lightning node
ssh me@node_ip_address
# create a src directory
mkdir -p src
# enter the src directory
cd src
# clone this repo
git clone https://github.com/PLEBNET-PLAYGROUND/stream-lnd-htlcs-bot.git
# enter the cloned repo
cd stream-lnd-htlcs-bot
# install the dependencies
pip3 install -r requirements.txt
# run the bot
./stream-lnd-htlcs-bot.py --tg-token <Bot's TG TOKEN>
# same command but for umbrel users:
./stream-lnd-htlcs-bot.py --tg-token <Bot's TG TOKEN> --lnd-dir /home/umbrel/umbrel/lnd
In telegram, you should now be able to run the /connect command, followed by the /start command.
If you get a response, you should be good.
If the bot is responding to you, the final step is making sure the process keeps on running in the background, even after your ssh session ends.
The most hacky way of doing this:
nohup ./stream-lnd-htlcs-bot.py --lnd-dir /home/umbrel/umbrel/lnd --tg-token MY_TG_TOKEN > /dev/null 2>&1 & disown
If you ever need to kill the process, you can safely do so:
pkill -f stream-lnd-htlcs-bot.py
A somewhat more standard way of deploying the bot is systemd.
# install the service file
sudo cp stream-lnd-htlcs-bot.service /etc/systemd/system/stream-lnd-htlcs-bot.service
# ask systemd to reload the service files
sudo systemctl daemon-reload
# get service status
sudo systemctl status stream-lnd-htlcs-bot
# enable service for boot
sudo systemctl enable stream-lnd-htlcs-bot
# start service for boot
sudo systemctl start stream-lnd-htlcs-bot
# disable service
sudo systemctl disable stream-lnd-htlcs-bot
# stop
sudo systemctl stop stream-lnd-htlcs-bot