@towns-protocol/contracts 0.0.302

package/src/base/registry/facets/checker/EntitlementChecker.sol

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {IEntitlementChecker} from "./IEntitlementChecker.sol";
+import {IEntitlementGatedBase} from "src/spaces/facets/gated/IEntitlementGated.sol";
+
+// libraries
+
+import {EntitlementCheckerStorage} from "./EntitlementCheckerStorage.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {NodeOperatorStatus, NodeOperatorStorage} from "src/base/registry/facets/operator/NodeOperatorStorage.sol";
+import {XChainLib} from "src/base/registry/facets/xchain/XChainLib.sol";
+import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
+
+// contracts
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+
+contract EntitlementChecker is IEntitlementChecker, Facet {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.UintSet;
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+    using CustomRevert for bytes4;
+
+    // =============================================================
+    //                           Initializer
+    // =============================================================
+
+    function __EntitlementChecker_init() external onlyInitializing {
+        _addInterface(type(IEntitlementChecker).interfaceId);
+    }
+
+    // =============================================================
+    //                           Modifiers
+    // =============================================================
+    modifier onlyNodeOperator(address node, address operator) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+
+        if (layout.operatorByNode[node] != operator) {
+            EntitlementChecker_InvalidNodeOperator.selector.revertWith();
+        }
+        _;
+    }
+
+    modifier onlyRegisteredApprovedOperator() {
+        NodeOperatorStorage.Layout storage nodeOperatorLayout = NodeOperatorStorage.layout();
+
+        if (!nodeOperatorLayout.operators.contains(msg.sender)) {
+            EntitlementChecker_InvalidOperator.selector.revertWith();
+        }
+        _;
+
+        if (nodeOperatorLayout.statusByOperator[msg.sender] != NodeOperatorStatus.Approved) {
+            EntitlementChecker_OperatorNotActive.selector.revertWith();
+        }
+    }
+
+    // =============================================================
+    //                           External
+    // =============================================================
+
+    /// @inheritdoc IEntitlementChecker
+    function registerNode(address node) external onlyRegisteredApprovedOperator {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+
+        if (layout.nodes.contains(node)) {
+            EntitlementChecker_NodeAlreadyRegistered.selector.revertWith();
+        }
+
+        layout.nodes.add(node);
+        layout.operatorByNode[node] = msg.sender;
+
+        emit NodeRegistered(node);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function unregisterNode(address node) external onlyNodeOperator(node, msg.sender) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+
+        if (!layout.nodes.contains(node)) {
+            EntitlementChecker_NodeNotRegistered.selector.revertWith();
+        }
+
+        layout.nodes.remove(node);
+        delete layout.operatorByNode[node];
+
+        emit NodeUnregistered(node);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function isValidNode(address node) external view returns (bool) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+        return layout.nodes.contains(node);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function getNodeCount() external view returns (uint256) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+        return layout.nodes.length();
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function getNodeAtIndex(uint256 index) external view returns (address) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+
+        require(index < layout.nodes.length(), "Index out of bounds");
+        return layout.nodes.at(index);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function getRandomNodes(uint256 count) external view returns (address[] memory) {
+        return _getRandomNodes(count);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function requestEntitlementCheck(
+        address walletAddress,
+        bytes32 transactionId,
+        uint256 roleId,
+        address[] memory nodes
+    ) external {
+        emit EntitlementCheckRequested(walletAddress, msg.sender, transactionId, roleId, nodes);
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function requestEntitlementCheckV2(
+        address walletAddress,
+        bytes32 transactionId,
+        uint256 requestId,
+        bytes memory extraData
+    ) external payable {
+        address space = msg.sender;
+        address senderAddress = abi.decode(extraData, (address));
+
+        XChainLib.Layout storage layout = XChainLib.layout();
+
+        layout.requestsBySender[senderAddress].add(transactionId);
+
+        // Only create the request if it doesn't exist yet
+        XChainLib.Request storage request = layout.requests[transactionId];
+        if (request.caller == address(0)) {
+            // First time creating this request
+            layout.requests[transactionId] = XChainLib.Request({
+                caller: space,
+                blockNumber: block.number,
+                value: msg.value,
+                completed: false,
+                receiver: walletAddress
+            });
+        } else {
+            if (msg.value != 0) {
+                EntitlementChecker_InvalidValue.selector.revertWith();
+            }
+        }
+
+        address[] memory randomNodes = _getRandomNodes(5);
+
+        XChainLib.Check storage check = XChainLib.layout().checks[transactionId];
+
+        check.requestIds.add(requestId);
+
+        for (uint256 i; i < randomNodes.length; ++i) {
+            check.nodes[requestId].add(randomNodes[i]);
+            check.votes[requestId].push(
+                IEntitlementGatedBase.NodeVote({
+                    node: randomNodes[i],
+                    vote: IEntitlementGatedBase.NodeVoteStatus.NOT_VOTED
+                })
+            );
+        }
+
+        emit EntitlementCheckRequestedV2(
+            walletAddress,
+            space,
+            address(this),
+            transactionId,
+            requestId,
+            randomNodes
+        );
+    }
+
+    /// @inheritdoc IEntitlementChecker
+    function getNodesByOperator(address operator) external view returns (address[] memory nodes) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+        uint256 totalNodeCount = layout.nodes.length();
+        nodes = new address[](totalNodeCount);
+        uint256 nodeCount;
+        for (uint256 i; i < totalNodeCount; ++i) {
+            address node = layout.nodes.at(i);
+            if (layout.operatorByNode[node] == operator) {
+                unchecked {
+                    nodes[nodeCount++] = node;
+                }
+            }
+        }
+        assembly ("memory-safe") {
+            mstore(nodes, nodeCount) // Update the length of the array
+        }
+    }
+
+    // =============================================================
+    //                           Internal
+    // =============================================================
+    function _getRandomNodes(uint256 count) internal view returns (address[] memory randomNodes) {
+        EntitlementCheckerStorage.Layout storage layout = EntitlementCheckerStorage.layout();
+
+        uint256 nodeCount = layout.nodes.length();
+
+        if (count > nodeCount) {
+            EntitlementChecker_InsufficientNumberOfNodes.selector.revertWith();
+        }
+
+        randomNodes = new address[](count);
+        uint256[] memory indices = new uint256[](nodeCount);
+
+        for (uint256 i; i < nodeCount; ++i) {
+            indices[i] = i;
+        }
+
+        unchecked {
+            for (uint256 i; i < count; ++i) {
+                // Adjust random function to generate within range 0 to n-1
+                uint256 rand = _pseudoRandom(i, nodeCount);
+                randomNodes[i] = layout.nodes.at(indices[rand]);
+                // Move the last element to the used slot and reduce the pool size
+                indices[rand] = indices[--nodeCount];
+            }
+        }
+    }
+
+    // Generate a pseudo-random index based on a seed and the node count
+    function _pseudoRandom(uint256 seed, uint256 nodeCount) internal view returns (uint256) {
+        return
+            uint256(keccak256(abi.encode(block.prevrandao, block.timestamp, seed, msg.sender))) %
+            nodeCount;
+    }
+}

package/src/base/registry/facets/checker/EntitlementCheckerStorage.sol

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+// contracts
+
+library EntitlementCheckerStorage {
+    // keccak256(abi.encode(uint256(keccak256("facets.entitlement.checker.storage")) - 1)) &
+    // ~bytes32(uint256(0xff))
+    bytes32 internal constant STORAGE_SLOT =
+        0x180c1d0b9e5eeea9f2f078bc2712cd77acc6afea03b37705abe96dda6f602600;
+
+    struct Layout {
+        EnumerableSet.AddressSet nodes;
+        mapping(address node => address operator) operatorByNode;
+    }
+
+    function layout() internal pure returns (Layout storage l) {
+        bytes32 slot = STORAGE_SLOT;
+        assembly {
+            l.slot := slot
+        }
+    }
+}

package/src/base/registry/facets/checker/IEntitlementChecker.sol

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+interface IEntitlementCheckerBase {
+    error EntitlementChecker_NodeAlreadyRegistered();
+    error EntitlementChecker_NodeNotRegistered();
+    error EntitlementChecker_InsufficientNumberOfNodes();
+    error EntitlementChecker_InvalidNodeOperator();
+    error EntitlementChecker_InvalidOperator();
+    error EntitlementChecker_OperatorNotActive();
+    error EntitlementChecker_NoPendingRequests();
+    error EntitlementChecker_InsufficientFunds();
+    error EntitlementChecker_NoRefundsAvailable();
+    error EntitlementChecker_InvalidValue();
+
+    // Events
+    event NodeRegistered(address indexed nodeAddress);
+    event NodeUnregistered(address indexed nodeAddress);
+
+    /// @notice Event emitted when an entitlement check is requested
+    event EntitlementCheckRequested(
+        address callerAddress,
+        address contractAddress,
+        bytes32 transactionId,
+        uint256 roleId,
+        address[] selectedNodes
+    );
+
+    event EntitlementCheckRequestedV2(
+        address walletAddress,
+        address spaceAddress,
+        address resolverAddress,
+        bytes32 transactionId,
+        uint256 roleId,
+        address[] selectedNodes
+    );
+}
+
+interface IEntitlementChecker is IEntitlementCheckerBase {
+    /// @notice Register a new node in the system
+    /// @param node The address of the node to register
+    function registerNode(address node) external;
+
+    /// @notice Unregister an existing node from the system
+    /// @param node The address of the node to unregister
+    function unregisterNode(address node) external;
+
+    /// @notice Check if a node address is registered and valid
+    /// @param node The address of the node to check
+    /// @return bool True if the node is valid, false otherwise
+    function isValidNode(address node) external view returns (bool);
+
+    /// @notice Get the total number of registered nodes
+    /// @return uint256 The count of registered nodes
+    function getNodeCount() external view returns (uint256);
+
+    /// @notice Get the node address at a specific index
+    /// @param index The index of the node to retrieve
+    /// @return address The address of the node at the given index
+    function getNodeAtIndex(uint256 index) external view returns (address);
+
+    /// @notice Get a random selection of registered nodes
+    /// @param count The number of random nodes to return
+    /// @return address[] Array of randomly selected node addresses
+    function getRandomNodes(uint256 count) external view returns (address[] memory);
+
+    /// @notice Request an entitlement check for a transaction
+    /// @param callerAddress The address initiating the check
+    /// @param transactionId The unique identifier of the transaction
+    /// @param roleId The role ID to check entitlements against
+    /// @param nodes Array of node addresses that will perform the check
+    function requestEntitlementCheck(
+        address callerAddress,
+        bytes32 transactionId,
+        uint256 roleId,
+        address[] memory nodes
+    ) external;
+
+    /// @notice Request an entitlement check with additional data (V2)
+    /// @param walletAddress The wallet address to check entitlements for
+    /// @param transactionId The unique identifier of the transaction
+    /// @param requestId The unique identifier for this specific request
+    /// @param extraData Additional data required for the check
+    function requestEntitlementCheckV2(
+        address walletAddress,
+        bytes32 transactionId,
+        uint256 requestId,
+        bytes memory extraData
+    ) external payable;
+
+    /// @notice Get all nodes registered to a specific operator
+    /// @param operator The address of the operator
+    /// @return address[] Array of node addresses registered to the operator
+    function getNodesByOperator(address operator) external view returns (address[] memory);
+}

package/src/base/registry/facets/delegation/ISpaceDelegation.sol

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+interface ISpaceDelegationBase {
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           ERRORS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    error SpaceDelegation__InvalidAddress();
+    error SpaceDelegation__InvalidOperator();
+    error SpaceDelegation__InvalidSpace();
+    error SpaceDelegation__NotSpaceOwner();
+    error SpaceDelegation__NotSpaceMember();
+    error SpaceDelegation__AlreadyDelegated(address operator);
+    error SpaceDelegation__NotDelegated();
+    error SpaceDelegation__InvalidStakeRequirement();
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           EVENTS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    event SpaceDelegatedToOperator(address indexed space, address indexed operator);
+    event RiverTokenChanged(address indexed riverToken);
+    event SpaceFactoryChanged(address indexed spaceFactory);
+}
+
+interface ISpaceDelegation is ISpaceDelegationBase {
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                         DELEGATION                         */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Adds a space delegation to an operator
+    /// @param space The address of the space
+    /// @param operator The address of the operator
+    function addSpaceDelegation(address space, address operator) external;
+
+    /// @notice Removes a space delegation from an operator
+    /// @param space The address of the space
+    function removeSpaceDelegation(address space) external;
+
+    /// @notice Gets the operator address for a given space
+    /// @param space The address of the space
+    /// @return The address of the operator delegated to the space
+    function getSpaceDelegation(address space) external view returns (address);
+
+    /// @notice Gets all spaces delegated to a specific operator
+    /// @param operator The address of the operator
+    /// @return An array of space addresses delegated to the operator
+    function getSpaceDelegationsByOperator(
+        address operator
+    ) external view returns (address[] memory);
+
+    /// @notice Gets the total delegation for a specific operator
+    /// @param operator The address of the operator
+    /// @return The total amount delegated to the operator
+    function getTotalDelegation(address operator) external view returns (uint256);
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           FACTORY                          */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Sets the address of the space factory
+    /// @param spaceFactory The address of the space factory
+    function setSpaceFactory(address spaceFactory) external;
+
+    /// @notice Gets the address of the space factory
+    /// @return The address of the space factory
+    function getSpaceFactory() external view returns (address);
+}

package/src/base/registry/facets/delegation/SpaceDelegationFacet.sol

@@ -0,0 +1,250 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {IERC173} from "@towns-protocol/diamond/src/facets/ownable/IERC173.sol";
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+import {IArchitect} from "../../../../factory/facets/architect/IArchitect.sol";
+import {IVotesEnumerable} from "../../../../diamond/facets/governance/votes/enumerable/IVotesEnumerable.sol";
+import {IMainnetDelegation} from "../mainnet/IMainnetDelegation.sol";
+import {IRewardsDistributionBase} from "../distribution/v2/IRewardsDistribution.sol";
+import {ISpaceDelegation} from "./ISpaceDelegation.sol";
+
+// libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {CustomRevert} from "../../../../utils/libraries/CustomRevert.sol";
+import {NodeOperatorStatus, NodeOperatorStorage} from "../operator/NodeOperatorStorage.sol";
+import {RewardsDistributionStorage} from "../distribution/v2/RewardsDistributionStorage.sol";
+import {StakingRewards} from "../distribution/v2/StakingRewards.sol";
+import {SpaceDelegationStorage} from "./SpaceDelegationStorage.sol";
+
+// contracts
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+import {OwnableBase} from "@towns-protocol/diamond/src/facets/ownable/OwnableBase.sol";
+
+contract SpaceDelegationFacet is ISpaceDelegation, OwnableBase, Facet {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using StakingRewards for StakingRewards.Layout;
+    using CustomRevert for bytes4;
+
+    modifier onlySpaceOwner(address space) {
+        if (!_isValidSpace(space)) SpaceDelegation__InvalidSpace.selector.revertWith();
+        if (!_isValidSpaceOwner(space)) SpaceDelegation__NotSpaceOwner.selector.revertWith();
+        _;
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                         DELEGATION                         */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /**
+     * @inheritdoc ISpaceDelegation
+     * @dev Delegates a space to a node operator for reward distribution.
+     * Authorization logic:
+     * - Only space members can delegate a space that has never been delegated
+     * - Only the space owner can delegate/redelegate once the space has been delegated before
+     *
+     * Process:
+     * 1. Validates operator address and space existence
+     * 2. Checks operator is registered and not exiting
+     * 3. Validates caller is member (for never delegated) or owner (for previously delegated)
+     * 4. Sweeps any pending rewards from previous delegation
+     * 5. Updates storage mappings and delegation timestamp
+     * 6. Emits SpaceDelegatedToOperator event
+     */
+    function addSpaceDelegation(address space, address operator) external {
+        if (operator == address(0)) SpaceDelegation__InvalidAddress.selector.revertWith();
+
+        // validate that the space exists
+        if (!_isValidSpace(space)) SpaceDelegation__InvalidSpace.selector.revertWith();
+
+        SpaceDelegationStorage.Layout storage ds = SpaceDelegationStorage.layout();
+
+        address currentOperator = ds.operatorBySpace[space];
+
+        if (currentOperator == operator) SpaceDelegation__AlreadyDelegated.selector.revertWith();
+
+        // Authorization logic: only members can delegate if space has never been delegated,
+        // only owner can delegate/redelegate if space has been delegated before (even if removed)
+        if (ds.spaceDelegationTime[space] != 0) {
+            // space has been delegated before (even if currently removed), only owner can delegate
+            if (!_isValidSpaceOwner(space)) SpaceDelegation__NotSpaceOwner.selector.revertWith();
+        } else {
+            // Space has never been delegated, only members can delegate
+            if (!_isValidSpaceMember(space)) SpaceDelegation__NotSpaceMember.selector.revertWith();
+        }
+
+        NodeOperatorStorage.Layout storage nodeOperatorDs = NodeOperatorStorage.layout();
+
+        // check if the operator is valid
+        if (!nodeOperatorDs.operators.contains(operator))
+            SpaceDelegation__InvalidOperator.selector.revertWith();
+
+        // check if operator is not exiting
+        if (nodeOperatorDs.statusByOperator[operator] == NodeOperatorStatus.Exiting)
+            SpaceDelegation__InvalidOperator.selector.revertWith();
+
+        _sweepSpaceRewardsIfNecessary(space, currentOperator);
+
+        // remove the space from the current operator
+        ds.spacesByOperator[currentOperator].remove(space);
+
+        // overwrite the operator for this space
+        ds.operatorBySpace[space] = operator;
+
+        // add the space to this new operator array
+        ds.spacesByOperator[operator].add(space);
+        ds.spaceDelegationTime[space] = block.timestamp;
+
+        emit SpaceDelegatedToOperator(space, operator);
+    }
+
+    /**
+     * @inheritdoc ISpaceDelegation
+     * @dev Removes delegation from a space, returning it to an undelegated state.
+     * Only the space owner can call this function.
+     * Note: The delegation timestamp is preserved to maintain history that the space
+     * was delegated before, ensuring only the owner can redelegate.
+     *
+     * Process:
+     * 1. Validates space address and delegation existence
+     * 2. Sweeps any pending rewards to the current operator
+     * 3. Clears operator mappings but preserves delegation timestamp
+     * 4. Emits SpaceDelegatedToOperator event with address(0)
+     */
+    function removeSpaceDelegation(address space) external onlySpaceOwner(space) {
+        if (space == address(0)) SpaceDelegation__InvalidAddress.selector.revertWith();
+
+        SpaceDelegationStorage.Layout storage ds = SpaceDelegationStorage.layout();
+
+        address operator = ds.operatorBySpace[space];
+
+        if (operator == address(0)) SpaceDelegation__NotDelegated.selector.revertWith();
+
+        _sweepSpaceRewardsIfNecessary(space, operator);
+
+        ds.operatorBySpace[space] = address(0);
+        ds.spacesByOperator[operator].remove(space);
+        // don't reset spaceDelegationTime to preserve delegation history
+
+        emit SpaceDelegatedToOperator(space, address(0));
+    }
+
+    /// @inheritdoc ISpaceDelegation
+    function getSpaceDelegation(address space) external view returns (address) {
+        return SpaceDelegationStorage.layout().operatorBySpace[space];
+    }
+
+    /// @inheritdoc ISpaceDelegation
+    function getSpaceDelegationsByOperator(
+        address operator
+    ) external view returns (address[] memory) {
+        return SpaceDelegationStorage.layout().spacesByOperator[operator].values();
+    }
+
+    /// @inheritdoc ISpaceDelegation
+    function getTotalDelegation(address operator) external view returns (uint256) {
+        return _getTotalDelegation(operator);
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           FACTORY                          */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @inheritdoc ISpaceDelegation
+    function setSpaceFactory(address spaceFactory) external onlyOwner {
+        if (spaceFactory == address(0)) SpaceDelegation__InvalidAddress.selector.revertWith();
+
+        SpaceDelegationStorage.layout().spaceFactory = spaceFactory;
+        emit SpaceFactoryChanged(spaceFactory);
+    }
+
+    /// @inheritdoc ISpaceDelegation
+    function getSpaceFactory() public view returns (address) {
+        return SpaceDelegationStorage.layout().spaceFactory;
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          INTERNAL                          */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @dev Sweeps the rewards in the space delegation to the operator if necessary
+    /// @dev Handles two scenarios:
+    /// 1. If currentOperator exists: transfers accumulated rewards to the current operator
+    ///    (rewards earned while the space was delegated to them)
+    /// 2. If no currentOperator: forfeits accumulated rewards (clears unallocated rewards from
+    ///    existing stakes after undelegation that shouldn't go to a new operator)
+    /// @param space The space address to sweep rewards from
+    /// @param currentOperator The current operator (address(0) if undelegated)
+    function _sweepSpaceRewardsIfNecessary(address space, address currentOperator) internal {
+        StakingRewards.Layout storage staking = RewardsDistributionStorage.layout().staking;
+
+        uint256 reward;
+        if (currentOperator != address(0)) {
+            // transfer rewards from space to current operator
+            reward = staking.transferReward(space, currentOperator);
+        } else {
+            // forfeit rewards (clear without transfer)
+            reward = staking.sweepReward(space);
+        }
+
+        if (reward != 0) {
+            emit IRewardsDistributionBase.SpaceRewardsSwept(space, currentOperator, reward);
+        }
+    }
+
+    function _getTotalDelegation(address operator) internal view returns (uint256) {
+        SpaceDelegationStorage.Layout storage ds = SpaceDelegationStorage.layout();
+        (address riverToken_, address mainnetDelegation_) = (ds.riverToken, ds.mainnetDelegation);
+        if (riverToken_ == address(0) || mainnetDelegation_ == address(0)) return 0;
+
+        // get the delegation from the mainnet delegation
+        uint256 delegation = IMainnetDelegation(mainnetDelegation_).getDelegatedStakeByOperator(
+            operator
+        );
+
+        // get the delegation from the base delegation
+        address[] memory baseDelegators = IVotesEnumerable(riverToken_).getDelegatorsByDelegatee(
+            operator
+        );
+        for (uint256 i; i < baseDelegators.length; ++i) {
+            delegation += IERC20(riverToken_).balanceOf(baseDelegators[i]);
+        }
+
+        address[] memory spaces = ds.spacesByOperator[operator].values();
+
+        for (uint256 i; i < spaces.length; ++i) {
+            address[] memory usersDelegatingToSpace = IVotesEnumerable(riverToken_)
+                .getDelegatorsByDelegatee(spaces[i]);
+
+            for (uint256 j; j < usersDelegatingToSpace.length; ++j) {
+                delegation += IERC20(riverToken_).balanceOf(usersDelegatingToSpace[j]);
+            }
+        }
+
+        return delegation;
+    }
+
+    /// @dev Checks if the space is valid by verifying if it has a nonzero token ID in the factory
+    function _isValidSpace(address space) internal view returns (bool) {
+        return IArchitect(getSpaceFactory()).getTokenIdBySpace(space) != 0;
+    }
+
+    /// @dev Checks if the caller is the owner of the space
+    /// @dev Assumes that the space is valid
+    function _isValidSpaceOwner(address space) internal view returns (bool) {
+        return IERC173(space).owner() == msg.sender;
+    }
+
+    /// @dev Checks if the caller is a member of the space (has at least one membership token)
+    /// @dev Also considers the space owner as a member
+    /// @dev Assumes that the space is valid
+    function _isValidSpaceMember(address space) internal view returns (bool) {
+        // Check if caller is the space owner
+        if (IERC173(space).owner() == msg.sender) return true;
+
+        // Check if caller has at least one membership token
+        return IERC721(space).balanceOf(msg.sender) != 0;
+    }
+}