Add Teku validator

One-page interactive guide to install Teku 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.

Teku 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).

Launch validator instance / validator(s)

  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/teku/vi1

    • If exists, remove deposit_data file from keystores folder

      :
      • Display files in the directory 
        cd $HOME/keystores/ddk_i1 && ls -lh
      • If there is deposit_data-XXX....json file, remove it 
        sudo rm deposit_data-XXX....json

    • Copy keystores dedicated for instance into /var/lib/teku/vi1/keystores folder

      sudo mkdir /var/lib/teku/vi1/keystores
      sudo cp -a $HOME/keystores/ddk_i1/* /var/lib/teku/vi1/keystores && cd /var/lib/teku/vi1/keystores

    • Teku requires a .txt file with encryption password for each .json validator file.

      1. Display all keystores in the directory 
        ls -lh

      2. .json

        Create a new .txt file for the keystore-m_12381_3600_X_0_0-XXXXXXXXXX.json keystore file

        sudo nano keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

        Insert an encryption password for the validator key (the one used during keystores generation) into that file.

        Press ctrl + x, then y to save and exit

      3. Set readonly permission for that file 
        sudo chmod 400 keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

      Now, you can either repeate the process for all other keystores in the folder, or use an automated solution to duplicate the created password file (with modified name) for all remaining keystores, see Shell Script to generate password files for Teku.

      With automated process, to generate .txt file with a content of /var/lib/teku/vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt for all remaining keystores in the /var/lib/teku/vi1/keystores/ directory, use command 

      sudo /opt/teku-create-validator-psw-files.sh /var/lib/teku/vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

    • Create a service user for the validator instance

      sudo useradd --system --no-create-home --shell /bin/false teku-vi1
    • Set ownership of validator instance data directory to validator-instance user 
      sudo chown -R teku-vi1:teku-vi1 /var/lib/teku/vi1

    • Create configuration service file for teku-vi1 service

      1. Open the configuration file 
        sudo nano /etc/systemd/system/teku-vi1.service
      2. Copy the configuration below into the file. 
        [Unit]
Description=Teku Validator Instance (Ethereum Mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=teku-vi1
Group=teku-vi1
Type=simple
Restart=always
RestartSec=5
Environment="JAVA_OPTS=-Xmx8g"
Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
ExecStart=/usr/local/bin/teku/bin/teku validator-client \
  --network mainnet \
  --beacon-node-api-endpoint http://127.0.0.1:5051 \
  #--beacon-node-api-endpoint http://127.0.0.1:5051,http://192.10.10.101:5051,http://192.140.110.44:5051 \
  --data-path /var/lib/teku/vi1 \
  --validator-keys /var/lib/teku/vi1/keystores:/var/lib/teku/vi1/keystores \
  --validators-proposer-default-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --validators-graffiti "Nethermind+Teku"
[Install]
WantedBy=multi-user.target
        [Unit]
Description=Teku Validator Instance (Gnosis Network)
Wants=network-online.target
After=network-online.target
[Service]
User=teku-vi1
Group=teku-vi1
Type=simple
Restart=always
RestartSec=5
Environment="JAVA_OPTS=-Xmx8g"
Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
ExecStart=/usr/local/bin/teku/bin/teku validator-client \
  --network gnosis \
  --beacon-node-api-endpoint http://127.0.0.1:5051 \
  #--beacon-node-api-endpoint http://127.0.0.1:5051,http://192.10.10.101:5051,http://192.140.110.44:5051 \
  --data-path /var/lib/teku/vi1 \
  --validator-keys /var/lib/teku/vi1/keystores:/var/lib/teku/vi1/keystores \
  --validators-proposer-default-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --validators-graffiti "Nethermind+Teku"
[Install]
WantedBy=multi-user.target

    • Stop running validator instance teku-vi1

      sudo systemctl stop teku-vi1

    • If exists, remove deposit_data file from keystores folder

      :
      • Display files in the directory 
        cd $HOME/keystores/ddk_i1 && ls -lh
      • If there is deposit_data-XXX....json file, remove it 
        rm deposit_data-XXX....json

    • Copy keystores dedicated for instance into /var/lib/teku/vi1/keystores folder

      sudo mkdir /var/lib/teku/vi1/keystores
      sudo cp -a $HOME/keystores/ddk_i1/* /var/lib/teku/vi1/keystores/keystores  && cd /var/lib/teku/vi1/keystores

    • Teku requires a .txt file with encryption password for each .json validator file.

      1. Display all keystores in the directory 
        ls -lh

      2. .json

        Vreate a new .txt file for the keystore-m_12381_3600_X_0_0-XXXXXXXXXX.json keystore file

        nano keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

        Insert an encryption password for the validator key (the one used during keystores generation) into that file.

        Press ctrl + x, then y to save and exit

      3. Set readonly permission for that file 
        sudo chmod 400 keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

      Now, you can either repeate the process for all other keystores in the folder, or use an automated solution to duplicate the created password file (with modified name) for all remaining keystores, see Shell Script to generate password files for Teku.

      With automated process, to generate .txt file with a content of /var/lib/teku/vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt for all remaining keystores in the /var/lib/teku-vi1/keystores/ directory, use command 

      $HOME/bashscripts/create-teku-pswfiles.sh /var/lib/teku/vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

  2. Load changes made in config files to the system

    sudo systemctl daemon-reload

  3. Start the validator instance

    sudo systemctl start teku-vi1

  4. Check the running validator instance

    systemctl status teku-vi1
    journalctl -fu teku-vi1

  5. Activate service to start automatically

    sudo systemctl enable teku-vi1
    1. Open Delayed Start shell 
      sudo nano /usr/local/bin/delayed-start.sh
    2. Attach command to remove lock files (to prevent start the validator in a case of existing lock fiels after a power failure). This must be processed before starting the validator service. 
      /usr/local/bin/remove-lock-files.sh '/var/lib/teku/vi1/keystores'
    3. Configurate service start inside it 
      systemctl start teku-vi1.service
    4. Be sure, delayed-start.service service controlling delayed-start.sh is enabled for auto start with system startup 
      sudo systemctl enable delayed-start.service

    1. Configurate Staking Manager util

      • Open the configuration file 
        sudo nano /usr/local/etc/staking/config/clients.conf

        If the file is empty, generate it with command sudo /usr/local/bin/staking.sh init

      • Set link to proper services. It should be as follow: 
        validatorServices="teku-vi1.service"

    2. Activate service to start automatically on OS startup

      • Open Start with delay util 
        sudo nano /usr/local/bin/delayed-start.sh
      • Attach command to remove lock files (to prevent start the validator in a case of existing lock fiels after a power failure). This must be processed before starting the validator service. 
        /opt/remove-teku-validator-lock-files.sh '/var/lib/teku/vi1/keystores'
      • Place or uncomment a command to start the Validator instance(s), if not made yet 
        /usr/local/bin/staking.sh start validators
      • Verify, that the service `delayed-start.service` exists and is automatically launched on system start. 
        sudo systemctl enable delayed-start.service