feat: introduce token reserve supply (#94)

* feat: update `IERC20Mintable` interface
* feat: update `IERC20Mintable` interface
* feat: implement new functions in `ERC20Mintable` contract
* test: cover new functions with tests
* fix: camel case typo
* feat: update `MintFromReserve` and `BurnToReserve` events

Author: igorsenych-cw

contracts/base/ERC20Mintable.sol

@@ -23,6 +23,7 @@ abstract contract ERC20Mintable is ERC20Base, IERC20Mintable {
         uint16 maxPendingPremintsCount;
         mapping(uint256 => uint256) premintReschedulings;
         mapping(uint256 => uint256) premintReschedulingCounters;
+        uint256 totalReserveSupply;
     }
 
     /// @notice The structure that represents an array of premint records
@@ -106,6 +107,9 @@ abstract contract ERC20Mintable is ERC20Base, IERC20Mintable {
     /// @notice The provided value cannot be cast to uint64 type
     error InappropriateUint64Value(uint256 value);
 
+    /// @notice The amount of tokens to burn is greater than the total reserve supply
+    error InsufficientReserveSupply();
+
     // -------------------- Modifiers --------------------------------
 
     /**
@@ -231,6 +235,25 @@ abstract contract ERC20Mintable is ERC20Base, IERC20Mintable {
         return _mintInternal(account, amount);
     }
 
+    /**
+     * @inheritdoc IERC20Mintable
+     *
+     * @dev The contract must not be paused
+     * @dev Can only be called by a minter account
+     * @dev The message sender must not be blocklisted
+     */
+    function mintFromReserve(
+        address account,
+        uint256 amount
+    ) external whenNotPaused onlyMinter notBlocklisted(_msgSender()) {
+        _mintInternal(account, amount);
+
+        ExtendedStorageSlot storage storageSlot = _getExtendedStorageSlot();
+        storageSlot.totalReserveSupply += amount;
+
+        emit MintFromReserve(_msgSender(), account, amount, storageSlot.totalReserveSupply);
+    }
+
     /**
      * @inheritdoc IERC20Mintable
      *
@@ -308,6 +331,30 @@ abstract contract ERC20Mintable is ERC20Base, IERC20Mintable {
         _burnInternal(_msgSender(), amount);
     }
 
+    /**
+     * @inheritdoc IERC20Mintable
+     *
+     * @dev The contract must not be paused
+     * @dev Can only be called by a minter account
+     * @dev The message sender must not be blocklisted
+     * @dev The amount of tokens to burn must be less than or equal to the total reserve supply
+     */
+    function burnToReserve(uint256 amount) external whenNotPaused onlyMinter notBlocklisted(_msgSender()) {
+        _burnInternal(_msgSender(), amount);
+
+        ExtendedStorageSlot storage storageSlot = _getExtendedStorageSlot();
+
+        if (storageSlot.totalReserveSupply < amount) {
+            revert InsufficientReserveSupply();
+        }
+
+        unchecked {
+            storageSlot.totalReserveSupply -= amount;
+        }
+
+        emit BurnToReserve(_msgSender(), amount, storageSlot.totalReserveSupply);
+    }
+
     /**
      * @notice Returns the total amount of preminted tokens
      * @param account The account to check the preminted balance for
@@ -385,6 +432,14 @@ abstract contract ERC20Mintable is ERC20Base, IERC20Mintable {
         return _mintersAllowance[minter];
     }
 
+    /**
+     * @inheritdoc IERC20Mintable
+     */
+    function totalReserveSupply() external view returns (uint256) {
+        ExtendedStorageSlot storage storageSlot = _getExtendedStorageSlot();
+        return storageSlot.totalReserveSupply;
+    }
+
     function _mintInternal(address account, uint256 amount) internal returns (bool) {
         if (amount == 0) {
             revert ZeroMintAmount();

contracts/base/interfaces/IERC20Mintable.sol

@@ -39,6 +39,21 @@ interface IERC20Mintable {
      */
     event Mint(address indexed minter, address indexed to, uint256 amount);
 
+    /**
+     * @notice Emitted when tokens are minted from reserve
+     *
+     * @param minter The address of the minter
+     * @param to The address of the tokens recipient
+     * @param amount The amount of tokens being minted
+     * @param newReserveSupply The new total reserve supply
+     */
+    event MintFromReserve(
+        address indexed minter,
+        address indexed to,
+        uint256 amount,
+        uint256 newReserveSupply
+    );
+
     /**
      * @notice Emitted when tokens are preminted
      *
@@ -79,6 +94,19 @@ interface IERC20Mintable {
      */
     event Burn(address indexed burner, uint256 amount);
 
+    /**
+     * @notice Emitted when tokens are burned to reserve
+     *
+     * @param burner The address of the tokens burner
+     * @param amount The amount of tokens being burned
+     * @param newReserveSupply The new total reserve supply
+     */
+    event BurnToReserve(
+        address indexed burner,
+        uint256 amount,
+        uint256 newReserveSupply
+    );
+
     /**
      * @notice Emitted when the limit of premints is configured
      *
@@ -107,6 +135,13 @@ interface IERC20Mintable {
      */
     function minterAllowance(address minter) external view returns (uint256);
 
+    /**
+     * @notice Returns the total reserve supply
+     *
+     * @return The total reserve supply
+     */
+    function totalReserveSupply() external view returns (uint256);
+
     /**
      * @notice Updates the main minter address
      *
@@ -189,6 +224,20 @@ interface IERC20Mintable {
      */
     function reschedulePremintRelease(uint256 originalRelease, uint256 targetRelease) external;
 
+    /**
+     * @notice Mints tokens from reserve
+     *
+     * @dev Minting from reserve means that the tokens are minted in a regular way, but we also
+     * increase the total reserve supply by the amount of tokens minted
+     *
+     * Emits a {Mint} event
+     * Emits a {MintFromReserve} event
+     *
+     * @param account The address of a tokens recipient
+     * @param amount The amount of tokens to mint
+     */
+    function mintFromReserve(address account, uint256 amount) external;
+
     /**
      * @notice Burns tokens
      *
@@ -197,4 +246,17 @@ interface IERC20Mintable {
      * @param amount The amount of tokens to burn
      */
     function burn(uint256 amount) external;
+
+    /**
+     * @notice Burns tokens to reserve
+     *
+     * @dev Burning to reserve means that the tokens are burned in a regular way, but we also
+     * decrease the total reserve supply by the amount of tokens burned
+     *
+     * Emits a {Burn} event
+     * Emits a {BurnToReserve} event
+     *
+     * @param amount The amount of tokens to burn
+     */
+    function burnToReserve(uint256 amount) external;
 }