[CCTPE-564] Add minimum fee (circlefin#68)

- Add `minFee` variable to store the minimum fee (in 1/1,000th basis
points) for all transfers and enforcement logic.
 - Add `minFeeController` role for managing `minFee`.
 - Add getter and setter for new variable.
 - Add getter and setter for new role.
 - Add and update relevant tests.
 - Update deployment scripts and tests.

Audit scope:
https://docs.google.com/document/d/129HaTPi1MojGf8zd8v657zkctSmFD87wjTf9naQVfkA/edit?tab=t.0

Author: epoon-circle

README.md

@@ -162,6 +162,8 @@ The proxies are deployed via `CREATE2` through Create2Factory. The scripts assum
     - `TOKEN_MESSENGER_V2_FEE_RECIPIENT_ADDRESS`
     - `TOKEN_MESSENGER_V2_DENYLISTER_ADDRESS`
     - `TOKEN_MESSENGER_V2_PROXY_ADMIN_ADDRESS`
+    - `TOKEN_MESSENGER_V2_MIN_FEE_CONTROLLER_ADDRESS`
+    - `TOKEN_MESSENGER_V2_MIN_FEE`
 
     - `DOMAIN`
     - `BURN_LIMIT_PER_MESSAGE`

anvil/crosschainTransferITV2.py

@@ -60,6 +60,8 @@ contract DeployProxiesV2Script is Script {
     address private tokenMessengerV2FeeRecipientAddress;
     address private tokenMessengerV2DenylisterAddress;
     address private tokenMessengerV2AdminAddress;
+    address private tokenMessengerV2MinFeeControllerAddress;
+    uint256 private tokenMessengerV2MinFee;
 
     uint32 private domain;
     uint32 private version;
@@ -185,11 +187,15 @@ contract DeployProxiesV2Script is Script {
         }
         bytes memory initializer = abi.encodeWithSelector(
             TokenMessengerV2.initialize.selector,
-            tokenMessengerV2OwnerAddress,
-            tokenMessengerV2RescuerAddress,
-            tokenMessengerV2FeeRecipientAddress,
-            tokenMessengerV2DenylisterAddress,
-            address(tokenMinterV2),
+            TokenMessengerV2.TokenMessengerV2Roles({
+                owner: tokenMessengerV2OwnerAddress,
+                rescuer: tokenMessengerV2RescuerAddress,
+                feeRecipient: tokenMessengerV2FeeRecipientAddress,
+                denylister: tokenMessengerV2DenylisterAddress,
+                tokenMinter: address(tokenMinterV2),
+                minFeeController: tokenMessengerV2MinFeeControllerAddress
+            }),
+            tokenMessengerV2MinFee,
             remoteDomains,
             remoteTokenMessengerAddresses
         );
@@ -333,6 +339,10 @@ contract DeployProxiesV2Script is Script {
         tokenMessengerV2AdminAddress = vm.envAddress(
             "TOKEN_MESSENGER_V2_PROXY_ADMIN_ADDRESS"
         );
+        tokenMessengerV2MinFeeControllerAddress = vm.envAddress(
+            "TOKEN_MESSENGER_V2_MIN_FEE_CONTROLLER_ADDRESS"
+        );
+        tokenMessengerV2MinFee = vm.envUint("TOKEN_MESSENGER_V2_MIN_FEE");
 
         domain = uint32(vm.envUint("DOMAIN"));
         version = uint32(vm.envUint("VERSION"));

scripts/v2/DeployProxiesV2.s.sol

@@ -62,6 +62,18 @@ abstract contract BaseTokenMessenger is Rescuable, Denylistable, Initializable {
      */
     event FeeRecipientSet(address feeRecipient);
 
+    /**
+     * @notice Emitted when the minimum fee controller is set
+     * @param minFeeController address of minimum fee controller
+     */
+    event MinFeeControllerSet(address minFeeController);
+
+    /**
+     * @notice Emitted when the minimum fee is set
+     * @param minFee minimum fee
+     */
+    event MinFeeSet(uint256 minFee);
+
     /**
      * @notice Emitted when tokens are minted
      * @param mintRecipient recipient address of minted tokens
@@ -92,6 +104,15 @@ abstract contract BaseTokenMessenger is Rescuable, Denylistable, Initializable {
     // Address to receive collected fees
     address public feeRecipient;
 
+    // Minimum fee controller address
+    address public minFeeController;
+
+    // Minimum fee for all transfers in 1/1000 basis points
+    uint256 public minFee;
+
+    // Minimum fee multiplier to support 1/1000 basis point precision
+    uint256 public constant MIN_FEE_MULTIPLIER = 10_000_000;
+
     // ============ Modifiers ============
     /**
      * @notice Only accept messages from a registered TokenMessenger contract on given remote domain
@@ -115,6 +136,17 @@ abstract contract BaseTokenMessenger is Rescuable, Denylistable, Initializable {
         _;
     }
 
+    /**
+     * @notice Reverts if called by any account other than the min fee controller
+     */
+    modifier onlyMinFeeController() {
+        require(
+            msg.sender == minFeeController,
+            "Caller is not the min fee controller"
+        );
+        _;
+    }
+
     // ============ Constructor ============
     /**
      * @param _messageTransmitter Message transmitter address
@@ -191,6 +223,26 @@ abstract contract BaseTokenMessenger is Rescuable, Denylistable, Initializable {
         _setFeeRecipient(_feeRecipient);
     }
 
+    /**
+     * @notice Sets the minimum fee controller address
+     * @dev Reverts if not called by the owner
+     * @dev Reverts if `_minFeeController` is the zero address
+     * @param _minFeeController Address of minimum fee controller
+     */
+    function setMinFeeController(address _minFeeController) external onlyOwner {
+        _setMinFeeController(_minFeeController);
+    }
+
+    /**
+     * @notice Sets the minimum fee for all transfers in 1/1000 basis points
+     * @dev Reverts if not called by the min fee controller
+     * @dev Reverts if the minimum fee is equal to or greater than MIN_FEE_MULTIPLIER
+     * @param _minFee Minimum fee
+     */
+    function setMinFee(uint256 _minFee) external onlyMinFeeController {
+        _setMinFee(_minFee);
+    }
+
     /**
      * @notice Returns the current initialized version
      */
@@ -335,6 +387,28 @@ abstract contract BaseTokenMessenger is Rescuable, Denylistable, Initializable {
         emit LocalMinterAdded(_newLocalMinter);
     }
 
+    /**
+     * @notice Sets the minimum fee controller address
+     * @dev Reverts if `_minFeeController` is the zero address
+     * @param _minFeeController Address of minimum fee controller
+     */
+    function _setMinFeeController(address _minFeeController) internal {
+        require(_minFeeController != address(0), "Zero address not allowed");
+        minFeeController = _minFeeController;
+        emit MinFeeControllerSet(_minFeeController);
+    }
+
+    /**
+     * @notice Sets the minimum fee for all transfers
+     * @dev Reverts if the minimum fee is equal to or greater than MIN_FEE_MULTIPLIER
+     * @param _minFee Minimum fee
+     */
+    function _setMinFee(uint256 _minFee) internal {
+        require(_minFee < MIN_FEE_MULTIPLIER, "Min fee too high");
+        minFee = _minFee;
+        emit MinFeeSet(_minFee);
+    }
+
     /**
      * @notice Add the TokenMessenger for a remote domain.
      * @dev Reverts if there is already a TokenMessenger set for domain.

src/v2/BaseTokenMessenger.sol

@@ -16,7 +16,9 @@
  * limitations under the License.
  */
 pragma solidity 0.7.6;
+pragma abicoder v2;
 
+import {SafeMath} from "@openzeppelin/contracts/math/SafeMath.sol";
 import {BaseTokenMessenger} from "./BaseTokenMessenger.sol";
 import {ITokenMinterV2} from "../interfaces/v2/ITokenMinterV2.sol";
 import {AddressUtils} from "../messages/v2/AddressUtils.sol";
@@ -32,6 +34,16 @@ import {TOKEN_MESSENGER_MIN_FINALITY_THRESHOLD} from "./FinalityThresholds.sol";
  * and to/from TokenMinters.
  */
 contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
+    // ============ Structs ============
+    struct TokenMessengerV2Roles {
+        address owner;
+        address rescuer;
+        address feeRecipient;
+        address denylister;
+        address tokenMinter;
+        address minFeeController;
+    }
+
     // ============ Events ============
     /**
      * @notice Emitted when a DepositForBurn message is sent
@@ -67,6 +79,7 @@ contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
     using BurnMessageV2 for bytes29;
     using TypedMemView for bytes;
     using TypedMemView for bytes29;
+    using SafeMath for uint256;
 
     // ============ Constructor ============
     /**
@@ -83,46 +96,40 @@ contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
     // ============ Initializers ============
     /**
      * @notice Initializes the contract
-     * @dev Reverts if `owner_` is the zero address
-     * @dev Reverts if `rescuer_` is the zero address
-     * @dev Reverts if `feeRecipient_` is the zero address
-     * @dev Reverts if `denylister_` is the zero address
-     * @dev Reverts if `tokenMinter_` is the zero address
+     * @dev Reverts if any of the roles are the zero address
      * @dev Reverts if `remoteDomains_` and `remoteTokenMessengers_` are unequal length
      * @dev Each remoteTokenMessenger address must correspond to the remote domain at the same
      * index in respective arrays.
      * @dev Reverts if any `remoteTokenMessengers_` entry equals bytes32(0)
-     * @param owner_ Owner address
-     * @param rescuer_ Rescuer address
-     * @param feeRecipient_ FeeRecipient address
-     * @param denylister_ Denylister address
-     * @param tokenMinter_ Local token minter address
+     * @param roles Roles configuration
+     * @param minFee_ Minimum fee
      * @param remoteDomains_ Array of remote domains to configure
      * @param remoteTokenMessengers_ Array of remote token messenger addresses
      */
     function initialize(
-        address owner_,
-        address rescuer_,
-        address feeRecipient_,
-        address denylister_,
-        address tokenMinter_,
+        TokenMessengerV2Roles calldata roles,
+        uint256 minFee_,
         uint32[] calldata remoteDomains_,
         bytes32[] calldata remoteTokenMessengers_
     ) external initializer {
-        require(owner_ != address(0), "Owner is the zero address");
+        require(roles.owner != address(0), "Owner is the zero address");
         require(
             remoteDomains_.length == remoteTokenMessengers_.length,
             "Invalid remote domain configuration"
         );
 
         // Roles
-        _transferOwnership(owner_);
-        _updateRescuer(rescuer_);
-        _updateDenylister(denylister_);
-        _setFeeRecipient(feeRecipient_);
+        _transferOwnership(roles.owner);
+        _updateRescuer(roles.rescuer);
+        _updateDenylister(roles.denylister);
+        _setFeeRecipient(roles.feeRecipient);
 
         // Local minter configuration
-        _setLocalMinter(tokenMinter_);
+        _setLocalMinter(roles.tokenMinter);
+
+        // Fee configuration
+        _setMinFeeController(roles.minFeeController);
+        _setMinFee(minFee_);
 
         // Remote token messenger configuration
         uint256 _remoteDomainsLength = remoteDomains_.length;
@@ -145,6 +152,7 @@ contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
      * to this contract is less than `amount`.
      * - burn() reverts. For example, if `amount` is 0.
      * - maxFee is greater than or equal to `amount`.
+     * - maxFee is less than `amount * minFee / MIN_FEE_MULTIPLIER`.
      * - MessageTransmitterV2#sendMessage reverts.
      * @param amount amount of tokens to burn
      * @param destinationDomain destination domain to receive message on
@@ -188,6 +196,7 @@ contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
      * to this contract is less than `amount`.
      * - burn() reverts. For example, if `amount` is 0.
      * - maxFee is greater than or equal to `amount`.
+     * - maxFee is less than `amount * minFee / MIN_FEE_MULTIPLIER`.
      * - MessageTransmitterV2#sendMessage reverts.
      * @param amount amount of tokens to burn
      * @param destinationDomain destination domain to receive message on
@@ -282,7 +291,33 @@ contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
         return _handleReceiveMessage(messageBody.ref(0), remoteDomain);
     }
 
+    /**
+     * @notice Returns the minimum fee for a given amount
+     * @param amount The amount for which to calculate the minimum fee
+     * @return The minimum fee for the given amount
+     */
+    function getMinFeeAmount(uint256 amount) external view returns (uint256) {
+        if (minFee == 0) return 0;
+
+        require(amount > 1, "Amount too low");
+        return _calcMinFeeAmount(amount);
+    }
+
     // ============ Internal Utils ============
+    /**
+     * Calculates the minimum fee amount for a given amount.
+     * @dev Amount should be constrained to be greater than 1.
+     * @dev Assumes `minFee` is non-zero.
+     * @param _amount The amount for which to calculate the minimum fee.
+     * @return The minimum fee for the given amount.
+     */
+    function _calcMinFeeAmount(
+        uint256 _amount
+    ) internal view returns (uint256) {
+        uint256 _minFeeAmount = _amount.mul(minFee) / MIN_FEE_MULTIPLIER;
+        return _minFeeAmount == 0 ? 1 : _minFeeAmount;
+    }
+
     /**
      * @notice Deposits and burns tokens from sender to be minted on destination domain.
      * Emits a `DepositForBurn` event.
@@ -308,6 +343,16 @@ contract TokenMessengerV2 is IMessageHandlerV2, BaseTokenMessenger {
         require(_mintRecipient != bytes32(0), "Mint recipient must be nonzero");
         require(_maxFee < _amount, "Max fee must be less than amount");
 
+        // Verify minimum fee
+        if (minFee > 0) {
+            // Implicitly constrains `_amount` to be greater than 1
+            // 0 < minFeeAmount <= maxFee < amount
+            require(
+                _maxFee >= _calcMinFeeAmount(_amount),
+                "Insufficient max fee"
+            );
+        }
+
         bytes32 _destinationTokenMessenger = _getRemoteTokenMessenger(
             _destinationDomain
         );

src/v2/TokenMessengerV2.sol

@@ -83,6 +83,7 @@ contract TestUtils is Test {
     address newTokenController = vm.addr(1900);
     address owner = vm.addr(1902);
     address arbitraryAddress = vm.addr(1903);
+    uint256 internal constant MIN_FEE_MULTIPLIER = 10_000_000;
 
     // See: https://github.com/foundry-rs/foundry/blob/2cdbfaca634b284084d0f86357623aef7a0d2ce3/crates/evm/core/src/constants.rs#L9
     // This address may be passed into fuzz tests by Foundry. VM.mockCalls fail when
@@ -513,4 +514,51 @@ contract TestUtils is Test {
 
         return _signaturesConcatenated;
     }
+
+    /**
+     * Returns the minimum fee amount for a given amount and minimum fee.
+     * @param _amount The amount to calculate the minimum fee for
+     * @param _minFee The minimum fee
+     * @return minFeeAmount The minimum fee amount
+     */
+    function _getMinFeeAmount(
+        uint256 _amount,
+        uint256 _minFee
+    ) internal pure returns (uint256 minFeeAmount) {
+        if (_minFee == 0) return 0;
+        minFeeAmount = (_amount * _minFee) / MIN_FEE_MULTIPLIER;
+        minFeeAmount = minFeeAmount == 0 ? 1 : minFeeAmount;
+    }
+
+    /**
+     * Helper function to prevent overflow. Takes into account no minimum fee.
+     * @param _amount The amount to bound
+     * @param _minFee The minimum fee
+     * @return The bounded amount
+     */
+    function _boundAmountForMinFee(
+        uint256 _amount,
+        uint256 _minFee
+    ) internal pure returns (uint256) {
+        return
+            bound(
+                _amount,
+                _minFee == 0 ? 1 : 2,
+                _minFee == 0 ? type(uint256).max : type(uint256).max / _minFee
+            );
+    }
+
+    /**
+     * Helper function to cause overflow. Assumes non-zero minimum fee.
+     * @param _amount The amount to bound
+     * @param _minFee The minimum fee
+     * @return The bounded amount
+     */
+    function _boundOverflowAmountForMinFee(
+        uint256 _amount,
+        uint256 _minFee
+    ) internal pure returns (uint256) {
+        return
+            bound(_amount, type(uint256).max / _minFee + 1, type(uint256).max);
+    }
 }

test/TestUtils.sol

@@ -16,6 +16,7 @@
  * limitations under the License.
  */
 pragma solidity 0.7.6;
+pragma abicoder v2;
 
 import {TokenMessengerV2} from "../../../src/v2/TokenMessengerV2.sol";