@venusprotocol/protocol-reserve 1.0.0-converters.1

package/contracts/TokenConverter/RiskFundConverter.sol

@@ -0,0 +1,436 @@
+// SPDX-License-Identifier: BSD-3-Clause
+pragma solidity 0.8.13;
+
+import { SafeERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol";
+import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
+import { ResilientOracle } from "@venusprotocol/oracle/contracts/ResilientOracle.sol";
+
+import { AbstractTokenConverter } from "./AbstractTokenConverter.sol";
+import { ensureNonzeroAddress, ensureNonzeroValue } from "../Utils/Validators.sol";
+import { IPoolRegistry } from "../Interfaces/IPoolRegistry.sol";
+import { IComptroller } from "../Interfaces/IComptroller.sol";
+import { IRiskFund, IRiskFundGetters } from "../Interfaces/IRiskFund.sol";
+import { IVToken } from "../Interfaces/IVToken.sol";
+
+/// @title RiskFundConverter
+/// @author Venus
+/// @notice RiskFundConverter used for token conversions and sends received token to RiskFund
+/// @custom:security-contact https://github.com/VenusProtocol/protocol-reserve#discussion
+contract RiskFundConverter is AbstractTokenConverter {
+    using SafeERC20Upgradeable for IERC20Upgradeable;
+
+    /// @notice Address of the core pool comptroller
+    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
+    address public immutable CORE_POOL_COMPTROLLER;
+
+    ///@notice Address of the vBNB
+    ///@dev This address is used to include the BNB market while in getPools method
+    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
+    address public immutable VBNB;
+
+    ///@notice Address of the native wrapped currency
+    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
+    address public immutable NATIVE_WRAPPED;
+
+    /// @notice Store the previous state for the asset transferred to ProtocolShareReserve combined(for all pools)
+    mapping(address => uint256) internal assetsReserves;
+
+    /// @notice Store the asset's reserve per pool in the ProtocolShareReserve
+    /// @dev Comptroller(pool) -> Asset -> amount
+    mapping(address => mapping(address => uint256)) internal poolsAssetsReserves;
+
+    /// @notice Address of pool registry contract
+    address public poolRegistry;
+
+    /// @notice The mapping contains the assets for each pool which are sent to RiskFund directly
+    /// @dev Comptroller(pool) -> Asset -> bool(should transfer directly on true)
+    mapping(address => mapping(address => bool)) public poolsAssetsDirectTransfer;
+
+    /// @notice Emitted when pool registry address is updated
+    event PoolRegistryUpdated(address indexed oldPoolRegistry, address indexed newPoolRegistry);
+
+    /// @notice Emitted after updating of the assets reserves
+    /// amount -> reserve increased by amount
+    event AssetsReservesUpdated(address indexed comptroller, address indexed asset, uint256 amount);
+
+    /// @notice Emmitted after the funds transferred to the destination address
+    event AssetTransferredToDestination(address indexed comptroller, address indexed asset, uint256 amount);
+
+    /// @notice Emitted after the poolsAssetsDirectTransfer mapping is updated
+    event PoolAssetsDirectTransferUpdated(address indexed comptroller, address indexed asset, bool value);
+
+    // Error thrown when comptrollers array length is not equal to assets array length
+    error InvalidArguments();
+
+    /// @notice thrown when amount entered is greater than balance
+    error InsufficientBalance();
+
+    /// @notice thrown when asset does not exist in the pool
+    error MarketNotExistInPool(address comptroller, address asset);
+
+    /// @notice thrown to prevent reentrancy
+    /// @dev This error is used to safeguard against reentrancy attacks, ensuring that a certain operation
+    /// cannot be called recursively within the same transaction.
+    error ReentrancyGuardError();
+
+    /// @param corePoolComptroller_ Address of the Comptroller pool
+    /// @param vBNB_ Address of the vBNB
+    /// @param nativeWrapped_ Address of the wrapped native currency
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor(
+        address corePoolComptroller_,
+        address vBNB_,
+        address nativeWrapped_
+    ) {
+        ensureNonzeroAddress(corePoolComptroller_);
+        ensureNonzeroAddress(vBNB_);
+        ensureNonzeroAddress(nativeWrapped_);
+
+        CORE_POOL_COMPTROLLER = corePoolComptroller_;
+        VBNB = vBNB_;
+        NATIVE_WRAPPED = nativeWrapped_;
+
+        // Note that the contract is upgradeable. Use initialize() or reinitializers
+        // to set the state variables.
+        _disableInitializers();
+    }
+
+    /// @param accessControlManager_ Access control manager contract address
+    /// @param priceOracle_ Resilient oracle address
+    /// @param destinationAddress_  Address at all incoming tokens will transferred to
+    /// @param poolRegistry_ Address of the pool registry
+    /// @param comptrollers Addresses of the pools
+    /// @param assets Addresses of the assets need to be added for direct transfer
+    /// @param values Boolean value to indicate whether direct transfer is allowed for each asset.
+    /// @custom:event PoolAssetsDirectTransferUpdated emits on success
+    function initialize(
+        address accessControlManager_,
+        ResilientOracle priceOracle_,
+        address destinationAddress_,
+        address poolRegistry_,
+        address[] calldata comptrollers,
+        address[][] calldata assets,
+        bool[][] calldata values
+    ) public initializer {
+        // Initialize AbstractTokenConverter
+        __AbstractTokenConverter_init(accessControlManager_, priceOracle_, destinationAddress_);
+        ensureNonzeroAddress(poolRegistry_);
+        poolRegistry = poolRegistry_;
+        _setPoolsAssetsDirectTransfer(comptrollers, assets, values);
+    }
+
+    /// @dev Pool registry setter
+    /// @param poolRegistry_ Address of the pool registry
+    /// @custom:event PoolRegistryUpdated emits on success
+    /// @custom:error ZeroAddressNotAllowed is thrown when pool registry address is zero
+    /// @custom:access Only Governance
+    function setPoolRegistry(address poolRegistry_) external onlyOwner {
+        ensureNonzeroAddress(poolRegistry_);
+        emit PoolRegistryUpdated(poolRegistry, poolRegistry_);
+        poolRegistry = poolRegistry_;
+    }
+
+    /// @notice Update the poolsAssetsDirectTransfer mapping
+    /// @param comptrollers Addresses of the pools
+    /// @param assets Addresses of the assets need to be added for direct transfer
+    /// @param values Boolean value to indicate whether direct transfer is allowed for each asset.
+    /// @custom:event PoolAssetsDirectTransferUpdated emits on success
+    /// @custom:access Restricted by ACM
+    function setPoolsAssetsDirectTransfer(
+        address[] calldata comptrollers,
+        address[][] calldata assets,
+        bool[][] calldata values
+    ) external {
+        _checkAccessAllowed("setPoolsAssetsDirectTransfer(address[],address[][],bool[][])");
+        _setPoolsAssetsDirectTransfer(comptrollers, assets, values);
+    }
+
+    /// @dev Get the Amount of the asset in the risk fund for the specific pool
+    /// @param comptroller Comptroller address (pool)
+    /// @param asset Asset address
+    /// @return Asset's reserve in risk fund
+    /// @custom:error MarketNotExistInPool When asset does not exist in the pool(comptroller)
+    /// @custom:error ReentrancyGuardError thrown to prevent reentrancy during the function execution
+    function getPoolAssetReserve(address comptroller, address asset) external view returns (uint256) {
+        if (_reentrancyGuardEntered()) revert ReentrancyGuardError();
+        if (!ensureAssetListed(comptroller, asset)) revert MarketNotExistInPool(comptroller, asset);
+
+        return poolsAssetsReserves[comptroller][asset];
+    }
+
+    /// @notice Get the balance for specific token
+    /// @param tokenAddress Address of the token
+    /// @return Reserves of the token the contract has
+    function balanceOf(address tokenAddress) public view override returns (uint256) {
+        return assetsReserves[tokenAddress];
+    }
+
+    /// @notice Get the array of all pools addresses
+    /// @param tokenAddress Address of the token
+    /// @return Array of the pools addresses in which token is available
+    function getPools(address tokenAddress) public view returns (address[] memory) {
+        address[] memory pools = IPoolRegistry(poolRegistry).getPoolsSupportedByAsset(tokenAddress);
+
+        if (isAssetListedInCore(tokenAddress)) {
+            uint256 poolsLength = pools.length;
+            address[] memory poolsWithCore = new address[](poolsLength + 1);
+
+            for (uint256 i; i < poolsLength; ) {
+                poolsWithCore[i] = pools[i];
+                unchecked {
+                    ++i;
+                }
+            }
+            poolsWithCore[poolsLength] = CORE_POOL_COMPTROLLER;
+            return poolsWithCore;
+        }
+
+        return pools;
+    }
+
+    /// @notice This hook is used to update the state for asset reserves before transferring tokenOut to user
+    /// @param tokenOutAddress Address of the asset to be transferred to the user
+    /// @param amountOut Amount of tokenAddressOut transferred from this converter
+    function _preTransferHook(address tokenOutAddress, uint256 amountOut) internal override {
+        assetsReserves[tokenOutAddress] -= amountOut;
+    }
+
+    /// @notice Hook to perform after converting tokens
+    /// @dev After transformation poolsAssetsReserves are settled by pool's reserves fraction
+    /// @param tokenInAddress Address of the tokenIn
+    /// @param tokenOutAddress Address of the tokenOut
+    /// @param amountIn Amount of tokenIn transferred
+    /// @param amountOut Amount of tokenOut transferred
+    /// @custom:event AssetTransferredToDestination emits on success for each pool which has share
+    function _postConversionHook(
+        address tokenInAddress,
+        address tokenOutAddress,
+        uint256 amountIn,
+        uint256 amountOut
+    ) internal override {
+        address[] memory pools = getPools(tokenOutAddress);
+        uint256 assetReserve = assetsReserves[tokenOutAddress] + amountOut;
+        ensureNonzeroValue(assetReserve);
+
+        uint256 poolsLength = pools.length;
+        uint256 distributedOutShare;
+        uint256 poolAmountInShare;
+        uint256 distributedInShare;
+
+        for (uint256 i; i < poolsLength; ) {
+            uint256 currentPoolsAssetsReserves = poolsAssetsReserves[pools[i]][tokenOutAddress];
+            if (currentPoolsAssetsReserves != 0) {
+                if (i < (poolsLength - 1)) {
+                    distributedOutShare += updatePoolAssetsReserve(pools[i], tokenOutAddress, amountOut, assetReserve);
+                    poolAmountInShare = (amountIn * currentPoolsAssetsReserves) / assetReserve;
+                    distributedInShare += poolAmountInShare;
+                } else {
+                    uint256 distributedDiff = amountOut - distributedOutShare;
+                    poolsAssetsReserves[pools[i]][tokenOutAddress] -= distributedDiff;
+                    emit AssetsReservesUpdated(pools[i], tokenOutAddress, distributedDiff);
+                    poolAmountInShare = amountIn - distributedInShare;
+                }
+                emit AssetTransferredToDestination(pools[i], tokenInAddress, poolAmountInShare);
+                IRiskFund(destinationAddress).updatePoolState(pools[i], tokenInAddress, poolAmountInShare);
+            }
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice Operations to perform before sweeping tokens
+    /// @param tokenAddress Address of the token
+    /// @param amount Amount transferred to address(to)
+    /// @custom:error InsufficientBalance is thrown when amount entered is greater than balance of token
+    function preSweepToken(address tokenAddress, uint256 amount) internal override {
+        uint256 balance = IERC20Upgradeable(tokenAddress).balanceOf(address(this));
+        if (amount > balance) revert InsufficientBalance();
+        uint256 balanceDiff = balance - assetsReserves[tokenAddress];
+
+        if (balanceDiff < amount) {
+            uint256 amountDiff;
+            unchecked {
+                amountDiff = amount - balanceDiff;
+            }
+
+            address[] memory pools = getPools(tokenAddress);
+            uint256 assetReserve = assetsReserves[tokenAddress];
+            uint256 poolsLength = pools.length;
+            uint256 distributedShare;
+
+            for (uint256 i; i < poolsLength; ) {
+                if (poolsAssetsReserves[pools[i]][tokenAddress] != 0) {
+                    if (i < (poolsLength - 1)) {
+                        distributedShare += updatePoolAssetsReserve(pools[i], tokenAddress, amountDiff, assetReserve);
+                    } else {
+                        uint256 distributedDiff = amountDiff - distributedShare;
+                        poolsAssetsReserves[pools[i]][tokenAddress] -= distributedDiff;
+                        emit AssetsReservesUpdated(pools[i], tokenAddress, distributedDiff);
+                    }
+                }
+                unchecked {
+                    ++i;
+                }
+            }
+            assetsReserves[tokenAddress] -= amountDiff;
+        }
+    }
+
+    /// @notice Update the poolAssetsReserves upon transferring the tokens
+    /// @param pool Address of the pool
+    /// @param tokenAddress Address of the token
+    /// @param amount Amount transferred to address(to)
+    /// @param assetReserve Asset's reserve for the pool
+    /// @return poolAmountShare Share of the pool as per it's reserve in compare to total reserves for the asset
+    /// @custom:event AssetsReservesUpdated emits on success
+    function updatePoolAssetsReserve(
+        address pool,
+        address tokenAddress,
+        uint256 amount,
+        uint256 assetReserve
+    ) internal returns (uint256 poolAmountShare) {
+        poolAmountShare = (poolsAssetsReserves[pool][tokenAddress] * amount) / assetReserve;
+        poolsAssetsReserves[pool][tokenAddress] -= poolAmountShare;
+        emit AssetsReservesUpdated(pool, tokenAddress, poolAmountShare);
+    }
+
+    /// @notice Update the poolsAssetsDirectTransfer mapping
+    /// @param comptrollers Addresses of the pools
+    /// @param assets Addresses of the assets need to be added for direct transfer
+    /// @param values Boolean value to indicate whether direct transfer is allowed for each asset.
+    /// @custom:event PoolAssetsDirectTransferUpdated emits on success
+    /// @custom:error InvalidArguments thrown when comptrollers array length is not equal to assets array length
+    function _setPoolsAssetsDirectTransfer(
+        address[] calldata comptrollers,
+        address[][] calldata assets,
+        bool[][] calldata values
+    ) internal {
+        uint256 comptrollersLength = comptrollers.length;
+
+        if ((comptrollersLength != assets.length) || (comptrollersLength != values.length)) {
+            revert InvalidArguments();
+        }
+
+        for (uint256 i; i < comptrollersLength; ) {
+            address[] memory poolAssets = assets[i];
+            bool[] memory assetsValues = values[i];
+            uint256 poolAssetsLength = poolAssets.length;
+
+            if (poolAssetsLength != assetsValues.length) {
+                revert InvalidArguments();
+            }
+
+            for (uint256 j; j < poolAssetsLength; ) {
+                poolsAssetsDirectTransfer[comptrollers[i]][poolAssets[j]] = assetsValues[j];
+                emit PoolAssetsDirectTransferUpdated(comptrollers[i], poolAssets[j], assetsValues[j]);
+                unchecked {
+                    ++j;
+                }
+            }
+
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @dev Update the reserve of the asset for the specific pool after transferring to risk fund
+    /// and transferring funds to the protocol share reserve
+    /// @param comptroller Comptroller address (pool)
+    /// @param asset Asset address
+    /// @return Amount of asset, for _privateConversion
+    /// @custom:event AssetTransferredToDestination emits when poolsAssetsDirectTransfer is enabled for entered comptroller and asset
+    /// @custom:error MarketNotExistInPool When asset does not exist in the pool(comptroller)
+    function _updateAssetsState(address comptroller, address asset) internal override returns (uint256) {
+        if (!ensureAssetListed(comptroller, asset)) revert MarketNotExistInPool(comptroller, asset);
+
+        IERC20Upgradeable token = IERC20Upgradeable(asset);
+        uint256 currentBalance = token.balanceOf(address(this));
+        uint256 assetReserve = assetsReserves[asset];
+        if (currentBalance > assetReserve) {
+            uint256 balanceDifference;
+            unchecked {
+                balanceDifference = currentBalance - assetReserve;
+            }
+            if (poolsAssetsDirectTransfer[comptroller][asset]) {
+                uint256 previousDestinationBalance = token.balanceOf(destinationAddress);
+                token.safeTransfer(destinationAddress, balanceDifference);
+                uint256 newDestinationBalance = token.balanceOf(destinationAddress);
+
+                emit AssetTransferredToDestination(comptroller, asset, balanceDifference);
+                IRiskFund(destinationAddress).updatePoolState(
+                    comptroller,
+                    asset,
+                    newDestinationBalance - previousDestinationBalance
+                );
+                return 0;
+            }
+            return balanceDifference;
+        }
+    }
+
+    /// @dev This hook is used to update states for the converter after the privateConversion
+    /// @param comptroller Comptroller address (pool)
+    /// @param tokenAddressIn Address of the destination's base asset
+    /// @param convertedTokenInBalance Amount of the base asset received after the conversion
+    /// @param tokenAddressOut Address of the asset transferred to other converter in exchange of base asset
+    /// @param convertedTokenOutBalance Amount of tokenAddressOut transferred from this converter
+    function _postPrivateConversionHook(
+        address comptroller,
+        address tokenAddressIn,
+        uint256 convertedTokenInBalance,
+        address tokenAddressOut,
+        uint256 convertedTokenOutBalance
+    ) internal override {
+        if (convertedTokenInBalance > 0) {
+            emit AssetTransferredToDestination(comptroller, tokenAddressIn, convertedTokenInBalance);
+            IRiskFund(destinationAddress).updatePoolState(comptroller, tokenAddressIn, convertedTokenInBalance);
+        }
+        if (convertedTokenOutBalance > 0) {
+            assetsReserves[tokenAddressOut] += convertedTokenOutBalance;
+            poolsAssetsReserves[comptroller][tokenAddressOut] += convertedTokenOutBalance;
+            emit AssetsReservesUpdated(comptroller, tokenAddressOut, convertedTokenOutBalance);
+        }
+    }
+
+    /// @notice This function checks for the given asset is listed in core pool or not
+    /// @param tokenAddress Address of the asset
+    /// @return isAssetListed true if the asset is listed
+    function isAssetListedInCore(address tokenAddress) internal view returns (bool isAssetListed) {
+        address[] memory coreMarkets = IComptroller(CORE_POOL_COMPTROLLER).getAllMarkets();
+
+        uint256 coreMarketsLength = coreMarkets.length;
+        for (uint256 i; i < coreMarketsLength; ) {
+            isAssetListed = (VBNB == coreMarkets[i])
+                ? (tokenAddress == NATIVE_WRAPPED)
+                : (IVToken(coreMarkets[i]).underlying() == tokenAddress);
+
+            if (isAssetListed) {
+                break;
+            }
+
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice This function checks for the given asset is listed or not
+    /// @param comptroller Address of the comptroller
+    /// @param asset Address of the asset
+    /// @return true if the asset is listed
+    function ensureAssetListed(address comptroller, address asset) internal view returns (bool) {
+        if (comptroller == CORE_POOL_COMPTROLLER) {
+            return isAssetListedInCore(asset);
+        }
+
+        return IPoolRegistry(poolRegistry).getVTokenForAsset(comptroller, asset) != address(0);
+    }
+
+    /// @notice Get base asset address of the RiskFund
+    /// @return Address of the base asset(RiskFund)
+    function _getDestinationBaseAsset() internal view override returns (address) {
+        return IRiskFundGetters(destinationAddress).convertibleBaseAsset();
+    }
+}

package/contracts/TokenConverter/SingleTokenConverter.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: BSD-3-Clause
+pragma solidity 0.8.13;
+
+import { SafeERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol";
+import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
+import { ResilientOracle } from "@venusprotocol/oracle/contracts/ResilientOracle.sol";
+
+import { AbstractTokenConverter } from "./AbstractTokenConverter.sol";
+import { ensureNonzeroAddress } from "../Utils/Validators.sol";
+
+/// @title SingleTokenConverter
+/// @author Venus
+/// @notice SingleTokenConverter used for token conversions and sends received tokens
+/// @custom:security-contact https://github.com/VenusProtocol/protocol-reserve#discussion
+contract SingleTokenConverter is AbstractTokenConverter {
+    using SafeERC20Upgradeable for IERC20Upgradeable;
+
+    /// @notice Address of the BASE_ASSET token
+    address public immutable BASE_ASSET;
+
+    /// @notice Emmitted after the funds transferred to the destination address
+    event AssetTransferredToDestination(uint256 amount);
+
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    /// @param baseAsset_ Address of the BASE_ASSET token
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor(address baseAsset_) {
+        ensureNonzeroAddress(baseAsset_);
+        BASE_ASSET = baseAsset_;
+
+        // Note that the contract is upgradeable. Use initialize() or reinitializers
+        // to set the state variables.
+        _disableInitializers();
+    }
+
+    /// @param accessControlManager_ Access control manager contract address
+    /// @param priceOracle_ Resilient oracle address
+    /// @param destinationAddress_  Address at all incoming tokens will transferred to
+    function initialize(
+        address accessControlManager_,
+        ResilientOracle priceOracle_,
+        address destinationAddress_
+    ) public initializer {
+        // Initialize AbstractTokenConverter
+        __AbstractTokenConverter_init(accessControlManager_, priceOracle_, destinationAddress_);
+    }
+
+    /// @notice Get the balance for specific token
+    /// @param tokenAddress Address of the token
+    /// @return tokenBalance Balance of the token the contract has
+    function balanceOf(address tokenAddress) public view override returns (uint256 tokenBalance) {
+        IERC20Upgradeable token = IERC20Upgradeable(tokenAddress);
+        tokenBalance = token.balanceOf(address(this));
+    }
+
+    /// @param comptroller Comptroller address (pool)
+    /// @param asset Asset address.
+    /// @return balanceLeft Amount of asset, for _privateConversion
+    // solhint-disable-next-line
+    function _updateAssetsState(address comptroller, address asset) internal override returns (uint256 balanceLeft) {
+        IERC20Upgradeable token = IERC20Upgradeable(asset);
+        uint256 balance = token.balanceOf(address(this));
+        balanceLeft = balance;
+
+        if (asset == BASE_ASSET) {
+            balanceLeft = 0;
+            token.safeTransfer(destinationAddress, balance);
+            emit AssetTransferredToDestination(balance);
+        }
+    }
+
+    /// @notice Get base asset address
+    /// @return Address of the base asset(BASE_ASSET)
+    function _getDestinationBaseAsset() internal view override returns (address) {
+        return BASE_ASSET;
+    }
+}

package/contracts/Utils/ArrayHelpers.sol

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: BSD-3-Clause
+pragma solidity 0.8.13;
+
+/// @notice Used to sort addresses array based on their token balances
+/// @param arr Array of token balances of different addresses
+/// @param addrs Array containing these addresses
+function sort(uint256[] memory arr, address[] memory addrs) pure {
+    if (arr.length > 1) {
+        return quickSortDescending(arr, addrs, 0, arr.length - 1);
+    }
+}
+
+/// @notice Used to sort addresses array based on their token balances
+/// @param arr Array of token balances of different addresses
+/// @param addrs Array containing these addresses
+/// @param left index of first value
+/// @param right index of last value
+function quickSortDescending(
+    uint256[] memory arr,
+    address[] memory addrs,
+    uint256 left,
+    uint256 right
+) pure {
+    if (left >= right) return;
+    uint256 p = arr[(left + right) / 2]; // p = the pivot element
+    uint256 i = left;
+    uint256 j = right;
+    while (i < j) {
+        while (arr[i] > p) ++i;
+        while (arr[j] < p) --j; // arr[j] < p means p still to the right, so j > 0
+        if (arr[i] < arr[j]) {
+            (arr[i], arr[j]) = (arr[j], arr[i]);
+            (addrs[i], addrs[j]) = (addrs[j], addrs[i]);
+        } else {
+            ++i;
+        }
+    }
+
+    if (j > left) quickSortDescending(arr, addrs, left, j - 1); // j > left, so j > 0
+    quickSortDescending(arr, addrs, j + 1, right);
+}

package/contracts/Utils/Constants.sol

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: BSD-3-Clause
+pragma solidity 0.8.13;
+
+/// @dev The approximate number of blocks per year that is assumed by the interest rate model
+uint256 constant BLOCKS_PER_YEAR = 10_512_000;
+
+/// @dev Base unit for computations, usually used in scaling (multiplications, divisions)
+uint256 constant EXP_SCALE = 1e18;
+
+/// @dev A unit (literal one) in EXP_SCALE, usually used in additions/subtractions
+uint256 constant MANTISSA_ONE = EXP_SCALE;

package/contracts/Utils/Validators.sol

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: BSD-3-Clause
+pragma solidity 0.8.13;
+
+/// @notice Thrown if the supplied address is a zero address where it is not allowed
+error ZeroAddressNotAllowed();
+
+/// @notice Thrown if the supplied value is 0 where it is not allowed
+error ZeroValueNotAllowed();
+
+/// @notice Checks if the provided address is nonzero, reverts otherwise
+/// @param address_ Address to check
+/// @custom:error ZeroAddressNotAllowed is thrown if the provided address is a zero address
+function ensureNonzeroAddress(address address_) pure {
+    if (address_ == address(0)) {
+        revert ZeroAddressNotAllowed();
+    }
+}
+
+/// @notice Checks if the provided value is nonzero, reverts otherwise
+/// @param value_ Value to check
+/// @custom:error ZeroValueNotAllowed is thrown if the provided value is 0
+function ensureNonzeroValue(uint256 value_) pure {
+    if (value_ == 0) {
+        revert ZeroValueNotAllowed();
+    }
+}