fix: enable forced reward reclaiming for TRST-L-1 and clarify precedence for TRST-R-5

Addresses TRST-L-1: "Reward reclaiming efficiency is significantly limited"
Addresses TRST-R-5: "Clarify reclaim precedence"

The TRST-L-1 audit finding identified that reward reclaiming through takeRewards()
is flawed because a rational indexer who would not receive rewards would not
trigger the rewarding logic in the first place. The recommended mitigation is to
add calls from SubgraphService so that any entity can force a reclaim of denied
rewards. (Not adding to StakingExtension as it is deprecated and will soon not
be used.)

The TRST-R-5 finding noted that the precedence when both denial reasons apply
should be documented. Added explicit documentation that subgraph denylist
reclaim is prioritized over indexer eligibility reclaim.

Key changes:

1. Created RewardsReclaim library with canonical reclaim reason constants
   using bytes32 identifiers (like OpenZeppelin roles) for extensibility

2. Migrated RewardsManagerStorage from separate reclaim address storage to
   extensible mapping:
   - Old: indexerEligibilityReclaimAddress, subgraphDeniedReclaimAddress
   - New: mapping(bytes32 => address) reclaimAddresses

3. Replaced type-specific setters with generic setReclaimAddress(bytes32, address)

4. Refactored RewardsManager.takeRewards() with early return for zero rewards
   and extracted helper functions:
   - _calcAllocationRewards(): extract allocation data calculation
   - _reclaimRewards(): common reclaim logic with named return value
   - _deniedRewards(): implements short-circuit pattern with precedence
     (SUBGRAPH_DENIED checked before INDEXER_INELIGIBLE)

5. Added public reclaimRewards() for external contracts to reclaim rewards
   with custom reasons and data

6. Updated AllocationManager._presentPOI() to explicitly call reclaimRewards()
   with specific reasons (STALE_POI, ALTRUISTIC_ALLOCATION, ZERO_POI,
   ALLOCATION_TOO_YOUNG) instead of relying on takeRewards(). This enables
   forced reclaiming of denied rewards, addressing the core TRST-L-1 issue.

7. Updated tests and mocks to use new bytes32-based API with RewardsReclaim
   constants

This allows any entity to force reclaim of denied rewards through SubgraphService,
and enables future extension with new reclaim reasons without contract changes.

Author: RembrandtK

packages/contracts/contracts/rewards/RewardsManager.sol

@@ -20,6 +20,7 @@ import { IRewardsManager } from "@graphprotocol/interfaces/contracts/contracts/r
 import { IIssuanceAllocationDistribution } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceAllocationDistribution.sol";
 import { IIssuanceTarget } from "@graphprotocol/interfaces/contracts/issuance/allocate/IIssuanceTarget.sol";
 import { IRewardsEligibility } from "@graphprotocol/interfaces/contracts/issuance/eligibility/IRewardsEligibility.sol";
+import { RewardsReclaim } from "@graphprotocol/interfaces/contracts/contracts/rewards/RewardsReclaim.sol";
 
 /**
  * @title Rewards Manager Contract
@@ -109,43 +110,29 @@ contract RewardsManager is RewardsManagerV6Storage, GraphUpgradeable, IERC165, I
     );
 
     /**
-     * @notice Emitted when the eligibility reclaim address is set
-     * @param oldReclaimAddress Previous eligibility reclaim address
-     * @param newReclaimAddress New eligibility reclaim address
+     * @notice Emitted when a reclaim address is set
+     * @param reason The reclaim reason identifier
+     * @param oldAddress Previous address
+     * @param newAddress New address
      */
