diff --git a/src/facets/StakingFacet.sol b/src/facets/StakingFacet.sol index 3e0d4d0d..5dce2f11 100644 --- a/src/facets/StakingFacet.sol +++ b/src/facets/StakingFacet.sol @@ -12,48 +12,108 @@ import { RewardsBalances } from "../shared/FreeStructs.sol"; contract StakingFacet is Modifiers { using LibHelpers for address; + /** + * @notice Staking ID for given token ID, entity ID and interval + * @param _entityId staking entity ID + * @param _tokenId token ID + * @param _interval staking interval + * @return vTokenId + */ function vTokenId(bytes32 _entityId, bytes32 _tokenId, uint64 _interval) external pure returns (bytes32) { return LibTokenizedVaultStaking._vTokenId(_entityId, _tokenId, _interval); } + /** + * @notice Get the current interval for a staking entity + * @param _entityId staking entity ID + * @return current interval + */ function currentInterval(bytes32 _entityId) external view returns (uint64) { return LibTokenizedVaultStaking._currentInterval(_entityId); } + /** + * @notice Get the configuration for a staking entity + * @param _entityId staking entity ID + * @return staking configuration + */ function getStakingConfig(bytes32 _entityId) external view returns (StakingConfig memory) { return LibTokenizedVaultStaking._stakingConfig(_entityId); } + /** + * @notice Initialize the configuration for a staking entity + * @param _entityId staking entity ID + * @param _config staking configuration + */ function initStaking(bytes32 _entityId, StakingConfig calldata _config) external assertPrivilege(LibAdmin._getSystemId(), LC.GROUP_SYSTEM_ADMINS) { LibTokenizedVaultStaking._initStaking(_entityId, _config); } + /** + * @notice Stake tokens into a staking entity + * @param _entityId staking entity ID + * @param _amount staking amount + */ function stake(bytes32 _entityId, uint256 _amount) external notLocked { bytes32 parentId = LibObject._getParentFromAddress(msg.sender); LibTokenizedVaultStaking._stake(parentId, _entityId, _amount); } + /** + * @notice Unstake tokens from a staking entity + * @param _entityId staking entity ID + */ function unstake(bytes32 _entityId) external notLocked { bytes32 parentId = LibObject._getParentFromAddress(msg.sender); LibTokenizedVaultStaking._unstake(parentId, _entityId); } + /** + * @notice Last interval reward was collected by the user entity + * @param _entityId staking entity ID + * @param _stakerId staker ID + * @return last collected interval + */ function lastCollectedInterval(bytes32 _entityId, bytes32 _stakerId) external view returns (uint64) { return LibTokenizedVaultStaking._lastCollectedInterval(_entityId, _stakerId); } + /** + * @notice Last interval reward was paid out by the staking entity + * @param _entityId staking entity ID + * @return last paid interval + */ function lastPaidInterval(bytes32 _entityId) external view returns (uint64) { return LibTokenizedVaultStaking._lastPaidInterval(_entityId); } + /** + * @notice Calculates the start time of an interval + * @param _entityId staking entity ID + * @param _interval interval + * @return start of interval + */ function calculateStartTimeOfInterval(bytes32 _entityId, uint64 _interval) external view returns (uint256) { return LibTokenizedVaultStaking._calculateStartTimeOfInterval(_entityId, _interval); } + /** + * @notice Calculates the start time of a current interval + * @param _entityId staking entity ID + * @return start of current interval + */ function calculateStartTimeOfCurrentInterval(bytes32 _entityId) external view returns (uint256) { return LibTokenizedVaultStaking._calculateStartTimeOfCurrentInterval(_entityId); } + /** + * @notice Gets the reward balance for a staker + * @param _stakerId staker ID + * @param _entityId entity ID + * @return rewardCurrencies_ currencies in which rewards are distributed + * @return rewardAmounts_ amounts distributed for respective currencies + */ function getRewardsBalance(bytes32 _stakerId, bytes32 _entityId) external view returns (bytes32[] memory rewardCurrencies_, uint256[] memory rewardAmounts_) { uint64 interval_ = LibTokenizedVaultStaking._currentInterval(_entityId); @@ -63,6 +123,10 @@ contract StakingFacet is Modifiers { rewardAmounts_ = b.amounts; } + /** + * @notice Collect rewards for a staker + * @param _entityId staking entity ID + */ function collectRewards(bytes32 _entityId) external notLocked { bytes32 parentId = LibObject._getParent(msg.sender._getIdForAddress()); uint64 lastPaid = LibTokenizedVaultStaking._lastPaidInterval(_entityId); @@ -81,10 +145,24 @@ contract StakingFacet is Modifiers { LibTokenizedVaultStaking._collectRewards(parentId, _entityId, _interval); } + /** + * @notice Pay out a reward to stakers + * @param _stakingRewardId unique staking reward GUID + * @param _entityId entity ID + * @param _rewardTokenId currency ID of the reward + * @param _amount reward amount + */ function payReward(bytes32 _stakingRewardId, bytes32 _entityId, bytes32 _rewardTokenId, uint256 _amount) external notLocked assertPrivilege(_entityId, LC.GROUP_ENTITY_ADMINS) { LibTokenizedVaultStaking._payReward(_stakingRewardId, _entityId, _rewardTokenId, _amount); } + /** + * @notice Gets the staked amount for a staker, with and without boost applied to it + * @param _stakerId staker ID + * @param _entityId staking entity ID + * @return stakedAmount_ total amount staked + * @return boostedAmount_ boosted staked amount, total amount with boost applied to it + */ function getStakingAmounts(bytes32 _stakerId, bytes32 _entityId) external view returns (uint256 stakedAmount_, uint256 boostedAmount_) { return LibTokenizedVaultStaking._getStakingAmounts(_stakerId, _entityId); }