docs: add documentation for collateral management

Luisfc68 · Luisfc68 · commit b84e3af46e61 · 2025-08-26T10:32:23.000-03:00
diff --git a/contracts/CollateralManagement.sol b/contracts/CollateralManagement.sol
@@ -10,14 +10,23 @@ import {ICollateralManagement} from "./interfaces/ICollateralManagement.sol";
 import {Flyover} from "./libraries/Flyover.sol";
 import {Quotes} from "./libraries/Quotes.sol";
 
+/// @title Collateral Management
+/// @notice This contract is used to manage the collateral related aspects of the Flyover system.
+/// This involves adding, slashing, resigning and withdrawing collateral.
+/// @author Rootstock Labs
 contract CollateralManagementContract is
     AccessControlDefaultAdminRulesUpgradeable,
     ReentrancyGuardUpgradeable,
     ICollateralManagement
 {
     /// @notice The version of the contract
     string constant public VERSION = "1.0.0";
+
+    /// @notice The role that can add collateral to the contract by using
+    /// the addPegInCollateralTo or addPegOutCollateralTo functions
     bytes32 public constant COLLATERAL_ADDER = keccak256("COLLATERAL_ADDER");
+    /// @notice The role that can slash collateral from the contract by using
+    /// the slashPegInCollateral or slashPegOutCollateral functions
     bytes32 public constant COLLATERAL_SLASHER = keccak256("COLLATERAL_SLASHER");
 
     uint256 private _minCollateral;
@@ -29,8 +38,17 @@ contract CollateralManagementContract is
     mapping(address => uint256) private _resignationBlockNum;
     mapping(address => uint256) private _rewards;
 
+    /// @notice Emitted when the minimum collateral is set
+    /// @param oldMinCollateral The old minimum collateral
+    /// @param newMinCollateral The new minimum collateral
     event MinCollateralSet(uint256 indexed oldMinCollateral, uint256 indexed newMinCollateral);
+    /// @notice Emitted when the resignation delay in blocks is set
+    /// @param oldResignDelayInBlocks The old resignation delay in blocks
+    /// @param newResignDelayInBlocks The new resignation delay in blocks
     event ResignDelayInBlocksSet(uint256 indexed oldResignDelayInBlocks, uint256 indexed newResignDelayInBlocks);
+    /// @notice Emitted when the reward percentage is set
+    /// @param oldReward The old reward percentage
+    /// @param newReward The new reward percentage
     event RewardPercentageSet(uint256 indexed oldReward, uint256 indexed newReward);
 
     modifier onlyRegisteredForPegIn(address addr) {
@@ -50,22 +68,32 @@ contract CollateralManagementContract is
         revert Flyover.PaymentNotAllowed();
     }
 
+    /// @inheritdoc ICollateralManagement
     function addPegInCollateralTo(address addr) external onlyRole(COLLATERAL_ADDER) payable override {
         _addPegInCollateralTo(addr, msg.value);
     }
 
+    /// @inheritdoc ICollateralManagement
     function addPegInCollateral() external onlyRegisteredForPegIn(msg.sender) payable override {
         _addPegInCollateralTo(msg.sender, msg.value);
     }
 
+    /// @inheritdoc ICollateralManagement
     function addPegOutCollateralTo(address addr) external onlyRole(COLLATERAL_ADDER) payable override {
         _addPegOutCollateralTo(addr, msg.value);
     }
 
+    /// @inheritdoc ICollateralManagement
     function addPegOutCollateral() external onlyRegisteredForPegOut(msg.sender) payable override {
         _addPegOutCollateralTo(msg.sender, msg.value);
     }
 
+    /// @notice Initializes the contract
+    /// @param owner The owner of the contract
+    /// @param initialDelay The initial delay for changes in the default admin role
+    /// @param minCollateral The minimum collateral required for a liquidity provider **per operation**
+    /// @param resignDelayInBlocks The delay in blocks before a liquidity provider can withdraw their collateral
+    /// @param rewardPercentage The reward percentage from the penalty fee of the quotes that the punisher will receive
     // solhint-disable-next-line comprehensive-interface
     function initialize(
         address owner,
@@ -82,24 +110,31 @@ contract CollateralManagementContract is
         _penalties = 0;
     }
 
+    /// @notice Sets the minimum collateral required for a liquidity provider **per operation**
+    /// @param minCollateral The new minimum collateral
     // solhint-disable-next-line comprehensive-interface
     function setMinCollateral(uint minCollateral) external onlyRole(DEFAULT_ADMIN_ROLE) {
         emit MinCollateralSet(_minCollateral, minCollateral);
         _minCollateral = minCollateral;
     }
 
+    /// @notice Sets the resignation delay in blocks
+    /// @param resignDelayInBlocks The new resignation delay in blocks
     // solhint-disable-next-line comprehensive-interface
     function setResignDelayInBlocks(uint resignDelayInBlocks) external onlyRole(DEFAULT_ADMIN_ROLE) {
         emit ResignDelayInBlocksSet(_resignDelayInBlocks, resignDelayInBlocks);
         _resignDelayInBlocks = resignDelayInBlocks;
     }
 
+    /// @notice Sets the reward percentage from the penalty fee of the quotes that the punisher will receive
+    /// @param rewardPercentage The new reward percentage
     // solhint-disable-next-line comprehensive-interface
     function setRewardPercentage(uint256 rewardPercentage) external onlyRole(DEFAULT_ADMIN_ROLE) {
         emit RewardPercentageSet(_rewardPercentage, rewardPercentage);
         _rewardPercentage = rewardPercentage;
     }
 
+    /// @inheritdoc ICollateralManagement
     function slashPegInCollateral(
         address punisher,
         Quotes.PegInQuote calldata quote,
@@ -123,6 +158,7 @@ contract CollateralManagementContract is
         );
     }
 