-    event IndexerEligibilityReclaimAddressSet(address indexed oldReclaimAddress, address indexed newReclaimAddress);
+    event ReclaimAddressSet(bytes32 indexed reason, address indexed oldAddress, address indexed newAddress);
 
     /**
-     * @notice Emitted when the subgraph reclaim address is set
-     * @param oldReclaimAddress Previous subgraph reclaim address
-     * @param newReclaimAddress New subgraph reclaim address
-     */
-    event SubgraphDeniedReclaimAddressSet(address indexed oldReclaimAddress, address indexed newReclaimAddress);
-
-    /**
-     * @notice Emitted when denied rewards are reclaimed due to eligibility
-     * @param indexer Address of the indexer whose rewards were denied
-     * @param allocationID Address of the allocation
+     * @notice Emitted when rewards are reclaimed to a configured address
+     * @param reason The reclaim reason identifier
      * @param amount Amount of rewards reclaimed
-     */
-    event RewardsReclaimedDueToIndexerEligibility(
-        address indexed indexer,
-        address indexed allocationID,
-        uint256 amount
-    );
-
-    /**
-     * @notice Emitted when denied rewards are reclaimed due to subgraph denylist
-     * @param indexer Address of the indexer whose rewards were denied
+     * @param indexer Address of the indexer
      * @param allocationID Address of the allocation
-     * @param subgraphDeploymentID Subgraph deployment ID that was denied
-     * @param amount Amount of rewards reclaimed
+     * @param subgraphDeploymentID Subgraph deployment ID for the allocation
+     * @param data Additional context data for the reclaim
      */
