Add Lodestar validator

Launch validator instance / validator(s)

Validators are defined by validator keys. Based on the network you are going to stake on, check Gnosis validator keys / Ethereum validator keys generation guide.

1. 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 nodejsusr lodestar-vi1

   • Create configuration service file for lodestar-vi1 service

     1. Open the configuration file

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

     2. 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/nodejsusr/.nvm/versions/node/v22.16.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/nodejsusr/.nvm/versions/node/v22.16.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

     3. 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

2. Load processed changes to the system

   sudo systemctl daemon-reload

3. Start the validator instance

   sudo systemctl start lodestar-vi1

4. Check the running validator instance

   systemctl status lodestar-vi1

   journalctl -fu lodestar-vi1

5. Other configurations

   Activate service to start automatically on OS startup

   $ sudo systemctl enable lodestar-vi1

   • Open Delayed Start shell

     sudo nano /usr/local/bin/delayed-start.sh

     Configurate service start inside it

     systemctl start lodestar-vi1.service

   • Be sure, delayed-start.service service controlling delayed-start.sh is enabled for auto start with system startup

     sudo systemctl enable delayed-start.service

   • 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:
       1. A database corruption occures
       2. Lodestar Log monitor detects it, stopping the validator instance and clearing broken database
       3. Very quick power failure happens while the staking node starts immediately automatically
       4. 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 validators prevents a human error when there is forgotten set of sudo systemctl enable ... for any staking-related service.

       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

     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. Place command to start all validator services, if not attached yet

        /usr/local/bin/staking.sh start validators

     5. Verify, that a service `delayed-start.service` exists and is automatically launched on system start. See GitHub for a guide to do that.