code style for libraires

README.md

@@ -1,5 +1,8 @@
 # EthStorage Decentralized Storage Contracts V1
 
+## Style Guide
+Smart contracts should be written according to this [STYLE_GUIDE.md](https://github.com/ethstorage/optimism/blob/develop/packages/contracts-bedrock/STYLE_GUIDE.md)
+
 ## How to verify the contract
 
 - Implementation: npx hardhat verify --network sepolia <contract address>

contracts/libraries/MiningLib.sol

@@ -1,44 +1,61 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @title MiningLib
+/// @notice Handles mining difficulty calculation and mining info update
 library MiningLib {
+    /// @notice MiningInfo represents the mining information of a shard
+    /// @custom:field lastMineTime The last time a block was mined
+    /// @custom:field difficulty The current difficulty of the shard
+    /// @custom:field blockMined The number of blocks mined
     struct MiningInfo {
         uint256 lastMineTime;
         uint256 difficulty;
         uint256 blockMined;
     }
 
+    /// @notice Calculate the expected difficulty of the next block
+    /// @param _info The mining information of the shard
+    /// @param _mineTime The mined time of the next block
+    /// @param _cutoff Cutoff time for difficulty adjustment
+    /// @param _diffAdjDivisor The divisor to adjust the difficulty
+    /// @param _minDiff The minimum difficulty
+    /// @return The expected difficulty of the next block
     function expectedDiff(
-        MiningInfo storage info,
-        uint256 mineTime,
-        uint256 cutoff,
-        uint256 diffAdjDivisor,
-        uint256 minDiff
+        MiningInfo storage _info,
+        uint256 _mineTime,
+        uint256 _cutoff,
+        uint256 _diffAdjDivisor,
+        uint256 _minDiff
     ) internal view returns (uint256) {
         // Check if the diff matches
         // Use modified ETH diff algorithm
-        uint256 interval = mineTime - info.lastMineTime;
-        uint256 diff = info.difficulty;
-        if (interval < cutoff) {
-            diff = diff + ((1 - interval / cutoff) * diff) / diffAdjDivisor;
-            if (diff < minDiff) {
-                diff = minDiff;
+        uint256 interval = _mineTime - _info.lastMineTime;
+        uint256 diff = _info.difficulty;
+        if (interval < _cutoff) {
+            diff = diff + ((1 - interval / _cutoff) * diff) / _diffAdjDivisor;
+            if (diff < _minDiff) {
+                diff = _minDiff;
             }
         } else {
-            uint256 dec = ((interval / cutoff - 1) * diff) / diffAdjDivisor;
-            if (dec + minDiff > diff) {
-                diff = minDiff;
+            uint256 dec = ((interval / _cutoff - 1) * diff) / _diffAdjDivisor;
+            if (dec + _minDiff > diff) {
+                diff = _minDiff;
             } else {
                 diff = diff - dec;
             }
         }
         return diff;
     }
 
-    function update(MiningInfo storage info, uint256 mineTime, uint256 diff) internal {
+    /// @notice Update the mining information of the shard
+    /// @param _info The mining information of the shard
+    /// @param _mineTime The mined time of the next block
+    /// @param _diff The difficulty of the next block
+    function update(MiningInfo storage _info, uint256 _mineTime, uint256 _diff) internal {
         // A block is mined!
-        info.blockMined = info.blockMined + 1;
-        info.difficulty = diff;
-        info.lastMineTime = mineTime;
+        _info.blockMined = _info.blockMined + 1;
+        _info.difficulty = _diff;
+        _info.lastMineTime = _mineTime;
     }
 }

contracts/libraries/RandaoLib.sol

@@ -3,13 +3,18 @@ pragma solidity ^0.8.0;
 
 import "./RLPReader.sol";
 
+/// @title RandaoLib
+/// @notice Handles Randao related operations
 library RandaoLib {
     using RLPReader for RLPReader.RLPItem;
     using RLPReader for RLPReader.Iterator;
     using RLPReader for bytes;
 
-    function getRandaoFromHeader(RLPReader.RLPItem memory item) pure internal returns (bytes32) {
-        RLPReader.Iterator memory iterator = item.iterator();
+    /// @notice Get the Randao mixDigest from the header
+    /// @param _item The RLP data of the header
+    /// @return The Randao mixDigest
+    function getRandaoFromHeader(RLPReader.RLPItem memory _item) internal pure returns (bytes32) {
+        RLPReader.Iterator memory iterator = _item.iterator();
         // mixDigest is at item 13 (0-base index)
         for (uint256 i = 0; i < 13; i++) {
             iterator.next();
@@ -18,15 +23,29 @@ library RandaoLib {
         return bytes32(iterator.next().toUint());
     }
 
-    function verifyHeaderAndGetRandao(bytes32 headerHash, bytes memory headerRlpBytes) pure internal returns (bytes32) {
-        RLPReader.RLPItem memory item = headerRlpBytes.toRlpItem();
-        require(headerHash == item.rlpBytesKeccak256(), "header hash mismatch");
+    /// @notice Verify the header hash and get the Randao mixDigest
+    /// @param _headerHash The hash of the header
+    /// @param _headerRlpBytes The RLP data of the header
+    /// @return The Randao mixDigest
+    function verifyHeaderAndGetRandao(
+        bytes32 _headerHash,
+        bytes memory _headerRlpBytes
+    ) internal pure returns (bytes32) {
+        RLPReader.RLPItem memory item = _headerRlpBytes.toRlpItem();
+        require(_headerHash == item.rlpBytesKeccak256(), "RandaoLib: header hash mismatch");
         return getRandaoFromHeader(item);
     }
 
-    function verifyHistoricalRandao(uint256 blockNumber, bytes memory headerRlpBytes) view internal returns (bytes32) {
-        bytes32 bh = blockhash(blockNumber);
-        require(bh != bytes32(0), "failed to obtain blockhash");
-        return verifyHeaderAndGetRandao(bh, headerRlpBytes);
-    }    
-}
+    /// @notice Get the historical Randao mixDigest by block number
+    /// @param _blockNumber The block number
+    /// @param _headerRlpBytes The RLP data of the header
+    /// @return The Randao mixDigest
+    function verifyHistoricalRandao(
+        uint256 _blockNumber,
+        bytes memory _headerRlpBytes
+    ) internal view returns (bytes32) {
+        bytes32 bh = blockhash(_blockNumber);
+        require(bh != bytes32(0), "RandaoLib: failed to obtain blockhash");
+        return verifyHeaderAndGetRandao(bh, _headerRlpBytes);
+    }
+}