-    event RewardsReclaimedDueToSubgraphDenylist(
+    event RewardsReclaimed(
+        bytes32 indexed reason,
+        uint256 amount,
         address indexed indexer,
         address indexed allocationID,
-        bytes32 indexed subgraphDeploymentID,
-        uint256 amount
+        bytes32 subgraphDeploymentID,
+        bytes data
     );
 
     // -- Modifiers --
@@ -306,27 +293,17 @@ contract RewardsManager is RewardsManagerV6Storage, GraphUpgradeable, IERC165, I
 
     /**
      * @inheritdoc IRewardsManager
-     * @dev Set to zero address to disable eligibility reclaim functionality
+     * @dev bytes32(0) is reserved as an invalid reason to prevent accidental misconfiguration
+     * and catch uninitialized reason identifiers.
      */
-    function setIndexerEligibilityReclaimAddress(address newReclaimAddress) external override onlyGovernor {
-        address oldReclaimAddress = indexerEligibilityReclaimAddress;
+    function setReclaimAddress(bytes32 reason, address newAddress) external override onlyGovernor {
+        require(reason != bytes32(0), "Cannot set reclaim address for (bytes32(0))");
 
-        if (oldReclaimAddress != newReclaimAddress) {
-            indexerEligibilityReclaimAddress = newReclaimAddress;
-            emit IndexerEligibilityReclaimAddressSet(oldReclaimAddress, newReclaimAddress);
-        }
-    }
+        address oldAddress = reclaimAddresses[reason];
 
-    /**
-     * @inheritdoc IRewardsManager
-     * @dev Set to zero address to disable subgraph reclaim functionality
-     */
-    function setSubgraphDeniedReclaimAddress(address newReclaimAddress) external override onlyGovernor {
-        address oldReclaimAddress = subgraphDeniedReclaimAddress;
-
-        if (oldReclaimAddress != newReclaimAddress) {
-            subgraphDeniedReclaimAddress = newReclaimAddress;
-            emit SubgraphDeniedReclaimAddressSet(oldReclaimAddress, newReclaimAddress);
+        if (oldAddress != newAddress) {
+            reclaimAddresses[reason] = newAddress;
+            emit ReclaimAddressSet(reason, oldAddress, newAddress);
         }
     }
 
@@ -561,64 +538,130 @@ contract RewardsManager is RewardsManagerV6Storage, GraphUpgradeable, IERC165, I
     }
 
     /**
-     * @notice Checks for and handles denial and reclaim of rewards due to subgraph deny list
-     * @dev If denied, emits RewardsDenied event and mints to reclaim address if configured
+     * @notice Calculate rewards for an allocation
+     * @param rewardsIssuer Address of the rewards issuer calling the function
+     * @param allocationID Address of the allocation
+     * @return rewards Amount of rewards calculated
+     * @return indexer Address of the indexer
+     * @return subgraphDeploymentID Subgraph deployment ID
+     */
+    function _calcAllocationRewards(
+        address rewardsIssuer,
+        address allocationID
+    ) private returns (uint256 rewards, address indexer, bytes32 subgraphDeploymentID) {
+        (
+            bool isActive,
+            address _indexer,
+            bytes32 _subgraphDeploymentID,
+            uint256 tokens,
+            uint256 accRewardsPerAllocatedToken,
+            uint256 accRewardsPending
+        ) = IRewardsIssuer(rewardsIssuer).getAllocationData(allocationID);
+
+        uint256 updatedAccRewardsPerAllocatedToken = onSubgraphAllocationUpdate(_subgraphDeploymentID);
+
+        rewards = isActive
+            ? accRewardsPending.add(
+                _calcRewards(tokens, accRewardsPerAllocatedToken, updatedAccRewardsPerAllocatedToken)
+            )
+            : 0;
+
+        indexer = _indexer;
+        subgraphDeploymentID = _subgraphDeploymentID;
+    }
+
+    /**
+     * @notice Common function to reclaim rewards to a configured address
+     * @param reason The reclaim reason identifier
+     * @param rewards Amount of rewards to reclaim
      * @param indexer Address of the indexer
      * @param allocationID Address of the allocation
-     * @param subgraphDeploymentID Subgraph deployment ID
-     * @param rewards Amount of rewards that would be distributed
-     * @return True if rewards are denied, false otherwise
+     * @param subgraphDeploymentID Subgraph deployment ID for the allocation
+     * @param data Additional context data for the reclaim
+     * @return reclaimed The amount of rewards that were reclaimed (0 if no reclaim address set)
      */
-    function _rewardsDeniedDueToSubgraphDenyList(
+    function _reclaimRewards(
+        bytes32 reason,
+        uint256 rewards,
         address indexer,
         address allocationID,
         bytes32 subgraphDeploymentID,
-        uint256 rewards
-    ) private returns (bool) {
-        if (isDenied(subgraphDeploymentID)) {
-            emit RewardsDenied(indexer, allocationID);
-
-            // If a reclaim address is set, mint the denied rewards there
-            if (0 < rewards && subgraphDeniedReclaimAddress != address(0)) {
-                graphToken().mint(subgraphDeniedReclaimAddress, rewards);
-                emit RewardsReclaimedDueToSubgraphDenylist(indexer, allocationID, subgraphDeploymentID, rewards);
-            }
-            return true;
+        bytes memory data
+    ) private returns (uint256 reclaimed) {
+        address target = reclaimAddresses[reason];
+        if (0 < rewards && target != address(0)) {
+            graphToken().mint(target, rewards);
+            emit RewardsReclaimed(reason, rewards, indexer, allocationID, subgraphDeploymentID, data);
+            reclaimed = rewards;
         }
-        return false;
     }
 
     /**
-     * @notice Checks for and handles denial and reclaim of rewards due to indexer eligibility
-     * @dev If denied, emits RewardsDeniedDueToEligibility event and mints to reclaim address if configured
+     * @notice Check if rewards should be denied and attempt to reclaim them
+     * @param rewards Amount of rewards to check
      * @param indexer Address of the indexer
      * @param allocationID Address of the allocation
-     * @param rewards Amount of rewards that would be distributed
-     * @return True if rewards are denied, false otherwise
-     */
-    function _rewardsDeniedDueToIndexerEligibility(
+     * @param subgraphDeploymentID Subgraph deployment ID for the allocation
+     * @return denied True if rewards should be denied (either reclaimed or dropped), false if they should be minted
+     * @dev First successful reclaim wins - checks performed in order with short-circuit on reclaim:
+     * 1. Subgraph deny list: emit RewardsDenied. If reclaim address set → reclaim and return (STOP, eligibility not checked)
+     * 2. Indexer eligibility: Checked if subgraph not denied OR denied without reclaim address. Emit RewardsDeniedDueToEligibility. If reclaim address set → reclaim and return
+     * Multiple denial events may be emitted only when multiple checks fail without reclaim addresses configured.
+     * Any failing check without a reclaim address still denies rewards (drops them without minting).
+     */
+    function _deniedRewards(
+        uint256 rewards,
         address indexer,
         address allocationID,
-        uint256 rewards
-    ) private returns (bool) {
+        bytes32 subgraphDeploymentID
+    ) private returns (bool denied) {
+        if (isDenied(subgraphDeploymentID)) {
+            emit RewardsDenied(indexer, allocationID);
+            if (
+                0 <
+                _reclaimRewards(
+                    RewardsReclaim.SUBGRAPH_DENIED,
+                    rewards,
+                    indexer,
+                    allocationID,
+                    subgraphDeploymentID,
+                    ""
+                )
+            ) {
+                return true; // Successfully reclaimed, deny rewards
+            }
+            denied = true; // Denied but no reclaim address
+        }
+
         if (address(rewardsEligibilityOracle) != address(0) && !rewardsEligibilityOracle.isEligible(indexer)) {
             emit RewardsDeniedDueToEligibility(indexer, allocationID, rewards);
-
-            // If a reclaim address is set, mint the denied rewards there
-            if (0 < rewards && indexerEligibilityReclaimAddress != address(0)) {
-                graphToken().mint(indexerEligibilityReclaimAddress, rewards);
-                emit RewardsReclaimedDueToIndexerEligibility(indexer, allocationID, rewards);
+            if (
+                0 <
+                _reclaimRewards(
+                    RewardsReclaim.INDEXER_INELIGIBLE,
+                    rewards,
+                    indexer,
+                    allocationID,
+                    subgraphDeploymentID,
+                    ""
+                )
+            ) {
+                return true; // Successfully reclaimed, deny rewards
             }
-            return true;
+            denied = true; // Denied but no reclaim address
         }
-        return false;
     }
 
     /**
      * @inheritdoc IRewardsManager
      * @dev This function can only be called by an authorized rewards issuer which are
      * the staking contract (for legacy allocations), and the subgraph service (for new allocations).
      * Mints 0 tokens if the allocation is not active.
+     * @dev First successful reclaim wins - short-circuits on reclaim:
+     * - If subgraph denied with reclaim address → reclaim to SUBGRAPH_DENIED address (eligibility NOT checked)
+     * - If subgraph not denied OR denied without address, then check eligibility → reclaim to INDEXER_INELIGIBLE if configured
+     * - Subsequent denial emitted only when earlier denial has no reclaim address
+     * - Any denial without reclaim address drops rewards (no minting)
      */
     function takeRewards(address _allocationID) external override returns (uint256) {
         address rewardsIssuer = msg.sender;
@@ -627,39 +670,37 @@ contract RewardsManager is RewardsManagerV6Storage, GraphUpgradeable, IERC165, I
             "Caller must be a rewards issuer"
         );
 
-        (
-            bool isActive,
-            address indexer,
-            bytes32 subgraphDeploymentID,
-            uint256 tokens,
-            uint256 accRewardsPerAllocatedToken,
-            uint256 accRewardsPending
-        ) = IRewardsIssuer(rewardsIssuer).getAllocationData(_allocationID);
-
-        uint256 updatedAccRewardsPerAllocatedToken = onSubgraphAllocationUpdate(subgraphDeploymentID);
+        (uint256 rewards, address indexer, bytes32 subgraphDeploymentID) = _calcAllocationRewards(
+            rewardsIssuer,
+            _allocationID
+        );
 
-        uint256 rewards = 0;
-        if (isActive) {
-            // Calculate rewards accrued by this allocation
-            rewards = accRewardsPending.add(
-                _calcRewards(tokens, accRewardsPerAllocatedToken, updatedAccRewardsPerAllocatedToken)
-            );
-        }
+        if (rewards == 0) return 0;
+        if (_deniedRewards(rewards, indexer, _allocationID, subgraphDeploymentID)) return 0;
 
-        if (_rewardsDeniedDueToSubgraphDenyList(indexer, _allocationID, subgraphDeploymentID, rewards)) return 0;
+        graphToken().mint(rewardsIssuer, rewards);
+        emit HorizonRewardsAssigned(indexer, _allocationID, rewards);
 
-        if (_rewardsDeniedDueToIndexerEligibility(indexer, _allocationID, rewards)) return 0;
+        return rewards;
+    }
 
-        // Mint rewards to the rewards issuer
-        if (rewards > 0) {
-            // Mint directly to rewards issuer for the reward amount
-            // The rewards issuer contract will do bookkeeping of the reward and
-            // assign in proportion to each stakeholder incentive
-            graphToken().mint(rewardsIssuer, rewards);
-        }
+    /**
+     * @inheritdoc IRewardsManager
+     * @dev bytes32(0) as a reason is reserved as a no-op and will not be reclaimed.
+     */
+    function reclaimRewards(
+        bytes32 reason,
+        address allocationID,
+        bytes calldata data
+    ) external override returns (uint256) {
+        address rewardsIssuer = msg.sender;
+        require(rewardsIssuer == address(subgraphService), "Not a rewards issuer");
 
-        emit HorizonRewardsAssigned(indexer, _allocationID, rewards);
+        (uint256 rewards, address indexer, bytes32 subgraphDeploymentID) = _calcAllocationRewards(
+            rewardsIssuer,
+            allocationID
+        );
 
-        return rewards;
+        return _reclaimRewards(reason, rewards, indexer, allocationID, subgraphDeploymentID, data);
     }
 }

packages/contracts/contracts/rewards/RewardsManagerStorage.sol

@@ -90,8 +90,7 @@ contract RewardsManagerV6Storage is RewardsManagerV5Storage {
     IRewardsEligibility public rewardsEligibilityOracle;
     /// @notice Address of the issuance allocator
     IIssuanceAllocationDistribution public issuanceAllocator;
-    /// @notice Address to receive tokens denied due to indexer eligibility checks, set to zero to disable
-    address public indexerEligibilityReclaimAddress;
-    /// @notice Address to receive tokens denied due to subgraph denylist, set to zero to disable
-    address public subgraphDeniedReclaimAddress;
+    /// @notice Mapping of reclaim reason identifiers to reclaim addresses
+    /// @dev Uses bytes32 for extensibility. See RewardsReclaim library for canonical reasons.
+    mapping(bytes32 => address) public reclaimAddresses;
 }

packages/contracts/contracts/tests/MockSubgraphService.sol

@@ -102,4 +102,28 @@ contract MockSubgraphService is IRewardsIssuer {
     function getSubgraphAllocatedTokens(bytes32 subgraphDeploymentId) external view override returns (uint256) {
         return subgraphAllocatedTokens[subgraphDeploymentId];
     }
+
+    /**
+     * @notice Helper function to call reclaimRewards on RewardsManager for testing
+     * @param rewardsManager Address of the RewardsManager contract
+     * @param reason Reason identifier for reclaiming rewards
+     * @param allocationId The allocation ID
+     * @param contextData Additional context data for the reclaim
+     * @return Amount of rewards reclaimed
+     */
+    function callReclaimRewards(
+        address rewardsManager,
+        bytes32 reason,
+        address allocationId,
+        bytes calldata contextData
+    ) external returns (uint256) {
+        // Call reclaimRewards on the RewardsManager
+        // solhint-disable-next-line avoid-low-level-calls
+        (bool success, bytes memory data) = rewardsManager.call(
+            // solhint-disable-next-line gas-small-strings
+            abi.encodeWithSignature("reclaimRewards(bytes32,address,bytes)", reason, allocationId, contextData)
+        );
+        require(success, "reclaimRewards call failed");
+        return abi.decode(data, (uint256));
+    }
 }