1094820989

Build # 1094820989

Build Type

github

Committed by GitHub

Commit Message

<a href="https://github.com/mstable/mStable-contracts/commit/<a class=hub.com/mstable/mStable-contracts/commit/aec421bcde70d7c9c692433461e86954a97a167c">aec421bcd<a href="https://github.com/mstable/mStable-contracts/commit/aec421bcde70d7c9c692433461e86954a97a167c">">Merge </a><a class="double-link" href="https://github.com/mstable/mStable-contracts/commit/<a class="double-link" href="https://github.com/mstable/mStable-contracts/commit/c0465fcfcc5700c5e2ef57da6a9c85b8be7e87aa">c0465fcfc</a>">c0465fcfc</a><a href="https://github.com/mstable/mStable-contracts/commit/aec421bcde70d7c9c692433461e86954a97a167c"> into 75c65c4b5">75c65c4b5</a>

Pull Request Pull Request #195: wip: Staking

Run Details

921 of 1116 branches covered (82.53%)

Branch coverage included in aggregate %.

254 of 254 new or added lines in 6 files covered. (100.0%)

2228 of 2539 relevant lines covered (87.75%)

1017.74 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/contracts/governance/staking/GamifiedToken.sol

// SPDX-License-Identifier: AGPL-3.0-or-later
pragma solidity ^0.8.0;

import { ILockedERC20 } from "./interfaces/ILockedERC20.sol";
import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import { HeadlessStakingRewards } from "../../rewards/staking/HeadlessStakingRewards.sol";
import { ContextUpgradeable } from "@openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol";
import { SignatureVerifier } from "./deps/SignatureVerifier.sol";
import { SafeCast } from "@openzeppelin/contracts/utils/math/SafeCast.sol";
import "./GamifiedTokenStructs.sol";

/**
 * @title GamifiedToken
 * @notice GamifiedToken is a non-transferrable ERC20 token that has both a raw balance and a scaled balance.
 * Scaled balance is determined by quests a user completes, and the length of time they keep the raw balance wrapped.
 * @author mStable
 * @dev Originally forked from openzeppelin-contracts-upgradeable/contracts/token/ERC20/ERC20Upgradeable.sol
 * Changes:
 *   - Removed the transfer, transferFrom, approve fns to make non-transferrable
 *   - Removed `_allowances` storage
 *   - Removed `_beforeTokenTransfer` hook
 *   - Replaced standard uint256 balance with a single struct containing all data from which the scaledBalance can be derived
 *   - Quest system implemented that tracks a users quest status and applies multipliers for them
 **/
