params packing, documentation and naming update

src/contracts/CLRatePriceCapAdapter.sol

@@ -2,9 +2,10 @@
 pragma solidity ^0.8.19;
 
 import {IACLManager} from 'aave-address-book/AaveV3.sol';
-import {PriceCapAdapterBase} from './PriceCapAdapterBase.sol';
 import {IChainlinkAggregator} from 'cl-synchronicity-price-adapter/interfaces/IChainlinkAggregator.sol';
 
+import {PriceCapAdapterBase, IPriceCapAdapter} from './PriceCapAdapterBase.sol';
+
 /**
  * @title CLRatePriceCapAdapter
  * @author BGD Labs
@@ -13,40 +14,43 @@ import {IChainlinkAggregator} from 'cl-synchronicity-price-adapter/interfaces/IC
  */
 contract CLRatePriceCapAdapter is PriceCapAdapterBase {
   /**
-   * @notice Price feed for (Asset / Peg) pair
+   * @notice Ratio provider for  (Asset / PEG) pair
    */
-  IChainlinkAggregator public immutable RATE_PROVIDER;
+  IChainlinkAggregator public immutable RATIO_PROVIDER;
 
   /**
-   * @param pegToBaseAggregatorAddress the address of PEG / BASE feed
-   * @param rateProviderAddress the address of the ASSET / PEG feed
+   * @param aclManager ACL manager contract
+   * @param pegToBaseAggregatorAddress the address of (PEG / USD) feed
+   * @param ratioProviderAddress the address of the (ASSET / PEG) ratio feed
    * @param pairName name identifier
+   * @param snapshotRatio The latest exchange ratio
+   * @param snapshotTimestamp The timestamp of the latest exchange ratio
+   * @param maxYearlyRatioGrowthPercent Maximum growth of the underlying asset value per year, 100_00 is equal 100%
    */
   constructor(
     IACLManager aclManager,
     address pegToBaseAggregatorAddress,
-    address rateProviderAddress,
+    address ratioProviderAddress,
     string memory pairName,
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
-    uint16 maxYearlyRatioGrowth
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
+    uint16 maxYearlyRatioGrowthPercent
   )
     PriceCapAdapterBase(
       aclManager,
       pegToBaseAggregatorAddress,
       pairName,
-      IChainlinkAggregator(rateProviderAddress).decimals(),
+      IChainlinkAggregator(ratioProviderAddress).decimals(),
       snapshotRatio,
       snapshotTimestamp,
-      maxYearlyRatioGrowth
+      maxYearlyRatioGrowthPercent
     )
   {
-    RATE_PROVIDER = IChainlinkAggregator(rateProviderAddress);
+    RATIO_PROVIDER = IChainlinkAggregator(ratioProviderAddress);
   }
 
-  function _getRatio() internal view override returns (int256) {
-    int256 ratio = RATE_PROVIDER.latestAnswer();
-
-    return ratio;
+  /// @inheritdoc IPriceCapAdapter
+  function getRatio() public view override returns (int256) {
+    return RATIO_PROVIDER.latestAnswer();
   }
 }

src/contracts/CbETHPriceCapAdapter.sol

@@ -2,9 +2,10 @@
 pragma solidity ^0.8.19;
 
 import {IACLManager} from 'aave-address-book/AaveV3.sol';
-import {PriceCapAdapterBase} from './PriceCapAdapterBase.sol';
 import {ICbEthRateProvider} from 'cl-synchronicity-price-adapter/interfaces/ICbEthRateProvider.sol';
 
+import {PriceCapAdapterBase, IPriceCapAdapter} from './PriceCapAdapterBase.sol';
+
 /**
  * @title CbETHPriceCapAdapter
  * @author BGD Labs
@@ -13,23 +14,27 @@ import {ICbEthRateProvider} from 'cl-synchronicity-price-adapter/interfaces/ICbE
  */
 contract CbETHPriceCapAdapter is PriceCapAdapterBase {
   /**
-   * @notice rate provider for (cbETH / Base)
+   * @notice ratio provider for (cbETH / Base)
    */
-  ICbEthRateProvider public immutable RATE_PROVIDER;
+  ICbEthRateProvider public immutable RATIO_PROVIDER;
 
   /**
+   * @param aclManager ACL manager contract
    * @param cbETHToBaseAggregatorAddress the address of cbETH / BASE feed
-   * @param rateProviderAddress the address of the rate provider
+   * @param ratioProviderAddress the address of the (cbETH / ETH) ratio provider
    * @param pairName name identifier
+   * @param snapshotRatio The latest exchange ratio
+   * @param snapshotTimestamp The timestamp of the latest exchange ratio
+   * @param maxYearlyRatioGrowthPercent Maximum growth of the underlying asset value per year, 100_00 is equal 100%
    */
   constructor(
     IACLManager aclManager,
     address cbETHToBaseAggregatorAddress,
-    address rateProviderAddress,
+    address ratioProviderAddress,
     string memory pairName,
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
-    uint16 maxYearlyRatioGrowth
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
+    uint16 maxYearlyRatioGrowthPercent
   )
     PriceCapAdapterBase(
       aclManager,
@@ -38,15 +43,14 @@ contract CbETHPriceCapAdapter is PriceCapAdapterBase {
       18,
       snapshotRatio,
       snapshotTimestamp,
-      maxYearlyRatioGrowth
+      maxYearlyRatioGrowthPercent
     )
   {
-    RATE_PROVIDER = ICbEthRateProvider(rateProviderAddress);
+    RATIO_PROVIDER = ICbEthRateProvider(ratioProviderAddress);
   }
 
-  function _getRatio() internal view override returns (int256) {
-    int256 ratio = int256(RATE_PROVIDER.exchangeRate());
-
-    return ratio;
+  /// @inheritdoc IPriceCapAdapter
+  function getRatio() public view override returns (int256) {
+    return int256(RATIO_PROVIDER.exchangeRate());
   }
 }

src/contracts/MaticPriceCapAdapter.sol

@@ -2,34 +2,43 @@
 pragma solidity ^0.8.19;
 
 import {IACLManager} from 'aave-address-book/AaveV3.sol';
-import {PriceCapAdapterBase} from './PriceCapAdapterBase.sol';
 import {IMaticRateProvider} from 'cl-synchronicity-price-adapter/interfaces/IMaticRateProvider.sol';
 
+import {PriceCapAdapterBase, IPriceCapAdapter} from './PriceCapAdapterBase.sol';
+
+// TODO: compare MaticX and stMATIC implementations, and take actions based on that
+
+// TODO: should I use MaticX reference everywhere, or it's more generic?
+// TODO: also title and contract name maybe MaticXPriceCapAdapter?
 /**
  * @title MaticPriceCapAdapter
  * @author BGD Labs
- * @notice Price capped adapter to calculate price of (lst matic / USD) pair by using
- * @notice Chainlink data feed for (MATIC / USD) and (liquid staked matic / MATIC) ratio.
+ * @notice Price capped adapter to calculate price of (MaticX / USD) pair by using
+ * @notice Chainlink data feed for (MATIC / USD) and (MaticX / MATIC) ratio.
  */
 contract MaticPriceCapAdapter is PriceCapAdapterBase {
   /**
-   * @notice Price feed for (MATIC / Base) pair
+   * @notice Ratio provider for  (MaticX / MATIC) pair
    */
-  IMaticRateProvider public immutable RATE_PROVIDER;
+  IMaticRateProvider public immutable RATIO_PROVIDER;
 
   /**
-   * @param maticToBaseAggregatorAddress the address of cbETH / BASE feed
-   * @param rateProviderAddress the address of the rETH token
+   * @param aclManager ACL manager contract
+   * @param maticToBaseAggregatorAddress the address of MaticX / USD feed
+   * @param ratioProviderAddress the address of the MaticX token
    * @param pairName name identifier
+   * @param snapshotRatio The latest exchange ratio
+   * @param snapshotTimestamp The timestamp of the latest exchange ratio
+   * @param maxYearlyRatioGrowthPercent Maximum growth of the underlying asset value per year, 100_00 is equal 100%
    */
   constructor(
     IACLManager aclManager,
     address maticToBaseAggregatorAddress,
-    address rateProviderAddress,
-    string memory pairName,
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
-    uint16 maxYearlyRatioGrowth
+    address ratioProviderAddress,
+    string memory pairName, // TODO: does it make any sense, or I can just hardcode it with MaticX/MATIC
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
+    uint16 maxYearlyRatioGrowthPercent
   )
     PriceCapAdapterBase(
       aclManager,
@@ -38,15 +47,14 @@ contract MaticPriceCapAdapter is PriceCapAdapterBase {
       18,
       snapshotRatio,
       snapshotTimestamp,
-      maxYearlyRatioGrowth
+      maxYearlyRatioGrowthPercent
     )
   {
-    RATE_PROVIDER = IMaticRateProvider(rateProviderAddress);
+    RATIO_PROVIDER = IMaticRateProvider(ratioProviderAddress);
   }
 
-  function _getRatio() internal view override returns (int256) {
-    int256 ratio = int256(RATE_PROVIDER.getRate());
-
-    return ratio;
+  /// @inheritdoc IPriceCapAdapter
+  function getRatio() public view override returns (int256) {
+    return int256(RATIO_PROVIDER.getRate());
   }
 }

src/contracts/PriceCapAdapterBase.sol

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BUSL-1.1
 pragma solidity ^0.8.19;
 
-import {PercentageMath} from 'aave-v3-core/contracts/protocol/libraries/math/PercentageMath.sol';
 import {IACLManager} from 'aave-address-book/AaveV3.sol';
 
 import {IChainlinkAggregator} from 'cl-synchronicity-price-adapter/interfaces/IChainlinkAggregator.sol';
@@ -13,7 +12,8 @@ import {IPriceCapAdapter, ICLSynchronicityPriceAdapter} from '../interfaces/IPri
  * @notice Price adapter to cap the price of the underlying asset.
  */
 abstract contract PriceCapAdapterBase is IPriceCapAdapter {
-  using PercentageMath for uint256;
+  // Maximum percentage factor (100.00%)
+  uint256 internal constant PERCENTAGE_FACTOR = 1e4;
 
   /// @inheritdoc IPriceCapAdapter
   uint256 public constant SECONDS_PER_YEAR = 365 days;
@@ -38,29 +38,34 @@ abstract contract PriceCapAdapterBase is IPriceCapAdapter {
   /**
    * @notice Ratio at the time of snapshot
    */
-  uint256 private _snapshotRatio;
+  uint104 private _snapshotRatio;
 
   /**
    * @notice Timestamp at the time of snapshot
    */
-  uint256 private _snapshotTimestamp;
+  uint48 private _snapshotTimestamp;
 
   /**
    * @notice Ratio growth per second
    */
-  uint256 private _maxRatioGrowthPerSecond;
+  uint104 private _maxRatioGrowthPerSecond;
 
   /**
-   * @param baseAggregatorAddress the address of BASE_CURRENCY / USD feed
-   * @param pairDescription description
+   * @param aclManager ACL manager contract
+   * @param baseAggregatorAddress The address of BASE_CURRENCY / USD price feed
+   * @param pairDescription The capped asset to underlying pair description
+   * @param ratioDecimals The number of decimal places of the capped asset to underlying ratio
+   * @param snapshotRatio The latest exchange ratio
+   * @param snapshotTimestamp The timestamp of the latest exchange ratio
+   * @param maxYearlyRatioGrowthPercent Maximum growth of the underlying asset value per year, 100_00 is equal 100%
    */
   constructor(
     IACLManager aclManager,
     address baseAggregatorAddress,
     string memory pairDescription,
     uint8 ratioDecimals,
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
     uint16 maxYearlyRatioGrowthPercent
   ) {
     ACL_MANAGER = aclManager;
@@ -100,8 +105,8 @@ abstract contract PriceCapAdapterBase is IPriceCapAdapter {
 
   /// @inheritdoc IPriceCapAdapter
   function setCapParameters(
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
     uint16 maxYearlyRatioGrowthPercent
   ) external {
     if (!ACL_MANAGER.isRiskAdmin(msg.sender)) {
@@ -113,8 +118,8 @@ abstract contract PriceCapAdapterBase is IPriceCapAdapter {
 
   /// @inheritdoc ICLSynchronicityPriceAdapter
   function latestAnswer() external view override returns (int256) {
-    // get the current ratio
-    int256 currentRatio = _getRatio();
+    // get the current lst to underlying ratio
+    int256 currentRatio = getRatio();
 
     // calculate the ratio based on snapshot ratio and max growth rate
     int256 maxRatio = int256(
@@ -135,8 +140,8 @@ abstract contract PriceCapAdapterBase is IPriceCapAdapter {
   }
 
   function _setCapParameters(
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
     uint16 maxYearlyRatioGrowthPercent
   ) internal {
     if (snapshotRatio == 0) {
@@ -145,9 +150,9 @@ abstract contract PriceCapAdapterBase is IPriceCapAdapter {
     _snapshotRatio = snapshotRatio;
     _snapshotTimestamp = snapshotTimestamp;
 
-    _maxRatioGrowthPerSecond =
-      (_snapshotRatio.percentMul(maxYearlyRatioGrowthPercent)) /
-      (SECONDS_PER_YEAR);
+    _maxRatioGrowthPerSecond = uint104(
+      (_snapshotRatio * maxYearlyRatioGrowthPercent) / PERCENTAGE_FACTOR / SECONDS_PER_YEAR
+    );
 
     emit CapParametersUpdated(
       snapshotRatio,
@@ -157,8 +162,6 @@ abstract contract PriceCapAdapterBase is IPriceCapAdapter {
     );
   }
 
-  /**
-   * @notice Returns the current exchange ratio to the underlying(base) asset
-   */
-  function _getRatio() internal view virtual returns (int256);
+  /// @inheritdoc IPriceCapAdapter
+  function getRatio() public view virtual returns (int256); // TODO: make it public?
 }

src/contracts/RETHPriceCapAdapter.sol

@@ -2,9 +2,10 @@
 pragma solidity ^0.8.19;
 
 import {IACLManager} from 'aave-address-book/AaveV3.sol';
-import {PriceCapAdapterBase} from './PriceCapAdapterBase.sol';
 import {IrETH} from 'cl-synchronicity-price-adapter/interfaces/IrETH.sol';
 
+import {PriceCapAdapterBase, IPriceCapAdapter} from './PriceCapAdapterBase.sol';
+
 /**
  * @title RETHPriceCapAdapter
  * @author BGD Labs
@@ -18,18 +19,22 @@ contract RETHPriceCapAdapter is PriceCapAdapterBase {
   IrETH public immutable RETH;
 
   /**
-   * @param rETHToBaseAggregatorAddress the address of cbETH / BASE feed
-   * @param rethAddress the address of the rETH token
+   * @param aclManager ACL manager contract
+   * @param rETHToBaseAggregatorAddress the address of (rETH / USD) feed
+   * @param rETHAddress the address of the rETH token, the (rETH / ETH) ratio feed
    * @param pairName name identifier
+   * @param snapshotRatio The latest exchange ratio
+   * @param snapshotTimestamp The timestamp of the latest exchange ratio
+   * @param maxYearlyRatioGrowthPercent Maximum growth of the underlying asset value per year, 100_00 is equal 100%
    */
   constructor(
     IACLManager aclManager,
     address rETHToBaseAggregatorAddress,
-    address rethAddress,
+    address rETHAddress,
     string memory pairName,
-    uint256 snapshotRatio,
-    uint256 snapshotTimestamp,
-    uint16 maxYearlyRatioGrowth
+    uint104 snapshotRatio,
+    uint48 snapshotTimestamp,
+    uint16 maxYearlyRatioGrowthPercent
   )
     PriceCapAdapterBase(
       aclManager,
@@ -38,15 +43,14 @@ contract RETHPriceCapAdapter is PriceCapAdapterBase {
       18,
       snapshotRatio,
       snapshotTimestamp,
-      maxYearlyRatioGrowth
+      maxYearlyRatioGrowthPercent
     )
   {
-    RETH = IrETH(rethAddress);
+    RETH = IrETH(rETHAddress);
   }
 
-  function _getRatio() internal view override returns (int256) {
-    int256 ratio = int256(RETH.getExchangeRate());
-
-    return ratio;
+  /// @inheritdoc IPriceCapAdapter
+  function getRatio() public view override returns (int256) {
+    return int256(RETH.getExchangeRate());
   }
 }