Community Staking Module | Integrations interfaces

Community Staking Module | Integrations interfaces



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

Integration Scenarios

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.

Tier 0. Software Setup Helper

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:

  • Setting up Ethereum validation tools (such as CL and EL nodes, validator client and MEV-boost)
  • Setting Lido feeRecipient in the CL node
  • Generating correct deposit data for subsequent uploading into CSM
    • Validator pubkey
    • Lido withdrawal credentials
    • 32 ETH amount
  • Configuring the MEV-boost client to use relays from MevBoostRelayAllowedList

A good reference is eth-docker.

Tier 1. Operator Statistics Monitor

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.

Tier 2. Operator Manager

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.

Tier 3. Full-featured operator UI

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

  • Shows Node Operator lifecycle graphs, e.g., earnings, performance, events
  • Compares Node Operator with average NOs stats

Node Operator Functionality

These methods are subject to change

Generate Deposit Data

Prior to engaging with the CSM contract, it's crucial for the node operator to produce 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 and equipped with the validator keys, ready for operation.

Add New Node Operator

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

  • addNodeOperatorETH
  • addNodeOperatorStETH
  • addNodeOperatorWstETH
  • addNodeOperatorStETHWithPermit
  • addNodeOperatorWstETHWithPermit

All of these 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.

Now, the address from the node operator has been created (referred to as managerAddress below) and is used by the node operator to operate itself further.

All the Node Operator functionality below has to be called from the managerAddress.

The default value of the address is used for receiving rewards as well and is referred to as rewardAddress. It might be changed separately later.

Upload New Keys

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

  • addValidatorKeysETH
  • addValidatorKeysStETH
  • addValidatorKeysWstETH
  • addValidatorKeysStETHWithPermit
  • addValidatorKeysWstETHWithPermit

Now the required bond will include the current NOs underbond or overbond increasing or decreasing the required amount consequently.

Delete Keys

The node operator is able to remove their yet unused keys by calling removeSigningKeys.

Depending on whether these keys are vetted or not, the node operator might be penalized for calling this method to prevent malicious deposit queue manipulation.

Add Additional Bond

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 to prepare for future key uploads for accounting purposes.

  • depositETH
  • depositStETH
  • depositWstETH
  • depositStETHWithPermit
  • depositWstETHWithPermit

Please note that these methods are housed within a distinct contract named CSAccounting, which is integrated with the CSM system. The address for CSAccounting can be obtained by invoking the accounting function on the primary CSM contract.

Claim Rewards

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

  • claimRewardsStETH
  • claimRewardsWstETH
  • requestRewardsETH (withdrawal NFT)

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

See Rewards available to claim for more calculating details.

View Bond Amounts

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

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

Required bond to upload keys

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

  • getRequiredBondETHForKeys()
  • getRequiredBondStETHForKeys()
  • getRequiredBondWstETHForKeys()
  • These methods solely rely on the existing bond computation mechanism.

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

  • getRequiredBondETH
  • getRequiredBondStETH
  • getRequiredBondWstETH
  • In these methods, the existing balance of the node operator is considered.

Current bond amount

The current amount is stored as stETH and available by calling getBondShares() function.

Missing bond

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:

  • getMissingBondETH
  • getMissingBondStETH
  • getMissingBondWstETH

Excess bond

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:

  • getExcessBondETH
  • getExcessBondStETH
  • getExcessBondWstETH

Rewards available to claim

To ascertain the total rewards that are claimable, one may employ the following functions, which calculate available rewards either for providing proof or directly for the claim:

  • getTotalRewardsETH
  • getTotalRewardsStETH
  • getTotalRewardsWstETH

This amount is a sum of the proven node operator’s rewards and the current excess/miss bond (if so):


Unbonded keys count

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.

Keys count by bond amount

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

  • getKeysCountByBondETH
  • getKeysCountByBondStETH
  • getKeysCountByBondWstETH

Change managerAddress

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

  • proposeNodeOperatorManagerAddressChange() from the current managerAddress and provide a new one
  • confirmNodeOperatorManagerAddressChange() from the new address to ensure it is the correct address and the node operator has access to it.

Change rewardAddress

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

  • proposeNodeOperatorRewardAddressChange()
  • confirmNodeOperatorRewardAddressChange()

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

Reset managerAddress

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

View Penalties

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.

View Exit Requests

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.

View Deposit Queue State

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:

  • totalAddedKeys - total keys uploaded by the NO
  • totalVettedKeys - total keys that were vetted and are ready to be deposited
  • totalDepositedKeys - total keys that have already received deposits

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, the keys start position and count to be next 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 after vetting. Each set of keys will be processed for deposit in the order they appear in the queue.