Blacklist Transfer Manager (BTM)

Introduced in	3.0.0
Contract name	BlacklistTransferManager
Type	Transfer Manager Module
Compatible Protocol Version	^3.0.0

How it works

This module allows approved employees/issuers to create and establish an automated blacklist to prevent insider investors from selling thus de-risking price swings during time-sensitive cases like earning calls. The blacklists can automatically become active/inactive at set recurring intervals.

Key functionalities (as defined in the Smart Contract)

Initialization

This module does not require any initialization.

Execute Transfer

Summary:

• If the module is paused or no blacklist is imposed on the sender, the transfer restrictions are skipped for that specific transfer.

• The module works by parsing through all the blacklists applied to the sender and returns the invalid transfer if any of the blacklists is currently active.

• Transfers are allowed to go through if none of the blacklists applied on the sender are active at that current moment.

    /** 
     * @param _from Address of the sender
     * @dev Restrict the blacklisted address to transfer tokens 
     * if the current time is between the timeframe define for the 
     * blacklist type associated with the _from address
     */
        function executeTransfer(address _from, address /* _to */, uint256 /* _amount */, bytes calldata /* _data */)

Managing blacklist types

Admins can add a new blacklist, modify an existing blacklist or delete a blacklist at any time using the below functions

Note:

• _startTime is the timestamp of the beginning of the first instance of the blacklist.

• _endTime is the timestamp of the end of the first instance of the blacklist.

• _repeatPeriodTime is a number of cooldown days after which the blacklist should be reactivated. If the

• _repeatPeriodTime == 0 makes the period non-repeating.

• _name is the name of the blacklist type.

Add Blacklist Type

Summary: This function is used to add the specified blacklist type.

   /**
    * @notice Used to add the blacklist type
    * @param _startTime Start date of the blacklist type
    * @param _endTime End date of the blacklist type
    * @param _blacklistName Name of the blacklist type
    * @param _repeatPeriodTime Repeat period of the blacklist type in days
    */
    function addBlacklistType(uint256 _startTime, uint256 _endTime, bytes32 _blacklistName, uint256 _repeatPeriodTime) public withPerm(ADMIN)

Add Blacklist Type Multi

Summary: This function is used to add multiple blacklist types in one transaction while having the same permission as addBlackListType().

Requirements:

• _startTimes.length == _endTimes.length

• _endTimes.length == _blacklistNames.length

• _blacklistNames.length == _repeatPeriodTimes.length, "Input array's length mismatch"

    /**
     * @notice Used to add the multiple blacklist type
     * @param _startTimes Start date of the blacklist type
     * @param _endTimes End date of the blacklist type
     * @param _blacklistNames Name of the blacklist type
     * @param _repeatPeriodTimes Repeat period of the blacklist type
     */
    function addBlacklistTypeMulti(
        uint256[] memory _startTimes,
        uint256[] memory _endTimes,
        bytes32[] memory _blacklistNames,
        uint256[] memory _repeatPeriodTimes
    )
        public
        withPerm(ADMIN)

Modify Blacklist Type

Summary: This function is used to modify the details of a given blacklist type.

Requirements:

• blacklists[_blacklistName].endTime != 0, "Blacklist type doesn't exist"

    /**
     * @notice Used to modify the details of a given blacklist type
     * @param _startTime Start date of the blacklist type
     * @param _endTime End date of the blacklist type
     * @param _blacklistName Name of the blacklist type
     * @param _repeatPeriodTime Repeat period of the blacklist type
     */
    function modifyBlacklistType(uint256 _startTime, uint256 _endTime, bytes32 _blacklistName, uint256 _repeatPeriodTime) public withPerm(ADMIN)

Modify Blacklist Type Multi

Summary: This function is used to modify multiple existing blacklist types as well as allow it to have the same access permission as modifyBlacklistType().

Requirements:

• _startTimes.length == _endTimes.length

• _endTimes.length == _blacklistNames.length

• _blacklistNames.length == _repeatPeriodTimes.length, "Input array's length mismatch"

    /**
     * @notice Used to modify the details of a given multiple blacklist types
     * @param _startTimes Start date of the blacklist type
     * @param _endTimes End date of the blacklist type
     * @param _blacklistNames Name of the blacklist type
     * @param _repeatPeriodTimes Repeat period of the blacklist type
     */
     function modifyBlacklistTypeMulti(
         uint256[] memory _startTimes,
         uint256[] memory _endTimes,
         bytes32[] memory _blacklistNames,
         uint256[] memory _repeatPeriodTimes
     )
         public
         withPerm(ADMIN)

Delete Blacklist Type

Summary: This function allows the issuer to delete the existing blacklist type.

Requirements:

• blacklists[_blacklistName].endTime != 0, "Blacklist type doesn’t exist"

• blacklistToInvestor[_blacklistName].length == 0, "Investors are associated with the blacklist"

    /**
     * @notice Used to delete the blacklist type
     * @param _blacklistName Name of the blacklist type
     */
     function deleteBlacklistType(bytes32 _blacklistName) public withPerm(ADMIN)

Delete Blacklist Type Multi

Summary: This function is used to delete the multiple blacklist types in a single transaction.

    /**
     * @notice Used to delete the multiple blacklist type
     * @param _blacklistNames Name of the blacklist type
     */
     function deleteBlacklistTypeMulti(bytes32[] memory _blacklistNames) public withPerm(ADMIN)

Applying blacklist to investors

Allows admins to add or remove users from blacklists at any time using listed functions below:

Note:

• _investor is the Ethereum address of the investor.

• _blacklistName is the name of the blacklist.

Add Investor to Blacklist

Summary: This function is used to assign a specific blacklist type to an investor. The _blacklistName should be pre-existing in the contract storage, otherwise, the transaction will fail.

