Skip to main content

NodeOperatorsRegistry

The NodeOperatorRegistry contract is the core contract that allows node operators to participate in the Lido staking protocol. Node Operators participate on the protocol as validators and get rewarded for their work. A Node Operator gets added to the Registry by the DAO. Validator reward is distributed evenly amongst all active operators. The contract contains a list of operators, their public keys, and the logic for managing their state.

Roles​

The NodeOperatoRegistry contract has the following roles

NameDescription
DAO_ROLEDAO role
PAUSE_ROLEAllows to pasuse the contract
UNPAUSE_ROLEAllows to unpasuse the contract
ADD_NODE_OPERATOR_ROLEAllows to add new node operator the contract
REMOVE_NODE_OPERATOR_ROLEAllows to remove a node operator the contract

Structs​

NodeOperatorStatus​

A node operator statuses

NameDescription
INACTIVEWhen the node operator is INACTIVE
ACTIVEWhen the node operator is ACTIVE
JAILEDWhen the node operator is JAILED
EJECTEDWhen the node operator is EJECTED
UNSTAKEDWhen the node operator is UNSTAKED
enum NodeOperatorRegistryStatus {
        INACTIVE,
        ACTIVE,
        JAILED,
        EJECTED,
        UNSTAKED
}

FullNodeOperatorRegistry​

NameDescription
validatorIdPolygon validator id
commissionRateThe commission rate applied by the validator on Polygon stake manager
validatorShareThe validator share address
rewardAddressThe validator reward address
delegationThe validator delegation status on Polygon stake manager
statusThe validator status
struct FullNodeOperatorRegistry {
        uint256 validatorId;
        uint256 commissionRate;
        address validatorShare;
        address rewardAddress;
        bool delegation;
        NodeOperatorRegistryStatus status;
}

ValidatorData​

The node operator data

NameDescription
validatorShareThe validator share address of the validator
rewardAddressThe validator reward address
struct ValidatorData {
        address validatorShare;
        address rewardAddress;
}

View Methods​

stakeManager​

Polygon stake manager address.

function stakeManager() view returns (address)

version​

Contract version.

function version() view returns (string memory)

stMATIC​

stMATIC address.

function stMATIC() view returns (address)

DAO_ROLE​

Role bytes.

function DAO_ROLE() view returns (bytes32)

PAUSE_ROLE​

Role bytes.

function PAUSE_ROLE() view returns (bytes32)

UNPAUSE_ROLE()​

Role bytes.

function UNPAUSE_ROLE() view returns (bytes32)

ADD_NODE_OPERATOR_ROLE()​

Role bytes.

function ADD_NODE_OPERATOR_ROLE() view returns (bytes32)

REMOVE_NODE_OPERATOR_ROLE()​

Role bytes.

function REMOVE_NODE_OPERATOR_ROLE() view returns (bytes32)

DISTANCE_THRESHOLD_PERCENTS()​

The min percent to recognize the system as balanced.

function DISTANCE_THRESHOLD_PERCENTS() view returns (uint256)

MAX_WITHDRAW_PERCENTAGE_PER_REBALANCE()​

The maximum percentage withdraw per system rebalance.

function MAX_WITHDRAW_PERCENTAGE_PER_REBALANCE() view returns (uint256)

MIN_REQUEST_WITHDRAW_RANGE_PERCENTS()​

Allows to increse the number of validators to request withdraw from when the system is balanced.

function MIN_REQUEST_WITHDRAW_RANGE_PERCENTS() view returns (uint8)

validatorIds()​

Get validator id.

Parameters:​

NameTypeDescription
indexuint256array index
function validatorIds(uint256 index) view returns (uint256)

Returns:​

NameTypeDescription
validatorIduint256validator id

validatorIdToRewardAddress()​

Mapping of all owners with node operator id. Mapping is used to be able to extend the struct.

Parameters:​

NameTypeDescription
validatorIduint256validator id
function validatorIdToRewardAddress(uint256 validatorId) view returns (address)

Returns:​

NameTypeDescription
rewardAddressaddressnode operator reward address.

validatorRewardAddressToId()​

Mapping of validator reward address to validator Id. Mapping is used to be able to extend the struct.

Parameters:​

NameTypeDescription
rewardAddressaddressnode operator reward address.
function validatorRewardAddressToId(address rewardAddress) view returns (uint256)

Returns:​

NameTypeDescription
validatorIduint256validator id

getNodeOperator()​

Returns the node operator based on the operator's reward address.

Parameters:​

NameTypeDescription
_rewardAddressaddressReward address of the node operator owner
function getNodeOperator(address _rewardAddress)
        external
        view
        returns (FullNodeOperatorRegistry memory)

