# 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.