chore: improve progressive fee comments and test coverage (#7153)

Author: yorhodes

solidity/contracts/token/fees/ProgressiveFee.sol

@@ -5,24 +5,26 @@ import {BaseFee, FeeType} from "./BaseFee.sol";
 
 /**
  * @title Progressive Fee Structure
- * @dev Implements a progressive fee model where the fee percentage increases as the transfer amount increases.
+ * @dev Implements a progressive fee model where the fee percentage increases with transfer amount
+ * until reaching a peak at halfAmount, then decreases as the absolute fee approaches maxFee.
  *
  * The fee calculation uses a rational function: fee = (maxFee * amount^2) / (halfAmount^2 + amount^2)
  *
  * Key characteristics:
- * - Higher fee percentage for larger transfers
- * - Lower fee percentage for smaller transfers
- * - Fee approaches but never reaches maxFee as amount increases
+ * - Fee percentage increases for transfers below halfAmount (progressive phase)
+ * - Fee percentage peaks at halfAmount where fee = maxFee/2
+ * - Fee percentage decreases for transfers above halfAmount (regressive phase due to maxFee cap)
+ * - Absolute fee approaches but never reaches maxFee as amount increases
  * - Fee approaches 0 as amount approaches 0
-
  *
  * Example:
- * - If maxFee = 1000 and halfAmount = 1000:
- *   - Transfer of 100 wei: fee = (1000 * 100^2) / (1000^2 + 100^2) = 9.9 wei (9.9%)
- *   - Transfer of 1000 wei: fee = (1000 * 1000^2) / (1000^2 + 1000^2) = 500 wei (50%)
- *   - Transfer of 10000 wei: fee = (1000 * 10000^2) / (1000^2 + 10000^2) = 990 wei (99%)
+ * - If maxFee = 1000 and halfAmount = 10000:
+ *   - Transfer of 2000 wei: fee = (1000 * 2000^2) / (10000^2 + 2000^2) = 38.5 wei (1.92% of amount)
+ *   - Transfer of 10000 wei: fee = (1000 * 10000^2) / (10000^2 + 10000^2) = 500 wei (5% of amount)
+ *   - Transfer of 50000 wei: fee = (1000 * 50000^2) / (10000^2 + 50000^2) = 961.5 wei (1.92% of amount)
  *
- * This structure encourages smaller transactions while applying higher fees to larger transfers.
+ * This structure encourages mid-sized transfers while applying lower effective rates to both
+ * very small and very large transactions.
  */
 contract ProgressiveFee is BaseFee {
     constructor(
@@ -35,9 +37,11 @@ contract ProgressiveFee is BaseFee {
     function _quoteTransfer(
         uint256 amount
     ) internal view override returns (uint256 fee) {
+        if (amount == 0) {
+            return 0;
+        }
         uint256 amountSquared = amount ** 2;
-        uint256 denominator = halfAmount ** 2 + amountSquared;
-        return denominator == 0 ? 0 : (maxFee * amountSquared) / denominator;
+        return (maxFee * amountSquared) / (halfAmount ** 2 + amountSquared);
     }
 
     function feeType() external pure override returns (FeeType) {

solidity/contracts/token/fees/RegressiveFee.sol

@@ -5,23 +5,24 @@ import {BaseFee, FeeType} from "./BaseFee.sol";
 
 /**
  * @title Regressive Fee Structure
- * @dev Implements a regressive fee model where the fee percentage decreases as the transfer amount increases.
+ * @dev Implements a regressive fee model where the fee percentage continuously decreases as the transfer amount increases.
  *
  * The fee calculation uses a rational function: fee = (maxFee * amount) / (halfAmount + amount)
  *
  * Key characteristics:
- * - Higher fee percentage for smaller transfers
- * - Lower fee percentage for larger transfers
- * - Fee approaches maxFee as amount approaches infinity
+ * - Fee percentage continuously decreases as amount increases (regressive throughout)
+ * - At halfAmount, fee = maxFee/2 and fee percentage = maxFee/(2*halfAmount)
+ * - Absolute fee approaches but never reaches maxFee as amount approaches infinity
  * - Fee approaches 0 as amount approaches 0
  *
  * Example:
- * - If maxFee = 1000 and halfAmount = 1000:
- *   - Transfer of 100 wei: fee = (1000 * 100) / (1000 + 100) = 90.9 wei (90.9%)
- *   - Transfer of 1000 wei: fee = (1000 * 1000) / (1000 + 1000) = 500 wei (50%)
- *   - Transfer of 10000 wei: fee = (1000 * 10000) / (1000 + 10000) = 909 wei (9.09%)
+ * - If maxFee = 1000 and halfAmount = 5000:
+ *   - Transfer of 1000 wei: fee = (1000 * 1000) / (5000 + 1000) = 166.7 wei (16.67% of amount)
+ *   - Transfer of 5000 wei: fee = (1000 * 5000) / (5000 + 5000) = 500 wei (10% of amount)
+ *   - Transfer of 20000 wei: fee = (1000 * 20000) / (5000 + 20000) = 800 wei (4% of amount)
  *
- * This structure encourages larger transfers while applying higher fees to smaller transactions.
+ * This structure encourages larger transfers while discouraging smaller transactions with higher
+ * effective fee rates.
  */
 contract RegressiveFee is BaseFee {
     constructor(

solidity/test/token/Fees.t.sol

@@ -177,6 +177,81 @@ contract ProgressiveFeeTest is BaseFeeTest {
             "Progressive fee mismatch"
         );
     }
+
+    function test_ProgressiveFee_IncreasingPercentageBeforePeak() public {
+        // Test that fee percentage increases as amount increases toward halfAmount
+        ProgressiveFee localProgressiveFee = new ProgressiveFee(
+            address(token),
+            1000,
+            10000,
+            OWNER
+        );
+
+        uint256 amount1 = 2000;
+        uint256 amount2 = 5000;
+        uint256 amount3 = 10000;
+
+        uint256 fee1 = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, amount1)[0].amount;
+        uint256 fee2 = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, amount2)[0].amount;
+        uint256 fee3 = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, amount3)[0].amount;
+
+        // Calculate percentages (scaled by 1e18 for precision)
+        uint256 percentage1 = (fee1 * 1e18) / amount1;
+        uint256 percentage2 = (fee2 * 1e18) / amount2;
+        uint256 percentage3 = (fee3 * 1e18) / amount3;
+
+        // Verify percentages increase before peak
+        assertLt(percentage1, percentage2, "Percentage should increase");
+        assertLt(percentage2, percentage3, "Percentage should increase");
+    }
+
+    function test_ProgressiveFee_DecreasingPercentageAfterPeak() public {
+        // Test that fee percentage decreases as amount increases beyond halfAmount
+        ProgressiveFee localProgressiveFee = new ProgressiveFee(
+            address(token),
+            1000,
+            10000,
+            OWNER
+        );
+
+        uint256 amount1 = 10000;
+        uint256 amount2 = 20000;
+        uint256 amount3 = 50000;
+
+        uint256 fee1 = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, amount1)[0].amount;
+        uint256 fee2 = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, amount2)[0].amount;
+        uint256 fee3 = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, amount3)[0].amount;
+
+        // Calculate percentages (scaled by 1e18 for precision)
+        uint256 percentage1 = (fee1 * 1e18) / amount1;
+        uint256 percentage2 = (fee2 * 1e18) / amount2;
+        uint256 percentage3 = (fee3 * 1e18) / amount3;
+
+        // Verify percentages decrease after peak
+        assertGt(percentage1, percentage2, "Percentage should decrease");
+        assertGt(percentage2, percentage3, "Percentage should decrease");
+    }
+
+    function test_ProgressiveFee_ZeroAmount() public {
+        // Test that fee is zero when amount is zero
+        ProgressiveFee localProgressiveFee = new ProgressiveFee(
+            address(token),
+            1000,
+            10000,
+            OWNER
+        );
+
+        uint256 fee = localProgressiveFee
+        .quoteTransferRemote(destination, recipient, 0)[0].amount;
+
+        assertEq(fee, 0, "Fee should be zero for zero amount");
+    }
 }
 
 // --- RegressiveFee Tests ---
