Skip to main content

11.5 Switch Clients

Client diversity refers to the use of multiple independent software implementations across a network, written by different teams and with different coding languages. Through the diverse setup, the network security is improved, and the risk of single points of failure get reduced as errors in a single client do not affect the overall network's security.

tip

Further details can be found on the Client Diversity page of the 🧠 Theory section

Client Imbalances

The majority of nodes on the LUKSO network is running Geth and Prysm setups. Node operators are responsible to ensure they split their client usage evenly across officially supported clients to improve resilence of the blockchain. If you are in a position to do so, you should adapt your client setup to ensure greater diversity.

info

The following steps are performed on your 📟 node server.

1. Stop Node Operation​

Depending on your setup method, there are different ways to stop your node before applying updates.

cd <lukso-working-directory>
lukso stop
info

Exchange <lukso-working-directory> with the path of the node folder.

Force Client Shutdown
sudo pkill geth

2. Switch Client Software​

Depending on whether you're switching only the execution client or both execution and consensus clients, the process and complexity will vary. While execution clients can be swapped directly within the existing node folder, changing the consensus client requires a full validator reconfiguration and monitoring updates.

TypeDescription
Execution Client Only Replaces client binary and reinitalizes the node folder while keeping the validator setup.
Execution and Consensus Requires new folder setup, new validator wallet, and firewall reconfiguration.
info

If you switch the consensus client, you must re-import your keystore-xxx.json key files generated within the Validator Setup. Additionally, you also have to update the Prometheus Ports, Prometheus Service, and Grafana Dashboard, as the monitoring software will not be able to read from the old consensus ports.

2.1 Navigate into the Node Folder: Move into the node's working directory to initialize your node clients.

cd ./<lukso-working-directory>

2.2 Remove Old State: Delete client-specific blockchain state and logs, and re-initialize the folder.

# Remove Blockchain Data
rm -rf <network>-data

# Remove Logs
rm -rf <network>-logs

# Initialize the Folder
sudo lukso init
tip

The lukso init command only adds missing files within the /configs/ folder without overwriting existing ones.

2.3 Install Client: Select and install a minority execution client alongside your old consensus client.

lukso install

Check if both clients were installed correctly using their version commands:

geth --version
info

If you encounter errors during the download or checkups, re-do the installation process.

3. Apply Client Modifications​

In case you did any modifications to your previous client configuration files, please re-apply them to your new client configuration files within the config folder of your node directory before starting up your updated validator node. Modifications may include:

4. Restart the Validator​

After installing and configuring the new client setup, you can start up the node again.

# Starting the Mainnet Node as Validator
lukso start --validator --transaction-fee-recipient "<transaction-fee-recipient-address>"

# Starting the Testnet Node as Validator
lukso start --validator --transaction-fee-recipient "<transaction-fee-recipient-address>" --testnet
info

Replace <transaction-fee-recipient-address> with your actual withdrawal address.

After the clients were started, verify that their services are still up.

sudo lukso status

5. Data Cleanup​

After switching clients, unused files and binaries can be removed from the old setup to avoid conflicts and free up storage.

Delete Old Client: Remove the unused execution client service from the system.

sudo rm -rf /usr/local/geth