fix: CCTP v2 external fee quoting (#7148)

Author: yorhodes

solidity/contracts/token/TokenBridgeCctpBase.sol

@@ -16,6 +16,7 @@ import {IMessageHandler} from "../interfaces/cctp/IMessageHandler.sol";
 import {TypeCasts} from "../libs/TypeCasts.sol";
 import {MovableCollateralRouter, MovableCollateralRouterStorage} from "./libs/MovableCollateralRouter.sol";
 import {TokenRouter} from "./libs/TokenRouter.sol";
+import {AbstractPostDispatchHook} from "../hooks/libs/AbstractPostDispatchHook.sol";
 
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
@@ -38,7 +39,7 @@ abstract contract TokenBridgeCctpBaseStorage is TokenRouter {
 abstract contract TokenBridgeCctpBase is
     TokenBridgeCctpBaseStorage,
     AbstractCcipReadIsm,
-    IPostDispatchHook
+    AbstractPostDispatchHook
 {
     using Message for bytes;
     using TypeCasts for bytes32;
@@ -284,26 +285,19 @@ abstract contract TokenBridgeCctpBase is
         return uint8(IPostDispatchHook.HookTypes.CCTP);
     }
 
-    /// @inheritdoc IPostDispatchHook
-    function supportsMetadata(
-        bytes calldata /*metadata*/
-    ) public pure override returns (bool) {
-        return true;
-    }
-
-    /// @inheritdoc IPostDispatchHook
-    function quoteDispatch(
-        bytes calldata,
-        bytes calldata
-    ) external pure override returns (uint256) {
+    /// @inheritdoc AbstractPostDispatchHook
+    function _quoteDispatch(
+        bytes calldata /*metadata*/,
+        bytes calldata /*message*/
+    ) internal pure override returns (uint256) {
         return 0;
     }
 
-    /// @inheritdoc IPostDispatchHook
-    function postDispatch(
-        bytes calldata /*metadata*/,
+    /// @inheritdoc AbstractPostDispatchHook
+    function _postDispatch(
+        bytes calldata metadata,
         bytes calldata message
-    ) external payable override {
+    ) internal override {
         bytes32 id = message.id();
         require(_isLatestDispatched(id), "Message not dispatched");
 
@@ -312,6 +306,8 @@ abstract contract TokenBridgeCctpBase is
         uint32 circleDestination = hyperlaneDomainToCircleDomain(destination);
 
         _sendMessageIdToIsm(circleDestination, ism, id);
+
+        _refund(metadata, message, address(this).balance);
     }
 
     /**

solidity/contracts/token/TokenBridgeCctpV2.sol

@@ -43,6 +43,7 @@ contract TokenBridgeCctpV2 is TokenBridgeCctpBase, IMessageHandlerV2 {
             _tokenMessenger
         )
     {
+        require(_maxFeeBps < 10_000, "maxFeeBps must be less than 100%");
         maxFeeBps = _maxFeeBps;
         minFinalityThreshold = _minFinalityThreshold;
     }
@@ -52,13 +53,34 @@ contract TokenBridgeCctpV2 is TokenBridgeCctpBase, IMessageHandlerV2 {
     /**
      * @inheritdoc TokenRouter
      * @dev Overrides to indicate v2 fees.
+     *
+     * Hyperlane uses a "minimum amount out" approach where users specify the exact amount
+     * they want the recipient to receive on the destination chain. This provides a better
+     * UX by guaranteeing predictable outcomes regardless of underlying bridge fee structures.
+     *
+     * However, some underlying bridges like CCTP charge fees as a percentage of the input
+     * amount (amountIn), not the output amount. This requires "reversing" the fee calculation:
+     * we need to determine what input amount (after fees are deducted) will result in the
+     * desired output amount reaching the recipient.
+     *
+     * The formula solves for the fee needed such that after Circle takes their percentage,
+     * the recipient receives exactly `amount`:
+     *
+     *   (amount + fee) * (10_000 - maxFeeBps) / 10_000 = amount
+     *
+     * Solving for fee:
+     *   fee = (amount * maxFeeBps) / (10_000 - maxFeeBps)
+     *
+     * Example: If amount = 100 USDC and maxFeeBps = 10 (0.1%):
+     *   fee = (100 * 10) / (10_000 - 10) = 1000 / 9990 ≈ 0.1001 USDC
+     *   We deposit 100.1001 USDC, Circle takes 0.1001 USDC, recipient gets exactly 100 USDC.
      */
     function _externalFeeAmount(
         uint32,
         bytes32,
         uint256 amount
     ) internal view override returns (uint256 feeAmount) {
-        return (amount * maxFeeBps) / 10_000;
+        return (amount * maxFeeBps) / (10_000 - maxFeeBps);
     }
 
     function _getCCTPVersion() internal pure override returns (uint32) {

solidity/test/token/TokenBridgeCctp.t.sol

@@ -32,6 +32,8 @@ import {IMailbox} from "../../contracts/interfaces/IMailbox.sol";
 import {ISpecifiesInterchainSecurityModule} from "../../contracts/interfaces/IInterchainSecurityModule.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {LinearFee} from "../../contracts/token/fees/LinearFee.sol";
+import {IPostDispatchHook} from "../../contracts/interfaces/hooks/IPostDispatchHook.sol";
+import {StandardHookMetadata} from "../../contracts/hooks/libs/StandardHookMetadata.sol";
 
 contract TokenBridgeCctpV1Test is Test {
     using TypeCasts for address;
@@ -670,6 +672,9 @@ contract TokenBridgeCctpV1Test is Test {
         assertEq(actualId, id);
     }
 
+    // needed for hook refunds
+    receive() external payable {}
+
     function testFork_postDispatch(
         bytes32 recipient,
         bytes calldata body
@@ -778,6 +783,53 @@ contract TokenBridgeCctpV1Test is Test {
         tbOrigin.postDispatch(bytes(""), message);
     }
 
+    function test_hookType() public {
+        assertEq(tbOrigin.hookType(), uint8(IPostDispatchHook.HookTypes.CCTP));
+    }
+
+    function test_supportsMetadata() public {
+        assertEq(tbOrigin.supportsMetadata(bytes("")), true);
+        assertEq(
+            tbOrigin.supportsMetadata(
+                StandardHookMetadata.format(0, 100_000, address(this))
+            ),
+            true
+        );
+    }
+
+    function test_quoteDispatch() public {
+        assertEq(tbOrigin.quoteDispatch(bytes(""), bytes("")), 0);
+    }
+
+    function test_postDispatch_refundsExcessValue(
+        bytes32 recipient,
+        bytes calldata body
+    ) public virtual {
+        address refundAddress = makeAddr("refundAddress");
+        uint256 refundBalanceBefore = refundAddress.balance;
+
+        // Create metadata with refund address using standard hook metadata format
+        bytes memory metadata = abi.encodePacked(
+            uint16(1), // variant
+            uint256(0), // msgValue
+            uint256(0), // gasLimit
+            refundAddress // refundAddress
+        );
+
+        uint256 excessValue = 1 ether;
+
+        mailboxOrigin.dispatch{value: excessValue}(
+            destination,
+            recipient,
+            body,
+            metadata,
+            tbOrigin
+        );
+
+        // Verify refund was sent
+        assertEq(refundAddress.balance, refundBalanceBefore + excessValue);
+    }
+
     function test_verify_hookMessage(bytes calldata body) public {
         TestRecipient recipient = new TestRecipient();
         recipient.setInterchainSecurityModule(address(tbDestination));
@@ -964,7 +1016,7 @@ contract TokenBridgeCctpV2Test is TokenBridgeCctpV1Test {
             version,
             address(tokenOrigin).addressToBytes32(),
             recipient,
-            amount + (amount * maxFee) / 10_000,
+            amount + (amount * maxFee) / (10_000 - maxFee),
             sender.addressToBytes32(),
             maxFee,
             bytes("")
@@ -1401,7 +1453,7 @@ contract TokenBridgeCctpV2Test is TokenBridgeCctpV1Test {
         );
         assertEq(quotes[1].token, address(tokenOrigin));
         assertEq(quotes[1].amount, amount);
-        uint256 fastFee = (amount * maxFee) / 10_000;
+        uint256 fastFee = (amount * maxFee) / (10_000 - maxFee);
         assertEq(quotes[2].token, address(tokenOrigin));
         assertEq(quotes[2].amount, fastFee);
     }