This document outlines the methods for third-party integrations to interact with Community Staking Module (CSM). Essentially, the integration provides a straightforward interface for the Node Operator functionality within the CSM (and possibly other Community Staking modules).

The tier-based structure of the integration process is designed with a deliberate foundational focus on Tier 0, which serves as the essential groundwork for the entire system. This pivotal tier is dedicated to ensuring a streamlined software setup, which is crucial in navigating the initial complexities faced by node operators. As the primary tier, Tier 0 establishes the baseline functionality upon which all other tiers are constructed. The higher tiers — Tier 1 and beyond — provide additional features and expanded capabilities. These subsequent tiers are recommended for their ability to enhance and refine the integration process, but their implementation is at the discretion of the third-party software provider.

Improving the node operator’s experience in the initial and probably the most challenging stage is what such integrations might do.

Tier 0 integration must be capable of:

A good reference is eth-docker.

By utilizing available CSM view functions, it is possible to implement a comprehensive interface that displays a node operator’s personal statistics by providing their ID. Integrations should not assume any CSM on-chain interactions other than an optional wallet connection to identify the node operator.

Tier 1 integration must be capable of:

The last one is not just information to note but a specific node operator state that requires actions from them, so the integration should consider it carefully to notify the node operator explicitly.

This scenario builds upon the prior tier by incorporating interactions that occur on-chain.

The integration need not include a graphical user interface; it could be implemented as a command-line interface (CLI) tool for Node Operator management.

This tier builds on what the earlier tiers do and adds visual features that work really well with a graphical interface:

Prior to engaging with the CSM contract, it's crucial for the node operator to prepare valid deposit data that includes the correct number of keys, signatures, and a withdrawal address, which can be accomplished by using tools such as the Ethereum staking-deposit-cli or similar. Additionally, the node operator must ensure that the execution and consensus layer (CL/EL) nodes are correctly configured with the validator keys and ready for operation.

A new node operator can be added by using one of the following calls, depending on the type of bond provided.

All methods listed above require uploading valid public keys and signatures.

The bond amount is calculated using Required bond for keys and depends on the provided key count.

It’s not possible to create a node operator without providing validator keys and the bond for them.

Custom addresses can be set for:

msg.sender is used for managerAddress and rewardAddress if custom values are not specified.

Both managerAddress and rewardAddress can be changed using a 2-step process (propose and confirm) later. A proposal for the new address should be made from the current managerAddress and rewardAddress, respectively.

rewardAddress can also reset managerAddress in an emergency case.

The integration has to set referrer address in order to identify node operators that join using the intergration.

After the Node Operator has been created, new keys can be uploaded using the following methods in a similar way to Node Operator creation, providing a bond.

Now, the required bond will account for the current NOs underbond or overbond, increasing or decreasing the required amount, respectively.

The Node Operator is able to remove their yet undeposited keys by calling removeKeys.

A removalCharge is confiscated from the Node Operator’s bond for each key deleted to cover operational costs of the deposit queue cleanup.

A node operator can deposit any amount into the CSM without needing to upload new keys (predeposit). This can be useful for compensating a bond deficit resulting from slashing or penalties or for preparing for future key uploads for accounting purposes.

There are methods for claiming rewards in stETH or wstETH by providing a Merkle proof:

Claimed funds will be transferred to the rewardAddress only and can be claimed partly by passing the amount as an argument.

These methods can be called without rewardsProof to claim only bond rewards.

These methods can be called with zero amount and rewardsProof to transfer accumulated rewards to the bond without transferring them to the rewardAddress.

See the rewards available to claim for more details on calculating.

There are many calculations around the node operator’s bond.

All of the functions below are called using the CSAccounting contract.

The initial bond for the provided key count is calculated by using static methods:

Bond for further keys depends on the current node operator state.

The current amount is stored as stETH and available by calling the getBondShares or getBond functions.

If the bond amount previously provided becomes insufficient due to events like slashing or penalties incurred by the node operator, the deficit will be compensated for by future rewards. The details of any such bond amounts can be checked using the following views:

Conversely, the bond might exceed the necessary amount as a result of stETH rebase rewards, prior top-ups, or the release of funds following the withdrawal of validators. This additional bond contributes to the total sum that is eligible for claiming. To determine the surplus bond that is available for claiming, the following methods can be used:

In this case, the excess bond is current - required or 0 if current ≤ required.

To get current non-distributed Node Operator rewards, one can call:

Summed with the excess bond, this value reflects total claimable rewards.

If a node operator incurs significant losses, they may have keys that are completely unbonded, indicating a deficit in their bond to secure potential further losses for their present number of keys. The number of such keys can be determined using the getUnbondedKeysCount function.

The following views show how many keys are available to deposit for the given amount of bond:

To prevent a possible change to the non-available address by mistake, the managerAddress can be changed using a two-step way:

The reward address can be changed similarly to the manager’s address by sequentially utilizing the following methods.

Note that managerAddress does not have the possibility to change rewardAddress. It allows managing funds separately from the node operator ops.

It is assumed that the rewardAddress might be cold storage to keep funds safe and not touch it in the routine node operator management. Therefore even if the managerAddress would be lost, the node operator is still able to reset it and get access back using resetManagerAddress.

Penalties may be incurred by the node operator for reasons such as initiating a voluntary exit with less than the required 32 ether on the validator, or for involvement in MEV stealing. These events are recorded and can be identified through the emission of a Penalty event. To determine if any penalties have been applied, one must look exclusively at the occurrence of these specific events.

Exit requests are events called ValidatorExitRequest on the ValidatorsExitBusOracle contract which is a general Lido contract. The node operator must follow such events and promptly exit the requested validators.

Node Operators keys

By using a getNodeOperator view function, it is possible to view the current state of node operator’s keys by the following properties:

Deposit Queue

The current deposit queue state may be received by using the depositQueue method. It gives back a bytes32 item that shows the Node Operator's ID and the keys count to be deposited.

Node Operators closer to the start of this list will have their deposits processed sooner.

The queue state example for the Node Operator with noId=2:

The Node Operator has submitted keys twice, resulting in two separate queue positions. Each set of keys will be processed for deposit in the order they appear in the queue.