feat: enumerable indexer tracking for REO and issuance constructor cleanup

Add EnumerableSet-based indexer tracking to RewardsEligibilityOracle with
a helper contract for paginated queries. Introduce retention-based cleanup
that removes indexers only after a configurable idle period. Split REO
interface into focused sub-interfaces for administration, status, events,
maintenance, and helper operations.

Also refactor issuance constructors from address to IGraphToken type
and normalise pragma to ^0.8.27 across issuance test files.

Author: RembrandtK

packages/interfaces/contracts/issuance/eligibility/IRewardsEligibilityAdministration.sol

@@ -34,4 +34,14 @@ interface IRewardsEligibilityAdministration is IRewardsEligibilityEvents {
      * @return True if successfully set (always the case for current code)
      */
     function setEligibilityValidation(bool enabled) external returns (bool);
+
+    /**
+     * @notice Set the indexer retention period for tracked indexer cleanup
+     * @dev Only callable by accounts with the OPERATOR_ROLE. Indexers whose last
+     * renewal timestamp is older than this period can be permissionlessly removed
+     * from the tracked set via {IRewardsEligibilityMaintenance-removeStaleIndexer}.
+     * @param indexerRetentionPeriod New retention period in seconds
+     * @return True if the state is as requested (retention period is set to the specified value)
+     */
+    function setIndexerRetentionPeriod(uint256 indexerRetentionPeriod) external returns (bool);
 }

packages/interfaces/contracts/issuance/eligibility/IRewardsEligibilityEvents.sol

@@ -31,4 +31,14 @@ interface IRewardsEligibilityEvents {
     /// @param oldTimeout The previous timeout period in seconds
     /// @param newTimeout The new timeout period in seconds
     event OracleUpdateTimeoutUpdated(uint256 indexed oldTimeout, uint256 indexed newTimeout);
+
+    /// @notice Emitted when an indexer is added to or removed from the tracked set
+    /// @param indexer The indexer address
+    /// @param tracked True when added (first renewal), false when removed (stale cleanup)
+    event IndexerTrackingUpdated(address indexed indexer, bool indexed tracked);
+
+    /// @notice Emitted when the indexer retention period is updated
+    /// @param oldPeriod The previous retention period in seconds
+    /// @param newPeriod The new retention period in seconds
+    event IndexerRetentionPeriodSet(uint256 indexed oldPeriod, uint256 indexed newPeriod);
 }

packages/interfaces/contracts/issuance/eligibility/IRewardsEligibilityHelper.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+pragma solidity ^0.7.6 || ^0.8.0;
+
+/**
+ * @title Interface for the {RewardsEligibilityHelper} contract
+ * @author Edge & Node
+ * @notice Stateless, permissionless convenience contract for {RewardsEligibilityOracle}.
+ * Provides batch removal of expired indexers from the tracked set.
+ * Independently deployable — better versions can be deployed without protocol changes.
+ *
+ * @custom:security-contact Please email security+contracts@thegraph.com if you find any
+ * bugs. We may have an active bug bounty program.
+ */
+interface IRewardsEligibilityHelper {
+    /**
+     * @notice Remove expired indexers from the tracked set by explicit address list
+     * @dev Calls {IRewardsEligibilityMaintenance-removeExpiredIndexer} for each address.
+     * @param indexers Array of indexer addresses to check and remove
+     * @return gone Number of indexers now absent from the tracked set
+     */
+    function removeExpiredIndexers(address[] calldata indexers) external returns (uint256 gone);
+
+    /**
+     * @notice Remove all expired indexers from the tracked set
+     * @dev Snapshots the full tracked set then calls
+     * {IRewardsEligibilityMaintenance-removeExpiredIndexer} for each.
+     * May be expensive for large sets; prefer the paginated overload for gas-bounded calls.
+     * @return gone Number of indexers now absent from the tracked set
+     */
+    function removeExpiredIndexers() external returns (uint256 gone);
+
+    /**
+     * @notice Remove expired indexers from the tracked set by paginated scan
+     * @dev Reads a slice of the tracked set via {IRewardsEligibilityStatus-getIndexers}
+     * and calls {IRewardsEligibilityMaintenance-removeExpiredIndexer} for each.
+     * Note: removals shift set indices between pages, so some indexers may be skipped
+     * across consecutive paginated calls. Use the parameterless overload to process all.
+     * @param offset Start index into the tracked indexer set
+     * @param count Maximum number of indexers to process
+     * @return gone Number of indexers now absent from the tracked set
+     */
+    function removeExpiredIndexers(uint256 offset, uint256 count) external returns (uint256 gone);
+}

