HackMDComprehensive guide to setting up a distributed Lido CSM validator cluster with Obol Network
The Community Staking Module (CSM) is the first permissionless module in the Lido protocol, allowing anyone to start running validators on the Ethereum blockchain with much greater capital efficiency compared to running a regular ("vanilla") Ethereum validator.
A distributed validator (DVT) is an Ethereum validator that runs on more than one node. Obol Network is a set of tools providing permissionless access to running distributed validators.
This tutorial uses the Holesky testnet for demonstration purposes, but the same steps can be applied to the mainnet.
Hardware & system requirements
- CPU: Quad-core
- RAM: 16GB
- Storage: 512GB NVME SSD (For mainnet at least 2TB)
A full guide to setting up your operating system can be found here or here. For this tutorial, I'm assuming that all cluster members are running Linux with Git and Docker installed, and have properly secured their servers.
Getting started
Creating a trust-minimised distributed Valdator cluster requires a multi-sig wallet for management, a split contract to distribute rewards to operators, and the client software needed to run the Obol DVT - Charon. Operators also need a full Ethereum node with an execution and consensus client of their choice, and the MEV-boost client configured with at least one of the Lido approved relays.
The Charon client
Charon (pronounced 'kharon') is the software that allows validators to be run on a group of independent nodes - a cluster. A complete multi-container Docker setup including execution client, consensus client, MEV-Boost and the Charon client can be found in this repository https://github.com/ObolNetwork/charon-distributed-validator-node and the first step is to clone it:
git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git
Make sure your user has the docker role. If not you can use this command to add it:
sudo usermod -a -G docker $USER
You will then need to exit the ssh session and log in again.
Finally, you will need to create the Charon data folder and the .env configuration file:
cd charon-distributed-validator-node
mkdir .charon
cp .env.sample.holesky .env
Preparing the ENR (Ethereum Node Record)
All cluster members will need an ENR (Ethereum Node Record) to connect to the Obol Network. To create an ENR the operator can use this code:
docker compose run --rm charon create enr
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Creating the DV cluster wallet
Detailed instructions on how to create a Safe Wallet can be found here. The Holesky Testnet Safe deployment can be found at this address: https://holesky-safe.protofire.io
One of the cluster members should obtain the signer addresses from all the cluster members, then connect his signer wallet and choose to create a new Safe.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
After giving the Safe a name and selecting the Holesky network, he continues by clicking the Next button.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Then he adds all the signer addresses of the cluster members and proceeds to the final step by clicking the Next button.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Finally, he sends the transaction to create the Safe by clicking on the Create button.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Creating the reward split contract
One of the cluster members should obtain the reward addresses from all the cluster members. Then he should open https://app.splits.org and select to create a new contract. Then he should select Holesky for the network.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Select Split for the contract type.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Add the reward addresses of all cluster members. Then he can choose whether the contract is immutable (recommended option), whether he wants to sponsor the maintainers of splits.org, and whether there is a distribution bounty so that third parties can distribute the rewards in exchange for a small fee.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Finally, click the Create Split button, execute the transaction and share the created split contract with all cluster members for review.
Creating the DV cluster
The official Obol documentation contains detailed instructions on setting up a distributed cluster. Theare two main steps:
- Performing the Distributed Key Generation Ceremony
Creating the cluster configuration
One of the cluster members opens the Holesky DV Launchpad at this address - https://holesky.launchpad.obol.org, then connects his wallet and chooses to create a Cluster with a group button.
- Creating the cluster configuration
Image Not Showing Possible Reasons
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Then he clicks on the Getting Started button on the next page.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Accepts all the necessary advisories and signs the confirmation.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
On the next page is where the cluster is configured. First, he should select the cluster name and size. Then he enters all cluster members' signer addresses,
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
sets the validators field to the nubmer of required validators and in the Withdrawal Configuration section selects the Lido CSM tab where the Withdrawal and Fee Recipient addresses are automaticaly set to Lido's Withdrawal Vault - 0xF0179dEC45a37423EAD4FaD5fCb136197872EAd9 and Lido's Execution Layer Rewards Vault - 0xE73a3602b99f1f913e72F8bdcBC235e206794Ac8 as per Lido documentation. Finally, he clicks on the Create cluster configuration button.
Note: The mainnet addresses are: Withdrawal Vault - 0xB9D7934878B5FB9610B3fE8A5e441e8fad7E293f and Fee Recipient - 0x388C818CA8B9251b393131C08a736A67ccB19297 (source)
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Lastly, he shares the cluster configuration link with the other cluster members.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Distributed Key Generation
All cluster members need to open the configuration link, connect their wallet, and check the cluster size, the threshold and the number of validators.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Then check that the Withdrawal Address mach Lido's Withdrawal Vault - 0xF0179dEC45a37423EAD4FaD5fCb136197872EAd9 and the Fee Recipient mach Lido's Execution Layer Rewards Vault - 0xE73a3602b99f1f913e72F8bdcBC235e206794Ac8 as per Lido documentation, and finally click the Getting Started button.
Note: The mainnet addresses are: Withdrawal Vault - 0xB9D7934878B5FB9610B3fE8A5e441e8fad7E293f and Fee Recipient - 0x388C818CA8B9251b393131C08a736A67ccB19297 (source)
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Accept all the necessary advisories.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
On the Accept configuration page, each cluster member submits its ENR (the whole address including the enr: prefix).
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Finally, confirms and signs the configuration…
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Then wait for all the other cluster members to accept it.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Once all members confirm the configuration they will see the continue button.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
On the next page, they will find a CLI command.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
After executing it they should wait for all the other cluster members to connect and complete the DKG ceremony.
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
A cluster-lock.json file is created in the .charon folder as well as the deposit-data.json file and the validator_keys folder containing each operator's partial key signatures for the validators.
At this point, each operator must make a backup of the .charon folder and keep it safe, as validator keys can't be recreated.
MEV Boost
What is MEV
MEV stands for Maximal Extractable Value. This is the additional value that can be captured by the block proposer by optimising the selection and order of the transactions included in the proposed block. Such an optimisation often requires the use of sophisticated algorithms and access to resources not available to the regular node operator. The parties capable of doing this are called Searchers. They find the most profitable transactions, bundle them and provide the bundles to the Block Builders who assemble the bundles into a complete block. At the beginning of each epoch, node operators register the validators they control with a Block Builder (or Relay) of their choice and if they are selected to propose a block they can choose to propose the one provided by the Relay in exchange for an additional tip. If the operator wishes to connect to multiple Relays a software called MEV-Boost is required. Using MEV-Boost allows the operator to select the most profitable block from all the connected Relays, creating a kind of Block Marketplace. In the context of Lido CSM, it is worth noting that running MEV-Boost is a requirement. Although there are currently no penalties for proposing self-built blocks, this may change in the future.
Configuring the MEV-boost client
To configure MEV-boost each cluster memeber needs to edit the .env file and set the BUILDER_API_ENABLED=true and MEVBOOST_RELAYS= to the URL of at least one of Lido's approved MEV relays here. Multiple relays must be separated by a comma. The use of unapproved relays is strictly forbidden! All cluster members must use identical configurations (same relays) to avoid missing block proposals due to a lack of consensus!
Starting the Node
Each cluster member should start the node with the following command:
docker compose up -d
At this point, execution and consensus clients should start syncing, and Charon and the validator client should start waiting for the validator to be activated.
Deploy the keys to Lido CSM
One of the cluster members opens the Lido CSM widget using this address https://csm.testnet.fi. He connects the cluster Safe to the widget using WalletConnect.
Copies the connection link…
And pastes it into the Safe WalletConnect screen.
He clicks on the Create Node Operator button…
Pastes the contents of the deposit-data.json file into the Upload deposit data field. There should be enough ETH/stETH/wstETH deposited in the cluster Safe to cover the bond.
Expand the Specify custom addresses section…
Set the Reward Address field to the Split contract address and the Manager Address field to the Safe wallet address. Make sure you select the Extended option before creating the operator, otherwise the reward address will have ultimate control over the node operator, and since this is a simple splitter contract, you won't be able to make any changes to the operator, as this contract has no signing capabilities. Check that the correct addresses are set and click the Create Node Operator button.
Sign the transaction in the safe and share it with the rest of the cluster members.
Before signing the transaction, the remaining members should check that the transaction details contain the correct manager address (the address of the Safe) and reward address (the address of the split contract).
Once the signature threshold has been reached and the transaction has been executed, the cluster is ready for deposit from Lido CSM.
Monitoring the CSM operator
You can follow this guide for the steps required to monitor your CSM operator.
Claiming Rewards
There are two types of rewards in CSM: bond rewards and operator rewards. The bond in Lido CSM is held in stETH and stETH being a rabasing token changes it's balance (most likely increasing) once a day. Operator rewards come from operating the node and include a share of the execution layer and consensus layer rewards. They are socialised across all operators and are awarded when the operator performs above a certain threshold, calculated every 7 days on the Holesky testnet and every 28 days on Mainnet.
To claim your rewards, go to the Bond & Rewards menu and select the Claim tab.
WARNING: Make sure you claim your rewards in wstETH (Wrapped Staked Ether), this is the only token compatible with the Split contract. When you request ETH, you will receive an NFT representing the withdrawal claim, which the Splitter contract cannot distribute. stETH is a rebasing token and when the supply decreases or increases, either not all recipients will be able to withdraw their share, or the yield will be stuck in Split. More information can be found in the splits.org documentation.
Exiting Validators
You can follow the Obol launchpad instructions on how to exit the cluster validators.
