MiniChefV3

Inherits: Multicall, AccessControlEnumerable, Rescuable, SelfPermit, Pausable

A contract for managing staking, rewards, and pool information for liquidity providers.

This contract handles the logic for staking LP tokens, distributing rewards, and managing pool information. It supports multiple reward tokens through external rewarder contracts and includes emergency withdrawal functionality. It does not support rebasing or fee on transfer tokens.

State Variables

REWARD_TOKEN

Address of REWARD_TOKEN contract.

IERC20 public immutable REWARD_TOKEN;

_poolInfo

Info of each MCV3 pool.

PoolInfo[] private _poolInfo;

lpToken

Address of the LP token for each MCV3 pool.

IERC20[] public lpToken;

lpSupply

Total amount of LP token staked in each MCV3 pool.

uint256[] public lpSupply;

rewarder

Address of each IRewarder contract in MCV3.

IMiniChefV3Rewarder[] public rewarder;

_userInfo

Info of each user that stakes LP tokens.

mapping(uint256 => mapping(address => UserInfo)) private _userInfo;

_pidPlusOne

PID of the LP token plus one.

mapping(address => uint256) private _pidPlusOne;

totalAllocPoint

Total allocation points. Must be the sum of all allocation points in all pools.

uint256 public totalAllocPoint;

rewardPerSecond

The amount of REWARD_TOKEN distributed per second.

uint256 public rewardPerSecond;

availableReward

The amount of REWARD_TOKEN available in this contract for distribution.

uint256 public availableReward;

MAX_REWARD_TOKEN_PER_SECOND

The maximum amount of REWARD_TOKEN that can be distributed per second.

uint256 public constant MAX_REWARD_TOKEN_PER_SECOND = 100_000_000 ether / uint256(1 weeks);

_ACC_REWARD_TOKEN_PRECISION

Precision factor to calculate accumulated reward tokens per share.

uint256 private constant _ACC_REWARD_TOKEN_PRECISION = 1e12;

TIMELOCK_ROLE

The timelock role for the contract.

bytes32 public constant TIMELOCK_ROLE = keccak256("TIMELOCK_ROLE");

PAUSER_ROLE

The pauser role for the contract.

bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

Functions

constructor

Constructs the MiniChefV3 contract with a specified reward token and admin address.

constructor(IERC20 rewardToken_, address admin, address pauser) payable;

Parameters

Name	Type	Description
`rewardToken_`	`IERC20`	The ERC20 token to be used as the reward token.
`admin`	`address`	The address that will be granted the default admin role.
`pauser`	`address`

poolLength

Returns the number of MCV3 pools.

function poolLength() public view returns (uint256 pools);

pidOfLPToken

Retrieves the pool ID of a given LP token.

Returns the pool ID by looking up the LP token address in the _pidPlusOne mapping.

function pidOfLPToken(IERC20 lpToken_) external view returns (uint256 pid);

Parameters

Name	Type	Description
`lpToken_`	`IERC20`	The LP token to query the pool ID for.

Returns

Name	Type	Description
`pid`	`uint256`	The pool ID of the given LP token.

isLPTokenAdded

Checks if an LP token has been added to any pool.

The unchecked block is used here because the subtraction is safe from underflow. The condition above ensures that pidPlusOne is greater than zero, so subtracting one will not underflow.

Returns true if the LP token exists in the _pidPlusOne mapping.

function isLPTokenAdded(IERC20 lpToken_) external view returns (bool added);

Parameters

Name	Type	Description
`lpToken_`	`IERC20`	The LP token to check.

Returns

Name	Type	Description
`added`	`bool`	True if the LP token has been added to a pool.

getUserInfo

Retrieves user information for a specific pool.

Returns the user's staked amount, reward debt, and unpaid rewards for a given pool.

function getUserInfo(uint256 pid, address user) external view returns (UserInfo memory info);

Parameters

Name	Type	Description
`pid`	`uint256`	The pool ID to retrieve user information for.
`user`	`address`	The user address to retrieve information for.

Returns

Name	Type	Description
`info`	`UserInfo`	The user's information for the specified pool.

getPoolInfo

Retrieves pool information for a specific pool ID.

Returns the pool's accumulated reward per share, last reward time, and allocation points.

function getPoolInfo(uint256 pid) external view returns (PoolInfo memory info);

Parameters

Name	Type	Description
`pid`	`uint256`	The pool ID to retrieve information for.

Returns

Name	Type	Description
`info`	`PoolInfo`	The pool's information.

add