+    /// @inheritdoc ICollateralManagement
     function slashPegOutCollateral(
         address punisher,
         Quotes.PegOutQuote calldata quote,
@@ -146,6 +182,7 @@ contract CollateralManagementContract is
         );
     }
 
+    /// @inheritdoc ICollateralManagement
     function withdrawCollateral() external nonReentrant override {
         address providerAddress = msg.sender;
         uint resignationBlock = _resignationBlockNum[providerAddress];
@@ -165,6 +202,7 @@ contract CollateralManagementContract is
         if (!success) revert WithdrawalFailed(providerAddress, amount);
     }
 
+    /// @inheritdoc ICollateralManagement
     function withdrawRewards() external override {
         address addr = msg.sender;
         uint256 rewards = _rewards[addr];
@@ -175,6 +213,7 @@ contract CollateralManagementContract is
         if (!success) revert WithdrawalFailed(addr, rewards);
     }
 
+    /// @inheritdoc ICollateralManagement
     function resign() external override {
         address providerAddress = msg.sender;
         if (providerAddress == address(0)) revert Flyover.InvalidAddress(providerAddress);
@@ -186,34 +225,42 @@ contract CollateralManagementContract is
         emit Resigned(providerAddress);
     }
 
+    /// @inheritdoc ICollateralManagement
     function getPegInCollateral(address addr) external view override returns (uint256) {
         return _pegInCollateral[addr];
     }
 
+    /// @inheritdoc ICollateralManagement
     function getPegOutCollateral(address addr) external view override returns (uint256) {
         return _pegOutCollateral[addr];
     }
 
+    /// @inheritdoc ICollateralManagement
     function getResignationBlock(address addr) external view override returns (uint256) {
         return _resignationBlockNum[addr];
     }
 
+    /// @inheritdoc ICollateralManagement
     function getRewardPercentage() external view override returns (uint256) {
         return _rewardPercentage;
     }
 
+    /// @inheritdoc ICollateralManagement
     function getResignDelayInBlocks() external view override returns (uint256) {
         return _resignDelayInBlocks;
     }
 
+    /// @inheritdoc ICollateralManagement
     function getMinCollateral() external view override returns (uint256) {
         return _minCollateral;
     }
 
+    /// @inheritdoc ICollateralManagement
     function isRegistered(Flyover.ProviderType providerType, address addr) external view override returns (bool) {
         return _isRegistered(providerType, addr);
     }
 
+    /// @inheritdoc ICollateralManagement
     function isCollateralSufficient(
         Flyover.ProviderType providerType,
         address addr
@@ -229,24 +276,41 @@ contract CollateralManagementContract is
         }
     }
 
+    /// @inheritdoc ICollateralManagement
     function getRewards(address addr) external view override returns (uint256) {
         return _rewards[addr];
     }
 
+    /// @inheritdoc ICollateralManagement
     function getPenalties() external view override returns (uint256) {
         return _penalties;
     }
 
+    /// @notice Adds peg in collateral to an account
+    /// @dev Is very important for this function to remain private as the public function
+    /// is the one protected by the role checks
+    /// @param addr The address of the account
+    /// @param amount The amount of peg in collateral to add
     function _addPegInCollateralTo(address addr, uint256 amount) private {
         _pegInCollateral[addr] += amount;
         emit ICollateralManagement.PegInCollateralAdded(addr, amount);
     }
 