@@ -225,6 +300,36 @@ contract RegressiveFeeTest is BaseFeeTest {
             "Regressive fee mismatch"
         );
     }
+
+    function test_RegressiveFee_ContinuouslyDecreasingPercentage() public {
+        // Test that fee percentage continuously decreases as amount increases
+        RegressiveFee localRegressiveFee = new RegressiveFee(
+            address(token),
+            1000,
+            5000,
+            OWNER
+        );
+
+        uint256 amount1 = 1000;
+        uint256 amount2 = 5000;
+        uint256 amount3 = 20000;
+
+        uint256 fee1 = localRegressiveFee
+        .quoteTransferRemote(destination, recipient, amount1)[0].amount;
+        uint256 fee2 = localRegressiveFee
+        .quoteTransferRemote(destination, recipient, amount2)[0].amount;
+        uint256 fee3 = localRegressiveFee
+        .quoteTransferRemote(destination, recipient, amount3)[0].amount;
+
+        // Calculate percentages (scaled by 1e18 for precision)
+        uint256 percentage1 = (fee1 * 1e18) / amount1;
+        uint256 percentage2 = (fee2 * 1e18) / amount2;
+        uint256 percentage3 = (fee3 * 1e18) / amount3;
+
+        // Verify percentages continuously decrease
+        assertGt(percentage1, percentage2, "Percentage should decrease");
+        assertGt(percentage2, percentage3, "Percentage should decrease");
+    }
 }
 
 // --- RoutingFee Tests ---