abstract contract GamifiedToken is
    ILockedERC20,
    Initializable,
    ContextUpgradeable,
    SignatureVerifier,
    HeadlessStakingRewards
{
    /// @notice name of this token (ERC20)
    string private _name;

    /// @notice symbol of this token (ERC20)
    string private _symbol;

    // TODO - make this more efficient than full slot
    /// @notice Timestamp at which the current season started
    uint32 private _seasonEpoch;

    /// @notice User balance structs containing all data needed to scale balance
    mapping(address => Balance) internal _balances;
    /// @notice Tracks the completion of each quest (user => completion[])
    mapping(address => bool[]) private _questCompletion;
    /// @notice List of quests, whose ID corresponds to their position in the array (from 0)
    Quest[] private _quests;

    /// @notice A whitelisted questMaster who can add quests
    address internal _questMaster;

    event QuestAdded(
        address questMaster,
        uint256 id,
        QuestType model,
        uint16 multiplier,
        QuestStatus status,
        uint32 expiry
    );
    event QuestComplete(address indexed user, uint256 indexed id);
    event QuestExpired(uint16 indexed id);
    event QuestSeasonEnded();

    /***************************************
                    INIT
    ****************************************/

    /**
     * @param _signer Signer address is used to verify completion of quests off chain
     * @param _nexus System nexus
     * @param _rewardsToken Token that is being distributed as a reward. eg MTA
     */
    constructor(
        address _signer,
        address _nexus,
        address _rewardsToken
    ) SignatureVerifier(_signer) HeadlessStakingRewards(_nexus, _rewardsToken) {}

    /**
     * @param _nameArg Token name
     * @param _symbolArg Token symbol
     * @param _rewardsDistributorArg mStable Rewards Distributor
     */
    function __GamifiedToken_init(
        string memory _nameArg,
        string memory _symbolArg,
        address _rewardsDistributorArg
    ) internal initializer {
        __Context_init_unchained();
        _name = _nameArg;
        _symbol = _symbolArg;
        _seasonEpoch = SafeCast.toUint32(block.timestamp);
        HeadlessStakingRewards._initialize(_rewardsDistributorArg);
    }

    /**
     * @dev Checks that _msgSender is either governor or the quest master
     */
    modifier questMasterOrGovernor() {
        require(_msgSender() == _questMaster || _msgSender() == _governor(), "Not verified");
        _;
    }

    /***************************************
                    VIEWS
    ****************************************/

    /**
     * @dev Name of this gamified token
     */
    function name() public view virtual override returns (string memory) {
        return _name;
    }

    /**
     * @dev Symbol of this gamified token
     */
    function symbol() public view virtual override returns (string memory) {
        return _symbol;
    }

    /**
     * @dev Always 18 decimals
     */
    function decimals() public view virtual override returns (uint8) {
        return 18;
    }

    /**
     * @dev Total sum of all scaled balances
     * In this instance, leave to the child token.
     */
    function totalSupply()
        public
        view
        virtual
        override(HeadlessStakingRewards, ILockedERC20)
        returns (uint256);

    /**
     * @dev Simply gets scaled balance
     * @return scaled balance for user
     */
    function balanceOf(address _account)
        public
        view
        virtual
        override(HeadlessStakingRewards, ILockedERC20)
        returns (uint256)
    {
        return _getBalance(_balances[_account]);
    }

    /**
     * @dev Scales the balance of a given user by applying multipliers
     */
    function _getBalance(Balance memory _balance) internal pure returns (uint256 balance) {
        balance =
            (_balance.raw *
                (100 +
                    _balance.permMultiplier +
                    _balance.seasonMultiplier +
                    _balance.timeMultiplier)) /
            100;
    }

    /**
     * @dev Raw balance data
     */
    function balanceData(address _account) external view returns (Balance memory) {
        return _balances[_account];
    }

    /**
     * @dev Gets raw quest data
     */
    function getQuest(uint256 _id) external view returns (Quest memory) {
        return _quests[_id];
    }

    /**
     * @dev Gets a users quest completion status
     */
    function getQuestCompletion(address _account, uint256 _id) external view returns (bool) {
        return _questCompletion[_account][_id];
    }

    /***************************************
                    QUESTS
    ****************************************/

    /**
     * @dev Called by questMasters to add a new quest to the system with default 'ACTIVE' status
     * @param _model Type of quest rewards multiplier (does it last forever or just for the season).
     * @param _multiplier Multiplier, from 1 == 1.01x to 100 == 2.00x
     * @param _expiry Timestamp at which quest expires. Note that permanent quests should still be given a timestamp.
     */
    function addQuest(
        QuestType _model,
        uint16 _multiplier,
        uint32 _expiry
    ) external questMasterOrGovernor {
        require(_expiry > block.timestamp + 1 days, "Quest window too small");
        require(_multiplier > 0 && _multiplier <= 100, "Quest multiplier too large (> 2x)");

        _quests.push(
            Quest({
                model: _model,
                multiplier: _multiplier,
                status: QuestStatus.ACTIVE,
                expiry: _expiry
            })
        );

        emit QuestAdded(
            _msgSender(),
            _quests.length - 1,
            _model,
            _multiplier,
            QuestStatus.ACTIVE,
            _expiry
        );
    }

    /**
     * @dev Called by questMasters to expire a quest, setting it's status as EXPIRED. After which it can
     * no longer be completed.
     * @param _id Quest ID (its position in the array)
     */
    function expireQuest(uint16 _id) external questMasterOrGovernor {
        require(_quests.length >= _id, "Quest does not exist");
        require(
            _quests[_id].status == QuestStatus.ACTIVE || block.timestamp < _quests[_id].expiry,
            "Quest already expired"
        );

        _quests[_id].status = QuestStatus.EXPIRED;

        emit QuestExpired(_id);
    }

    /**
     * @dev Called by questMasters to start a new quest season. After this, all current
     * seasonMultipliers will be reduced at the next user action (or triggered manually).
     * In order to reduce cost for any keepers, it is suggested to add quests at the start
     * of a new season to incentivise user actions.
     * A new season can only begin after 9 months has passed.
     */
    function startNewQuestSeason() external questMasterOrGovernor {
        require(block.timestamp > (_seasonEpoch + 39 weeks), "Not enough time elapsed in season");

        _seasonEpoch = SafeCast.toUint32(block.timestamp);

        emit QuestSeasonEnded();
    }

    /**
     * @dev Called by anyone to complete a quest for a staker. The user must first collect a signed message
     * from the whitelisted _signer.
     * @param _account Account that has completed the quest
     * @param _id Quest ID (its position in the array)
     * @param _signature Signature from the verified _signer, containing keccak hash of account & id
     */
    function completeQuest(
        address _account,
        uint256 _id,
        bytes calldata _signature
    ) external {
        require(_validQuest(_id), "Err: Invalid Quest");
        require(!_hasCompleted(_account, _id), "Err: Already Completed");
        require(verify(_account, _id, _signature), "Err: Invalid Signature");

        // TODO - is this valid? dont think so
        _questCompletion[_account][_id] = true;

        _applyQuestMultiplier(_account, _quests[_id]);

        emit QuestComplete(_account, _id);
    }

    /**
     * @dev Called by anyone to poke the timestamp of a given account. This allows users to
     * effectively 'claim' any new timeMultiplier, but will revert if there is no change there.
     */
    function reviewTimestamp(address _account) external {
        _reviewWeightedTimestamp(_account);
    }

    /**
     * @dev Simply checks if a quest is valid. Quests are valid if their id exists,
     * they have an ACTIVE status and they have not yet reached their expiry timestamp.
     * @param _id Position of quest in array
     * @return bool with validity status
     */
    function _validQuest(uint256 _id) internal view returns (bool) {
        return
            _quests.length >= _id &&
            _quests[_id].status == QuestStatus.ACTIVE &&
            block.timestamp < _quests[_id].expiry;
    }

    /**
     * @dev Simply checks if a given user has already completed a given quest
     * @param _account User address
     * @param _id Position of quest in array
     * @return bool with completion status
     */
    function _hasCompleted(address _account, uint256 _id) internal view returns (bool) {
        return _questCompletion[_account][_id];
    }

    /**
     * @dev Gets the multiplier awarded for a given weightedTimestamp
     * @param _ts WeightedTimestamp of a user
     * @return timeMultiplier Ranging from 20 (0.2x) to 60 (0.6x)
     */
    function _timeMultiplier(uint32 _ts) internal pure returns (uint16 timeMultiplier) {
        if (_ts < 13 weeks) {
            // 0-3 months = 1x
            return 0;
        } else if (_ts < 26 weeks) {
            // 3 months = 1.2x
            return 20;
        } else if (_ts < 52 weeks) {
            // 6 months = 1.3x
            return 30;
        } else if (_ts < 78 weeks) {
            // 12 months = 1.4x
            return 40;
        } else if (_ts < 104 weeks) {
            // 18 months = 1.5x
            return 50;
        } else {
            // 24 months = 1.6x
            return 60;
        }
    }

    /***************************************
                BALANCE CHANGES
    ****************************************/

    /**
     * @dev Pokes the weightedTimestamp of a given user and checks if it entitles them
     * to a better timeMultiplier. If not, it simply reverts as there is nothing to update.
     * @param _account Address of user that should be updated
     */
    function _reviewWeightedTimestamp(address _account) internal updateReward(_account) {
        require(_account != address(0), "ERC20: mint to the zero address");

        // 1. Get current balance
        (Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);

        // 2. Set weighted timestamp, if it changes
        uint16 newTimeMultiplier = _timeMultiplier(oldBalance.weightedTimestamp);
        require(newTimeMultiplier != oldBalance.timeMultiplier, "Nothing worth poking here");
        _balances[_account].timeMultiplier = newTimeMultiplier;

        // 3. Update scaled balance
        _settleScaledBalance(_account, oldScaledBalance);
    }

    /**
     * @dev Adds the multiplier awarded from quest completion to a users data, taking the opportunity
     * to check time multipliers etc.
     * @param _account Address of user that should be updated
     * @param _quest Quest that has just been completed
     */
    function _applyQuestMultiplier(address _account, Quest memory _quest)
        internal
        virtual
        updateReward(_account)
    {
        require(_account != address(0), "ERC20: mint to the zero address");

        // 1. Get current balance & update questMultiplier
        (Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);
        if (_quest.model == QuestType.PERMANENT) {
            _balances[_account].permMultiplier += _quest.multiplier;
        } else {
            _balances[_account].seasonMultiplier += _quest.multiplier;
        }

        // 2. Take the opportunity to set weighted timestamp, if it changes
        _balances[_account].timeMultiplier = _timeMultiplier(oldBalance.weightedTimestamp);

        // 3. Update scaled balance
        _settleScaledBalance(_account, oldScaledBalance);
    }

    /**
     * @dev Called to mint from raw tokens. Adds raw to a users balance, and then propagates the scaledBalance.
     * Importantly, when a user stakes more, their weightedTimestamp is reduced proportionate to their stake.
     * @param _account Address of user to credit
     * @param _rawAmount Raw amount of tokens staked
     */
    function _mintRaw(address _account, uint256 _rawAmount)
        internal
        virtual
        updateReward(_account)
    {
        require(_account != address(0), "ERC20: mint to the zero address");

        // 1. Get and update current balance
        (Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);
        _balances[_account].raw = oldBalance.raw + SafeCast.toUint128(_rawAmount);

        // 2. Set weighted timestamp
        //  i) For new _account, set up weighted timestamp
        if (oldBalance.weightedTimestamp == 0) {
            _balances[_account].weightedTimestamp = SafeCast.toUint32(block.timestamp);
            _mintScaled(_account, _getBalance(_balances[_account]));
            return;
        }
        //  ii) For previous minters, recalculate time held
        //      Calc new weighted timestamp
        uint256 secondsHeld = (block.timestamp - oldBalance.weightedTimestamp) * oldBalance.raw;
        uint256 newWeightedTs = secondsHeld / (oldBalance.raw + ((_rawAmount / 3) * 2));
        _balances[_account].weightedTimestamp = SafeCast.toUint32(block.timestamp - newWeightedTs);

        uint16 timeMultiplier = _timeMultiplier(SafeCast.toUint32(newWeightedTs));
        _balances[_account].timeMultiplier = timeMultiplier;

        // 3. Update scaled balance
        _settleScaledBalance(_account, oldScaledBalance);
    }

    /**
     * @dev Called to burn a given amount of raw tokens.
     * @param _account Address of user
     * @param _rawAmount Raw amount of tokens to remove
     */
    function _burnRaw(address _account, uint256 _rawAmount)
        internal
        virtual
        updateReward(_account)
    {
        require(_account != address(0), "ERC20: burn from the zero address");

        // 1. Get and update current balance
        (Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);
        require(oldBalance.raw >= _rawAmount, "ERC20: burn amount exceeds balance");
        unchecked {
            _balances[_account].raw = oldBalance.raw - SafeCast.toUint128(_rawAmount);
        }

        // 2. Set back scaled time
        // e.g. stake 10 for 100 seconds, withdraw 5.
        //      secondsHeld = (100 - 0) * (10 - 1.25) = 875
        uint256 secondsHeld = (block.timestamp - oldBalance.weightedTimestamp) *
            (oldBalance.raw - (_rawAmount / 4));
        //      newWeightedTs = 875 / 100 = 87.5
        uint256 newWeightedTs = secondsHeld / oldBalance.raw;
        _balances[_account].weightedTimestamp = SafeCast.toUint32(block.timestamp - newWeightedTs);

        uint16 timeMultiplier = _timeMultiplier(SafeCast.toUint32(newWeightedTs));
        _balances[_account].timeMultiplier = timeMultiplier;

        // 3. Update scaled balance
        _burnScaled(_account, oldScaledBalance - _getBalance(_balances[_account]));
    }

    /***************************************
                    PRIVATE
    updateReward should already be called by now
    ****************************************/

    /**
     * @dev Fetches the balance of a given user, scales it, and also takes the opportunity
     * to check if the season has just finished between now and their last action.
     * @param _account Address of user to fetch
     * @return oldBalance struct containing all balance information
     * @return oldScaledBalance scaled balance after applying multipliers
     */
    function _prepareOldBalance(address _account)
        private
        returns (Balance memory oldBalance, uint256 oldScaledBalance)
    {
        // Get the old balance
        oldBalance = _balances[_account];
        oldScaledBalance = _getBalance(oldBalance);
        // Take the opportunity to check for season finish
        _checkForSeasonFinish(oldBalance, _account);
    }

    /**
     * @dev Checks if the season has just finished between now and the users last action.
     * If it has, we reset the seasonMultiplier. Either way, we update the lastAction for the user.
     * @param _balance Struct containing all users balance information
     * @param _account Address of user that should be updated
     */
    function _checkForSeasonFinish(Balance memory _balance, address _account) private {
        // If the last action was before current season, then reset the season timing
        if (_balance.lastAction < _seasonEpoch) {
            // Remove 75% of the multiplier gained in this season
            _balances[_account].seasonMultiplier = (_balance.seasonMultiplier * 25) / 100;
        }
        _balances[_account].lastAction = SafeCast.toUint32(block.timestamp);
    }

    /**
     * @dev Settles the scaled balance of a given account. The reason this is done here, is because
     * in each of the write functions above, there is the chance that a users balance can go down,
     * requiring to burn sacled tokens. This could happen at the end of a season when multipliers are slashed.
     * This is called after updating all multipliers etc.
     * @param _account Address of user that should be updated
     * @param _oldScaledBalance Previous scaled balance of the user
     */
    function _settleScaledBalance(address _account, uint256 _oldScaledBalance) private {
        uint256 newScaledBalance = _getBalance(_balances[_account]);
        if (newScaledBalance > _oldScaledBalance) {
            _mintScaled(_account, newScaledBalance - _oldScaledBalance);
        }
        // This can happen if the user moves back a time class, but is unlikely to result in a negative mint
        else {
            _burnScaled(_account, _oldScaledBalance - newScaledBalance);
        }
    }

    /**
     * @dev Propagates the minting of the tokens downwards.
     * @param _account Address of user that has minted
     * @param _amount Amount of scaled tokens minted
     */
    function _mintScaled(address _account, uint256 _amount) private {
        emit Transfer(address(0), _account, _amount);

        _afterTokenTransfer(address(0), _account, _amount);
    }

    /**
     * @dev Propagates the burning of the tokens downwards.
     * @param _account Address of user that has burned
     * @param _amount Amount of scaled tokens burned
     */
    function _burnScaled(address _account, uint256 _amount) private {
        emit Transfer(_account, address(0), _amount);

        _afterTokenTransfer(_account, address(0), _amount);
    }

    /***************************************
                    HOOKS
    ****************************************/

    /**
     * @dev Unchanged from OpenZeppelin. Used in child contracts to react to any balance changes.
     */
    function _afterTokenTransfer(
        address _from,
        address _to,
        uint256 _amount
    ) internal virtual {}

    // TODO - ensure this represents storage space
    uint256[45] private __gap;
}