Returns:​

NameTypeDescription
nodeOperatorFullNodeOperatorRegistryNode operator data.

getNodeOperator()​

Returns the node operator based on the operator's validator id.

Parameters:​

NameTypeDescription
_operatorIduint256Id of the operator
function getNodeOperator(uint256 _validatorId)
        external
        view
        returns (FullNodeOperatorRegistry memory)

Returns:​

NameTypeDescription
nodeOperatorFullNodeOperatorRegistryNode operator data.

getStats()​

Returns a list all the node operator statuses in the system.

function getStats()
        external
        view
        override
        returns (
            uint256 inactiveNodeOperator,
            uint256 activeNodeOperator,
            uint256 jailedNodeOperator,
            uint256 ejectedNodeOperator,
            uint256 unstakedNodeOperator
        )

Returns:​

NameTypeDescription
inactiveNodeOperatoruint256the number of inactive operators.
activeNodeOperatoruint256the number of active operators.
jailedNodeOperatoruint256the number of jailed operators.
ejectedNodeOperatoruint256the number of ejected operators.
unstakedNodeOperatoruint256the number of unstaked operators.

listDelegatedNodeOperators()​

Returns a list all the ACTIVE operators

function listDelegatedNodeOperators()
        external
        view
        override
        returns (ValidatorData[] memory, uint256)

Returns:​

NameTypeDescription
activeNodeOperatorsValidatorData[]a list of ACTIVE node operator.
totalActiveNodeOperatorsuint256total number of ACTIVE node operators.

listWithdrawNodeOperators()​

Returns a list all the operators on the stakeManager that can be withdrawn from this includes ACTIVE, JAILED, ejected, and UNSTAKED operators.

function listWithdrawNodeOperators()
        external
        view
        override
        returns (ValidatorData[] memory nodeOperators, uint256 totalNodeOperators)

Returns:​

NameTypeDescription
nodeOperatorsValidatorData[]a list of ACTIVE, JAILED or UNSTAKED node operator.
totalNodeOperatorsuint256total number of node operators.

getValidatorsDelegationAmount()​

Calculate how total buffered should be delegated between the active validators, depending on if the system is balanced or not. If validators are in EJECTED or UNSTAKED status the function will revert.

Parameters:​

NameTypeDescription
amountToDelegateuint256The total that can be delegated.
function getValidatorsDelegationAmount(uint256 amountToDelegate)
        external
        view
        returns (
            ValidatorData[] memory validators,
            uint256 totalActiveNodeOperator,
            uint256[] memory operatorRatios,
            uint256 totalRatio
        );

Returns:​

NameTypeDescription
validatorsValidatorData[]all active node operators.
totalActiveNodeOperatoruint256total active node operators.
operatorRatiosuint256[]is a list of operator's ratio.
totalRatiouint256the total ratio. If ZERO that means the system is balanced.

getValidatorsRebalanceAmount()​

Calculate how the system could be rebalanced depending on the current buffered tokens. If validators are in EJECTED or UNSTAKED status the function will revert. If the system is balanced the function will revert.

Parameters:​

NameTypeDescription
_totalBuffereduint256totalBuffered MATIC amount in the StMatic contract
function getValidatorsRebalanceAmount(uint256 totalBuffered)
        external
        view
        returns (
            ValidatorData[] memory validators,
            uint256 totalActiveNodeOperator,
            uint256[] memory operatorRatios,
            uint256 totalRatio,
            uint256 totalToWithdraw
        );

Returns:​

NameTypeDescription
validatorsValidatorData[]all active node operators.
totalActiveNodeOperatoruint256total active node operators.
operatorRatiosuint256[]is a list of operator's ratio.
totalRatiouint256the total ratio. If ZERO that means the system is balanced.
totalToWithdrawuint256the total amount to withdraw.

getValidatorsRequestWithdraw()​

Calculate the validators to request withdrawal from depending on whether the system is balanced or not.

Parameters:​

NameTypeDescription
_withdrawAmountuint256amount to withdraw from validator
function getValidatorsRequestWithdraw(uint256 _withdrawAmount)
        external
        view
        returns (
            ValidatorData[] memory validators,
            uint256 totalDelegated,
            uint256 bigNodeOperatorLength,
            uint256[] memory bigNodeOperatorIds,
            uint256 smallNodeOperatorLength,
            uint256[] memory smallNodeOperatorIds,
            uint256[] memory operatorAmountCanBeRequested,
            uint256 totalValidatorToWithdrawFrom
        );

Returns:​

