[feat] adjust additionalGasUsed calculation + gas measurement docs

foundry.toml

@@ -8,5 +8,6 @@ build_info = true
 extra_output = ["storageLayout"]
 evm_version = 'shanghai'
 solc_version = '0.8.28'
+block_gas_limit = 2000000000
 
 # See more config options https://github.com/foundry-rs/foundry/tree/master/config

script/SetupGasPriceTunnelRouter.s.sol

@@ -67,6 +67,7 @@ contract Executor is Script {
                     IVault(proxyVaultAddr),
                     msg.sender,
                     100000,
+                    14000,
                     300000,
                     gasPrice,
                     keccak256(bytes(sourceChainId)),

script/SetupPriorityFeeTunnelRouter.s.sol

@@ -67,6 +67,7 @@ contract Executor is Script {
                     IVault(proxyVaultAddr),
                     msg.sender,
                     100000,
+                    14000,
                     300000,
                     priorityFee,
                     keccak256(bytes(sourceChainId)),

src/interfaces/ITunnelRouter.sol

@@ -34,14 +34,6 @@ interface ITunnelRouter {
      */
     event CallbackGasLimitSet(uint256 callbackGasLimit);
 
-    /**
-     * @notice Emitted when the additional gas used is set.
-     *
-     * @param additionalGasUsed The additional gas estimated for relaying the message;
-     * does not include the gas cost for executing the target contract.
-     */
-    event AdditionalGasUsedSet(uint256 additionalGasUsed);
-
     /**
      * @notice Emitted after the message is relayed to the target contract
      * to indicate the result of the process.

src/router/BaseTunnelRouter.sol

@@ -16,23 +16,20 @@ import "../libraries/PacketDecoder.sol";
 import "../libraries/Originator.sol";
 
 import "./ErrorHandler.sol";
+import "./L1RouterGasCalculator.sol";
 
 abstract contract BaseTunnelRouter is
-    Initializable,
-    Ownable2StepUpgradeable,
     PausableUpgradeable,
     AccessControlUpgradeable,
     ITunnelRouter,
-    ErrorHandler
+    ErrorHandler,
+    L1RouterGasCalculator
 {
     using PacketDecoder for bytes;
 
     ITssVerifier public tssVerifier;
     IVault public vault;
 
-    // Additional gas estimated for relaying the message;
-    // does not include the gas cost for executing the target contract.
-    uint256 public additionalGasUsed;
     // The maximum gas limit can be used when calling the target contract.
     uint256 public callbackGasLimit;
     // The hash of the source chain ID.
@@ -60,7 +57,8 @@ abstract contract BaseTunnelRouter is
         ITssVerifier tssVerifier_,
         IVault vault_,
         address initialOwner,
-        uint256 additionalGasUsed_,
+        uint256 packedAdditionalGasFuncCoeffs,
+        uint256 maxCalldataBytes_,
         uint256 callbackGasLimit_,
         bytes32 sourceChainIdHash_,
         bytes32 targetChainIdHash_
@@ -71,24 +69,27 @@ abstract contract BaseTunnelRouter is
         __AccessControl_init();
         _grantRole(DEFAULT_ADMIN_ROLE, initialOwner);
         _grantRole(GAS_FEE_UPDATER_ROLE, initialOwner);
+        __L1RouterGasCalculator_init(
+            packedAdditionalGasFuncCoeffs,
+            maxCalldataBytes_
+        ); // UPDATED
 
         tssVerifier = tssVerifier_;
         vault = vault_;
         sourceChainIdHash = sourceChainIdHash_;
         targetChainIdHash = targetChainIdHash_;
 
-        _setAdditionalGasUsed(additionalGasUsed_);
         _setCallbackGasLimit(callbackGasLimit_);
     }
 
     /**
-     * @dev Sets the additionalGasUsed being used in relaying message.
-     * @param additionalGasUsed_ The new additional gas used amount.
+     * @dev Sets the packedCoeffs being used in relaying message.
+     * @param packedCoeffs The new packed value [c2|c1|c0] (fixed-point 1e18 lanes).
      */
-    function setAdditionalGasUsed(
-        uint256 additionalGasUsed_
+    function setPackedAdditionalGasFuncCoeffs(
+        uint256 packedCoeffs
     ) external onlyOwner {
-        _setAdditionalGasUsed(additionalGasUsed_);
+        _setPackedAdditionalGasFuncCoeffs(packedCoeffs);
     }
 
     /**
@@ -141,6 +142,9 @@ abstract contract BaseTunnelRouter is
             revert InvalidSequence(tunnelDetail.sequence + 1, packet.sequence);
         }
 
+        // update the sequence.
+        tunnelDetails[originatorHash_].sequence = packet.sequence;
+
         // verify signature.
         bool isValid = tssVerifier.verify(
             keccak256(message),
@@ -151,21 +155,25 @@ abstract contract BaseTunnelRouter is
             revert InvalidSignature();
         }
 
-        // update the sequence.
-        tunnelDetails[originatorHash_].sequence = packet.sequence;
-
         // forward the message to the target contract.
-        uint256 gasLeft = gasleft();
+        uint256 beginGasleft = gasleft();
         (bool isSuccess, ) = _callWithCustomErrorHandling(
             tunnelDetail.targetAddr,
             callbackGasLimit,
             abi.encodeWithSelector(IPacketConsumer.process.selector, tssMessage)
         );
+        uint256 targetGasUsed = beginGasleft - gasleft();
 
         emit MessageProcessed(originatorHash_, packet.sequence, isSuccess);
 
         // charge a fee from the target contract and send to caller.
-        uint256 fee = _routerFee(gasLeft - gasleft() + additionalGasUsed);
+        uint256 calldataSize;
+        assembly {
+            calldataSize := calldatasize()
+        }
+        uint256 fee = _routerFee(
+            targetGasUsed + _additionalGasForCalldata(calldataSize)
+        );
         vault.collectFee(originatorHash_, msg.sender, fee);
 
         // deactivate the target contract if the remaining balance is under the threshold.
@@ -222,7 +230,10 @@ abstract contract BaseTunnelRouter is
      * @dev See {ITunnelRouter-minimumBalanceThreshold}.
      */
     function minimumBalanceThreshold() public view override returns (uint256) {
-        return _routerFee(additionalGasUsed + callbackGasLimit);
+        return
+            _routerFee(
+                callbackGasLimit + _additionalGasForCalldata(maxCalldataBytes)
+            );
     }
 
     /**
@@ -349,12 +360,6 @@ abstract contract BaseTunnelRouter is
         emit CallbackGasLimitSet(callbackGasLimit_);
     }
 
-    /// @dev Sets additionalGasUsed and emit an event.
-    function _setAdditionalGasUsed(uint256 additionalGasUsed_) internal {
-        additionalGasUsed = additionalGasUsed_;
-        emit AdditionalGasUsedSet(additionalGasUsed_);
-    }
-
     /// @dev Grants `GAS_FEE_UPDATER_ROLE` to `accounts`
     function grantGasFeeUpdater(address[] calldata accounts) external onlyRole(DEFAULT_ADMIN_ROLE) {
         for (uint256 i = 0; i < accounts.length; i++) {

src/router/GasPriceTunnelRouter.sol

@@ -19,7 +19,8 @@ contract GasPriceTunnelRouter is BaseTunnelRouter {
         ITssVerifier tssVerifier_,
         IVault vault_,
         address initialOwner,
-        uint256 additionalGas_,
+        uint256 packedAdditionalGasFuncCoeffs,
+        uint256 maxCalldataBytes_,
         uint256 callbackGasLimit_,
         uint256 gasPrice_,
         bytes32 sourceChainIdHash_,
@@ -29,7 +30,8 @@ contract GasPriceTunnelRouter is BaseTunnelRouter {
             tssVerifier_,
             vault_,
             initialOwner,
-            additionalGas_,
+            packedAdditionalGasFuncCoeffs,
+            maxCalldataBytes_,
             callbackGasLimit_,
             sourceChainIdHash_,
             targetChainIdHash_
@@ -51,7 +53,9 @@ contract GasPriceTunnelRouter is BaseTunnelRouter {
         emit SetGasFee(gasFee_);
     }
 
-    function _routerFee(uint256 gasUsed) internal view virtual override returns (uint256) {
+    function _routerFee(
+        uint256 gasUsed
+    ) internal view virtual override returns (uint256) {
         uint256 effectiveGasPrice = Math.min(tx.gasprice, gasFee.gasPrice);
         return effectiveGasPrice * gasUsed;
     }

src/router/L1RouterGasCalculator.sol

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
+
+/**
+ * @title L1RouterGasCalculator
+ * @notice Owns and evaluates a quadratic model for base gas as a function of calldata size.
+ *
+ * packedAdditionalGasFuncCoeffs layout (fixed-point 1e18):
+ *   packed = [ c2 | c1 | c0 ], each ci is uint80 (0..2^80-1) representing ci/1e18
+ *
+ * f(x) = (c2*x^2 + c1*x + c0) / 1e18, where x = calldata size in bytes.
+ *
+ */
+abstract contract L1RouterGasCalculator is
+    Initializable,
+    Ownable2StepUpgradeable
+{
+    // ----- packing constants -----
+    uint256 internal constant COEFF_BITS = 80;
+    uint256 internal constant COEFF_MASK = (uint256(1) << COEFF_BITS) - 1;
+    uint256 internal constant FP_SCALE = 1e18;
+    uint256 internal constant SHIFT_C1 = COEFF_BITS;
+    uint256 internal constant SHIFT_C2 = COEFF_BITS * 2;
+
+    /// @dev packed coefficients: [c2 (80b) | c1 (80b) | c0 (80b)]
+    uint256 public packedAdditionalGasFuncCoeffs;
+
+    /// @dev maximum calldata length (bytes) the model will accept.
+    uint256 public maxCalldataBytes;
+
+    /**
+     * @notice Emitted when the packed coefficients are updated.
+     * @param packedCoeffs The new packed value [c2|c1|c0] (fixed-point 1e18 lanes).
+     */
+    event PackedAdditionalGasFuncCoeffsSet(uint256 packedCoeffs);
+
+    /**
+     * @notice Emitted when the maximum supported calldata length is updated.
+     * @param maxBytes New maximum calldata bytes accepted by the model.
+     */
+    event MaxCalldataBytesSet(uint256 maxBytes);
+
+    error CoefficientOutOfRange(); // any ci > 2^80-1
+    error CalldataSizeTooLarge(uint256 got, uint256 maxAllowed);
+
+    function __L1RouterGasCalculator_init(
+        uint256 packedCoeffs,
+        uint256 maxBytes
+    ) internal onlyInitializing {
+        _setPackedAdditionalGasFuncCoeffs(packedCoeffs);
+        _setMaxCalldataBytes(maxBytes);
+    }
+
+    /// @notice Pack 3×80-bit fixed-point (1e18) coefficients into one uint256.
+    function packCoeffs(
+        uint256 c2,
+        uint256 c1,
+        uint256 c0
+    ) public pure returns (uint256 packedCoeffs) {
+        if (c2 > COEFF_MASK || c1 > COEFF_MASK || c0 > COEFF_MASK) {
+            revert CoefficientOutOfRange();
+        }
+        unchecked {
+            packedCoeffs = (c2 << SHIFT_C2) | (c1 << SHIFT_C1) | c0;
+        }
+    }
+
+    /// @notice Unpack a provided packed value into its (c2, c1, c0) lanes.
+    function unpackCoeffs(
+        uint256 packedCoeffs
+    ) public pure returns (uint256 c2, uint256 c1, uint256 c0) {
+        unchecked {
+            c2 = (packedCoeffs >> SHIFT_C2) & COEFF_MASK;
+            c1 = (packedCoeffs >> SHIFT_C1) & COEFF_MASK;
+            c0 = packedCoeffs & COEFF_MASK;
+        }
+    }
+
+    /// @notice View the currently stored coefficients.
+    function currentCoeffs()
+        public
+        view
+        returns (uint256 c2, uint256 c1, uint256 c0)
+    {
+        return unpackCoeffs(packedAdditionalGasFuncCoeffs);
+    }
+
+    /// @dev Store a new packed coefficient triple and emit.
+    function _setPackedAdditionalGasFuncCoeffs(uint256 packedCoeffs) internal {
+        packedAdditionalGasFuncCoeffs = packedCoeffs;
+        emit PackedAdditionalGasFuncCoeffsSet(packedCoeffs);
+    }
+
+    /// @notice Owner: set the maximum accepted calldata bytes.
+    function setMaxCalldataBytes(uint256 maxBytes) external onlyOwner {
+        _setMaxCalldataBytes(maxBytes);
+    }
+
+    /// @dev Internal setter with event.
+    function _setMaxCalldataBytes(uint256 maxBytes) internal {
+        maxCalldataBytes = maxBytes;
+        emit MaxCalldataBytesSet(maxBytes);
+    }
+
+    /**
+     * @dev Evaluate baseGas(x) in *gas units* for a calldata length `x` (bytes).
+     *      Reverts if `x` exceeds `maxCalldataBytes`.
+     *      Returns the quadratic (c2*x^2 + c1*x + c0)/1e18 using the stored coefficients.
+     *
+     * @param x Calldata size in bytes (i.e., `calldatasize()` when called from a router).
+     */
+    function _additionalGasForCalldata(
+        uint256 x
+    ) internal view returns (uint256 y) {
+        if (x > maxCalldataBytes)
+            revert CalldataSizeTooLarge(x, maxCalldataBytes);
+        (uint256 c2, uint256 c1, uint256 c0) = unpackCoeffs(
+            packedAdditionalGasFuncCoeffs
+        );
+        unchecked {
+            y = (c2 * x * x + c1 * x + c0) / FP_SCALE;
+        }
+    }
+
+    /// @notice Public preview of baseGas(x) using the stored coefficients.
+    function additionalGasForCalldata(
+        uint256 x
+    ) external view returns (uint256 y) {
+        return _additionalGasForCalldata(x);
+    }
+}

src/router/PriorityFeeTunnelRouter.sol

@@ -18,7 +18,8 @@ contract PriorityFeeTunnelRouter is BaseTunnelRouter {
         ITssVerifier tssVerifier_,
         IVault vault_,
         address initialOwner,
-        uint256 additionalGas_,
+        uint256 packedAdditionalGasFuncCoeffs,
+        uint256 maxCalldataBytes_,
         uint256 callbackGasLimit_,
         uint256 priorityFee_,
         bytes32 sourceChainIdHash_,
@@ -28,7 +29,8 @@ contract PriorityFeeTunnelRouter is BaseTunnelRouter {
             tssVerifier_,
             vault_,
             initialOwner,
-            additionalGas_,
+            packedAdditionalGasFuncCoeffs,
+            maxCalldataBytes_,
             callbackGasLimit_,
             sourceChainIdHash_,
             targetChainIdHash_
@@ -50,8 +52,13 @@ contract PriorityFeeTunnelRouter is BaseTunnelRouter {
         emit SetGasFee(gasFee_);
     }
 
-    function _routerFee(uint256 gasUsed) internal view virtual override returns (uint256) {
-        uint256 effectiveGasPrice = Math.min(tx.gasprice, gasFee.priorityFee + block.basefee);
+    function _routerFee(
+        uint256 gasUsed
+    ) internal view virtual override returns (uint256) {
+        uint256 effectiveGasPrice = Math.min(
+            tx.gasprice,
+            gasFee.priorityFee + block.basefee
+        );
         return effectiveGasPrice * gasUsed;
     }
 }

test/PacketConsumer.t.sol

@@ -332,7 +332,8 @@ contract PacketConsumerTest is Test, Constants {
             tssVerifier,
             vault,
             address(this),
-            75000,
+            75000 * 1e18,
+            14000,
             50000,
             1,
             0x0e1ac2c4a50a82aa49717691fc1ae2e5fa68eff45bd8576b0f2be7a0850fa7c6,

test/PacketConsumerMultipleTunnel.t.sol

@@ -31,6 +31,7 @@ contract PacketConsumerMultipleTunnelTest is Test, Constants {
             vault,
             address(this),
             75000,
+            14000,
             100000,
             1,
             keccak256("bandchain"),