---
# System prepended metadata

title: 'Testnet Bitcoind, CLN, and VLS'

---

## Initial Setup

># Testnet Bitcoind, CLN, and VLS

### First Time Setup Instructions
- Follow the CLN/VLS integration [First Time Setup Instructions](https://gitlab.com/lightning-signer/vls-hsmd/-/blob/main/SETUP.md).

### CLN and VLS Setup
Execute the following sections of `~/lightning-signer/vls-hsmd/vls/contrib/testnet-cln-vlsd/README.md`:
- `Setup bitcoind service`
- `Build vls`
- `Install CLN`
> [Need to install poetry using command: `curl -sSL https://install.python-poetry.org | python3 -` ][Followed by command: `export PATH="/home/user/.local/bin:$PATH"` ]
- `Install remote_hsmd_serial`
- `Make cln user/group`
- `Create a cln config file ...`
- `Create ~cln/.lightning/testnet-env ...`
- `Update ~cln/.lightning/testnet-env to CLN version`
- `Setup the CLN service config` (but don't start `cln-testnet` yet)

#### When `poetry` fails with keyring / dbus / unlock issues:
Needed when `poetry install` fails w/ dbus error blah blah keyring ...
https://github.com/jaraco/keyring#using-keyring-on-headless-linux-systems
Unlock the keyring:
```
dbus-run-session -- sh 
gnome-keyring-daemon --unlock
```
Run `poetry install` to enter user password and test

### Move CLN onto the mirror
Transplant ~cln onto the mirror:
```
sudo mkdir -p /mnt/md0/home
sudo rsync -av /home/cln /mnt/md0/home/
sudo mv /home/cln /home/cln.old
cd /home && sudo ln -s /mnt/md0/home/cln
# make sure ~cln is a happy place
sudo rm -rf /home/cln.old
```

### Install CLBOSS
```
sudo apt update
sudo apt install build-essential pkg-config libev-dev libcurl4-gnutls-dev libsqlite3-dev -y
sudo apt install dnsutils -y
sudo apt install git automake autoconf-archive libtool -y

sudo chown -R user:user /usr/local/src
cd /usr/local/src
git clone --recurse-submodules https://github.com/ksedgwic/clboss.git
cd clboss
git checkout vls-testnet-mods
autoreconf -i
./configure
make -j `nproc`
sudo make install
```

Add to `~cln/.lightning/testnet-config`:
```
important-plugin=/usr/local/bin/clboss
clboss-auto-close=true
```

### Install CLN plugins
Setup plugins
```
sudo pip3 install pyln-client pyln-testing

cd /usr/local/src
git clone --recurse-submodules https://github.com/lightningd/plugins.git && cd plugins

# make sure the summary plugin is ready to go, this should politly demure:
summary/summary.py
```

Add to `~cln/.lightning/testnet-config`:
```
plugin=/usr/local/src/plugins/summary/summary.py
```

### Setup STM32 dev machine

On the machine you will be using to program the stm32 setup the environment [using the directions](https://gitlab.com/lightning-signer/validating-lightning-signer/-/blob/main/vls-signer-stm32/README.md).

These directions should be run from the directory: `~/lightning-signer/vls-hsmd/vls/vls-signer-stm32`


## Mainnet Bitcoind + Electrs: [optional, recommended]

### Bitcoind
[copy testnet configuration, alter for mainnet, run]

Bitcoind might take 50 hours to sync on mainnet.

### Electrs
https://github.com/romanz/electrs/blob/master/doc/install.md
```
sudo apt update
sudo apt install clang cmake build-essential
sudo apt install librocksdb-dev=6.11.4-3
git clone https://github.com/romanz/electrs && cd electrs
cargo build --locked --release --no-default-features

sudo cp target/release/electrs /usr/local/bin
sudo mkdir /home/bitcoin/electrs
sudo chown bitcoin:bitcoin /home/bitcoin/electrs
```

Setup `/lib/systemd/system/electrs.service`:
```
[Unit]
Description=Electrs
After=bitcoind.service

[Service]
WorkingDirectory=/home/bitcoin/electrs
ExecStart=/usr/local/bin/electrs --conf /home/bitcoin/electrs/electrs.toml
User=bitcoin
Group=bitcoin
Type=simple
KillMode=process
TimeoutSec=60
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target
```

Setup `/home/bitcoin/electrs/electrs.toml`:
```
auth = "rpcuser:your-passwd-here"
log_filters = "INFO"
db_dir = "/home/bitcoin/electrs/db"
electrum_rpc_addr = "127.0.0.1:50001"
```

Make it so ...
```
sudo systemctl daemon-reload
sudo systemctl enable electrs
sudo systemctl start electrs

sudo journalctl -u electrs -f
```

Electrs might take {N} hours to sync on mainnet.

## Update CLN and VLS

Use this procedure every time you want to update CLN and/or VLS software.

On the cln host, logged in as `user`:

### Stop `cln-testnet`
```
sudo systemctl stop cln-testnet vls-testnet
    
# check that daemon process are gone:
ps uaxgwww | grep 'cln\|vls'
```

### Update the software

Choose a `vls-hsmd`  version or branch, if unsure use `main`
```
cd ~/lightning-signer/vls-hsmd
git fetch --recurse-submodules
git checkout <your-branch-or-main>
git pull
make setup
```

Execute the following sections of `~/lightning-signer/vls-hsmd/vls/contrib/testnet-cln-vlsd/README.md`:
- `Build vls:`
- `Install CLN:`
- `Install remote_hsmd_serial`
- `Update ~cln/.lightning/testnet-env to CLN version`
- Check config in `~cln/.lightning/testnet-{env,config}`

### OPTIONAL - remove cln state, only do this is you want to start over
```
sudo rm -rf ~cln/.lightning/testnet
```

### Update signer software

On stm32 dev machine ...

Connect a USB cable between the `ST_LINK` port on the stm32 and the dev machine. Test that it's recognized with `lsusb` on the dev machine.  You should see a line like:
```
Bus 001 Device 073: ID 0483:374b STMicroelectronics ST-LINK/V2.1
```

If you don't see the ST-LINK in the `lsusb` output try different USB cables, some are "charge only" ...

Build and load the VLS software:

```
cd ~/lightning-signer/vls-hsmd/vls
git fetch --recurse-submodules
git checkout main # or other
git pull
cd ~/lightning-signer/vls-hsmd/vls/vls-signer-stm32
cargo run --features stm32f413 --bin demo_signer --release
```
[note - using `--features debug` may cause heap overrun ...]

Remove `ST_LINK` cable. [OPTIONAL - Leave on for debug logging]

### Connect signer to CLN host with serial cable

Move the power jumper on the STM32F413 to `5V_USB_FS` as described in section `5.2.3 Power Supply` in the [UM2135 User manual](https://www.st.com/resource/en/user_manual/um2135-discovery-kit-with-stm32f413zh-mcu-stmicroelectronics.pdf).

Connect the `User USB` port to a USB port on the CLN host.

The demo signer should power up and wait at the intro screen.

### OPTIONAL - consider creating/switching/deleting demo_signer state

Hold blue button down while resetting, use setup menu.

Consider creating new `testnet` node.

Consider setting `PERMISSIVE` mode on the node.

### Start `cln-testnet`

On the cln host, logged in as `user`:

First, run in separate shells to monitor:
```
sudo journalctl --follow -u cln-testnet
sudo tail -F ~cln/.lightning/testnet/remote_hsmd_serial.log
sudo tail -F ~cln/.lightning/testnet/lightning.log
```

Light the fuse ...
```
sudo systemctl start cln-testnet
```

### Status Check:
Good command for quick status check:
```
for svc in \
bitcoind \
electrs \
bitcoind-testnet \
cln-testnet \
vls-testnet \
; do SYSTEMD_COLORS=1 systemctl status $svc | head -n 3; done
```

## Node Operation

### But First ...

On cln host logged in as `user`, become `cln`
```
sudo su cln
exec bash
cd
```

### Check state:
```
lightning-cli --testnet getinfo
lightning-cli --testnet summary
```

### Fund node:
```
lightning-cli --testnet newaddr
# send tBTC to addr, wait for {N} confirmations
```

### Prime the pump w/ a manual channel (ensures gossip):
Use https://1ml.com/testnet to find:
- a recently updated channel ...
- ... connected to a node w/ multiple channels ...
- ... and an IPV4 connection suffix

Connect and fund a minimal channel to that node:
```
lightning-cli --testnet connect 027455aef8453d92f4706b560b61527cc217ddf14da41770e8ed6607190a1851b8@3.13.29.161:9735
lightning-cli --testnet fundchannel 027455aef8453d92f4706b560b61527cc217ddf14da41770e8ed6607190a1851b8 0.04btc
```

### Status Commands

#### Summary
```
lightning-cli --testnet summary
```

#### Peer Status
```
lightning-cli --testnet listpeers | less
```

#### CLBOSS Status
```
lightning-cli --testnet clboss-status | less
```