NameTypeDescription
validatorsValidatorData[]all node operators.
totalDelegateduint256total amount delegated.
bigNodeOperatorLengthuint256number of ids bigNodeOperatorIds.
bigNodeOperatorIdsuint256[]stores the ids of node operators that amount delegated to it is greater than the average delegation.
smallNodeOperatorLengthuint256number of ids smallNodeOperatorIds.
smallNodeOperatorIdsuint256[]stores the ids of node operators that amount delegated to it is less than the average delegation.
operatorAmountCanBeRequesteduint256[]amount that can be requested from a spécific validator when the system is not balanced.
totalValidatorToWithdrawFromuint256the number of validator to withdraw from when the system is balanced.

getNodeOperatorStatus()​

Returns a node operator status.

Parameters:​

NameTypeDescription
_validatorIduint256validator id
function getNodeOperatorStatus(uint256 _validatorId)
        external
        view
        override
        returns (NodeOperatorRegistryStatus operatorStatus)

Returns:​

NameTypeDescription
operatorStatusenumThe validator status

getValidatorIds()​

Returns a list of all validator ids in the system.

function getValidatorIds()
        external
        view
        override
        returns (uint256[] memory)

Returns:​

NameTypeDescription
validatorIdsArray<uint256>The list of all validator ids in the protocol

getProtocolStats()​

Returns the protocol stats.

function getProtocolStats()
        external
        view
        returns (
            bool isBalanced,
            uint256 distanceThreshold,
            uint256 minAmount,
            uint256 maxAmount
        );

Returns:​

NameTypeDescription
isBalancedbooleanif the system is balanced or not
distanceThresholduint256the distance threshold between the big and small amount deposit in validators
minAmountuint256The min amount delegated to a validator
maxAmountuint256The max amount delegated to a validator

Methods​

exitNodeOperatorRegistry()​

Allows the Node Operator to exit the Registry by itself

 function exitNodeOperatorRegistry() external override

removeInvalidNodeOperator()​

Remove a node operator from the system if it fails to meet certain conditions:

  1. If the commission of the Node Operator is less than the standard commission.
  2. If the Node Operator is either Unstaked or Ejected.
function removeInvalidNodeOperator(uint256 _validatorId)
        external
        override
        whenNotPaused

Parameters:​

NameTypeDescription
_validatorIduint256validator id

setRewardAddress()​

Update the reward address of a Node Operator.

function setRewardAddress(address _newRewardAddress) external override

setOperatorRewardAddress()​

Allows operator's owner to update reward address

function setOperatorRewardAddress(address _rewardAddress)
        external

Parameters:​

NameTypeDescription
_rewardAddressaddressNew reward address

pasue()​

Allows an authorized user with PAUSE ROLE to pause the contract.

function pause() external onlyRole(PAUSE_ROLE);

unpasue()​

Allows an authorized user with UNPAUSE ROLE to unpause the contract.

function unpause() external onlyRole(PAUSE_ROLE);

DAO Methods​

note

These methods can be called by DAO-only roles.

addNodeOperator()​

Allows the DAO to add a new node operator to the system.

function addNodeOperator(uint256 _validatorId, address _rewardAddress)
        external
        override
        userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
_validatorIduint256Validator Id
_rewardAddressaddressReward address which receives stMATIC rewards for this operator

removeNodeOperator()​

Allows the DAO to remove a node operator from the system and withdraw total delegated tokens to it.

function removeNodeOperator(uint256 _validatorId)
        external
        override
        userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
_validatorIduint256Validator Id

setStMaticAddress()​

Allows the DAO to set the StMATIC contract address.

function setStMaticAddress(address _newStMatic)
        external
        userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
_newStMaticaddressNew stMATIC address

setDistanceThreshold()​

Allows the DAO to set the distance threshold for balancing the system.

function setDistanceThreshold(uint256 _newDistanceThreshold)
        external
        override
        userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
_newDistanceThresholduint256New distance threshold

setMinRequestWithdrawRange()​

Allows the DAO to set the minimum request withdraw range to keep the system balanced

function setMinRequestWithdrawRange(uint8 _newMinRequestWithdrawRange)
        external
        override
        userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
_newMinRequestWithdrawRangeuint8New min request withdraw range threshold

setMaxWithdrawPercentagePerRebalance()​

Allows the DAO to set the maximum withdraw percentage per balance of each validator

function setMaxWithdrawPercentagePerRebalance(uint256 _newMaxWithdrawPercentagePerRebalance)
        external
        override
        userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
__newMaxWithdrawPercentagePerRebalanceuint8New max withdraw percentage per baalnce

setVersion()​

Allows the DAO to set the contract version

function setVersion(string memory _newVersion) external userHasRole(DAO_ROLE)

Parameters:​

NameTypeDescription
_newVersionstringNew version