packages/interfaces/contracts/issuance/eligibility/IRewardsEligibilityMaintenance.sol

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+pragma solidity ^0.7.6 || ^0.8.0;
+
+import { IRewardsEligibilityEvents } from "./IRewardsEligibilityEvents.sol";
+
+/**
+ * @title IRewardsEligibilityMaintenance
+ * @author Edge & Node
+ * @notice Interface for permissionless maintenance of the tracked indexer set.
+ * Allows anyone to remove indexers whose last renewal is older than the
+ * configured indexer retention period.
+ */
+interface IRewardsEligibilityMaintenance is IRewardsEligibilityEvents {
+    /**
+     * @notice Remove an expired indexer from the tracked set
+     * @dev Permissionless. An indexer is expired when
+     * `block.timestamp >= renewalTimestamp + indexerRetentionPeriod`.
+     * Removes the indexer from the enumerable set and deletes its renewal timestamp.
+     * No-op (returns true) if the indexer is not in the tracked set.
+     * @param indexer The indexer address to remove
+     * @return gone True if the indexer is absent from the tracked set (whether removed
+     * by this call or already not tracked); false if the indexer is still tracked (not expired)
+     */
+    function removeExpiredIndexer(address indexer) external returns (bool gone);
+}

packages/interfaces/contracts/issuance/eligibility/IRewardsEligibilityStatus.sol

@@ -39,4 +39,31 @@ interface IRewardsEligibilityStatus {
      * @return True if eligibility validation is enabled, false otherwise
      */
     function getEligibilityValidation() external view returns (bool);
+
+    /**
+     * @notice Get the indexer retention period for tracked indexer cleanup
+     * @return The current indexer retention period in seconds
+     */
+    function getIndexerRetentionPeriod() external view returns (uint256);
+
+    /**
+     * @notice Get the number of tracked indexers
+     * @return count The number of indexers in the tracked set
+     */
+    function getIndexerCount() external view returns (uint256 count);
+
+    /**
+     * @notice Get all tracked indexer addresses
+     * @dev May be expensive for large sets — prefer the paginated overload for on-chain use.
+     * @return result Array of tracked indexer addresses
+     */
+    function getIndexers() external view returns (address[] memory result);
+
+    /**
+     * @notice Get a paginated slice of tracked indexer addresses
+     * @param offset The index to start from
+     * @param count Maximum number to return (clamped to available)
+     * @return result Array of tracked indexer addresses
+     */
+    function getIndexers(uint256 offset, uint256 count) external view returns (address[] memory result);
 }

packages/issuance/contracts/allocate/DirectAllocation.sol

@@ -5,6 +5,7 @@ pragma solidity ^0.8.27;
 import { IIssuanceTarget } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceTarget.sol";
 import { ISendTokens } from "@graphprotocol/interfaces/contracts/issuance/allocate/ISendTokens.sol";
 import { BaseUpgradeable } from "../common/BaseUpgradeable.sol";
+import { IGraphToken } from "../common/IGraphToken.sol";
 
 // solhint-disable-next-line no-unused-import
 import { ERC165Upgradeable } from "@openzeppelin/contracts-upgradeable/utils/introspection/ERC165Upgradeable.sol"; // Used by @inheritdoc