Add a new LP to the pool. Can only be called by the owner. DO NOT add the same LP token more than once. Rewards will be messed up if you do.

function add(uint32 allocPoint, IERC20 lpToken_, IMiniChefV3Rewarder rewarder_) public onlyRole(TIMELOCK_ROLE);

Parameters

Name	Type	Description
`allocPoint`	`uint32`	AP of the new pool.
`lpToken_`	`IERC20`	Address of the LP ERC-20 token.
`rewarder_`	`IMiniChefV3Rewarder`	Address of the rewarder delegate.

set

Update the given pool's REWARD_TOKEN allocation point and IRewarder contract. Can only be called by the owner.

function set(
    uint256 pid,
    uint32 allocPoint,
    IERC20 lpToken_,
    IMiniChefV3Rewarder rewarder_,
    bool overwrite
)
    public
    onlyRole(TIMELOCK_ROLE);

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.
`allocPoint`	`uint32`	New AP of the pool.
`lpToken_`	`IERC20`	Address of the LP ERC-20 token.
`rewarder_`	`IMiniChefV3Rewarder`	Address of the rewarder delegate.
`overwrite`	`bool`	True if rewarder_ should be `set`. Otherwise `rewarder_` is ignored.

rescue

function rescue(IERC20 token, address to, uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE);

setRewardPerSecond

Sets the reward per second to be distributed. Can only be called by the owner.

function setRewardPerSecond(uint256 rewardPerSecond_) public onlyRole(TIMELOCK_ROLE);

Parameters

Name	Type	Description
`rewardPerSecond_`	`uint256`	The amount of reward token to be distributed per second.

commitReward

Commits REWARD_TOKEN to the contract for distribution.

function commitReward(uint256 amount) external;

Parameters

Name	Type	Description
`amount`	`uint256`	The amount of REWARD_TOKEN to commit.

pendingReward

View function to see pending REWARD_TOKEN on frontend.

function pendingReward(uint256 pid, address user_) external view returns (uint256 pending);

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.
`user_`	`address`	Address of user.

Returns

Name	Type	Description
`pending`	`uint256`	REWARD_TOKEN reward for a given user.

updatePool

Update reward variables of the given pool.

function updatePool(uint256 pid) public returns (PoolInfo memory pool);

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.

Returns

Name	Type	Description
`pool`	`PoolInfo`	Returns the pool that was updated.

deposit

Deposit LP tokens to MCV3 for REWARD_TOKEN allocation.

Deposits can be paused in case of emergencies by the admin or pauser roles.

function deposit(uint256 pid, uint256 amount, address to) public whenNotPaused;

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.
`amount`	`uint256`	LP token amount to deposit.
`to`	`address`	The receiver of `amount` deposit benefit.

harvestAndWithdraw

Withdraw LP tokens from MCV3.

+= is slightly more gas efficient (5300) than the alternative (5365) using solidity 0.8.18. The rule only applies to non-mapping storage variables.

function harvestAndWithdraw(uint256 pid, uint256 amount, address to) public;

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.
`amount`	`uint256`	LP token amount to withdraw.
`to`	`address`	Receiver of the LP tokens.

harvest

Harvest proceeds for transaction sender to to.

unchecked is used as the subtraction is guaranteed to not underflow because rewardAmount is always less than or equal to availableReward_.

function harvest(uint256 pid, address to) public;

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.
`to`	`address`	Receiver of REWARD_TOKEN rewards.

emergencyWithdraw

Withdraw without caring about rewards. EMERGENCY ONLY.

unchecked is used as the subtraction is guaranteed to not underflow because rewardAmount is always less than or equal to availableReward_.

function emergencyWithdraw(uint256 pid, address to) public;

Parameters

Name	Type	Description
`pid`	`uint256`	The index of the pool. See `_poolInfo`.
`to`	`address`	Receiver of the LP tokens.

pause

Pauses the contract. Only callable by PAUSER_ROLE or DEFAULT_ADMIN_ROLE.

function pause() external;

unpause

Unpauses the contract. Only callable by DEFAULT_ADMIN_ROLE.

function unpause() external onlyRole(DEFAULT_ADMIN_ROLE);

Events

Deposit

Emitted when a user deposits LP tokens into a pool.

event Deposit(address indexed user, uint256 indexed pid, uint256 amount, address indexed to);

Parameters

Name	Type	Description
`user`	`address`	The address of the user making the deposit.
`pid`	`uint256`	The pool ID into which the deposit is made.
`amount`	`uint256`	The amount of LP tokens deposited.
`to`	`address`	The address receiving the deposit.

