# IncentiveRewardsDistributor
### Overview
**IncentiveRewardsDistributor** is a contract that builds upon an abstract **RewardsDistributor** to manage the distribution of incentive rewards within the EYWA ecosystem. The **RewardsDistributor** base contract provides fundamental logic for tracking deposits, withdrawals, reward notifications, and reward claims over discrete epochs. The **IncentiveRewardsDistributor** adds:
1. **Whitelisting of Tokens:** Before accepting a new token as a reward token, it checks with the escrow vote manager to ensure it is whitelisted.
2. **Escrow Vote Manager Authorization:** Restricts calls to certain functions (like `getReward`) to only the authorized vote manager.
3. **Inheritance and Extended Logic:** Integrates seamlessly with the epoch-based deposit/withdraw system in `RewardsDistributor` to finalize reward amounts and calculations.
By implementing `IIncentiveRewardsDistributor`, this contract conforms to a standard reward distributor interface used throughout the EYWA ecosystem.
***
### Inherited Contracts and Interfaces
* **RewardsDistributor (Abstract Contract):**
* Manages core reward distribution functionality, such as:
* Tracking how many tokens each owner has deposited during a specific epoch.
* Storing how many rewards are allocated to a token for each epoch.
* Calculating earned rewards for each owner at specific epochs and enabling claim logic.
* Declares and implements the `IRewardsDistributor` interface.
* **IIncentiveRewardsDistributor:**
* Extends `IRewardsDistributor` with additional constraints and methods (`getReward` & `notifyRewardAmount` restricted to certain checks).
**Additional External References:**
* **IEscrowVoteManagerV1:**
* Provides `s_isWhitelistedToken` to validate new reward tokens.
* Acts as an authorization gate for methods that require `msg.sender` to be the vote manager.
* **IEscrowManager:**
* Gives ownership and deposit/withdraw data for NFT-based locks.
* Indirectly leveraged via `RewardsDistributor` functions for deposit/withdraw logic.
* **ReentrancyGuard (OpenZeppelin):**
* Inherited in `RewardsDistributor` to prevent re-entrant calls.
* **SafeERC20, IERC20 (OpenZeppelin):**
* Used for secure ERC20 transfers.
***
### Contract Architecture
```
IncentiveRewardsDistributor (Concrete)
└── RewardsDistributor (Abstract)
└── IRewardsDistributor (Interface)
```
#### Inherited from **RewardsDistributor**
The base **RewardsDistributor** constructor sets immutable references for `ESCROW_VOTE_MANAGER` and `ESCROW_MANAGER`. It also defines the following main categories of functionality:
1. **Epoch-Based Deposit and Withdrawal:**
* `deposit(uint256 amount_, uint256 tokenId_)`
* `withdraw(uint256 amount_, uint256 tokenId_)`
2. **Reward Notification and Calculation:**
* `notifyRewardAmount(address rewardToken_, uint256 rewardAmount_)` (abstract here, implemented in the child contract)
* `earned(address owner_, address rewardToken_)` and `earnedByEpoch(address owner_, address rewardToken_, uint256 epoch_)`
* `rewardPerToken(address rewardToken_, uint256 epoch_)`
3. **Claiming Rewards:**
* `getReward(address owner_, address[] calldata rewardTokens_)` (abstract here, partially implemented in the child)
* `_getReward(address owner_, address[] calldata rewardTokens_)` (internal)
4. **Data Structures for Epoch Accounting and Balances:**
* Mappings storing how much each user has deposited per epoch, total supply per epoch, and how much reward is allocated per epoch.
We now detail each of these base functions.
***
### Functions in the **Base Contract**: `RewardsDistributor`
#### 1. **Constructor**
```solidity
constructor(address escrowVoteManager_, address escrowManager_) {
ESCROW_VOTE_MANAGER = escrowVoteManager_;
ESCROW_MANAGER = escrowManager_;
}
```
* **Description:**\
Sets `ESCROW_VOTE_MANAGER` and `ESCROW_MANAGER` as immutable addresses, used for authorization and lock ownership lookups.
* **Parameters:**
* `escrowVoteManager_`: The address of the escrow vote manager contract.
* `escrowManager_`: The address of the escrow manager contract.
***
#### 2. **`deposit(uint256 amount_, uint256 tokenId_)`**
```solidity
function deposit(uint256 amount_, uint256 tokenId_) external
```
* **Description:**
* Called by the escrow vote manager to record that `amount_` of tokens have been deposited for the lock represented by `tokenId_` in the current epoch.
* Increments the total supply and the lock owner’s balance for the current epoch.
* **Checks:**
* `msg.sender == ESCROW_VOTE_MANAGER`; otherwise `UnauthorizedAccess()`.
* **Logic:**
1. Queries the current epoch start via `IEscrowVoteManagerV1(ESCROW_VOTE_MANAGER).currentEpochStart()`.
2. Increments `s_totalSupplyByEpoch[m_currentEpochStart]` by `amount_`.
3. Retrieves lock owner via `IEscrowManager(ESCROW_MANAGER).ownerOf(tokenId_)`.
4. Increments `s_balanceByOwnerAndEpoch[m_owner][m_currentEpochStart]` by `amount_`.
5. Emits `TokensDeposited(m_owner, tokenId_, amount_)`.
***
#### 3. **`withdraw(uint256 amount_, uint256 tokenId_)`**
```solidity
function withdraw(uint256 amount_, uint256 tokenId_) external
```
* **Description:**
* Called by the escrow vote manager to record that `amount_` of tokens have been removed from the lock represented by `tokenId_` in the current epoch.
* Decrements the total supply and the lock owner’s balance for the current epoch.
* **Checks:**
* `msg.sender == ESCROW_VOTE_MANAGER`; otherwise `UnauthorizedAccess()`.
* **Logic:**
1. Gets the current epoch start, as with `deposit`.
2. Decrements `s_totalSupplyByEpoch[m_currentEpochStart]` by `amount_`.
3. Finds lock owner and decreases `s_balanceByOwnerAndEpoch[m_owner][m_currentEpochStart]` by `amount_`.
4. Emits `TokensWithdrawn(m_owner, tokenId_, amount_)`.
***
#### 4. **`getRewardTokensCount()`**
```solidity
function getRewardTokensCount() external view returns (uint256)
```
* **Description:**\
Returns the length of the `s_rewardTokens` array, i.e., how many reward tokens the distributor currently recognizes.
* **Return:**
* `uint256`: number of recognized reward tokens.
***
#### 5. **`earned(address owner_, address rewardToken_)`**
```solidity
function earned(address owner_, address rewardToken_) public view returns (uint256, uint256)
```
* **Description:**
* Computes how many tokens of `rewardToken_` the `owner_` has earned across epochs since their last claim.
* Iterates through epochs in weekly increments up to a maximum of 52 (1-year look-back) or until reaching the current epoch.
* **Returns:**
* `(uint256 m_reward, uint256 m_lastRewardClaim)`: the total reward due and the final epoch boundary used for calculation.
* **Logic:**
1. Checks if `rewardToken_` is recognized in `s_isRewardToken[rewardToken_]`. If not, returns `(0,0)`.
2. Locates the last claimed epoch timestamp for `(owner_, rewardToken_)`.
3. Repeatedly calls `earnedByEpoch(...)` for each epoch from `m_lastRewardClaim` up to but not including `currentEpochStart`.
4. Summation is the total pending rewards.
***
#### 6. **`earnedByEpoch(address owner_, address rewardToken_, uint256 epoch_)`**
```solidity
function earnedByEpoch(address owner_, address rewardToken_, uint256 epoch_) public view returns (uint256)
```
* **Description:**
* Returns how many `rewardToken_` tokens were earned by `owner_` specifically in a single epoch.
* Calculated as `rewardPerToken(rewardToken_, epoch_) * s_balanceByOwnerAndEpoch[owner_][epoch_] / 1e18`.
***
#### 7. **`rewardPerToken(address rewardToken_, uint256 epoch_)`**
```solidity
function rewardPerToken(address rewardToken_, uint256 epoch_) public view returns (uint256)
```
* **Description:**
* Calculates the distribution ratio for `rewardToken_` in a given `epoch_`.
* If `s_totalSupplyByEpoch[epoch_]` is zero, it simply returns `s_rewardAmountByTokenAndEpoch[rewardToken_][epoch_]`.
* Otherwise, divides that reward amount by the epoch’s total supply (scaled by `1e18`).
* **Return:**
* `uint256`: The per-token reward ratio used to multiply by an owner’s deposit amount to get their share.
***
#### 8. **`getReward(address owner_, address[] calldata rewardTokens_)` (abstract)**
```solidity
function getReward(address owner_, address[] calldata rewardTokens_) external virtual;
```
* **Description:**
* Abstract in the base **RewardsDistributor**. The child contract (`IncentiveRewardsDistributor`) provides the actual implementation.
* Child’s implementation calls `_getReward(...)` internally after verifying authorization.
***
#### 9. **`notifyRewardAmount(address rewardToken_, uint256 rewardAmount_)` (abstract)**
```solidity
function notifyRewardAmount(address rewardToken_, uint256 rewardAmount_) external virtual;
```
* **Description:**
* Abstract method for adding new reward tokens. Child contract overrides this to add whitelisting checks or additional logic.
* The base logic is available in `_notifyRewardAmount(...)` (see below).
***
#### 10. **`_getReward(address owner_, address[] calldata rewardTokens_)` (internal)**
```solidity
function _getReward(address owner_, address[] calldata rewardTokens_) internal
```
* **Description:**
* The internal function that loops over `rewardTokens_`, calculates `earned(...)`, updates `s_lastRewardClaimByOwnerAndToken`, and transfers the reward to `owner_`.
* Finally, emits `RewardsClaimed(owner_, token, amount)`.
***
#### 11. **`_notifyRewardAmount(address sender_, address rewardToken_, uint256 rewardAmount_)` (internal)**
```solidity
function _notifyRewardAmount(address sender_, address rewardToken_, uint256 rewardAmount_) internal
```
* **Description:**
* Transfers `rewardAmount_` of `rewardToken_` from `sender_` to this distributor.
* Adds the difference in the contract’s balance to `s_rewardAmountByTokenAndEpoch[rewardToken_][currentEpochStart]`.
* If `s_initialIncentiveTimestamp == 0`, sets it to the current epoch start.
* Emits `RewardNotified(sender_, rewardToken_, epoch, difference)`.
***
### Functions in **IncentiveRewardsDistributor**
#### Constructor
```solidity
constructor(address escrowVoteManager_, address escrowManager_)
RewardsDistributor(escrowVoteManager_, escrowManager_)
{}
```
* **Description:**
* Calls the **RewardsDistributor** constructor to set `ESCROW_VOTE_MANAGER` and `ESCROW_MANAGER`.
* No additional logic besides inheritance.
***
#### `getReward(address owner_, address[] calldata rewardTokens_)`
```solidity
function getReward(
address owner_,
address[] calldata rewardTokens_
)
external
override (RewardsDistributor, IIncentiveRewardsDistributor)
nonReentrant
```
* **Description:**
* Implementation of `getReward` from both `RewardsDistributor` (abstract) and `IIncentiveRewardsDistributor`.
* Allows the escrow vote manager to claim rewards for `owner_`.
* Calls `_getReward(...)` internally after checking `msg.sender == ESCROW_VOTE_MANAGER`.
***
#### `notifyRewardAmount(address rewardToken_, uint256 rewardAmount_)`
```solidity
function notifyRewardAmount(
address rewardToken_,
uint256 rewardAmount_
)
external
override (RewardsDistributor, IIncentiveRewardsDistributor)
nonReentrant
```
* **Description:**
* Implementation of `notifyRewardAmount` from both `RewardsDistributor` (abstract) and `IIncentiveRewardsDistributor`.
* First ensures `rewardToken_` is whitelisted via `s_isWhitelistedToken` in `IEscrowVoteManagerV1`.
* If the token is not recognized (`!s_isRewardToken[rewardToken_]`), checks the vote manager to see if it’s whitelisted; if so, it’s now added to `s_rewardTokens`.
* If not whitelisted, reverts with `NotWhitelisted()`.
* Calls `_notifyRewardAmount(msg.sender, rewardToken_, rewardAmount_)` to handle actual fund transfer and epoch reward updates.
***
### Events and Errors
#### Inherited Events
1. **`TokensDeposited(from, tokenId, amount)`**
2. **`TokensWithdrawn(from, tokenId, amount)`**
3. **`RewardNotified(from, token, epoch, amount)`**
4. **`RewardsClaimed(from, token, amount)`**
#### Inherited Errors
* **`InvalidRewardToken()`**
* **`UnauthorizedAccess()`**
* **`ZeroAmountProvided()`**
* **`NotWhitelisted()`**
No new custom events or errors are introduced in **IncentiveRewardsDistributor** beyond what’s inherited.
***
### Summary
**IncentiveRewardsDistributor** leverages the robust, epoch-based reward accounting system from **RewardsDistributor** to facilitate secure incentive distribution in the EYWA ecosystem, adding token whitelisting checks and limiting reward claims (`getReward`) to calls from the escrow vote manager. This design ensures:
* **Authorized Control:** Only recognized and whitelisted tokens can be notified as rewards; only the escrow vote manager can trigger claims.
* **Accurate Reward Calculations:** Inherits deposit/withdraw logic to track each user’s epoch-based balance.
* **Easy Integration:** Conforms to the `IIncentiveRewardsDistributor` interface, providing consistent methods for reward notifications and claims across the system.
Together with the **RewardsDistributor** base contract, **IncentiveRewardsDistributor** offers a flexible, robust means of awarding incentive tokens in a multi-lock, epoch-based environment.