Vesting Escrow Wallet

Vesting Escrow Wallet

• Introduced in: 2.1.0
• Contract name: VestingEscrowWallet.sol
• Type: Wallet Module

How it works

This module will allow approved staff to create token (ST) vesting schedule for employees and/or affiliates so that tokens get delivered to their wallets as contractually defined. Admin can send tokens to and then select the address that would be able to withdraw them according to their specific vesting schedule.

Key functionalities (as defined in the Smart Contract)

Initialization

This module should be configured by the treasury wallet address. You will need to call the configure function of this contract during creation. Note that the treasury wallet can be changed later by the owner.

/**
 * @notice Used to initialize the treasury wallet address
 * @param _treasuryWallet Address of the treasury wallet
 */
 function configure(address _treasuryWallet) public onlyFactory {

Managing schedules

These functions allow for the admin/issuer to add a new schedule, modify or revoke existing schedule at any time using the following functions:

Add Schedule

This function is used for creating vesting schedules for each beneficiary.

/**
 * @notice Adds vesting schedules for each of the beneficiary's address
 * @param _beneficiary Address of the beneficiary for whom it is scheduled
 * @param _templateName Name of the template that will be created
 * @param _numberOfTokens Total number of tokens for created schedule
 * @param _duration Duration of the created vesting schedule
 * @param _frequency Frequency of the created vesting schedule
 * @param _startTime Start time of the created vesting schedule
 */
function addSchedule(
    address _beneficiary,
    bytes32 _templateName,
    uint256 _numberOfTokens,
    uint256 _duration,
    uint256 _frequency,
    uint256 _startTime
)
    external
    withPerm(ADMIN)

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty
• require(_name != bytes32(0), "Invalid name") template name shouldn’t be empty
• require(!_isTemplateExists(_name), "Already exists") template with an appropriate name shouldn’t be created
• require(_numberOfTokens > 0, "Zero amount") number of tokens should be positive value
• require(_duration % _frequency == 0, "Invalid frequency") duration should be divided by frequency without a remainder
• require(_numberOfTokens % periodCount == 0) number of tokens should be divided by count of periods without a remainder
• require(amountPerPeriod % ISecurityToken(securityToken).granularity() == 0, "Invalid granularity") amount per period should be divided by token granularity without a remainder
• Schedule with an appropriate template name shouldn’t be added to the beneficiary address
• require(_startTime >= now, "Date in the past") date shouldn’t be in the past

Adding Schedule From Template

This function is for adding vesting schedules from template for each beneficiary.

/**
 * @notice Adds vesting schedules from template for the beneficiary
 * @param _beneficiary Address of the beneficiary for whom it is scheduled
 * @param _templateName Name of the exists template
 * @param _startTime Start time of the created vesting schedule
 */
function addScheduleFromTemplate(address _beneficiary, bytes32 _templateName, uint256 _startTime) external withPerm(ADMIN) {

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty
• require(_isTemplateExists(_templateName), "Template not found") template should be already created
• Schedule with an appropriate template name shouldn’t be added to the beneficiary address
• require(_startTime >= now, "Date in the past") date shouldn’t be in the past

Modify Schedule

This function is used to modify vesting schedules for each beneficiary. Note that only the start time for schedule can be changed. If you need to modify other fields you have to remove and then add a schedule.

/**
 * @notice Modifies vesting schedules for each of the beneficiary
 * @param _beneficiary Address of the beneficiary for whom it is modified
 * @param _templateName Name of the template was used for schedule creation
 * @param _startTime Start time of the created vesting schedule
 */
function modifySchedule(address _beneficiary, bytes32 _templateName, uint256 _startTime) public withPerm(ADMIN) {

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty
• Schedule with the given template name should be already added to the beneficiary address
• require(_startTime >= now, "Date in the past") date shouldn’t be in the past
• require(now < schedule.startTime, "Schedule started") schedule shouldn’t be started

Revoking schedule

This function is used to revoke a beneficiary’s schedule.

/**
 * @notice Revokes vesting schedule with given template name for given beneficiary
 * @param _beneficiary Address of the beneficiary for whom it is revoked
 * @param _templateName Name of the template was used for schedule creation
 */
function revokeSchedule(address _beneficiary, bytes32 _templateName) external withPerm(ADMIN) {

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty
• Schedule with the given template name should be already added to the beneficiary address

Revoke all schedules

This function is used to revoke all of the beneficiaries schedules.

/**
 * @notice Revokes all vesting schedules for given beneficiary's address
 * @param _beneficiary Address of the beneficiary for whom all schedules will be revoked
 */
function revokeAllSchedules(address _beneficiary) public withPerm(ADMIN) {

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty

Get schedule data

This function is called to return a specific beneficiary’s schedule.

/**
 * @notice Returns beneficiary's schedule created using template name
 * @param _beneficiary Address of the beneficiary who will receive tokens
 * @param _templateName Name of the template was used for schedule creation
 * @return beneficiary's schedule data (numberOfTokens, duration, frequency, startTime, claimedTokens, State)
 */
function getSchedule(address _beneficiary, bytes32 _templateName) external view returns(uint256, uint256, uint256, uint256, uint256, State) {

Getting Template Names

This function is used to return a list of template names as well as for which have been used for schedule creation for some beneficiary.

/**
 * @notice Returns list of the template names for given beneficiary's address
 * @param _beneficiary Address of the beneficiary
 * @return List of the template names that were used for schedule creation
 */
function getTemplateNames(address _beneficiary) external view returns(bytes32[] memory)

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty

Get schedule count

This function is used to return the count of a beneficiary’s schedules.

/**
 * @notice Returns count of the schedules were created for given beneficiary
 * @param _beneficiary Address of the beneficiary
 * @return Count of beneficiary's schedules
 */
function getScheduleCount(address _beneficiary) external view returns(uint256) {

Required checks

• require(_beneficiary != address(0), "Invalid address") beneficiary address shouldn’t be empty

Managing templates

The Admin can add a new template or delete an existing template (if the template isn’t used by any schedule) at any time using the following functions:

Adding a Template

This function is used to add a template. The template inputs needed are:

• Name

• Number of Tokens

• Vesting Duration

• Vesting Frequency

   /**
    * @notice Adds template that can be used for creating a schedule
    * @param _name Name of the template will be created
    * @param _numberOfTokens Number of tokens that should be assigned to schedule
    * @param _duration Duration of the vesting schedule
    * @param _frequency Frequency of the vesting schedule
    */
     function addTemplate(
        bytes32 _name,
        uint256 _numberOfTokens,
        uint256 _duration, 
        uint256 _frequency
     ) 
        external
        withPerm(ADMIN)
  

Required checks

• require(_name != bytes32(0), "Invalid name") template name shouldn’t be empty
• require(!_isTemplateExists(_name), "Already exists") template with an appropriate name shouldn’t be created
• require(_numberOfTokens > 0, "Zero amount") number of tokens should be positive value
• require(_duration % _frequency == 0, "Invalid frequency") duration should be divided by frequency without a remainder
• require(_numberOfTokens % periodCount == 0) number of tokens should be divided by count of periods without a remainder
• require(amountPerPeriod % ISecurityToken(securityToken).granularity() == 0, "Invalid granularity") amount per period should be divided by token granularity without a remainder

Removing template

This function is used to remove templates and their respective name.

Note: Please take into consideration that the template can't be removed if at least one schedule already uses it.

/**
 * @notice Removes template with a given name
 * @param _name Name of the template that will be removed
 */
function removeTemplate(bytes32 _name) external withPerm(ADMIN) {

Required checks

• require(_isTemplateExists(_templateName), "Template not found") template should be already created
• require(templateToUsers[_name].length == 0, "Template is used") template shouldn’t be used by any schedules

Get template count

This function returns the count of the templates and issuer has.

/**
 * @notice Returns count of the templates those can be used for creating schedule
 * @return Count of the templates
 */
function getTemplateCount() external view returns(uint256) {

Get template names

This function allows the issuer to get a list of the template names that they have set up.

/**
 * @notice Gets the list of the template names those can be used for creating schedule
 * @return bytes32 Array of all template names were created
 */
function getAllTemplateNames() external view returns(bytes32[]) {

Depositing/withdrawing tokens

An admin/issuer can deposit tokens to the wallet and withdraw tokens from it. Depositing can be done by any delegate using an account with tokens. On the other hand when tokens get to withdraw from the contract, receiver always be the treasury wallet.

Change Treasury Wallet

This function is used to change the treasury wallet address. Please note that only the issuer can change the treasury wallet.

/**
 * @notice Used to change the treasury wallet address
 * @param _newTreasuryWallet Address of the treasury wallet
 */
function changeTreasuryWallet(address _newTreasuryWallet) public onlyOwner {

Required checks

• require(_newTreasuryWallet != address(0)) treasury wallet address shouldn’t be empty

Deposit Tokens

This function used for the issuer to deposit tokens from their treasury.

/**
 * @notice Used to deposit tokens from treasury wallet to the vesting escrow wallet
 * @param _numberOfTokens Number of tokens that should be deposited
 */
function depositTokens(uint256 _numberOfTokens) external withPerm(ADMIN) {

Required checks

• require(_numberOfTokens > 0, "Should be > 0")number of tokens should be a positive value

Send To Treasury

This function allows the issuer to send the unassigned tokens to their treasury.

/**
 * @notice Sends unassigned tokens to the treasury wallet
 * @param _amount Amount of tokens that should be send to the treasury wallet
 */
function sendToTreasury(uint256 _amount) external withPerm(ADMIN) {

Required checks

• require(_amount > 0, "Amount cannot be zero") amount should be a positive value
• require(_amount <= unassignedTokens, "Amount is greater than unassigned tokens") Amount shouldn’t be greater than unassigned tokens

Push Available Tokens

This function allows the issuer to push available tokens to the respective beneficiaries.

/**
 * @notice Pushes available tokens to the beneficiary's address
 * @param _beneficiary Address of the beneficiary who will receive tokens
 */
function pushAvailableTokens(address _beneficiary) public withPerm(ADMIN) {

Pull Available Tokens

This function allows the issuer to withdraw available tokens by the beneficiary.

/**
 * @notice Used to withdraw available tokens by beneficiary
 */
function pullAvailableTokens() external {

Multi-operations

These functions allow the admin/issuer to add a new schedule, modify or revoke existing schedule and send available tokens for few employees and/or affiliates at any time using the following functions:

Push Available Tokens Multi

This function allows the issuer to bulk send available tokens for each beneficiary.

    /**
     * @notice Used to bulk send available tokens for each of the beneficiaries
     * @param _fromIndex Start index of array of beneficiary's addresses
     * @param _toIndex End index of array of beneficiary's addresses
     */
    function pushAvailableTokensMulti(uint256 _fromIndex, uint256 _toIndex) public withPerm(OPERATOR)

Required checks

• require(_toIndex <= beneficiaries.length - 1, "Array out of bound") _toIndex should be within the bounds of the beneficiary array

Add Schedule Multi

This function is used to bulk add respective vesting schedules for each of the beneficiaries.

/**
     * @notice Used to bulk add vesting schedules for each of beneficiary
     * @param _beneficiaries Array of the beneficiary's addresses
     * @param _templateNames Array of the template names
     * @param _numberOfTokens Array of number of tokens should be assigned to schedules
     * @param _durations Array of the vesting duration
     * @param _frequencies Array of the vesting frequency
     * @param _startTimes Array of the vesting start time
     */
    function addScheduleMulti(
        address[] memory _beneficiaries,
        bytes32[] memory _templateNames,
        uint256[] memory _numberOfTokens,
        uint256[] memory _durations,
        uint256[] memory _frequencies,
        uint256[] memory _startTimes
    )
        public
        withPerm(ADMIN)

Required checks

• All arrays should have the same length

Add Schedule From Template Multi

This function is used to bulk add the vesting schedules from a template for each of the beneficiaries.

    /**
     * @notice Used to bulk add vesting schedules from template for each of the beneficiary
     * @param _beneficiaries Array of beneficiary's addresses
     * @param _templateNames Array of the template names were used for schedule creation
     * @param _startTimes Array of the vesting start time
     */
    function addScheduleFromTemplateMulti(
        address[] memory _beneficiaries,
        bytes32[] memory _templateNames,
        uint256[] memory _startTimes
    )
        public
        withPerm(ADMIN)

Required checks

• All arrays should have the same length

Revoking Schedules Multi

This function is used to bulk revoke vesting schedules for each of the beneficiaries.

/**
     * @notice Used to bulk revoke vesting schedules for each of the beneficiaries
     * @param _beneficiaries Array of the beneficiary's addresses
     */
    function revokeSchedulesMulti(address[] memory _beneficiaries) public withPerm(ADMIN)

Modify Schedule Multi

This function is used to bulk modify vesting schedules for each of the beneficiaries.

    /**
     * @notice Used to bulk modify vesting schedules for each of the beneficiaries
     * @param _beneficiaries Array of the beneficiary's addresses
     * @param _templateNames Array of the template names
     * @param _startTimes Array of the vesting start time
     */
    function modifyScheduleMulti(
        address[] memory _beneficiaries,
        bytes32[] memory _templateNames,
        uint256[] memory _startTimes
    )
        public
        withPerm(ADMIN)

Required checks

• All arrays should have the same length