Requirements:

• blacklists[_blacklistName].endTime != 0, "Blacklist type doesn't exist"

• investor != address(0), "Invalid investor address"

• investorToIndex[_investor][_blacklistName] == 0, "Blacklist already added to investor”

    /**
     * @notice Used to assign the blacklist type to the investor
     * @param _investor Address of the investor
     * @param _blacklistName Name of the blacklist
     */
     function addInvestorToBlacklist(address _investor, bytes32 _blacklistName) public withPerm(ADMIN)

Add Investor to Blacklist Multi

Summary: This function is used to assign the blacklist type to multiple investors.

    /**
     * @notice Used to assign the blacklist type to the multiple investor
     * @param _investors Address of the investor
     * @param _blacklistName Name of the blacklist
     */
    function addInvestorToBlacklistMulti(address[] memory _investors, bytes32 _blacklistName) public withPerm(ADMIN)

Add Multi Investor to Blacklist Multi

Summary: This function is used to assign the multiple blacklist type to multiple investors.

Requirements:

• _investors.length == _blacklistNames.length, "Input array's length mismatch"

    /**
     * @notice Used to assign the multiple blacklist type to the multiple investor
     * @param _investors Address of the investor
     * @param _blacklistNames Name of the blacklist
     */
    function addMultiInvestorToBlacklistMulti(address[] memory _investors, bytes32[] memory _blacklistNames) public withPerm(ADMIN)

Add Investor To New Blacklist

Summary: This function is used to assign the new blacklist type to an investor. It works by creating a new blacklistType and assign it to the investor.

    /**
     * @notice Used to assign the new blacklist type to the investor
     * @param _startTime Start date of the blacklist type
     * @param _endTime End date of the blacklist type
     * @param _blacklistName Name of the blacklist type
     * @param _repeatPeriodTime Repeat period of the blacklist type
     * @param _investor Address of the investor
     */
    function addInvestorToNewBlacklist(
        uint256 _startTime,
        uint256 _endTime,
        bytes32 _blacklistName,
        uint256 _repeatPeriodTime,
        address _investor
    ) public withPerm(ADMIN)

Delete Investor From All Blacklist(s)

Summary: This function is used to delete the investor from all of the associated blacklist types.

Requirements:

• investor != address(0), "Invalid investor address"

    /**
     * @notice Used to delete the investor from all the associated blacklist types
     * @param _investor Address of the investor
     */
    function deleteInvestorFromAllBlacklist(address _investor) public withPerm(ADMIN)

Delete Investor From All Blacklist(s) Multi

Summary: This function is used to delete multiple investors from all the associated blacklist types.

    /**
     * @notice Used to delete the multiple investors from all the associated blacklist types
     * @param _investor Address of the investor
     */
     function deleteInvestorFromAllBlacklistMulti(address[] memory _investor) public withPerm(ADMIN)

Delete Investor From Blacklist

Summary: This function is used to delete the investor from the blacklist

Requirement:

• _investor != address(0), "Invalid investor address"

• _blacklistName != bytes32(0),"Invalid blacklist name”

• investorToBlacklist = blacklistName, "Investor not associated to the blacklist"

    /**
     * @notice Used to delete the investor from the blacklist
     * @param _investor Address of the investor
     * @param _blacklistName Name of the blacklist
     */
     function deleteInvestorFromBlacklist(address _investor, bytes32 _blacklistName) public withPerm(ADMIN)

Delete Multi Investors From Blacklist Multi

Summary: This function is used to delete multiple investors from a blacklist.

Requirements:

• _investors.length == _blacklistNames.length, "Input array's length mismatch"

   /**
    * @notice Used to delete the multiple investor from the blacklist
    * @param _investors address of the investor
    * @param _blacklistNames name of the blacklist
    */
    function deleteMultiInvestorsFromBlacklistMulti(address[] memory _investors, bytes32[] memory _blacklistNames) public withPerm(ADMIN)

Get List Of Addresses

Summary: This function allows the issuer to get the list of the investors of a blacklist type.

Requirement:

• blacklists[_blacklistName].endTime != 0, "Blacklist type doesn't exist"

   /**
    * @notice get the list of the investors of a blacklist type
    * @param _blacklistName Name of the blacklist type
    * @return address List of investors associated with the blacklist
    */
    function getListOfAddresses(bytes32 _blacklistName) external view returns(address[] memory)

Get Blacklist Names To User

Summary: This function allows the issuer/employee to get the list of the investors of a blacklist type.

   /**
    * @notice get the list of the investors of a blacklist type
    * @param _user Address of the user
    * @return bytes32 List of blacklist names associated with the given address
    */
    function getBlacklistNamesToUser(address _user) external view returns(bytes32[] memory)

Get All Blacklists

Summary: This function allows the issuer to get a list of all the blacklist names.

    /**
     * @notice get the list of blacklist names
     * @return bytes32 Array of blacklist names
     */
    function getAllBlacklists() external view returns(bytes32[] memory)

Summary: Use to get the balance of token holder for a given partition

    /**
     * @notice return the amount of tokens for a given user as per the partition
     * @param _partition Identifier
     * @param _tokenHolder Whom token amount need to query
     * @param _additionalBalance It is the `_value` that transfer during transfer/transferFrom function call
     */
    function getTokensByPartition(bytes32 _partition, address _tokenHolder, uint256 _additionalBalance) external view returns(uint256)

Special considerations / notes

• function addInvestorToBlacklistMulti is limited by GAS limit and can only process the maximum number of address at a time.

• To set a non-recurring blacklist, _repeatPeriodTime can be set to a zero.

• All investors must be removed from a blacklist before that blacklist can be deleted using deleteBlacklistType function.