@@ -38,19 +39,16 @@ contract DirectAllocation is BaseUpgradeable, IIssuanceTarget, ISendTokens {
     event TokensSent(address indexed to, uint256 indexed amount);
     // Do not need to index amount, ignoring gas-indexed-events warning.
 
-    /// @notice Emitted before the issuance allocation changes
-    event BeforeIssuanceAllocationChange();
-
     // -- Constructor --
 
     /**
      * @notice Constructor for the DirectAllocation contract
      * @dev This contract is upgradeable, but we use the constructor to pass the Graph Token address
      * to the base contract.
-     * @param graphToken Address of the Graph Token contract
+     * @param graphToken The Graph Token contract
      * @custom:oz-upgrades-unsafe-allow constructor
      */
-    constructor(address graphToken) BaseUpgradeable(graphToken) {}
+    constructor(IGraphToken graphToken) BaseUpgradeable(graphToken) {}
 
     // -- Initialization --
 
@@ -89,9 +87,7 @@ contract DirectAllocation is BaseUpgradeable, IIssuanceTarget, ISendTokens {
      * before an allocation change. We simply receive tokens from the IssuanceAllocator.
      * @inheritdoc IIssuanceTarget
      */
-    function beforeIssuanceAllocationChange() external virtual override {
-        emit BeforeIssuanceAllocationChange();
-    }
+    function beforeIssuanceAllocationChange() external virtual override {}
 
     /**
      * @dev No-op for DirectAllocation; issuanceAllocator is not stored.

packages/issuance/contracts/allocate/IssuanceAllocator.sol

@@ -15,6 +15,7 @@ import { IIssuanceAllocationStatus } from "@graphprotocol/interfaces/contracts/i
 import { IIssuanceAllocationData } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocationData.sol";
 import { IIssuanceTarget } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceTarget.sol";
 import { BaseUpgradeable } from "../common/BaseUpgradeable.sol";
+import { IGraphToken } from "../common/IGraphToken.sol";
 import { ReentrancyGuardTransient } from "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";
 import { IERC165 } from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
@@ -324,10 +325,10 @@ contract IssuanceAllocator is
      * @notice Constructor for the IssuanceAllocator contract
      * @dev This contract is upgradeable, but we use the constructor to pass the Graph Token address
      * to the base contract.
-     * @param _graphToken Address of the Graph Token contract
+     * @param _graphToken The Graph Token contract
      * @custom:oz-upgrades-unsafe-allow constructor
      */
-    constructor(address _graphToken) BaseUpgradeable(_graphToken) {}
+    constructor(IGraphToken _graphToken) BaseUpgradeable(_graphToken) {}
 
     // -- Initialization --
 

packages/issuance/contracts/common/BaseUpgradeable.sol

@@ -87,12 +87,12 @@ abstract contract BaseUpgradeable is
      * @notice Constructor for the BaseUpgradeable contract
      * @dev This contract is upgradeable, but we use the constructor to set immutable variables
      * and disable initializers to prevent the implementation contract from being initialized.
-     * @param graphToken Address of the Graph Token contract
+     * @param graphToken The Graph Token contract
      * @custom:oz-upgrades-unsafe-allow constructor
      */
-    constructor(address graphToken) {
-        require(graphToken != address(0), GraphTokenCannotBeZeroAddress());
-        GRAPH_TOKEN = IGraphToken(graphToken);
+    constructor(IGraphToken graphToken) {
+        require(address(graphToken) != address(0), GraphTokenCannotBeZeroAddress());
+        GRAPH_TOKEN = graphToken;
         _disableInitializers();
     }
 

packages/issuance/contracts/common/EnumerableSetUtil.sol

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+pragma solidity ^0.8.27;
+
+import { EnumerableSet } from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+/**
+ * @title EnumerableSetUtil
+ * @author Edge & Node
+ * @notice Pagination helpers for OpenZeppelin EnumerableSet types.
+ */
+library EnumerableSetUtil {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+
+    /**
+     * @notice Return a page of addresses from an AddressSet.
+     * @param set The enumerable address set to paginate
+     * @param offset Number of entries to skip
+     * @param count Maximum number of entries to return
+     * @return result Array of addresses (may be shorter than count)
+     */
+    function getPage(
+        EnumerableSet.AddressSet storage set,
+        uint256 offset,
+        uint256 count
+    ) internal view returns (address[] memory result) {
+        uint256 total = set.length();
+        // solhint-disable-next-line gas-strict-inequalities
+        if (total <= offset) return new address[](0);
+
+        uint256 remaining = total - offset;
+        if (remaining < count) count = remaining;
+
+        result = new address[](count);
+        for (uint256 i = 0; i < count; ++i) result[i] = set.at(offset + i);
+    }
+
+    /**
+     * @notice Return a page of bytes16 ids from a Bytes32Set (truncating each entry).
+     * @param set The enumerable bytes32 set to paginate
+     * @param offset Number of entries to skip
+     * @param count Maximum number of entries to return
+     * @return result Array of bytes16 values (may be shorter than count)
+     */
+    function getPageBytes16(
+        EnumerableSet.Bytes32Set storage set,
+        uint256 offset,
+        uint256 count
+    ) internal view returns (bytes16[] memory result) {
+        uint256 total = set.length();
+        // solhint-disable-next-line gas-strict-inequalities
+        if (total <= offset) return new bytes16[](0);
+
+        uint256 remaining = total - offset;
+        if (remaining < count) count = remaining;
+
+        result = new bytes16[](count);
+        for (uint256 i = 0; i < count; ++i) result[i] = bytes16(set.at(offset + i));
+    }
+}

packages/issuance/contracts/eligibility/RewardsEligibilityHelper.sol

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+pragma solidity ^0.8.27;
+
+import { IRewardsEligibilityHelper } from "@graphprotocol/interfaces/contracts/issuance/eligibility/IRewardsEligibilityHelper.sol";
+import { IRewardsEligibilityMaintenance } from "@graphprotocol/interfaces/contracts/issuance/eligibility/IRewardsEligibilityMaintenance.sol";
+import { IRewardsEligibilityStatus } from "@graphprotocol/interfaces/contracts/issuance/eligibility/IRewardsEligibilityStatus.sol";
+
+/**
+ * @title RewardsEligibilityHelper
+ * @author Edge & Node
+ * @notice Stateless, permissionless convenience contract for {RewardsEligibilityOracle}.
+ * Provides batch removal of expired indexers from the tracked set.
+ * Independently deployable — better versions can be deployed without protocol changes.
+ *
+ * @custom:security-contact Please email security+contracts@thegraph.com if you find any
+ * bugs. We may have an active bug bounty program.
+ */
+contract RewardsEligibilityHelper is IRewardsEligibilityHelper {
+    /// @notice The RewardsEligibilityOracle contract address
+    address public immutable ORACLE;
+
+    /// @notice Thrown when an address parameter is the zero address
+    error ZeroAddress();
+
+    /**
+     * @notice Constructor for the RewardsEligibilityHelper contract
+     * @param oracle Address of the RewardsEligibilityOracle contract
+     */
+    constructor(address oracle) {
+        require(oracle != address(0), ZeroAddress());
+        ORACLE = oracle;
+    }
+
+    /// @inheritdoc IRewardsEligibilityHelper
+    function removeExpiredIndexers(address[] calldata indexers) external returns (uint256 gone) {
+        for (uint256 i = 0; i < indexers.length; ++i)
+            if (IRewardsEligibilityMaintenance(ORACLE).removeExpiredIndexer(indexers[i])) ++gone;
+    }
+
+    /// @inheritdoc IRewardsEligibilityHelper
+    function removeExpiredIndexers() external returns (uint256 gone) {
+        address[] memory indexers = IRewardsEligibilityStatus(ORACLE).getIndexers();
+        for (uint256 i = 0; i < indexers.length; ++i)
+            if (IRewardsEligibilityMaintenance(ORACLE).removeExpiredIndexer(indexers[i])) ++gone;
+    }
+
+    /// @inheritdoc IRewardsEligibilityHelper
+    function removeExpiredIndexers(uint256 offset, uint256 count) external returns (uint256 gone) {
+        address[] memory indexers = IRewardsEligibilityStatus(ORACLE).getIndexers(offset, count);
+        for (uint256 i = 0; i < indexers.length; ++i)
+            if (IRewardsEligibilityMaintenance(ORACLE).removeExpiredIndexer(indexers[i])) ++gone;
+    }
+}