Merge pull request #1256 from graphprotocol/rewards-eligibility-oracle-4

Rewards Eligibility Oracle (REO) (rebased)

Author: RembrandtK

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

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+pragma solidity ^0.7.6 || ^0.8.0;
+
+import { IRewardsEligibilityEvents } from "./IRewardsEligibilityEvents.sol";
+
+/**
+ * @title IRewardsEligibilityAdministration
+ * @author Edge & Node
+ * @notice Interface for administrative operations on rewards eligibility
+ * @dev Functions in this interface are restricted to accounts with OPERATOR_ROLE
+ */
+interface IRewardsEligibilityAdministration is IRewardsEligibilityEvents {
+    /**
+     * @notice Set the eligibility period for indexers
+     * @dev Only callable by accounts with the OPERATOR_ROLE
+     * @param eligibilityPeriod New eligibility period in seconds
+     * @return True if the state is as requested (eligibility period is set to the specified value)
+     */
+    function setEligibilityPeriod(uint256 eligibilityPeriod) external returns (bool);
+
+    /**
+     * @notice Set the oracle update timeout
+     * @dev Only callable by accounts with the OPERATOR_ROLE
+     * @param oracleUpdateTimeout New timeout period in seconds
+     * @return True if the state is as requested (timeout is set to the specified value)
+     */
+    function setOracleUpdateTimeout(uint256 oracleUpdateTimeout) external returns (bool);
+
+    /**
+     * @notice Set eligibility validation state
+     * @dev Only callable by accounts with the OPERATOR_ROLE
+     * @param enabled True to enable eligibility validation, false to disable
+     * @return True if successfully set (always the case for current code)
+     */
+    function setEligibilityValidation(bool enabled) external returns (bool);
+}

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+pragma solidity ^0.7.6 || ^0.8.0;
+
+/**
+ * @title IRewardsEligibilityEvents
+ * @author Edge & Node
+ * @notice Shared events for rewards eligibility interfaces
+ */
+interface IRewardsEligibilityEvents {
+    /// @notice Emitted when an oracle submits eligibility data
+    /// @param oracle The address of the oracle that submitted the data
+    /// @param data The eligibility data submitted by the oracle
+    event IndexerEligibilityData(address indexed oracle, bytes data);
+
+    /// @notice Emitted when an indexer's eligibility is renewed by an oracle
+    /// @param indexer The address of the indexer whose eligibility was renewed
+    /// @param oracle The address of the oracle that renewed the indexer's eligibility
+    event IndexerEligibilityRenewed(address indexed indexer, address indexed oracle);
+
+    /// @notice Emitted when the eligibility period is updated
+    /// @param oldPeriod The previous eligibility period in seconds
+    /// @param newPeriod The new eligibility period in seconds
+    event EligibilityPeriodUpdated(uint256 indexed oldPeriod, uint256 indexed newPeriod);
+
+    /// @notice Emitted when eligibility validation is enabled or disabled
+    /// @param enabled True if eligibility validation is enabled, false if disabled
+    event EligibilityValidationUpdated(bool indexed enabled);
+
+    /// @notice Emitted when the oracle update timeout is updated
+    /// @param oldTimeout The previous timeout period in seconds
+    /// @param newTimeout The new timeout period in seconds
+    event OracleUpdateTimeoutUpdated(uint256 indexed oldTimeout, uint256 indexed newTimeout);
+}

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

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+pragma solidity ^0.7.6 || ^0.8.0;
+
+import { IRewardsEligibilityEvents } from "./IRewardsEligibilityEvents.sol";
+
+/**
+ * @title IRewardsEligibilityReporting
+ * @author Edge & Node
+ * @notice Interface for oracle reporting of indexer eligibility
+ * @dev Functions in this interface are restricted to accounts with ORACLE_ROLE
+ */
+interface IRewardsEligibilityReporting is IRewardsEligibilityEvents {
+    /**
+     * @notice Renew eligibility for provided indexers to receive rewards
+     * @param indexers Array of indexer addresses. Zero addresses are ignored.
+     * @param data Arbitrary calldata for future extensions
+     * @return Number of indexers whose eligibility renewal timestamp was updated
+     */
+    function renewIndexerEligibility(address[] calldata indexers, bytes calldata data) external returns (uint256);
+}

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

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+pragma solidity ^0.7.6 || ^0.8.0;
+
+/**
+ * @title IRewardsEligibilityStatus
+ * @author Edge & Node
+ * @notice Interface for querying rewards eligibility status and configuration
+ * @dev All functions are view-only and can be called by anyone
+ */
+interface IRewardsEligibilityStatus {
+    /**
+     * @notice Get the last eligibility renewal timestamp for an indexer
+     * @param indexer Address of the indexer
+     * @return The last eligibility renewal timestamp, or 0 if the indexer's eligibility has never been renewed
+     */
+    function getEligibilityRenewalTime(address indexer) external view returns (uint256);
+
+    /**
+     * @notice Get the eligibility period
+     * @return The current eligibility period in seconds
+     */
+    function getEligibilityPeriod() external view returns (uint256);
+
+    /**
+     * @notice Get the oracle update timeout
+     * @return The current oracle update timeout in seconds
+     */
+    function getOracleUpdateTimeout() external view returns (uint256);
+
+    /**
+     * @notice Get the last oracle update time
+     * @return The timestamp of the last oracle update
+     */
+    function getLastOracleUpdateTime() external view returns (uint256);
+
+    /**
+     * @notice Get eligibility validation state
+     * @return True if eligibility validation is enabled, false otherwise
+     */
+    function getEligibilityValidation() external view returns (bool);
+}