1	// SPDX-License-Identifier: AGPL-3.0-or-later
2	pragma solidity ^0.8.0;
3
4	import { ILockedERC20 } from "./interfaces/ILockedERC20.sol";
5	import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
6	import { HeadlessStakingRewards } from "../../rewards/staking/HeadlessStakingRewards.sol";
7	import { ContextUpgradeable } from "@openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol";
8	import { SignatureVerifier } from "./deps/SignatureVerifier.sol";
9	import { SafeCast } from "@openzeppelin/contracts/utils/math/SafeCast.sol";
10	import "./GamifiedTokenStructs.sol";
11
12	/**
13	* @title GamifiedToken
14	* @notice GamifiedToken is a non-transferrable ERC20 token that has both a raw balance and a scaled balance.
15	* Scaled balance is determined by quests a user completes, and the length of time they keep the raw balance wrapped.
16	* @author mStable
17	* @dev Originally forked from openzeppelin-contracts-upgradeable/contracts/token/ERC20/ERC20Upgradeable.sol
18	* Changes:
19	* - Removed the transfer, transferFrom, approve fns to make non-transferrable
20	* - Removed `_allowances` storage
21	* - Removed `_beforeTokenTransfer` hook
22	* - Replaced standard uint256 balance with a single struct containing all data from which the scaledBalance can be derived
23	* - Quest system implemented that tracks a users quest status and applies multipliers for them
24	**/
25	abstract contract GamifiedToken is
26	ILockedERC20,
27	Initializable,
28	ContextUpgradeable,
29	SignatureVerifier,
30	HeadlessStakingRewards
31	{
32	/// @notice name of this token (ERC20)
33	string private _name;
34
35	/// @notice symbol of this token (ERC20)
36	string private _symbol;
37
38	// TODO - make this more efficient than full slot
39	/// @notice Timestamp at which the current season started
40	uint32 private _seasonEpoch;
41
42	/// @notice User balance structs containing all data needed to scale balance
43	mapping(address => Balance) internal _balances;
44	/// @notice Tracks the completion of each quest (user => completion[])
45	mapping(address => bool[]) private _questCompletion;
46	/// @notice List of quests, whose ID corresponds to their position in the array (from 0)
47	Quest[] private _quests;
48
49	/// @notice A whitelisted questMaster who can add quests
50	address internal _questMaster;
51
52	event QuestAdded(
53	address questMaster,
54	uint256 id,
55	QuestType model,
56	uint16 multiplier,
57	QuestStatus status,
58	uint32 expiry
59	);
60	event QuestComplete(address indexed user, uint256 indexed id);
61	event QuestExpired(uint16 indexed id);
62	event QuestSeasonEnded();
63
64	/***************************************
65	INIT
66	****************************************/
67
68	/**
69	* @param _signer Signer address is used to verify completion of quests off chain
70	* @param _nexus System nexus
71	* @param _rewardsToken Token that is being distributed as a reward. eg MTA
72	*/
73	constructor(
74	address _signer,
75	address _nexus,
76	address _rewardsToken
77	) SignatureVerifier(_signer) HeadlessStakingRewards(_nexus, _rewardsToken) {}
78
79	/**
80	* @param _nameArg Token name
81	* @param _symbolArg Token symbol
82	* @param _rewardsDistributorArg mStable Rewards Distributor
83	*/
84	function __GamifiedToken_init(
85	string memory _nameArg,
86	string memory _symbolArg,
87	address _rewardsDistributorArg
88	) internal initializer {
89	__Context_init_unchained();	×
90	_name = _nameArg;	×
91	_symbol = _symbolArg;	×
92	_seasonEpoch = SafeCast.toUint32(block.timestamp);	×
93	HeadlessStakingRewards._initialize(_rewardsDistributorArg);	×
94	}
95
96	/**
97	* @dev Checks that _msgSender is either governor or the quest master
98	*/
99	modifier questMasterOrGovernor() {
100	require(_msgSender() == _questMaster \|\| _msgSender() == _governor(), "Not verified");	×
101	_;	×
102	}
103
104	/***************************************
105	VIEWS
106	****************************************/
107
108	/**
109	* @dev Name of this gamified token
110	*/
111	function name() public view virtual override returns (string memory) {
112	return _name;	×
113	}
114
115	/**
116	* @dev Symbol of this gamified token
117	*/
118	function symbol() public view virtual override returns (string memory) {
119	return _symbol;	×
120	}
121
122	/**
123	* @dev Always 18 decimals
124	*/
125	function decimals() public view virtual override returns (uint8) {
126	return 18;	×
127	}
128
129	/**
130	* @dev Total sum of all scaled balances
131	* In this instance, leave to the child token.
132	*/
133	function totalSupply()
134	public
135	view
136	virtual
137	override(HeadlessStakingRewards, ILockedERC20)
138	returns (uint256);
139
140	/**
141	* @dev Simply gets scaled balance
142	* @return scaled balance for user
143	*/
144	function balanceOf(address _account)
145	public
146	view
147	virtual
148	override(HeadlessStakingRewards, ILockedERC20)
149	returns (uint256)
150	{
151	return _getBalance(_balances[_account]);	×
152	}
153
154	/**
155	* @dev Scales the balance of a given user by applying multipliers
156	*/
157	function _getBalance(Balance memory _balance) internal pure returns (uint256 balance) {
158	balance =	×
159	(_balance.raw *
160	(100 +
161	_balance.permMultiplier +
162	_balance.seasonMultiplier +
163	_balance.timeMultiplier)) /
164	100;
165	}
166
167	/**
168	* @dev Raw balance data
169	*/
170	function balanceData(address _account) external view returns (Balance memory) {
171	return _balances[_account];	×
172	}
173
174	/**
175	* @dev Gets raw quest data
176	*/
177	function getQuest(uint256 _id) external view returns (Quest memory) {
178	return _quests[_id];	×
179	}
180
181	/**
182	* @dev Gets a users quest completion status
183	*/
184	function getQuestCompletion(address _account, uint256 _id) external view returns (bool) {
185	return _questCompletion[_account][_id];	×
186	}
187
188	/***************************************
189	QUESTS
190	****************************************/
191
192	/**
193	* @dev Called by questMasters to add a new quest to the system with default 'ACTIVE' status
194	* @param _model Type of quest rewards multiplier (does it last forever or just for the season).
195	* @param _multiplier Multiplier, from 1 == 1.01x to 100 == 2.00x
196	* @param _expiry Timestamp at which quest expires. Note that permanent quests should still be given a timestamp.
197	*/
198	function addQuest(
199	QuestType _model,
200	uint16 _multiplier,
201	uint32 _expiry
202	) external questMasterOrGovernor {
203	require(_expiry > block.timestamp + 1 days, "Quest window too small");	×
204	require(_multiplier > 0 && _multiplier <= 100, "Quest multiplier too large (> 2x)");	×
205
206	_quests.push(	×
207	Quest({
208	model: _model,
209	multiplier: _multiplier,
210	status: QuestStatus.ACTIVE,
211	expiry: _expiry
212	})
213	);
214
215	emit QuestAdded(	×
216	_msgSender(),
217	_quests.length - 1,
218	_model,
219	_multiplier,
220	QuestStatus.ACTIVE,
221	_expiry
222	);
223	}
224
225	/**
226	* @dev Called by questMasters to expire a quest, setting it's status as EXPIRED. After which it can
227	* no longer be completed.
228	* @param _id Quest ID (its position in the array)
229	*/
230	function expireQuest(uint16 _id) external questMasterOrGovernor {
231	require(_quests.length >= _id, "Quest does not exist");	×
232	require(	×
233	_quests[_id].status == QuestStatus.ACTIVE \|\| block.timestamp < _quests[_id].expiry,
234	"Quest already expired"
235	);
236
237	_quests[_id].status = QuestStatus.EXPIRED;	×
238
239	emit QuestExpired(_id);	×
240	}
241
242	/**
243	* @dev Called by questMasters to start a new quest season. After this, all current
244	* seasonMultipliers will be reduced at the next user action (or triggered manually).
245	* In order to reduce cost for any keepers, it is suggested to add quests at the start
246	* of a new season to incentivise user actions.
247	* A new season can only begin after 9 months has passed.
248	*/
249	function startNewQuestSeason() external questMasterOrGovernor {
250	require(block.timestamp > (_seasonEpoch + 39 weeks), "Not enough time elapsed in season");	×
251
252	_seasonEpoch = SafeCast.toUint32(block.timestamp);	×
253
254	emit QuestSeasonEnded();	×
255	}
256
257	/**
258	* @dev Called by anyone to complete a quest for a staker. The user must first collect a signed message
259	* from the whitelisted _signer.
260	* @param _account Account that has completed the quest
261	* @param _id Quest ID (its position in the array)
262	* @param _signature Signature from the verified _signer, containing keccak hash of account & id
263	*/
264	function completeQuest(
265	address _account,
266	uint256 _id,
267	bytes calldata _signature
268	) external {
269	require(_validQuest(_id), "Err: Invalid Quest");	×
270	require(!_hasCompleted(_account, _id), "Err: Already Completed");	×
271	require(verify(_account, _id, _signature), "Err: Invalid Signature");	×
272
273	// TODO - is this valid? dont think so
274	_questCompletion[_account][_id] = true;	×
275
276	_applyQuestMultiplier(_account, _quests[_id]);	×
277
278	emit QuestComplete(_account, _id);	×
279	}
280
281	/**
282	* @dev Called by anyone to poke the timestamp of a given account. This allows users to
283	* effectively 'claim' any new timeMultiplier, but will revert if there is no change there.
284	*/
285	function reviewTimestamp(address _account) external {
286	_reviewWeightedTimestamp(_account);	×
287	}
288
289	/**
290	* @dev Simply checks if a quest is valid. Quests are valid if their id exists,
291	* they have an ACTIVE status and they have not yet reached their expiry timestamp.
292	* @param _id Position of quest in array
293	* @return bool with validity status
294	*/
295	function _validQuest(uint256 _id) internal view returns (bool) {
296	return	×
297	_quests.length >= _id &&
298	_quests[_id].status == QuestStatus.ACTIVE &&
299	block.timestamp < _quests[_id].expiry;
300	}
301
302	/**
303	* @dev Simply checks if a given user has already completed a given quest
304	* @param _account User address
305	* @param _id Position of quest in array
306	* @return bool with completion status
307	*/
308	function _hasCompleted(address _account, uint256 _id) internal view returns (bool) {
309	return _questCompletion[_account][_id];	×
310	}
311
312	/**
313	* @dev Gets the multiplier awarded for a given weightedTimestamp
314	* @param _ts WeightedTimestamp of a user
315	* @return timeMultiplier Ranging from 20 (0.2x) to 60 (0.6x)
316	*/
317	function _timeMultiplier(uint32 _ts) internal pure returns (uint16 timeMultiplier) {
318	if (_ts < 13 weeks) {	×
319	// 0-3 months = 1x
320	return 0;	×
321	} else if (_ts < 26 weeks) {	×
322	// 3 months = 1.2x
323	return 20;	×
324	} else if (_ts < 52 weeks) {	×
325	// 6 months = 1.3x
326	return 30;	×
327	} else if (_ts < 78 weeks) {	×
328	// 12 months = 1.4x
329	return 40;	×
330	} else if (_ts < 104 weeks) {	×
331	// 18 months = 1.5x
332	return 50;	×
333	} else {
334	// 24 months = 1.6x
335	return 60;	×
336	}
337	}
338
339	/***************************************
340	BALANCE CHANGES
341	****************************************/
342
343	/**
344	* @dev Pokes the weightedTimestamp of a given user and checks if it entitles them
345	* to a better timeMultiplier. If not, it simply reverts as there is nothing to update.
346	* @param _account Address of user that should be updated
347	*/
348	function _reviewWeightedTimestamp(address _account) internal updateReward(_account) {
349	require(_account != address(0), "ERC20: mint to the zero address");	×
350
351	// 1. Get current balance
352	(Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);	×
353
354	// 2. Set weighted timestamp, if it changes
355	uint16 newTimeMultiplier = _timeMultiplier(oldBalance.weightedTimestamp);	×
356	require(newTimeMultiplier != oldBalance.timeMultiplier, "Nothing worth poking here");	×
357	_balances[_account].timeMultiplier = newTimeMultiplier;	×
358
359	// 3. Update scaled balance
360	_settleScaledBalance(_account, oldScaledBalance);	×
361	}
362
363	/**
364	* @dev Adds the multiplier awarded from quest completion to a users data, taking the opportunity
365	* to check time multipliers etc.
366	* @param _account Address of user that should be updated
367	* @param _quest Quest that has just been completed
368	*/
369	function _applyQuestMultiplier(address _account, Quest memory _quest)
370	internal
371	virtual
372	updateReward(_account)
373	{
374	require(_account != address(0), "ERC20: mint to the zero address");	×
375
376	// 1. Get current balance & update questMultiplier
377	(Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);	×
378	if (_quest.model == QuestType.PERMANENT) {	×
379	_balances[_account].permMultiplier += _quest.multiplier;	×
380	} else {
381	_balances[_account].seasonMultiplier += _quest.multiplier;	×
382	}
383
384	// 2. Take the opportunity to set weighted timestamp, if it changes
385	_balances[_account].timeMultiplier = _timeMultiplier(oldBalance.weightedTimestamp);	×
386
387	// 3. Update scaled balance
388	_settleScaledBalance(_account, oldScaledBalance);	×
389	}
390
391	/**
392	* @dev Called to mint from raw tokens. Adds raw to a users balance, and then propagates the scaledBalance.
393	* Importantly, when a user stakes more, their weightedTimestamp is reduced proportionate to their stake.
394	* @param _account Address of user to credit
395	* @param _rawAmount Raw amount of tokens staked
396	*/
397	function _mintRaw(address _account, uint256 _rawAmount)
398	internal
399	virtual
400	updateReward(_account)
401	{
402	require(_account != address(0), "ERC20: mint to the zero address");	×
403
404	// 1. Get and update current balance
405	(Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);	×
406	_balances[_account].raw = oldBalance.raw + SafeCast.toUint128(_rawAmount);	×
407
408	// 2. Set weighted timestamp
409	// i) For new _account, set up weighted timestamp
410	if (oldBalance.weightedTimestamp == 0) {	×
411	_balances[_account].weightedTimestamp = SafeCast.toUint32(block.timestamp);	×
412	_mintScaled(_account, _getBalance(_balances[_account]));	×
413	return;	×
414	}
415	// ii) For previous minters, recalculate time held
416	// Calc new weighted timestamp
417	uint256 secondsHeld = (block.timestamp - oldBalance.weightedTimestamp) * oldBalance.raw;	×
418	uint256 newWeightedTs = secondsHeld / (oldBalance.raw + ((_rawAmount / 3) * 2));	×
419	_balances[_account].weightedTimestamp = SafeCast.toUint32(block.timestamp - newWeightedTs);	×
420
421	uint16 timeMultiplier = _timeMultiplier(SafeCast.toUint32(newWeightedTs));	×
422	_balances[_account].timeMultiplier = timeMultiplier;	×
423
424	// 3. Update scaled balance
425	_settleScaledBalance(_account, oldScaledBalance);	×
426	}
427
428	/**
429	* @dev Called to burn a given amount of raw tokens.
430	* @param _account Address of user
431	* @param _rawAmount Raw amount of tokens to remove
432	*/
433	function _burnRaw(address _account, uint256 _rawAmount)
434	internal
435	virtual
436	updateReward(_account)
437	{
438	require(_account != address(0), "ERC20: burn from the zero address");	×
439
440	// 1. Get and update current balance
441	(Balance memory oldBalance, uint256 oldScaledBalance) = _prepareOldBalance(_account);	×
442	require(oldBalance.raw >= _rawAmount, "ERC20: burn amount exceeds balance");	×
443	unchecked {	×
444	_balances[_account].raw = oldBalance.raw - SafeCast.toUint128(_rawAmount);
445	}
446
447	// 2. Set back scaled time
448	// e.g. stake 10 for 100 seconds, withdraw 5.
449	// secondsHeld = (100 - 0) * (10 - 1.25) = 875
450	uint256 secondsHeld = (block.timestamp - oldBalance.weightedTimestamp) *	×
451	(oldBalance.raw - (_rawAmount / 4));
452	// newWeightedTs = 875 / 100 = 87.5
453	uint256 newWeightedTs = secondsHeld / oldBalance.raw;	×
454	_balances[_account].weightedTimestamp = SafeCast.toUint32(block.timestamp - newWeightedTs);	×
455
456	uint16 timeMultiplier = _timeMultiplier(SafeCast.toUint32(newWeightedTs));	×
457	_balances[_account].timeMultiplier = timeMultiplier;	×
458
459	// 3. Update scaled balance
460	_burnScaled(_account, oldScaledBalance - _getBalance(_balances[_account]));	×
461	}
462
463	/***************************************
464	PRIVATE
465	updateReward should already be called by now
466	****************************************/
467
468	/**
469	* @dev Fetches the balance of a given user, scales it, and also takes the opportunity
470	* to check if the season has just finished between now and their last action.
471	* @param _account Address of user to fetch
472	* @return oldBalance struct containing all balance information
473	* @return oldScaledBalance scaled balance after applying multipliers
474	*/
475	function _prepareOldBalance(address _account)
476	private
477	returns (Balance memory oldBalance, uint256 oldScaledBalance)
478	{
479	// Get the old balance
480	oldBalance = _balances[_account];	×
481	oldScaledBalance = _getBalance(oldBalance);	×
482	// Take the opportunity to check for season finish
483	_checkForSeasonFinish(oldBalance, _account);	×
484	}
485
486	/**
487	* @dev Checks if the season has just finished between now and the users last action.
488	* If it has, we reset the seasonMultiplier. Either way, we update the lastAction for the user.
489	* @param _balance Struct containing all users balance information
490	* @param _account Address of user that should be updated
491	*/
492	function _checkForSeasonFinish(Balance memory _balance, address _account) private {
493	// If the last action was before current season, then reset the season timing
494	if (_balance.lastAction < _seasonEpoch) {	×
495	// Remove 75% of the multiplier gained in this season
496	_balances[_account].seasonMultiplier = (_balance.seasonMultiplier * 25) / 100;	×
497	}
498	_balances[_account].lastAction = SafeCast.toUint32(block.timestamp);	×
499	}
500
501	/**
502	* @dev Settles the scaled balance of a given account. The reason this is done here, is because
503	* in each of the write functions above, there is the chance that a users balance can go down,
504	* requiring to burn sacled tokens. This could happen at the end of a season when multipliers are slashed.
505	* This is called after updating all multipliers etc.
506	* @param _account Address of user that should be updated
507	* @param _oldScaledBalance Previous scaled balance of the user
508	*/
509	function _settleScaledBalance(address _account, uint256 _oldScaledBalance) private {
510	uint256 newScaledBalance = _getBalance(_balances[_account]);	×
511	if (newScaledBalance > _oldScaledBalance) {	×
512	_mintScaled(_account, newScaledBalance - _oldScaledBalance);	×
513	}
514	// This can happen if the user moves back a time class, but is unlikely to result in a negative mint
515	else {
516	_burnScaled(_account, _oldScaledBalance - newScaledBalance);	×
517	}
518	}
519
520	/**
521	* @dev Propagates the minting of the tokens downwards.
522	* @param _account Address of user that has minted
523	* @param _amount Amount of scaled tokens minted
524	*/
525	function _mintScaled(address _account, uint256 _amount) private {
526	emit Transfer(address(0), _account, _amount);	×
527
528	_afterTokenTransfer(address(0), _account, _amount);	×
529	}
530
531	/**
532	* @dev Propagates the burning of the tokens downwards.
533	* @param _account Address of user that has burned
534	* @param _amount Amount of scaled tokens burned
535	*/
536	function _burnScaled(address _account, uint256 _amount) private {
537	emit Transfer(_account, address(0), _amount);	×
538
539	_afterTokenTransfer(_account, address(0), _amount);	×
540	}
541
542	/***************************************
543	HOOKS
544	****************************************/
545
546	/**
547	* @dev Unchanged from OpenZeppelin. Used in child contracts to react to any balance changes.
548	*/
549	function _afterTokenTransfer(
550	address _from,
551	address _to,
552	uint256 _amount
553	) internal virtual {}
554
555	// TODO - ensure this represents storage space
556	uint256[45] private __gap;
557	}

mstable / mStable-contracts / 1094820989

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous