Install Lodestar client

One-page interactive guide to install Lodestar client and configurate it for running on supported chain.

Disclaimer

This guide is for informational purposes only. The author nor website owner does not guarantee accuracy of the information in this guide and is not responsible for any damages or losses incurred by following the guide.

Lodestar client can be used for staking on various supported chains. Client installation is always only one, used by services with an individual configuration (different service name, data path and ports in use).

Interactive variables

System:
User:
SSH port:
CPU type:

Execution layer

Client:
Service:
- Data:
- Port:
- P2P:
- RPC:

Consensus layer

Client:
NodeJs version:
jdk ver version:
Beacon service:
- Data:
- Port:
- P2P:
- Quic:

Install Lodestar client

Installing NodeJS through the Node Version Manager

Node Version Manager (NVM) is a piece of shell code that allows you to easily install and maintain different versions of Node.js and its associated packages.
1. Check latest verision of NVM on GitHub.
2. View code of NVM ver 0.39.4
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh
```
3. Install NVM
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash
```
  NVM will be installed with permissions of a user that processing that request (you). NVM is installed to user account, specifically to "~/.bashrc" directory.
4. source/reload nvm for an option to use it
```
source ~/.bashrc
```
5. Check available Node.js versions
```
nvm list-remote
```
  Selected version: v
6. Install requested Node.js version
```
nvm install v20.11.0
```
  Node.js is installed with permissions of a user that processing that request (you)
7. Show active Node.js version in use
```
node -v
```
  If o version is selected, use nvm use 20.11.0
Install build-essential tools
```
sudo apt-get install build-essential -y
```

Install Yarn

corepack enable

corepack prepare yarn@stable --activate

yarn help

Build Lodestar

Download latest Lodestar client from GitHub

cd ~/downloads && git clone -b stable https://github.com/chainsafe/lodestar.git

Install yarn
```
cd lodestar && yarn install
```
Build Lodestart client
```
yarn run build
```
Check builded Lodestar version
```
./lodestar -v
```

Copy new production client to /usr/local/bin directory
```
sudo cp -a ~/downloads/lodestar /usr/local/bin
```

Configurate the service

Configuring lodestarbeacon service user and data directory
- Create a service user
  Service/User name:
```
$ sudo useradd --system --no-create-home --shell /bin/false lodestarbeacon
```
- Enable lodestarbeacon user access NodeJs
  User with NodeJs:
```
sudo usermod -aG myserveruser lodestarbeacon
```
- Create a directory for Lodestar Beacon data
  Service data directory:
```
sudo mkdir -p /var/lib/lodestar/beacon
```
- Set directory ownership
```
sudo chown -R lodestarbeacon:lodestarbeacon /var/lib/lodestar/beacon
```
Communication ports selection

Each service on the server needs a custom port for communication. Through ports, consensus client communicates with other peers in the network as well as other services running on the server, such as validator clients. There is an IPv4 and IPv6 variant, depending on the ISP support / preference. Each protocol version needs custom port. If you are not sure what to select, continue with default IPv4 port.
1. Configurate public IPv4 port for P2P communication with other peers
  - Choose P2P communication port:
  - Verify availability of selected port 9000
    ss -tuln | grep ':9000'
    
    If it returns empty response, the port 9000 is free and can be used.
  - Enable traffic on the port through UFW
    $ sudo ufw allow 9000
  - Disable IPv6 traffic on the port
    
    List allowed ports
    sudo ufw status numbered
    
    Find order number for V6, see 9000 (V6) and remove it with the following line
    sudo ufw delete <Number>
2. QUIC IPv4 port
  - Choose QUIC IPv4 port:
  - Verify availability of selected port 9001
    ss -tuln | grep ':9001'
    
    If it returns empty response, the port 9001 is free and can be used.
3. Beacon API port for internal communication
  - Choose Beacon API port:
  - Verify availability of selected port 5052
    ss -tuln | grep ':5052'
    
    If it returns empty response, the port 5052 is free and can be used.
1. Configurate public IPv6 port for P2P communication with other peers
  - P2P communication port:
  - Verify availability of selected port 9090
    ss -tuln | grep ':9090'
    
    If it returns empty response, the port 9090 is free and can be used.
  - Enable traffic on the port through UFW
    $ sudo ufw allow 9090
  - Disable IPv6 traffic on the port
    
    List allowed ports
    sudo ufw status numbered
    
    Find order number for V6, see 9090 and remove it with the following line
    sudo ufw delete <Number>
