feat: vesting distribution

Author: PavelNaydanov

lib/openzeppelin-contracts

@@ -1,3 +1,4 @@
 ds-test/=lib/solmate/lib/ds-test/src/
 forge-std/=lib/forge-std/src/
-solmate/=lib/solmate/src/
+solmate/=lib/solmate/src/
+@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/

remappings.txt

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {SafeERC20, IERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
+
+import {MetaToken} from "src/MetaToken.sol";
+
+import {IMetaTokenDistributor} from "./interfaces/IMetaTokenDistributor.sol";
+import {Vesting, IVesting} from "./vesting/Vesting.sol";
+import {IVestingParams} from "./vesting/interfaces/IVestingParams.sol";
+import {Schedule, Beneficiary, VestingType} from "./utils/Common.sol";
+
+contract MetaTokenDistributor is IMetaTokenDistributor {
+    using SafeERC20 for IERC20;
+
+    address private _vestingImpl;
+    IERC20 private _META;
+
+    IVestingParams private _vestingParams;
+    uint64 private _vestingStartTime;
+
+    constructor(address vestingParams, uint64 vestingStartTime) {
+        if (vestingStartTime < block.timestamp) {
+            revert InvalidVestingStartTime();
+        }
+
+        if (address(vestingParams) == address(0)) {
+            revert ZeroAddress();
+        }
+
+        _vestingStartTime = vestingStartTime;
+        _vestingParams = IVestingParams(vestingParams);
+
+        _vestingImpl = address(new Vesting());
+        _META = IERC20(address(new MetaToken(address(this))));
+
+        if (_META.balanceOf(address(this)) != _META.totalSupply()) {
+            revert IncorrectMetaAmountForDistribution();
+        }
+
+        emit MetaTokenDeployed(address(_META));
+    }
+
+    function startVesting(VestingType vestingType) external returns (address vesting) {
+        if (block.timestamp < _vestingStartTime) {
+            revert VestingStartTimeHasNotArrived();
+        }
+
+        vesting = Clones.clone(_vestingImpl);
+
+        // TODO: Можно две функции объединить
+        (
+            Beneficiary[] memory beneficiaries,
+            Schedule memory schedule
+        ) = _vestingParams.getBeneficiariesAndSchedule(vestingType);
+
+        (uint256 vestingAmount,,,,) = _vestingParams.getVestingParams(vestingType);
+
+        _META.safeTransfer(address(vesting), vestingAmount);
+        IVesting(vesting).initialize(_META, schedule, beneficiaries);
+
+        emit VestingStarted(vesting);
+    }
+
+    function getMETA() external view returns (address) {
+        return address(_META);
+    }
+}

src/tokenDistribution/MetaTokenDistributor.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {VestingType} from "../utils/Common.sol";
+
+interface IMetaTokenDistributor {
+    event VestingStarted(address vesting);
+    event MetaTokenDeployed(address META);
+
+    error InvalidVestingStartTime();
+    error VestingStartTimeHasNotArrived();
+    error IncorrectMetaAmountForDistribution();
+    error ZeroAddress();
+
+    function startVesting(VestingType vestingType) external returns (address vesting);
+}

src/tokenDistribution/interfaces/IMetaTokenDistributor.sol

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+struct Period {
+    uint256 endTime;
+    uint256 portion;
+}
+
+struct Schedule {
+    uint256 startTime;
+    Period[] periods;
+}
+
+struct Beneficiary {
+    address account;
+    uint256 amount;
+}
+
+enum VestingType {
+    TEAM,
+    LIQUIDITY
+}

src/tokenDistribution/utils/Common.sol

@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {SafeERC20, IERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {Initializable} from "@openzeppelin/contracts/proxy/utils/Initializable.sol";
+
+import {IVesting} from "./interfaces/IVesting.sol";
+import {Schedule, Period, Beneficiary} from "../utils/Common.sol";
+
+// TODO: Проверить отчет на предмет замечаний
+
+/**
+ * @title Vesting contract of the base token
+ * @dev Each new vesting instance is created through a factory using the Minimal Clones pattern.
+ * Vesting settings are set at the time of deploying a new instance in the initialize() function.
+ * Beneficiaries can claim the token according to the schedule by calling the claim() function
+ */
+contract Vesting is IVesting, Initializable {
+    using SafeERC20 for IERC20;
+
+    /// @notice The factor used to calculate percentages for the vesting schedule period.
+    /// It is set to 10_000 to handle basis points (0.01% increments)
+    uint256 private constant _BASIS_POINTS = 10_000; // ex: 10% = 1_000
+
+    /// @notice Structure of the vesting schedule params
+    Schedule private _schedule;
+
+    /// @notice Base token that will be vested
+    IERC20 private _baseToken;
+
+    /// @notice The initial amount of tokens in the account that was locked
+    mapping(address account => uint256 amount) private _initialLocked;
+
+    /// @notice The total initial amount of tokens that was locked
+    uint256 private _initialTotalLocked;
+
+    /// @notice The amount of released tokens by the account
+    mapping(address account => uint256 amount) private _released;
+
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    /**
+     * @notice Initialization function for the vesting contract
+     * @param baseToken Address of the base token that will be vested
+     * @param schedule The structure that defines the vesting schedule
+     * @param beneficiaries List of accounts and amounts to be distributed
+     */
+    function initialize(IERC20 baseToken, Schedule calldata schedule, Beneficiary[] calldata beneficiaries) external initializer {
+        if (address(baseToken) == address(0)) {
+            revert ZeroAddress();
+        }
+
+        _baseToken = baseToken;
+
+        _initializeSchedule(schedule);
+        _initializeBeneficiaries(beneficiaries, baseToken);
+    }
+
+    /**
+     * @notice Claims the base token according to the vesting schedule
+     * @dev The claimed amount will be store in _released mapping
+     */
+    function claim() external {
+        Schedule memory schedule = _schedule;
+
+        if (block.timestamp < schedule.startTime) {
+            revert VestingHasNotStarted();
+        }
+
+        uint256 unlockedAmount = availableToClaim(msg.sender);
+        if (unlockedAmount > 0) {
+            _released[msg.sender] += unlockedAmount;
+            _baseToken.safeTransfer(msg.sender, unlockedAmount);
+
+            emit Claimed(msg.sender, unlockedAmount);
+        }
+    }
+
+    // region - Public view function -
+
+    /// @notice Retrieves the vesting schedule structure
+    function getSchedule() external view returns (Schedule memory) {
+        return _schedule;
+    }
+
+    /// @notice Returns the base token address
+    function getBaseToken() external view returns (address) {
+        return address(_baseToken);
+    }
+
+    /// @notice Returns the total amount of unlocked tokens
+    function totalUnlocked() public view returns (uint256) {
+        return _computeUnlocked(_initialTotalLocked);
+    }
+
+    /// @notice Returns the total amount of locked tokens
+    function totalLocked() external view returns (uint256) {
+        return _initialTotalLocked - totalUnlocked();
+    }
+
+    /// @notice Returns the amount of unlocked tokens for a specific account
+    function unlockedOf(address account) public view returns (uint256) {
+        return _computeUnlocked(_initialLocked[account]);
+    }
+
+    /// @notice Returns the amount of locked tokens for a specific account
+    function lockedOf(address account) external view returns (uint256) {
+        return _initialLocked[account] - unlockedOf(account);
+    }
+
+    /// @notice Returns the available amount of unlocked tokens that can be claimed by a specific account
+    function availableToClaim(address account) public view returns (uint256) {
+        return unlockedOf(account) - _released[account];
+    }
+
+    // endregion
+
+    // region - Private functions
+
+    /**
+     * @notice Validates and sets the vesting schedule parameters
+     * @param schedule The structure that defines the vesting schedule
+     */
+    function _initializeSchedule(Schedule calldata schedule) private {
+        if (schedule.startTime < block.timestamp) {
+            revert InvalidStartTime();
+        }
+
+        // Check that every period portion param is valid.
+        // Variable to keep track of the total percentage of the vesting schedule periods
+        uint256 totalPercentageOfPortions;
+        uint256 numberOfPeriods = schedule.periods.length;
+        for (uint256 i = 0; i < numberOfPeriods; i++) {
+            Period memory period = schedule.periods[i];
+
+            if (period.portion > _BASIS_POINTS) {
+                revert InvalidPortion();
+            }
+
+            totalPercentageOfPortions += period.portion;
+
+            if (i > 0) {
+                Period memory prevPeriod = schedule.periods[i - 1];
+
+                if (prevPeriod.endTime >= period.endTime) {
+                    revert IncorrectPeriodTime();
+                }
+            }
+        }
+
+        if (totalPercentageOfPortions != _BASIS_POINTS) {
+            revert IncorrectTotalPeriodPortions();
+        }
+
+        _schedule.startTime = schedule.startTime;
+
+        for (uint256 i = 0; i < schedule.periods.length; i++) {
+            Period memory period = schedule.periods[i];
+            _schedule.periods.push(period);
+        }
+
+        emit ScheduleInitialized(schedule);
+    }
+
+    /**
+     * @notice Validates and sets the list of beneficiaries
+     * @param beneficiaries List of accounts and amounts to be distributed
+     * @param baseToken Address of base token for vesting
+     */
+    function _initializeBeneficiaries(Beneficiary[] calldata beneficiaries, IERC20 baseToken) private {
+        if (beneficiaries.length == 0) {
+            revert ZeroBeneficiaries();
+        }
+
+        for (uint256 i = 0; i < beneficiaries.length; i++) {
+            Beneficiary memory beneficiary = beneficiaries[i];
+
+            if (beneficiary.account == address(0)) {
+                revert ZeroAddress();
+            }
+
+            if (beneficiary.amount == 0) {
+                revert ZeroAmount();
+            }
+
+            if (_initialLocked[beneficiary.account] > 0) {
+                revert DuplicateBeneficiary(beneficiary.account);
+            }
+
+            _initialLocked[beneficiary.account] = beneficiary.amount;
+            _initialTotalLocked += beneficiary.amount;
+        }
+
+        if (_initialTotalLocked != baseToken.balanceOf(address(this))) {
+            revert IncorrectAmountOfBeneficiaries();
+        }
+
+        emit BeneficiariesInitialized(beneficiaries);
+    }
+
+    /**
+     * @notice Computes the amount of unlocked tokens based on the initial locked amount
+     * @param initialLockedAmount The total amount of initially locked tokens
+     * @return unlockedAmount The total amount of unlocked tokens
+     */
+    function _computeUnlocked(uint256 initialLockedAmount) private view returns (uint256 unlockedAmount) {
+        if (block.timestamp < _schedule.startTime) {
+            return 0;
+        }
+
+        uint256 startTime = _schedule.startTime;
+        Period[] memory periods = _schedule.periods;
+
+        for (uint256 i = 0; i < periods.length; i++) {
+            Period memory period = _schedule.periods[i];
+
+            uint256 endTime = period.endTime;
+            uint256 portion = period.portion;
+
+            if (block.timestamp < endTime) {
+                uint256 partPeriod = block.timestamp - startTime;
+                uint256 fullPeriod = endTime - startTime;
+
+                // Calculate the unlocked tokens based on the elapsed time within the period
+                unlockedAmount += (initialLockedAmount * partPeriod * portion) / (fullPeriod * _BASIS_POINTS);
+
+                // Exit the loop since the unlocked tokens for the current period
+                // have been calculated
+                break;
+            } else {
+                // All tokens for the current period are unlocked
+                unlockedAmount += (initialLockedAmount * portion) / _BASIS_POINTS;
+                startTime = endTime;
+            }
+        }
+    }
+
+    // endregion
+}