Merge pull request #168 from SocketDotTech/contract/natspecs

docs: contract natspecs

contracts/CapacitorFactory.sol

@@ -11,14 +11,27 @@ import "./libraries/RescueFundsLib.sol";
 import "./utils/AccessControlExtended.sol";
 import {RESCUE_ROLE} from "./utils/AccessRoles.sol";
 
+/**
+ * @title CapacitorFactory
+ * @notice Factory contract for creating capacitor and decapacitor pairs of different types.
+ * @dev The capacitorType_ parameter determines the type of capacitor and decapacitor to deploy.
+ */
 contract CapacitorFactory is ICapacitorFactory, AccessControlExtended {
     uint256 private constant SINGLE_CAPACITOR = 1;
     uint256 private constant HASH_CHAIN_CAPACITOR = 2;
 
+    /**
+     * @notice initialises owner and grants RESCUE_ROLE to owner.
+     * @param owner_ The address of the owner of the contract.
+     */
     constructor(address owner_) AccessControlExtended(owner_) {
         _grantRole(RESCUE_ROLE, owner_);
     }
 
+    /**
+     * @notice Creates a new capacitor and decapacitor pair based on the given type.
+     * @param capacitorType_ The type of capacitor to be created. Can be SINGLE_CAPACITOR or HASH_CHAIN_CAPACITOR.
+     */
     function deploy(
         uint256 capacitorType_,
         uint256 /** siblingChainSlug */,
@@ -41,6 +54,12 @@ contract CapacitorFactory is ICapacitorFactory, AccessControlExtended {
         revert InvalidCapacitorType();
     }
 
+    /**
+     * @notice Rescues funds from a contract that has lost access to them.
+     * @param token_ The address of the token contract.
+     * @param userAddress_ The address of the user who lost access to the funds.
+     * @param amount_ The amount of tokens to be rescued.
+     */
     function rescueFunds(
         address token_,
         address userAddress_,

contracts/ExecutionManager.sol

@@ -9,17 +9,34 @@ import "./libraries/SignatureVerifierLib.sol";
 import "./libraries/FeesHelper.sol";
 import {WITHDRAW_ROLE, RESCUE_ROLE, GOVERNANCE_ROLE, EXECUTOR_ROLE} from "./utils/AccessRoles.sol";
 
+/**
+ * @title ExecutionManager
+ * @dev Implementation of the IExecutionManager interface, providing functions for executing cross-chain transactions and managing fees.
+ * This contract also implements the AccessControlExtended interface, allowing for role-based access control.
+ */
 contract ExecutionManager is IExecutionManager, AccessControlExtended {
     IGasPriceOracle public gasPriceOracle__;
     event GasPriceOracleSet(address gasPriceOracle);
 
+    /**
+     * @dev Constructor for ExecutionManager contract
+     * @param gasPriceOracle_ Address of the Gas Price Oracle contract
+     * @param owner_ Address of the contract owner
+     */
     constructor(
         IGasPriceOracle gasPriceOracle_,
         address owner_
     ) AccessControlExtended(owner_) {
         gasPriceOracle__ = IGasPriceOracle(gasPriceOracle_);
     }
 
+    /**
+     * @notice Checks whether the provided signer address is an executor for the given packed message and signature
+     * @param packedMessage Packed message to be executed
+     * @param sig Signature of the message
+     * @return executor Address of the executor
+     * @return isValidExecutor Boolean value indicating whether the executor is valid or not
+     */
     function isExecutor(
         bytes32 packedMessage,
         bytes memory sig
@@ -31,21 +48,40 @@ contract ExecutionManager is IExecutionManager, AccessControlExtended {
         isValidExecutor = _hasRole(EXECUTOR_ROLE, executor);
     }
 
-    // these details might be needed for on-chain fee distribution later
+    /**
+     * @dev Function to be used for on-chain fee distribution later
+     */
     function updateExecutionFees(address, uint256, bytes32) external override {}
 
+    /**
+     * @notice Function for paying fees for cross-chain transaction execution
+     * @param msgGasLimit_ Gas limit for the transaction
+     * @param siblingChainSlug_ Sibling chain identifier
+     */
     function payFees(
         uint256 msgGasLimit_,
         uint32 siblingChainSlug_
     ) external payable override {}
 
+    /**
+     * @notice Function for getting the minimum fees required for executing a cross-chain transaction
+     * @param msgGasLimit_ Gas limit for the transaction
+     * @param siblingChainSlug_ Sibling chain identifier
+     * @return Minimum fees required for executing the transaction
+     */
     function getMinFees(
         uint256 msgGasLimit_,
         uint32 siblingChainSlug_
     ) external view override returns (uint256) {
         return _getMinExecutionFees(msgGasLimit_, siblingChainSlug_);
     }
 
+    /**
+     * @dev Function for getting the minimum fees required for executing a cross-chain transaction
+     * @param msgGasLimit_ Gas limit for the transaction
+     * @param dstChainSlug_ Destination chain identifier
+     * @return Minimum fees required for executing the transaction
+     */
     function _getMinExecutionFees(
         uint256 msgGasLimit_,
         uint32 dstChainSlug_
@@ -67,10 +103,20 @@ contract ExecutionManager is IExecutionManager, AccessControlExtended {
         emit GasPriceOracleSet(gasPriceOracle_);
     }
 
+    /**
+     * @notice withdraws fees from contract
+     * @param account_ withdraw fees to
+     */
     function withdrawFees(address account_) external onlyRole(WITHDRAW_ROLE) {
         FeesHelper.withdrawFees(account_);
     }
 
+    /**
+     * @notice Rescues funds from a contract that has lost access to them.
+     * @param token_ The address of the token contract.
+     * @param userAddress_ The address of the user who lost access to the funds.
+     * @param amount_ The amount of tokens to be rescued.
+     */
     function rescueFunds(
         address token_,
         address userAddress_,

contracts/GasPriceOracle.sol

@@ -7,31 +7,73 @@ import "./utils/AccessControlExtended.sol";
 import "./libraries/RescueFundsLib.sol";
 import {GOVERNANCE_ROLE, RESCUE_ROLE} from "./utils/AccessRoles.sol";
 
+/**
+ * @title GasPriceOracle
+ * @notice A contract to maintain and update gas prices across multiple chains.
+ * It implements the IGasPriceOracle interface and uses AccessControlExtended to define roles and access permissions.
+ * It also imports other contracts and libraries, including ITransmitManager for transmitting transactions across chains,
+ * and RescueFundsLib for rescuing funds from contracts that have lost access to them.
+ */
 contract GasPriceOracle is IGasPriceOracle, AccessControlExtended {
+    /**
+     * @notice The ITransmitManager contract instance that is used to transmit transactions across chains.
+     */
     ITransmitManager public transmitManager__;
-
-    // plugs/switchboards/transmitter can use it to ensure prices are updated
+    /**
+     * @notice A mapping that stores the timestamp of the last update for each chain.
+     */
     mapping(uint256 => uint256) public updatedAt;
-    // chain slug => relative gas price
+    /**
+     * @notice A mapping that stores the relative gas price of each chain.
+     */
     mapping(uint32 => uint256) public override relativeGasPrice;
-
-    // transmitter => nextNonce
+    /**
+     * @notice A mapping that stores the next nonce of each transmitter.
+     */
     mapping(address => uint256) public nextNonce;
-
-    // gas price of source chain
+    /**
+     * @notice The gas price of the source chain.
+     */
     uint256 public override sourceGasPrice;
+    /**
+     * @notice The chain slug of the contract.
+     */
     uint32 public immutable chainSlug;
 
+    /**
+     * @notice An event that is emitted when the transmitManager is updated.
+     * @param transmitManager The address of the new transmitManager.
+     */
     event TransmitManagerUpdated(address transmitManager);
+    /**
+     * @notice An event that is emitted when the relative gas price of a chain is updated.
+     * @param dstChainSlug The chain slug of the destination chain.
+     * @param relativeGasPrice The new relative gas price of the destination chain.
+     */
     event RelativeGasPriceUpdated(
         uint256 dstChainSlug,
         uint256 relativeGasPrice
     );
+    /**
+     * @notice An event that is emitted when the source gas price is updated.
+     * @param sourceGasPrice The new source gas price.
+     */
     event SourceGasPriceUpdated(uint256 sourceGasPrice);
 
+    /**
+     * @dev An error that is thrown when a transmitter is not found.
+     */
     error TransmitterNotFound();
+    /**
+     * @dev An error that is thrown when an invalid nonce is provided.
+     */
     error InvalidNonce();
 
+    /**
+     * @dev Constructs a new GasPriceOracle contract instance.
+     * @param owner_ The address of the owner of the contract.
+     * @param chainSlug_ The chain slug of the contract.
+     */
     constructor(
         address owner_,
         uint32 chainSlug_
@@ -102,19 +144,33 @@ contract GasPriceOracle is IGasPriceOracle, AccessControlExtended {
         emit RelativeGasPriceUpdated(siblingChainSlug_, relativeGasPrice_);
     }
 
+    /**
+     * @notice Returns the gas prices for a destination chain.
+     * @param siblingChainSlug_ The identifier of the destination chain.
+     */
     function getGasPrices(
         uint32 siblingChainSlug_
     ) external view override returns (uint256, uint256) {
         return (sourceGasPrice, relativeGasPrice[siblingChainSlug_]);
     }
 
+    /**
+     * @notice updates transmitManager_
+     * @param transmitManager_ address of Transmit Manager
+     */
     function setTransmitManager(
         ITransmitManager transmitManager_
     ) external onlyRole(GOVERNANCE_ROLE) {
         transmitManager__ = transmitManager_;
         emit TransmitManagerUpdated(address(transmitManager_));
     }
 
+    /**
+     * @notice Rescues funds from a contract that has lost access to them.
+     * @param token_ The address of the token contract.
+     * @param userAddress_ The address of the user who lost access to the funds.
+     * @param amount_ The amount of tokens to be rescued.
+     */
     function rescueFunds(
         address token_,
         address userAddress_,