2. QUIC IPv6 port
  - Choose QUIC IPv4 port:
  - Verify availability of selected port 9091
    ss -tuln | grep ':9091'
    
    If it returns empty response, the port 9091 is free and can be used.

Create configuration file for the Lodestar beacon service

Open the configuration file

sudo nano /etc/systemd/system/lodestarbeacon.service

Copy following configuration to the file

Installed NodeJs version on the server:
This can be get with command $ node version

[Unit]
Description=Lodestar Consensus Beacon Client (Ethereum mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=lodestarbeacon
Type=simple
Restart=always
RestartSec=5
WorkingDirectory=/usr/local/bin/lodestar
Environment="PATH=/home/myserveruser/.nvm/versions/node/v20.11.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/lodestar/lodestar beacon \
  --network mainnet \
  --dataDir /var/lib/lodestar/beacon \
  --execution.urls http://127.0.0.1:8551 \
  --jwt-secret /var/lib/jwtsecret/ethereum.hex \
  --port 9000 \
  --port6 9090
  #--suggestedFeeRecipient 0x.........................
[Install]
WantedBy=multi-user.target

[Unit]
Description=Lodestar Consensus Beacon Client (Gnosis Chain)
Wants=network-online.target
After=network-online.target
[Service]
User=lodestarbeacon
Type=simple
Restart=always
RestartSec=5
WorkingDirectory=/usr/local/bin/lodestar
Environment="PATH=/home/myserveruser/.nvm/versions/node/v20.11.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/lodestar/lodestar beacon \
  --network gnosis \
  --dataDir /var/lib/lodestar/beacon \
  --execution.urls http://127.0.0.1:8551 \
  --jwt-secret /var/lib/jwtsecret/gnosis.hex \
  --port 9000 \
  --port6 9090
  #--suggestedFeeRecipient 0x.........................
[Install]
WantedBy=multi-user.target

*Note: Update jwt-secret, if you use different

Check all available flags.

Press CTRL + X then Y then ENTER to save and exit the config file.

Reload daemon
```
sudo systemctl daemon-reload
```
Run the service
```
sudo systemctl start lodestarbeacon
```

Monitor the running lodestar Beacon service

systemctl status lodestarbeacon

journalctl -fu lodestarbeacon

Enable auto start on server statup
```
sudo systemctl enable lodestarbeacon
```

Launch validator instance / validator(s)

Instance ID:
Fee Recipient wallet:
Validator Instance service config
- Name:
- User:
- Data:

Do you want to create a new validation instance or extend exisiting instance for more validators?

Create a directory for validator instance data
```
sudo mkdir -p /var/lib/lodestar/vi1
```
Enable accessing /var/lib/lodestar/vi1 for server user myserveruser
```
sudo chown -R myserveruser:myserveruser /var/lib/lodestar/vi1
```
Load keystores to /var/lib/lodestar/vi1
Directory with Deposit Data keystores:
Move to Lodestar client directory
```
cd /usr/local/bin/lodestar
```
```
./lodestar validator import --network mainnet --importKeystores $HOME/keystores/ddk_i1 --dataDir /var/lib/lodestar/vi1
```
```
./lodestar validator import --network gnosis --importKeystores $HOME/keystores/ddk_i1 --dataDir /var/lib/lodestar/vi1
```
- Insert keystores encryption password (the one used during keystores generation) on request
- If there are keystores with different encryption password, repeat the process for each encryption password

Create a service user for the validator instance

sudo useradd --system --no-create-home --shell /bin/false lodestar-vi1

Set ownership of `/var/lib/lodestar/vi1` to `lodestar-vi1` user

sudo chown -R lodestar-vi1:lodestar-vi1 /var/lib/lodestar/vi1

Enable access to NodeJs for user lodestar-vi1
User with NodeJs:
```
sudo usermod -aG myserveruser lodestar-vi1
```

Create configuration service file for `lodestar-vi1` service

Open the configuration file

sudo nano /etc/systemd/system/lodestar-vi1.service

Copy the configuration below into the file.

Installed NodeJs version on the server:
This can be get with command $ node version
What's fee recipient wallet?
What's your execution client?

[Unit]
Description=Lodestar Validator Instance (Ethereum Mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=lodestar-vi1
Group=lodestar-vi1
Type=simple
Restart=always
RestartSec=5
WorkingDirectory=/usr/local/bin/lodestar
Environment="PATH=/home/myserveruser/.nvm/versions/node/v20.11.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/lodestar/lodestar validator \
  --network mainnet \
  --dataDir /var/lib/lodestar/validators/i1 \
  --suggestedFeeRecipient 0xXXXXXXXXXXXXXXXX \
  # ToDo: Add Beacon API URL
  --force \
  --graffiti "Nethermind+Lodestar"
[Install]
WantedBy=multi-user.target

[Unit]
Description=Lodestar Validator Instance (Gnosis Network)
Wants=network-online.target
After=network-online.target
[Service]
User=lodestar-vi1
Group=lodestar-vi1
Type=simple
Restart=always
RestartSec=5
WorkingDirectory=/usr/local/bin/lodestar
Environment="PATH=/home/myserveruser/.nvm/versions/node/v20.11.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/usr/local/bin/lodestar/lodestar validator \
  --network gnosis \
  --dataDir /var/lib/lodestar/validators/i1 \
  --suggestedFeeRecipient 0xXXXXXXXXXXXXXXXX \
  # ToDo: Add Beacon API URL
  --force \
  --graffiti "Nethermind+Lodestar"
[Install]
WantedBy=multi-user.target

Press CTRL + X then Y then ENTER to save and exit the config file.

Adding validator instance to staking services manager

If you use a staking manager client, add the new instance into it.

Stop running validator instance lodestar-vi1
```
sudo systemctl stop lodestar-vi1
```
Extend /var/lib/lodestar/validators/i1 for new keystores
```
./lodestar validator import --network mainnet --importKeystores $HOME/keystores/ddk_i1 --dataDir /var/lib/lodestar/vi1
```
```
./lodestar validator import --network gnosis --importKeystores $HOME/keystores/ddk_i1 --dataDir /var/lib/lodestar/vi1
```
- You will be requested to insert keystores encryption password (the one used during keystores generation)
- If there are keystores with different encryption password, repeat the process for each encryption password
- Already existing keystores in the directory will be skipped

Load processed changes to the system
```
sudo systemctl daemon-reload
```
Start the validator instance
```
sudo systemctl start lodestar-vi1
```

Check the running validator instance

systemctl status lodestar-vi1

journalctl -fu lodestar-vi1

Other configurations
Activate service to start automatically on OS startup
```
$ sudo systemctl enable lodestar-vi1
```
- Configurate Lodestar validator Log monitor service
  
  Log monitor service monitors the service log and process defined action (fixes) in a case of any issue detected.
  1. Check, whether the logmonitor util is installed:
    /usr/local/bin/logmonitor.sh version
    
    If the util is not installed, install Lodestar validator Log monitor from GitHub.
  2. Check defined Errors list for lodestarvalidator service
    sudo nano /usr/local/etc/lodestarvalidator_tracking_records.txt
    
    If not available, download it from GitHub. You can also modifiy it, if needed.
  3. Configurate the validator log monitor for service lodestar-vi1, see guide on Github.
- Activate service to start automatically on OS startup
  
  Our guide uses a custom util for launching services. It has following benefits:
  - It allows set delay for starting services. It eliminates slashing risk in the following scenario:
    
    A database corruption occures
    
    Lodestar Log monitor detects it, stopping the validator instance and clearing broken database
    
    Very quick power failure happens while the staking node starts immediately automatically
    
    As the database with last attestation is removed now, we need to prevent start of the validator instance to avoid double attestation / block proposal within the same slot.
  - It allows starting services through a shared script
    Starting all services through the Staking Manager util and its command /usr/local/bin/staking.sh start execution prevents a human error when there is forgotten set of sudo systemctl enable ... for any staking-related service.
  There's a Start with delay util to manage this.
  1. Install Start with delay util from GitHub, if not installed yet.
  2. Open Start with delay util
    sudo nano /usr/local/bin/delayed-start.sh
  3. Place new services (validator isntance and validator instance monitor) into the file
    lodestar-vi1
    
    lodestar-vi1_logmonitor
  4. Verify, that a service `delayed-start.service` exists and is automatically launched on system start. See GitHub for a guide to do that.
- Extend Staking manager clients.conf
  Insert lodestar-vi1 into clients.conf file that is used by Staking Manager.
```
sudo nano /usr/local/etc/staking/config/clients.conf
```

Exit validator instance / validator(s)

Instance ID:
Fee Recipient wallet:
Validator Instance service config
- Name:
- User:
- Data:

Bulk exit of all validators under the instance (within a directory)

Go to a directory with Lodestar client
```
/usr/local/bin
```

Perform the exit request for validator keystores in certain directory

./lodestar validator voluntary-exit --network mainnet --yes --dataDir /var/lib/lodestar/vi1

./lodestar validator voluntary-exit --network gnosis --yes --dataDir /var/lib/lodestar/vi1