Withdraw

Emitted when a user withdraws LP tokens from a pool.

event Withdraw(address indexed user, uint256 indexed pid, uint256 amount, address indexed to);

Parameters

Name	Type	Description
`user`	`address`	The address of the user making the withdrawal.
`pid`	`uint256`	The pool ID from which the withdrawal is made.
`amount`	`uint256`	The amount of LP tokens withdrawn.
`to`	`address`	The address receiving the withdrawn LP tokens.

EmergencyWithdraw

Emitted when a user performs an emergency withdrawal of LP tokens from a pool.

event EmergencyWithdraw(address indexed user, uint256 indexed pid, uint256 amount, address indexed to);

Parameters

Name	Type	Description
`user`	`address`	The address of the user making the emergency withdrawal.
`pid`	`uint256`	The pool ID from which the emergency withdrawal is made.
`amount`	`uint256`	The amount of LP tokens emergency withdrawn.
`to`	`address`	The address receiving the emergency withdrawn LP tokens.

Harvest

Emitted when a user harvests reward tokens from a pool.

event Harvest(address indexed user, uint256 indexed pid, uint256 amount);

Parameters

Name	Type	Description
`user`	`address`	The address of the user performing the harvest.
`pid`	`uint256`	The pool ID from which the harvest is performed.
`amount`	`uint256`	The amount of reward tokens harvested.

LogPoolAddition

Emitted when a new pool is added to the MiniChef contract.

event LogPoolAddition(
    uint256 indexed pid, uint256 allocPoint, IERC20 indexed lpToken, IMiniChefV3Rewarder indexed rewarder
);

Parameters

Name	Type	Description
`pid`	`uint256`	The pool ID of the newly added pool.
`allocPoint`	`uint256`	The number of allocation points assigned to the new pool.
`lpToken`	`IERC20`	The address of the LP token for the new pool.
`rewarder`	`IMiniChefV3Rewarder`	The address of the rewarder contract for the new pool.

LogSetPool

Emitted when a pool's configuration is updated.

event LogSetPool(uint256 indexed pid, uint256 allocPoint, IMiniChefV3Rewarder indexed rewarder, bool overwrite);

Parameters

Name	Type	Description
`pid`	`uint256`	The pool ID of the updated pool.
`allocPoint`	`uint256`	The new number of allocation points assigned to the pool.
`rewarder`	`IMiniChefV3Rewarder`	The address of the rewarder contract for the pool.
`overwrite`	`bool`	Indicates whether the update overwrites the existing rewarder contract.

LogUpdatePool

Emitted when a pool's rewards are updated.

event LogUpdatePool(uint256 indexed pid, uint64 lastRewardTime, uint256 lpSupply, uint256 accRewardPerShare);

Parameters

Name	Type	Description
`pid`	`uint256`	The pool ID of the updated pool.
`lastRewardTime`	`uint64`	The last timestamp when the pool's rewards were calculated.
`lpSupply`	`uint256`	The total amount of LP tokens staked in the pool.
`accRewardPerShare`	`uint256`	The accumulated reward tokens per share, scaled to precision.

LogRewardPerSecond

Emitted when the reward per second is updated.

event LogRewardPerSecond(uint256 rewardPerSecond);

Parameters

Name	Type	Description
`rewardPerSecond`	`uint256`	The new amount of reward tokens distributed per second.

LogRewardCommitted

Emitted when a reward amount is committed for distribution.

event LogRewardCommitted(uint256 amount);

Parameters

Name	Type	Description
`amount`	`uint256`	The amount of reward tokens committed.

LogRewarderEmergencyWithdrawFaulty

Emitted when an emergency withdrawal from a rewarder contract is faulty.

event LogRewarderEmergencyWithdrawFaulty(address indexed user, uint256 indexed pid, uint256 amount, address indexed to);

Parameters

Name	Type	Description
`user`	`address`	The address of the user performing the emergency withdrawal.
`pid`	`uint256`	The pool ID from which the emergency withdrawal is made.
`amount`	`uint256`	The amount of tokens emergency withdrawn.
`to`	`address`	The address receiving the emergency withdrawn tokens.

Structs

UserInfo

struct UserInfo {
    uint256 amount;
    uint256 rewardDebt;
    uint256 unpaidRewards;
}

PoolInfo

struct PoolInfo {
    uint160 accRewardPerShare;
    uint64 lastRewardTime;
    uint32 allocPoint;
}