Community Staking Module | Integrations interfaces

Community Staking Module | Integrations interfaces

Group
Integrations

Introduction

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 CSM + eth-docker integration.

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

Useful resources

⚠️
This description is not an absolute source of truth but an inspirational reference. Please refer to the linked documents for more details.

Generate Deposit Data

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.

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.

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.

The integration has to set referrer address in order to identify node operators that join using an integration. Using the CSM UI, it might be set via url parameter in the following way: https://csm.testnet.fi/?ref=0x... , where ref is an referral address of the integration.

Management Properties

Custom addresses can be set for:

  • managerAddress - address eligible to call any methods related to the Node Operator management.
  • rewardAddress - address to receive rewards and initiate reward claims (also can be done from the managerAddress)

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.

There also an alternative and less secure way to change default relations between manager and reward addresses by changing extendedManagerPermissions flag on creation, after that:

  • rewardAddress will not be able to reset managerAddress
  • managerAddress will be able to change rewardAddress without additional confirmation from the new address

E.g. it might be useful for node operators which in fact a DVT cluster.

Here is a good explainer for management properties.

Early Adoption participants

When creating a Node Operator from the integration interface (CSM UI will handle it automatically) it is crucial to check if the wallet used is the Early Adoption (EA) member. During the Early Adoption period only EA members are eligible to create CSM Node Operators. Once the publicRelease is activated EA members can still create a Node Operator with the beneficial bond curve.

To check if the address is the EA member integration need to refer to the corresponding file (Holesky example). If the address is a member of the EA corresponding proof to be passed as eaProof argument can be found in proofs file or the proof can be constructed from the original tree.

CSM can not determine if the address is a member of the Early Adoption without a proof. Make sure to perform corresponding checks and supply proof on the integration side to ensure correct bond curve setting and ability to join CSM during the Early Adoption period.

Upload New Keys

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 unbonded keys and penalties, or excess bond, increasing or decreasing the required amount, respectively.

Remove Keys

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

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

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

Claim Rewards

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

Here is a pre-generated proofs for all the node operators. This repository is updated regularly and can be used as a source for rewardsProof argument.

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.

It is also possible to transfer accumulated rewards to the bond without transferring them to the rewardAddress by calling permissionless method pullFeeRewards on CSAccounting contract.

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

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:

These methods solely rely on the existing bond computation mechanism.

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

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 the getBondShares or getBond functions.

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:

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:

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

Rewards available to claim

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

This is a FeeDistributor contract method

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

image

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:

In case of wstETH corresponding stETH amount should be calculated separately before the call

Change managerAddress

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

Change rewardAddress

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

When enabled extendedManagerPermissions, it’s also possible to change reward address by calling changeNodeOperatorRewardAddress by manager.

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.

☝
extendedManagerPermissions disables this option

Manage 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, involvement in MEV stealing, or slashing. The following events might be emitted:

- InitialSlashingSubmitted

- WithdrawalSubmitted with the amount less than 32 ETH

- ELRewardsStealingPenaltySettled

To determine if any penalties have been applied, one must look exclusively at the occurrence of these specific events, and all of them may lead to BondBurned event in the CSAccounting contract.

Compensate MEV Stealing

MEV stealing penalty may be caused by misconfiguration and there is a possibility to compensate it using compensateELRewardsStealingPenalty. See the guide for details.

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. See corresponding guide for details.

View Deposit Queue State

Node Operators keys

By using a getNodeOperator view function, it is possible to view all node operator properties, including the current state of keys:

  • totalAddedKeys - total keys uploaded by the NO
  • totalVettedKeys - total keys that are vetted. This number being not equal to totalAddedKeys indicates that invalid keys were detected by Deposit Security Module. Invalid keys should be deleted by the Node Operator to resume deposits.
  • enqueuedCount - number of the keys in the deposit queue
  • totalDepositedKeys - total keys that have already received deposits including totalWithdrawnKeys

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:

image

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.