@web3dotorg/evm-slc-core-contracts 0.3.2

package/governance/NeutralsRegistry.sol

@@ -0,0 +1,1130 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {ERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {ERC1967Utils} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Utils.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+
+import {PRECISION} from "@solarity/solidity-lib/utils/Globals.sol";
+import {Paginator} from "@solarity/solidity-lib/libs/arrays/Paginator.sol";
+import {PriorityQueue} from "@solarity/solidity-lib/libs/data-structures/PriorityQueue.sol";
+
+import {Errors} from "../libs/Errors.sol";
+
+import {DAOSLC_PARAM_NAME, TREASURY_ADDRESS_PARAM_NAME, MAX_BASIS_POINTS} from "../utils/Globals.sol";
+
+import {IGovernance} from "../interfaces/IGovernance.sol";
+import {IQParameters} from "../interfaces/IQParameters.sol";
+import {NeutralsSelection} from "../libs/NeutralsSelection.sol";
+import {INeutralsRegistry} from "../interfaces/INeutralsRegistry.sol";
+
+/**
+ * @title NeutralsRegistry
+ * @notice This contract manages the registration, staking, delegation, reward distribution, and slashing of neutrals in the SLC system.
+ * Neutrals can stake tokens to participate, receive delegations, and earn rewards. The contract supports withdrawal announcements
+ * and integrates with governance and parameter registries. Only authorized roles (DAOSLC, Governance)
+ * can perform certain sensitive operations such as slashing and reward distribution.
+ */
+contract NeutralsRegistry is INeutralsRegistry, ERC165, UUPSUpgradeable {
+    using SafeERC20 for IERC20;
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using PriorityQueue for PriorityQueue.AddressQueue;
+
+    // keccak256(abi.encode(uint256(keccak256("evm-slc-core.storage.NeutralsRegistry")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant NEUTRALS_REGISTRY_STORAGE_LOCATION =
+        0x02eec0af57616a1cb2ef3538f733bfc9b20f30a56aced6911a05ed5520d14900;
+
+    string private constant MAX_ACTIVE_NEUTRALS_PARAM_NAME = "slc.neutrals.maxActiveNeutrals";
+
+    // solhint-disable-next-line gas-small-strings
+    string private constant MAX_DELEGATION_AMPLIFICATION_PARAM_NAME =
+        "slc.neutrals.maxDelegationAmplification";
+
+    string private constant MINIMUM_STAKE_PARAM_NAME = "slc.neutrals.minimumStake";
+
+    // solhint-disable-next-line gas-small-strings
+    string private constant NEUTRALS_WITHDRAWAL_PERIOD_PARAM_NAME =
+        "slc.neutrals.neutralsWithdrawalPeriod";
+
+    // solhint-disable-next-line gas-small-strings
+    string private constant DELEGATORS_WITHDRAWAL_PERIOD_PARAM_NAME =
+        "slc.neutrals.delegatorsWithdrawalPeriod";
+
+    string private constant NEUTRALS_SLASHING_RECIPIENT_PARAM_NAME =
+        "slc.neutrals.slashingRecipient";
+
+    struct DelegatorRewardPool {
+        uint256 cumulativeSum;
+    }
+
+    struct Delegation {
+        uint256 delegationAmount;
+        WithdrawalAnnouncement withdrawal;
+        uint256 owedValue;
+        uint256 cumulativeSum;
+    }
+
+    struct NeutralsInfo {
+        uint256 selfStake;
+        uint256 weight;
+        uint256 delegatedStake;
+        uint256 rewards;
+        uint256 delegationShare;
+        string externalLink;
+        bool isActive;
+        bool isStandby;
+    }
+
+    struct WithdrawalAnnouncement {
+        uint256 amount;
+        uint256 announcedAt;
+        uint256 availableAt;
+    }
+
+    struct NeutralsRegistryStorage {
+        IGovernance governance;
+        IERC20 stakeToken;
+        IQParameters parametersRegistry;
+        uint256 rewardsToDistribute;
+        PriorityQueue.AddressQueue activeNeutrals;
+        PriorityQueue.AddressQueue standbyNeutrals;
+        uint256 maxActiveNeutrals;
+        mapping(address neutral => NeutralsInfo info) neutrals;
+        mapping(address neutral => WithdrawalAnnouncement) neutralsWithdrawalAnnouncements;
+        mapping(address neutral => DelegatorRewardPool) delegatorsRewardPools;
+        mapping(address delegator => mapping(address neutral => Delegation)) delegations;
+        mapping(address neutral => EnumerableSet.AddressSet delegators) delegatorsPerNeutral;
+        mapping(address delegator => EnumerableSet.AddressSet delegatedNeutrals) neutralsPerDelegator;
+    }
+
+    modifier onlyDAOSLC() {
+        _requireDAOSLC();
+        _;
+    }
+
+    modifier onlyGovernance() {
+        _requireGovernance();
+        _;
+    }
+
+    modifier syncedMaxActiveNeutrals() {
+        _requiredSyncedMaxActiveNeutrals();
+        _;
+    }
+
+    function __NeutralsRegistry_init(address governance_) external initializer {
+        __UUPSUpgradeable_init();
+
+        if (governance_ == address(0)) revert Errors.InvalidGovernance();
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        $.governance = IGovernance(governance_);
+
+        address stakeToken_ = $.governance.getSystemToken();
+        address parametersRegistry_ = $.governance.getParametersRegistry();
+
+        if (stakeToken_ == address(0)) revert Errors.InvalidERC20Token();
+        if (parametersRegistry_ == address(0)) revert Errors.InvalidParametersRegistry();
+
+        $.stakeToken = IERC20(stakeToken_);
+        $.parametersRegistry = IQParameters(parametersRegistry_);
+        $.maxActiveNeutrals = _getMaxActiveNeutrals();
+    }
+
+    /**
+     * @notice Stake tokens to become a neutral
+     * @param amount_ Amount of tokens to stake
+     */
+    function addNeutralsStake(uint256 amount_) external syncedMaxActiveNeutrals {
+        if (amount_ == 0) revert Errors.InvalidStakeAmount(amount_);
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo_ = $.neutrals[msg.sender];
+
+        neutralInfo_.selfStake += amount_;
+
+        _manipulateNeutralState(msg.sender);
+
+        $.stakeToken.safeTransferFrom(msg.sender, address(this), amount_);
+
+        emit NeutralStaked(msg.sender, amount_, neutralInfo_.selfStake);
+    }
+
+    /**
+     * @notice Announce intention to withdraw a portion of self-stake
+     * @param amount_ Amount of tokens to withdraw
+     */
+    function announceNeutralsWithdrawal(uint256 amount_) public syncedMaxActiveNeutrals {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        NeutralsInfo storage neutralInfo_ = $.neutrals[msg.sender];
+        WithdrawalAnnouncement storage announcement_ = $.neutralsWithdrawalAnnouncements[
+            msg.sender
+        ];
+
+        if (neutralInfo_.selfStake == 0) revert NeutralHasNoStake(msg.sender);
+        if (amount_ > neutralInfo_.selfStake)
+            revert Errors.InsufficientStakeAmount(msg.sender, amount_, neutralInfo_.selfStake);
+        if (announcement_.announcedAt != 0) revert WithdrawalAlreadyAnnounced(msg.sender);
+
+        uint256 withdrawalPeriod_ = _getNeutralsWithdrawalPeriod();
+        uint256 availableAt_ = block.timestamp + withdrawalPeriod_;
+
+        announcement_.amount = amount_;
+        announcement_.announcedAt = block.timestamp;
+        announcement_.availableAt = availableAt_;
+
+        neutralInfo_.selfStake -= amount_;
+
+        _manipulateNeutralState(msg.sender);
+
+        emit WithdrawalAnnounced(msg.sender, amount_, availableAt_);
+    }
+
+    /**
+     * @notice Cancel a previously announced withdrawal
+     */
+    function cancelNeutralsWithdrawal() public syncedMaxActiveNeutrals {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[msg.sender];
+        WithdrawalAnnouncement storage announcement = $.neutralsWithdrawalAnnouncements[
+            msg.sender
+        ];
+
+        if (announcement.announcedAt == 0) revert NoWithdrawalAnnouncement(msg.sender);
+
+        uint256 amount_ = announcement.amount;
+
+        neutralInfo.selfStake += amount_;
+
+        delete $.neutralsWithdrawalAnnouncements[msg.sender];
+
+        _manipulateNeutralState(msg.sender);
+
+        emit WithdrawalCancelled(msg.sender, amount_);
+    }
+
+    /**
+     * @notice Update the amount for a previously announced withdrawal
+     * @param newAmount_ New withdrawal amount
+     */
+    function updateNeutralsWithdrawal(uint256 newAmount_) public {
+        cancelNeutralsWithdrawal();
+        announceNeutralsWithdrawal(newAmount_);
+    }
+
+    /**
+     * @notice Complete withdrawal after the announcement period has passed
+     */
+    function completeNeutralsWithdrawal() external {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[msg.sender];
+        WithdrawalAnnouncement storage announcement = $.neutralsWithdrawalAnnouncements[
+            msg.sender
+        ];
+
+        if (announcement.announcedAt == 0) revert NoWithdrawalAnnouncement(msg.sender);
+
+        if (block.timestamp < announcement.availableAt) {
+            revert WithdrawalNotReady(msg.sender, announcement.availableAt);
+        }
+
+        uint256 amount_ = announcement.amount;
+
+        delete $.neutralsWithdrawalAnnouncements[msg.sender];
+
+        $.stakeToken.safeTransfer(msg.sender, amount_);
+
+        emit NeutralUnstaked(msg.sender, amount_, neutralInfo.selfStake);
+    }
+
+    /**
+     * @notice Delegate tokens to a neutral
+     * @param neutral_ Address of the neutral to delegate to
+     * @param amount_ Amount of tokens to delegate
+     */
+    function delegate(address neutral_, uint256 amount_) external {
+        if (amount_ == 0) revert InvalidDelegationAmount(amount_);
+        if (neutral_ == msg.sender) revert NeutralCannotDelegateToHimself(msg.sender);
+
+        _checkDelegation(neutral_, amount_);
+
+        _addDelegationStake(msg.sender, neutral_, amount_);
+
+        _getNeutralsRegistryStorage().stakeToken.safeTransferFrom(
+            msg.sender,
+            address(this),
+            amount_
+        );
+    }
+
+    /**
+     * @notice Complete withdrawal of delegated tokens after the announcement period
+     * @param neutral_ Address of the neutral
+     */
+    function completeDelegationWithdrawal(address neutral_) external {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        WithdrawalAnnouncement storage announcement = $
+        .delegations[msg.sender][neutral_].withdrawal;
+
+        if (announcement.announcedAt == 0) revert NoWithdrawalAnnouncement(msg.sender);
+
+        if (block.timestamp < announcement.availableAt) {
+            revert WithdrawalNotReady(msg.sender, announcement.availableAt);
+        }
+
+        uint256 amount_ = announcement.amount;
+
+        delete $.delegations[neutral_][msg.sender].withdrawal;
+
+        $.stakeToken.safeTransfer(msg.sender, amount_);
+
+        emit DelegationWithdrawn(msg.sender, neutral_, amount_);
+    }
+
+    /**
+     * @notice Claim rewards accrued as a neutral
+     */
+    function claimNeutralRewards() external {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 rewards_ = $.neutrals[msg.sender].rewards;
+
+        if (rewards_ == 0) revert Errors.NoRewardsAvailible(msg.sender);
+
+        delete $.neutrals[msg.sender].rewards;
+
+        _getNeutralsRegistryStorage().stakeToken.safeTransfer(msg.sender, rewards_);
+
+        emit RewardsClaimed(msg.sender, rewards_);
+    }
+
+    /**
+     * @notice Claim rewards accrued as a delegator for a specific neutral
+     * @param neutral_ Address of the neutral
+     */
+    function claimDelegatorRewards(address neutral_) external {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 rewards_ = _distributeAllDelegatorRewards(msg.sender, neutral_);
+
+        $.stakeToken.safeTransfer(msg.sender, rewards_);
+
+        emit RewardsClaimed(msg.sender, rewards_);
+    }
+
+    /**
+     * @notice Set the share of rewards to be distributed to delegators
+     * @param delegationShare_ Percentage of rewards for delegators in basis points (for example, 250 basis points = 2.5 %)
+     */
+    function setDelegationShare(uint256 delegationShare_) external {
+        require(
+            delegationShare_ <= MAX_BASIS_POINTS,
+            Errors.ValueShouldBeInBasisPoints(delegationShare_)
+        );
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[msg.sender];
+
+        if (neutralInfo.selfStake == 0) revert NeutralHasNoStake(msg.sender);
+        neutralInfo.delegationShare = delegationShare_;
+    }
+
+    /**
+     * @notice Set an external link for the neutral (e.g., profile or info page)
+     * @param externalLink_ The external link string
+     */
+    function setExternalLink(string calldata externalLink_) external {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[msg.sender];
+
+        if (neutralInfo.selfStake == 0) revert NeutralHasNoStake(msg.sender);
+
+        neutralInfo.externalLink = externalLink_;
+    }
+
+    /**
+     * @notice Slash a neutral's self-stake (only callable by DAOSLC)
+     * @param neutral_ Address of the neutral to slash
+     * @param amount_ Amount to slash
+     * @dev This function accounts for withdrawal announcements to prevent front-running.
+     *      If an executor has announced withdrawal, the total slashable amount includes
+     *      both their current stake and the withdrawal announcement amount.
+     */
+    function slashNeutral(
+        address neutral_,
+        uint256 amount_
+    ) external onlyDAOSLC syncedMaxActiveNeutrals {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[neutral_];
+        WithdrawalAnnouncement storage announcement = $.neutralsWithdrawalAnnouncements[neutral_];
+
+        uint256 totalSlashableAmount_ = neutralInfo.selfStake;
+        if (announcement.announcedAt != 0) {
+            totalSlashableAmount_ += announcement.amount;
+        }
+
+        if (totalSlashableAmount_ == 0) revert NeutralHasNoStake(neutral_);
+        if (amount_ > totalSlashableAmount_)
+            revert Errors.InsufficientStakeAmount(neutral_, amount_, neutralInfo.selfStake);
+
+        address slashingRecipient_ = _getSlashingRecipient();
+
+        if (amount_ > neutralInfo.selfStake && announcement.announcedAt != 0) {
+            neutralInfo.selfStake += announcement.amount;
+            delete $.neutralsWithdrawalAnnouncements[neutral_];
+        }
+
+        neutralInfo.selfStake -= amount_;
+
+        _manipulateNeutralState(neutral_);
+
+        $.stakeToken.safeTransfer(slashingRecipient_, amount_);
+
+        emit NeutralSlashed(neutral_, amount_, slashingRecipient_);
+    }
+
+    /**
+     * @notice Synchronize local maxActiveNeutrals parameter with the one in the registry
+     */
+    function boundActiveNeutralsList() external {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 remoteMaxActiveNeutrals_ = _getMaxActiveNeutrals();
+        if ($.maxActiveNeutrals == remoteMaxActiveNeutrals_) {
+            revert Errors.ParameterIsAlreadySynced(MAX_ACTIVE_NEUTRALS_PARAM_NAME);
+        }
+
+        $.maxActiveNeutrals = remoteMaxActiveNeutrals_;
+
+        _handleMaxActiveNeutralsResize();
+    }
+
+    function tryBecomeActive() external syncedMaxActiveNeutrals {
+        _tryActivateNeutral(msg.sender);
+    }
+
+    /**
+     * @notice Distribute rewards to selected neutrals (only callable by Governance)
+     * @param selectedNeutrals_ Array of selected neutral addresses
+     * @param amount_ Total amount to distribute
+     */
+    function distributeRewards(
+        address[] calldata selectedNeutrals_,
+        uint256 amount_
+    ) external onlyGovernance {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        uint256 selectedNeutralsLen_ = selectedNeutrals_.length;
+        uint256 neutralPart_ = amount_ / selectedNeutralsLen_;
+        uint256 remainder_ = amount_ % selectedNeutralsLen_;
+
+        for (uint256 i = 0; i < selectedNeutralsLen_; ++i) {
+            _updateNeutralRewards(selectedNeutrals_[i], neutralPart_);
+        }
+
+        address treasuryAddress_ = _getTreasuryAddress();
+
+        $.stakeToken.safeTransferFrom(msg.sender, address(this), amount_);
+        $.stakeToken.safeTransfer(treasuryAddress_, remainder_);
+        emit RewardsDistributed(selectedNeutrals_, amount_);
+    }
+
+    /**
+     * @notice Get the current governance contract address
+     * @return Address of the governance contract
+     */
+    function getCurrentGovernance() external view returns (address) {
+        return address(_getNeutralsRegistryStorage().governance);
+    }
+
+    /**
+     * @notice Get the address of the staking token
+     * @return Address of the staking token
+     */
+    function getToken() external view returns (address) {
+        return address(_getNeutralsRegistryStorage().stakeToken);
+    }
+
+    function getCurrentMaxActiveNeutralsParameter() external view returns (uint256) {
+        return _getNeutralsRegistryStorage().maxActiveNeutrals;
+    }
+
+    /**
+     * @notice Get the address of the parameters registry
+     * @return Address of the parameters registry
+     */
+    function getParameterRegistry() external view returns (address) {
+        return address(_getNeutralsRegistryStorage().parametersRegistry);
+    }
+
+    /**
+     * @notice Get a paginated list of active neutrals
+     * @param offset_ Starting index
+     * @param limit_ Maximum number of neutrals to return
+     * @return Array of active neutral addresses
+     */
+    function getActiveNeutrals(
+        uint256 offset_,
+        uint256 limit_
+    ) external view returns (address[] memory) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        uint256 to_ = Paginator.getTo($.activeNeutrals.length(), offset_, limit_);
+
+        address[] memory result = new address[](to_ - offset_);
+
+        for (uint256 i = offset_; i < to_; ++i) {
+            result[i - offset_] = address(uint160(uint256(($.activeNeutrals._queue._values[i]))));
+        }
+
+        return result;
+    }
+
+    /**
+     * @notice Get a paginated list of standby neutrals
+     * @param offset_ Starting index
+     * @param limit_ Maximum number of neutrals to return
+     * @return Array of standby neutral addresses
+     */
+    function getStandbyNeutrals(
+        uint256 offset_,
+        uint256 limit_
+    ) external view returns (address[] memory) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        uint256 to_ = Paginator.getTo($.standbyNeutrals.length(), offset_, limit_);
+
+        address[] memory result = new address[](to_ - offset_);
+
+        for (uint256 i = offset_; i < to_; ++i) {
+            result[i - offset_] = address(uint160(uint256(($.standbyNeutrals._queue._values[i]))));
+        }
+
+        return result;
+    }
+
+    /**
+     * @notice Get withdrawal announcement information for a neutral
+     * @param neutral_ Address of the neutral
+     * @return Withdrawal announcement struct
+     */
+    function getWithdrawalAnnouncement(
+        address neutral_
+    ) external view returns (WithdrawalAnnouncement memory) {
+        return _getNeutralsRegistryStorage().neutralsWithdrawalAnnouncements[neutral_];
+    }
+
+    /**
+     * @notice Get delegation of delegator for neutral
+     * @param delegator_ Address of the delegator_
+     * @param neutral_ Address of the neutral
+     * @return Info about delegation
+     */
+    function getDelegation(
+        address delegator_,
+        address neutral_
+    ) external view returns (Delegation memory) {
+        return _getNeutralsRegistryStorage().delegations[delegator_][neutral_];
+    }
+
+    /**
+     * @notice Get all delegators for the neutral
+     */
+    function getDelegatorsPerNeutral(
+        address neutral_,
+        uint256 offset_,
+        uint256 limit_
+    ) external view returns (address[] memory) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        return Paginator.part($.delegatorsPerNeutral[neutral_], offset_, limit_);
+    }
+
+    /**
+     * @notice Get all neutrals that were delegated by the delegator.
+     */
+    function getNeutralsPerDelegator(
+        address delegator_,
+        uint256 offset_,
+        uint256 limit_
+    ) external view returns (address[] memory) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        return Paginator.part($.neutralsPerDelegator[delegator_], offset_, limit_);
+    }
+
+    /**
+     * @notice Check if a neutral's withdrawal is ready to be completed
+     * @param neutral_ Address of the neutral
+     * @return True if withdrawal can be completed
+     */
+    function isWithdrawalReady(address neutral_) external view returns (bool) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        WithdrawalAnnouncement storage announcement_ = $.neutralsWithdrawalAnnouncements[neutral_];
+
+        if (announcement_.announcedAt == 0) return false;
+
+        return block.timestamp >= announcement_.availableAt;
+    }
+
+    /**
+     * @notice Get a random slice of active neutrals for selection
+     * @param number_ Number of neutrals to select
+     * @return Array of selected neutral addresses
+     */
+    function getNeutralsSlice(uint256 number_) external view returns (address[] memory) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 activeNeutralsLength_ = $.activeNeutrals.length();
+
+        if (number_ > activeNeutralsLength_ || number_ == 0) {
+            revert SelectedNeutralsNumberOutOfRange(number_, activeNeutralsLength_);
+        }
+
+        address[] memory activeNeutrals_ = $.activeNeutrals.values();
+        uint256[] memory randomizedWeights_ = new uint256[](activeNeutralsLength_);
+        bytes32 seed_ = keccak256(abi.encode(blockhash(block.number - 1)));
+
+        for (uint256 i = 0; i < activeNeutralsLength_; ++i) {
+            address neutral_ = activeNeutrals_[i];
+            uint256 neutralWeight_ = $.neutrals[neutral_].weight;
+
+            uint256 randomNumber_ = NeutralsSelection.getRandomNumber(abi.encodePacked(seed_, i));
+            randomizedWeights_[i] = Math.mulDiv(randomNumber_, neutralWeight_, PRECISION);
+        }
+
+        NeutralsSelection.selectTopAddressesByWeight(activeNeutrals_, randomizedWeights_, number_);
+
+        // solhint-disable-next-line no-inline-assembly
+        assembly ("memory-safe") {
+            mstore(activeNeutrals_, number_)
+        }
+
+        return activeNeutrals_;
+    }
+
+    /**
+     * @notice Get the count of currently active neutrals
+     * @return Number of active neutrals
+     */
+    function getNeutralsCount() external view override returns (uint256) {
+        return _getNeutralsRegistryStorage().activeNeutrals.length();
+    }
+
+    /**
+     * @notice Get detailed information about a neutral
+     * @param neutral_ Address of the neutral
+     * @return NeutralsInfo struct with all neutral data
+     */
+    function getNeutralInfo(address neutral_) external view returns (NeutralsInfo memory) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        return $.neutrals[neutral_];
+    }
+
+    /**
+     * @notice Get the delegation share set by a neutral
+     * @param neutral_ Address of the neutral
+     * @return Delegation share (percentage)
+     */
+    function getNeutralDelegationShare(address neutral_) external view returns (uint256) {
+        return _getNeutralsRegistryStorage().neutrals[neutral_].delegationShare;
+    }
+
+    /**
+     * @notice Get the external link set by a neutral
+     * @param neutral_ Address of the neutral
+     * @return The external link string
+     */
+    function getExternalLink(address neutral_) external view returns (string memory) {
+        return _getNeutralsRegistryStorage().neutrals[neutral_].externalLink;
+    }
+
+    function implementation() external view returns (address) {
+        return ERC1967Utils.getImplementation();
+    }
+
+    /**
+     * @notice Announce intention to withdraw delegated tokens from a neutral
+     * @param neutral_ Address of the neutral
+     * @param amount_ Amount of tokens to withdraw
+     */
+    function announceDelegationWithdrawal(address neutral_, uint256 amount_) public {
+        if (amount_ == 0) revert InvalidDelegationAmount(amount_);
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        WithdrawalAnnouncement storage announcement = $
+        .delegations[msg.sender][neutral_].withdrawal;
+
+        uint256 delegationAmount_ = $.delegations[msg.sender][neutral_].delegationAmount;
+
+        if (amount_ > delegationAmount_)
+            revert InsufficientDelegationAmount(msg.sender, neutral_, amount_, delegationAmount_);
+        if (announcement.announcedAt != 0) revert WithdrawalAlreadyAnnounced(msg.sender);
+
+        uint256 withdrawalPeriod_ = _getDelegatorsWithdrawalPeriod();
+        uint256 availableAt_ = block.timestamp + withdrawalPeriod_;
+
+        announcement.amount = amount_;
+        announcement.announcedAt = block.timestamp;
+        announcement.availableAt = availableAt_;
+
+        _removeDelegationStake(msg.sender, neutral_, amount_);
+
+        emit WithdrawalAnnounced(msg.sender, amount_, availableAt_);
+    }
+
+    /**
+     * @notice Cancel a previously announced delegation withdrawal
+     * @param neutral_ Address of the neutral
+     */
+    function cancelDelegationWithdrawal(address neutral_) public {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        WithdrawalAnnouncement storage announcement = $
+        .delegations[msg.sender][neutral_].withdrawal;
+
+        if (announcement.announcedAt == 0) revert NoWithdrawalAnnouncement(msg.sender);
+        uint256 amount_ = announcement.amount;
+
+        _addDelegationStake(msg.sender, neutral_, amount_);
+
+        delete $.delegations[msg.sender][neutral_].withdrawal;
+
+        emit WithdrawalCancelled(msg.sender, amount_);
+    }
+
+    /**
+     * @notice Update the amount for a previously announced delegation withdrawal
+     * @param neutral_ Address of the neutral
+     * @param newAmount_ New withdrawal amount
+     */
+    function updateDelegationWithdrawal(address neutral_, uint256 newAmount_) public {
+        cancelDelegationWithdrawal(neutral_);
+        announceDelegationWithdrawal(neutral_, newAmount_);
+    }
+
+    /**
+     * @notice Check if an address is an active neutral
+     * @param candidate_ Address to check
+     * @return True if the address is an active neutral
+     */
+    function isNeutral(address candidate_) public view returns (bool) {
+        return _getNeutralsRegistryStorage().neutrals[candidate_].isActive;
+    }
+
+    /**
+     * @notice Get the available rewards for a neutral
+     * @param neutral_ Address of the neutral
+     * @return Amount of available rewards
+     */
+    function getAvailibleRewards(address neutral_) public view returns (uint256) {
+        return _getNeutralsRegistryStorage().neutrals[neutral_].rewards;
+    }
+
+    /// @inheritdoc	ERC165
+    function supportsInterface(
+        bytes4 interfaceId_
+    ) public view override(ERC165, IERC165) returns (bool) {
+        return
+            interfaceId_ == type(INeutralsRegistry).interfaceId ||
+            super.supportsInterface(interfaceId_);
+    }
+
+    function _tryActivateNeutral(address neutral_) internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[neutral_];
+
+        if (neutralInfo.selfStake < _getMinimumStake()) return;
+
+        if ($.activeNeutrals.length() < $.maxActiveNeutrals) {
+            _activateNeutral(neutral_);
+        } else {
+            address lowestNeutral_ = $.activeNeutrals.topValue();
+            uint256 lowestStake_ = $.neutrals[lowestNeutral_].selfStake;
+
+            if (neutralInfo.selfStake > lowestStake_) {
+                _removeFromActiveQueue(lowestNeutral_);
+                _addToStandby(lowestNeutral_);
+
+                _activateNeutral(neutral_);
+            } else {
+                _addToStandby(neutral_);
+            }
+        }
+    }
+
+    /**
+     * @notice Handle changing of maxActiveNeutrals parameter in Registry.
+     * In case of maxActiveNeutrals increasing, do nothing, but if it is decreased,
+     * and size of the list of active neutrals is greater than
+     * the maxActiveNeutrals parameter, then the list will be reduced.
+     * Neutrals, which was removed from active queue, are moved to standby list.
+     */
+    function _handleMaxActiveNeutralsResize() internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 maxActiveNeutrals_ = $.maxActiveNeutrals;
+        uint256 activeNeutralsLength_ = $.activeNeutrals.length();
+
+        if (maxActiveNeutrals_ >= activeNeutralsLength_) return;
+
+        // SAFE: Previously checked, that activeNeutralsLength_ > maxActiveNeutrals
+        uint256 delta_ = activeNeutralsLength_ - maxActiveNeutrals_;
+
+        while (delta_ > 0) {
+            address lowestNeutral_ = $.activeNeutrals.topValue();
+
+            _removeFromActiveQueue(lowestNeutral_);
+            _addToStandby(lowestNeutral_);
+
+            --delta_;
+        }
+    }
+
+    function _addToActiveQueue(address neutral_) internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[neutral_];
+
+        $.activeNeutrals.add(neutral_, type(uint256).max - neutralInfo.selfStake);
+
+        neutralInfo.isActive = true;
+    }
+
+    function _addToStandby(address neutral_) internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo = $.neutrals[neutral_];
+
+        if (neutralInfo.selfStake < _getMinimumStake()) return;
+
+        if (neutralInfo.isStandby) {
+            _removeFromStandby(neutral_);
+        }
+
+        $.standbyNeutrals.add(neutral_, neutralInfo.selfStake);
+
+        neutralInfo.isStandby = true;
+
+        emit NeutralMovedToStandby(neutral_);
+    }
+
+    function _removeFromStandby(address neutral_) internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        $.standbyNeutrals.remove(neutral_);
+
+        $.neutrals[neutral_].isStandby = false;
+    }
+
+    function _removeFromActiveQueue(address neutral_) internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        $.activeNeutrals.remove(neutral_);
+
+        $.neutrals[neutral_].isActive = false;
+    }
+
+    /**
+     * @inheritdoc UUPSUpgradeable
+     */
+    // solhint-disable-next-line no-empty-blocks
+    function _authorizeUpgrade(address newImplementation_) internal override onlyDAOSLC {}
+
+    function _activateNeutral(address neutral_) internal {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        _removeFromStandby(neutral_);
+        _addToActiveQueue(neutral_);
+
+        emit NeutralActivated(neutral_, $.neutrals[neutral_].selfStake);
+    }
+
+    function _getMinimumStake() internal view returns (uint256) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getUint(MINIMUM_STAKE_PARAM_NAME) returns (
+            uint256 minimumStake_
+        ) {
+            return minimumStake_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                MINIMUM_STAKE_PARAM_NAME
+            );
+        }
+    }
+
+    function _getMaxDelegationAmplification() private view returns (uint256) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        try $.parametersRegistry.getUint(MAX_DELEGATION_AMPLIFICATION_PARAM_NAME) returns (
+            uint256 maxDelegationAmplification_
+        ) {
+            return maxDelegationAmplification_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                MAX_DELEGATION_AMPLIFICATION_PARAM_NAME
+            );
+        }
+    }
+
+    function _getMaxActiveNeutrals() internal view returns (uint256) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getUint(MAX_ACTIVE_NEUTRALS_PARAM_NAME) returns (
+            uint256 maxActiveNeutrals_
+        ) {
+            return maxActiveNeutrals_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                MAX_ACTIVE_NEUTRALS_PARAM_NAME
+            );
+        }
+    }
+
+    function _getDAOSLC() internal view returns (address) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getAddr(DAOSLC_PARAM_NAME) returns (address daoslc_) {
+            return daoslc_;
+        } catch {
+            revert Errors.ParameterIsNotSet(address($.parametersRegistry), DAOSLC_PARAM_NAME);
+        }
+    }
+
+    function _getNeutralsWithdrawalPeriod() internal view returns (uint256) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getUint(NEUTRALS_WITHDRAWAL_PERIOD_PARAM_NAME) returns (
+            uint256 neutralsWithdrawalPeriod_
+        ) {
+            return neutralsWithdrawalPeriod_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                NEUTRALS_WITHDRAWAL_PERIOD_PARAM_NAME
+            );
+        }
+    }
+
+    function _getDelegatorsWithdrawalPeriod() internal view returns (uint256) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getUint(NEUTRALS_WITHDRAWAL_PERIOD_PARAM_NAME) returns (
+            uint256 delegatorsWithdrawalPeriod_
+        ) {
+            return delegatorsWithdrawalPeriod_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                DELEGATORS_WITHDRAWAL_PERIOD_PARAM_NAME
+            );
+        }
+    }
+
+    function _getTreasuryAddress() internal view returns (address) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getAddr(TREASURY_ADDRESS_PARAM_NAME) returns (
+            address treasuryAddress_
+        ) {
+            return treasuryAddress_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                TREASURY_ADDRESS_PARAM_NAME
+            );
+        }
+    }
+
+    function _getSlashingRecipient() internal view returns (address) {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        try $.parametersRegistry.getAddr(NEUTRALS_SLASHING_RECIPIENT_PARAM_NAME) returns (
+            address slashingRecipient_
+        ) {
+            return slashingRecipient_;
+        } catch {
+            revert Errors.ParameterIsNotSet(
+                address($.parametersRegistry),
+                NEUTRALS_SLASHING_RECIPIENT_PARAM_NAME
+            );
+        }
+    }
+
+    function _recalculateNeutralWeight(address neutral_) private {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 selfStake = $.neutrals[neutral_].selfStake;
+        uint256 delegatedStake = $.neutrals[neutral_].delegatedStake;
+
+        $.neutrals[neutral_].weight = Math.sqrt(selfStake + delegatedStake);
+    }
+
+    function _addDelegationStake(address delegator_, address neutral_, uint256 amount_) private {
+        _updateDelegatorOwedValue(delegator_, neutral_);
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralsInfo = $.neutrals[neutral_];
+        Delegation storage delegation = $.delegations[delegator_][neutral_];
+
+        if (delegation.delegationAmount == 0) {
+            $.neutralsPerDelegator[delegator_].add(neutral_);
+            $.delegatorsPerNeutral[neutral_].add(delegator_);
+        }
+
+        delegation.delegationAmount += amount_;
+        neutralsInfo.delegatedStake += amount_;
+
+        _recalculateNeutralWeight(neutral_);
+    }
+
+    function _removeDelegationStake(
+        address delegator_,
+        address neutral_,
+        uint256 amount_
+    ) private {
+        _updateDelegatorOwedValue(delegator_, neutral_);
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralsInfo = $.neutrals[neutral_];
+        Delegation storage delegation = $.delegations[delegator_][neutral_];
+
+        delegation.delegationAmount -= amount_;
+        neutralsInfo.delegatedStake -= amount_;
+
+        if (delegation.delegationAmount == 0) {
+            $.neutralsPerDelegator[delegator_].remove(neutral_);
+            $.delegatorsPerNeutral[neutral_].remove(delegator_);
+        }
+
+        _recalculateNeutralWeight(neutral_);
+    }
+
+    function _updateNeutralRewards(address neutral_, uint256 amount_) private {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 delegatedStake_ = $.neutrals[neutral_].delegatedStake;
+
+        if (delegatedStake_ == 0) {
+            $.neutrals[neutral_].rewards += amount_;
+            return;
+        }
+
+        uint256 delegationShare_ = $.neutrals[neutral_].delegationShare;
+        uint256 delegatorsPart_ = Math.mulDiv(delegationShare_, amount_, MAX_BASIS_POINTS);
+        uint256 neutralPart_ = amount_ - delegatorsPart_;
+
+        $.neutrals[neutral_].rewards += neutralPart_;
+        _updateDelegatorsRewardPool(neutral_, delegatorsPart_);
+    }
+
+    function _updateDelegatorsRewardPool(address neutral_, uint256 amount_) private {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        uint256 delegatedStake_ = $.neutrals[neutral_].delegatedStake;
+
+        $.delegatorsRewardPools[neutral_].cumulativeSum += Math.mulDiv(
+            amount_,
+            PRECISION,
+            delegatedStake_
+        );
+    }
+
+    function _updateDelegatorOwedValue(address delegator_, address neutral_) private {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        DelegatorRewardPool storage rewardPool = $.delegatorsRewardPools[neutral_];
+        Delegation storage delegation = $.delegations[delegator_][neutral_];
+
+        uint256 delegatedAmount_ = delegation.delegationAmount;
+        uint256 poolCummulativeSum_ = rewardPool.cumulativeSum;
+        uint256 delegatorCummulativeSum_ = delegation.cumulativeSum;
+
+        delegation.owedValue += Math.mulDiv(
+            delegatedAmount_,
+            poolCummulativeSum_ - delegatorCummulativeSum_,
+            PRECISION
+        );
+
+        delegation.cumulativeSum = rewardPool.cumulativeSum;
+    }
+
+    function _distributeAllDelegatorRewards(
+        address delegator_,
+        address neutral_
+    ) private returns (uint256) {
+        _updateDelegatorOwedValue(delegator_, neutral_);
+
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        Delegation storage delegation = $.delegations[delegator_][neutral_];
+
+        uint256 amount_ = delegation.owedValue;
+
+        if (amount_ == 0) revert Errors.NoRewardsAvailible(delegator_);
+
+        delete delegation.owedValue;
+
+        return amount_;
+    }
+
+    function _manipulateNeutralState(address neutral_) private {
+        if (isNeutral(neutral_)) {
+            _removeFromActiveQueue(neutral_);
+        } else {
+            _removeFromStandby(neutral_);
+        }
+
+        _addToStandby(neutral_);
+        _tryActivateFromStandby();
+
+        _recalculateNeutralWeight(neutral_);
+    }
+
+    function _tryActivateFromStandby() private {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+
+        if ($.standbyNeutrals.length() == 0) return;
+        _tryActivateNeutral($.standbyNeutrals.topValue());
+    }
+
+    function _requireDAOSLC() private view {
+        if (msg.sender != _getDAOSLC()) {
+            revert Errors.SenderExpectedToBeDAOSLC(msg.sender);
+        }
+    }
+
+    function _checkDelegation(address neutral_, uint256 amount_) private view {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        NeutralsInfo storage neutralInfo_ = $.neutrals[neutral_];
+
+        uint256 neutralsStake_ = neutralInfo_.selfStake;
+        uint256 maxDelegationAmplification_ = _getMaxDelegationAmplification();
+        uint256 expectedDelegationAmount_ = neutralInfo_.delegatedStake + amount_;
+        uint256 allowedDelegationAmount_ = maxDelegationAmplification_ * neutralsStake_;
+
+        if (neutralInfo_.selfStake == 0) revert NeutralHasNoStake(neutral_);
+
+        if (expectedDelegationAmount_ >= allowedDelegationAmount_)
+            revert MaxDelegationAmplificationConstraintViolated(
+                amount_,
+                expectedDelegationAmount_,
+                allowedDelegationAmount_
+            );
+    }
+
+    function _requireGovernance() private view {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        if (msg.sender != address($.governance)) {
+            revert Errors.SenderExpectedToBeGovernance(msg.sender);
+        }
+    }
+
+    function _requiredSyncedMaxActiveNeutrals() private view {
+        NeutralsRegistryStorage storage $ = _getNeutralsRegistryStorage();
+        if ($.maxActiveNeutrals != _getMaxActiveNeutrals()) {
+            revert Errors.ParameterIsNotSynced(MAX_ACTIVE_NEUTRALS_PARAM_NAME);
+        }
+    }
+
+    function _getNeutralsRegistryStorage()
+        private
+        pure
+        returns (NeutralsRegistryStorage storage $)
+    {
+        /* solhint-disable-next-line no-inline-assembly */
+        assembly ("memory-safe") {
+            $.slot := NEUTRALS_REGISTRY_STORAGE_LOCATION
+        }
+    }
+}