+    /// @notice Adds peg out collateral to an account
+    /// @dev Is very important for this function to remain private as the public function
+    /// is the one protected by the role checks
+    /// @param addr The address of the account
+    /// @param amount The amount of peg out collateral to add
     function _addPegOutCollateralTo(address addr, uint256 amount) private {
         _pegOutCollateral[addr] += amount;
         emit ICollateralManagement.PegOutCollateralAdded(addr, amount);
     }
 
+    /// @notice Checks if an account is registered
+    /// @dev Registered means having added collateral to the contract and not having resigned
+    /// @param providerType The type of provider
+    /// @param addr The address of the account
+    /// @return True if the account is registered, false otherwise
     function _isRegistered(Flyover.ProviderType providerType, address addr) private view returns (bool) {
         if (providerType == Flyover.ProviderType.PegIn) {
             return _pegInCollateral[addr] > 0 && _resignationBlockNum[addr] == 0;
diff --git a/contracts/interfaces/ICollateralManagement.sol b/contracts/interfaces/ICollateralManagement.sol
@@ -6,12 +6,43 @@ import {Quotes} from "../libraries/Quotes.sol";
 
 event CollateralManagementSet(address indexed oldAddress, address indexed newAddress);
 
+/// @title Collateral Management interface
+/// @notice This interface is used to expose the required functions to
+/// provide the Flyover collateral management service.
+/// This involves, slashing, resigning and registering processes.
 interface ICollateralManagement {
+
+    /// @notice Emitted when the collateral is withdrawn
+    /// @param addr The address of the liquidity provider
+    /// @param amount The amount of collateral withdrawn
     event WithdrawCollateral(address indexed addr, uint indexed amount);
+
+    /// @notice Emitted when the liquidity provider resigns
+    /// @param addr The address of the liquidity provider
     event Resigned(address indexed addr);
+
+    /// @notice Emitted when the rewards are withdrawn by a punisher
+    /// @param addr The address of the punisher
+    /// @param amount The amount of rewards withdrawn
     event RewardsWithdrawn(address indexed addr, uint256 indexed amount);
+
+    /// @notice Emitted when the peg in collateral is added
+    /// @param addr The address of the liquidity provider
+    /// @param amount The amount of peg in collateral added
     event PegInCollateralAdded(address indexed addr, uint256 indexed amount);
+
+    /// @notice Emitted when the peg out collateral is added
+    /// @param addr The address of the liquidity provider
+    /// @param amount The amount of peg out collateral added
     event PegOutCollateralAdded(address indexed addr, uint256 indexed amount);
+
+    /// @notice Emitted when a liquidity provider is penalized by not behaving as expected
+    /// @param liquidityProvider The address of the liquidity provider
+    /// @param punisher The address of the punisher
+    /// @param quoteHash The hash of the quote
+    /// @param collateralType The type of collateral
+    /// @param penalty The penalty amount for the liquidity provider
+    /// @param reward The reward amount for the punisher
     event Penalized(
         address indexed liquidityProvider,
         address indexed punisher,
@@ -21,38 +52,131 @@ interface ICollateralManagement {
         uint256 reward
     );
 
+    /// @notice Emitted when a liquidity provider has already resigned
+    /// @param from The address of the liquidity provider
     error AlreadyResigned(address from);
+
+    /// @notice Emitted when a liquidity provider has not resigned yet
+    /// @param from The address of the liquidity provider
     error NotResigned(address from);
+
+    /// @notice Emitted when a liquidity provider has not resigned yet
+    /// @param from The address of the liquidity provider
+    /// @param resignationBlockNum The block number at which the liquidity provider resigned
+    /// @param resignDelayInBlocks The delay in blocks before a liquidity provider can withdraw their collateral
     error ResignationDelayNotMet(address from, uint resignationBlockNum, uint resignDelayInBlocks);
+
+    /// @notice Emitted when a liquidity provider tries to withdraw collateral but the withdrawal fails
+    /// @param from The address of the liquidity provider
+    /// @param amount The amount of collateral that was attempted to be withdrawn
     error WithdrawalFailed(address from, uint amount);
+
+    /// @notice Emitted when a liquidity provider tries to withdraw collateral but has nothing to withdraw
+    /// @param from The address of the liquidity provider
     error NothingToWithdraw(address from);
 
+    /// @notice Adds peg in collateral to an account
+    /// @param addr The address of the account
+    /// @dev This function requires the COLLATERAL_ADDER role
     function addPegInCollateralTo(address addr) external payable;
+
+    /// @notice Adds peg in collateral to the caller
+    /// @dev This function can only be called by a liquidity provider. This means an
+    /// account that has been registered by adding collateral with addPegInCollateralTo.
+    /// This means the COLLATERAL_ADDER can't use this function unless they register themselves.
     function addPegInCollateral() external payable;
+
+    /// @notice Slashes peg in collateral from a liquidity provider. The slashed amount
+    /// is the penalty fee of the quote. Depending on the reward percentage, the punisher
+    /// will receive a reward. The rest of the penalty fee remains in the contract.
+    /// @param punisher The address of the punisher
+    /// @param quote The quote of the peg in collateral
+    /// @param quoteHash The hash of the quote
+    /// @dev This function requires the COLLATERAL_SLASHER role
     function slashPegInCollateral(
         address punisher,
         Quotes.PegInQuote calldata quote,
         bytes32 quoteHash
     ) external;
+
+    /// @notice Adds peg out collateral to an account
+    /// @param addr The address of the account
+    /// @dev This function requires the COLLATERAL_ADDER role
     function addPegOutCollateralTo(address addr) external payable;
+
+    /// @notice Adds peg out collateral to the caller
+    /// @dev This function can only be called by a liquidity provider. This means an
+    /// account that has been registered by adding collateral with addPegOutCollateralTo.
+    /// This means the COLLATERAL_ADDER can't use this function unless they register themselves.
     function addPegOutCollateral() external payable;
+
+    /// @notice Slashes peg out collateral from a liquidity provider. The slashed amount
+    /// is the penalty fee of the quote. Depending on the reward percentage, the punisher
+    /// will receive a reward. The rest of the penalty fee remains in the contract.
+    /// @param punisher The address of the punisher
+    /// @param quote The quote of the peg out collateral
+    /// @param quoteHash The hash of the quote
+    /// @dev This function requires the COLLATERAL_SLASHER role
     function slashPegOutCollateral(
         address punisher,
         Quotes.PegOutQuote calldata quote,
         bytes32 quoteHash
     ) external;
+
+    /// @notice Withdraws rewards from the contract. This implies that the caller has
+    /// been a punisher at some point in time.
     function withdrawRewards() external;
+
+    /// @notice Withdraws collateral from the contract. This requires the liquidity provider
+    /// to have resigned and the resignation delay to have passed.
     function withdrawCollateral() external;
+
+    /// @notice Resigns a liquidity provider
     function resign() external;
 
+    /// @notice Gets the peg in collateral of an account
+    /// @param addr The address of the account
+    /// @return The amount of peg in collateral
     function getPegInCollateral(address addr) external view returns (uint256);
+
+    /// @notice Gets the peg out collateral of an account
+    /// @param addr The address of the account
+    /// @return The amount of peg out collateral
     function getPegOutCollateral(address addr) external view returns (uint256);
+
+    /// @notice Gets the block number at which a liquidity provider resigned
     function getResignationBlock(address addr) external view returns (uint256);
+
+    /// @notice Gets the reward percentage from the penalty fee that the punisher will receive
+    /// @return The reward percentage
     function getRewardPercentage() external view returns (uint256);
+
+    /// @notice Gets the resignation delay in blocks
+    /// @return The resignation delay in blocks
     function getResignDelayInBlocks() external view returns (uint256);
+
+    /// @notice Gets the minimum collateral **per operation** required for a liquidity provider
+    /// @return The minimum collateral required for a liquidity provider
     function getMinCollateral() external view returns (uint256);
+
+    /// @notice Checks if an account is registered this means having added collateral to the
+    /// contract and not having resigned
+    /// @param providerType The type of provider
+    /// @param addr The address of the account
     function isRegistered(Flyover.ProviderType providerType, address addr) external view returns (bool);
+
+    /// @notice Checks if an account has sufficient collateral. This means having at least the minimum collateral
+    /// for that operation and not having resigned.
+    /// @param providerType The type of provider
+    /// @param addr The address of the account
     function isCollateralSufficient(Flyover.ProviderType providerType, address addr) external view returns (bool);
+
+    /// @notice Gets the rewards of an account accumulated from the punishments
+    /// @param addr The address of the account
+    /// @return The rewards of the account
     function getRewards(address addr) external view returns (uint256);
+
+    /// @notice Gets the total penalties stored in the contract from the penalized liquidity providers
+    /// @return The penalties amount
     function getPenalties() external view returns (uint256);
 }
