Add solidity-docgen

contracts/stableCoin/MintNewVotingTokensForStableCoinFunctionality.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity 0.7.0;
+pragma solidity ^0.6.0;
 
 /**
  * @title Mint Voting Tokens (unifi) by burning Stable Coin (uSD) // DOCUMENT

contracts/stableCoin/standalone/Address.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 /**
  * @dev Collection of functions related to the address type

contracts/stableCoin/standalone/Context.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 /**
  * @dev Provides information about the current execution context, including the

contracts/stableCoin/standalone/ERC20.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 import "./Context.sol";
 import "./IERC20.sol";

contracts/stableCoin/standalone/IERC20.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 /**
  * @dev Interface of the ERC20 standard as defined in the EIP.

contracts/stableCoin/standalone/IStableCoin.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 /**
  * @title Interface for the "uSD" AKA "uniswap State Dollar", Unifi stablecoin.
@@ -33,46 +33,46 @@ interface IStableCoin {
     // |------------------------------------------------------------------------------------------|
 
     /**
-     * @return All tiers of data of the carried context
+     * @return Array of allowed Uniswap pairs
      */
-    function tierData() external view returns (uint256[] memory, uint256[] memory);
+    function allowedPairs() external view returns (address[] memory);
 
     /**
      * @return The amount of available mintable token
      */
     function availableToMint() external view returns (uint256);
 
+    // DOCUMENT
+    function differences() external view returns (uint256, uint256);
+
     /**
      * @return The address for the doubleProxy smart contract
      */
     function doubleProxy() external view returns (address);
 
     /**
-     * @return Array of allowed Uniswap pairs
+     * @return The multiplier used to compute the rebalancing rewards
      */
-    function allowedPairs() external view returns (address[] memory);
-
-    // DOCUMENT
-    function differences() external view returns (uint256, uint256);
+    function rebalanceRewardMultiplier() external view returns (uint256[] memory);
 
     /**
-     * @return The multiplier used to compute the rebalancing rewards
+     * @return All tiers of data of the carried context
      */
-    function rebalanceRewardMultiplier() external view returns (uint256[] memory);
+    function tierData() external view returns (uint256[] memory, uint256[] memory);
 
     // |------------------------------------------------------------------------------------------|
     // | ----- SETTERS ----- |
     // |------------------------------------------------------------------------------------------|
 
     /**
-     * @param newDoubleProxy new DoubleProxy to set
+     * @param newAllowedPairs list of Uniswap pairs to be whitelisted
      */
-    function setDoubleProxy(address newDoubleProxy) external;
+    function setAllowedPairs(address[] calldata newAllowedPairs) external;
 
     /**
-     * @param newAllowedPairs list of Uniswap pairs to be whitelisted
+     * @param newDoubleProxy new DoubleProxy to set
      */
-    function setAllowedPairs(address[] calldata newAllowedPairs) external;
+    function setDoubleProxy(address newDoubleProxy) external;
 
     // |------------------------------------------------------------------------------------------|
     // | ----- CORE FUNCTIONS ----- |
@@ -112,11 +112,13 @@ interface IStableCoin {
      *
      * @param pairIndex Index of the pair inside the allowedPairs array
      * @param amountA The amount of tokenA to add as liquidity if the B/A price is <=
-     *  amountBDesired/amountADesired (A depreciates).
+     *  amountBDesired/amountADesired (A depreciates)
      * @param amountB The amount of tokenB to add as liquidity if the A/B price is <=
-     *  amountADesired/amountBDesired (B depreciates).
-     * @param amountAMin Bounds the extent to which the B/A price can go up before the transaction reverts. Must be <= amountADesired.
-     * @param amountBMin Bounds the extent to which the A/B price can go up before the transaction reverts. Must be <= amountBDesired.
+     *  amountADesired/amountBDesired (B depreciates)
+     * @param amountAMin Bounds the extent to which the B/A price can go up before the transaction reverts.
+     *  Must be <= amountADesired
+     * @param amountBMin Bounds the extent to which the A/B price can go up before the transaction reverts.
+     *  Must be <= amountBDesired
      *
      * =====
      *
@@ -154,14 +156,20 @@ interface IStableCoin {
     ) external returns (uint256 amountA, uint256 amountB);
 
     /**
-     * @dev // DOCUMENT
+     * @dev Rebalance by Credit is triggered when the total amount of source tokens is greater
+     * than uSD circulating supply. Rebalancing is done by withdrawing the excess from the pool.
+     *
+     * =====
+     *
+     * @notice Positive imbalances can be caused by the accrual of liquidity provider fee. Withdrawn tokens
+     * are stored inside the Unifi DFO as a source of long-term value
      */
     function rebalanceByCredit(
         uint256 pairIndex,
         uint256 pairAmount,
-        uint256 amount0,
-        uint256 amount1
-    ) external returns (uint256);
+        uint256 amountA,
+        uint256 amountB
+    ) external returns (uint256 redeemed);
 
     /**
      * @dev // DOCUMENT

contracts/stableCoin/standalone/SafeMath.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 /**
  * @dev Wrappers over Solidity's arithmetic operations with added overflow

contracts/stableCoin/standalone/StableCoin.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.7.0;
+pragma solidity ^0.6.0;
 
 import "./ERC20.sol";
 import "./IStableCoin.sol";
@@ -44,8 +44,7 @@ contract StableCoin is ERC20, IStableCoin {
         uint256[] memory rebalanceRewardMultiplier,
         uint256[] memory timeWindows,
         uint256[] memory mintables
-    ) {
-        // DOCUMENT
+    ) public {
         if (doubleProxy == address(0)) {
             return;
         }
@@ -90,8 +89,8 @@ contract StableCoin is ERC20, IStableCoin {
     /**
      * @inheritdoc IStableCoin
      */
-    function tierData() public override view returns (uint256[] memory, uint256[] memory) {
-        return (_timeWindows, _mintables);
+    function allowedPairs() public override view returns (address[] memory) {
+        return _allowedPairs;
     }
 
     /**
@@ -111,6 +110,20 @@ contract StableCoin is ERC20, IStableCoin {
         return minted >= mintable ? 0 : mintable - minted;
     }
 
+    /**
+     * @inheritdoc IStableCoin
+     */
+    function differences() public override view returns (uint256 credit, uint256 debt) {
+        uint256 totalSupply = totalSupply();
+        uint256 effectiveAmount = 0;
+        for (uint256 i = 0; i < _allowedPairs.length; i++) {
+            (uint256 amount0, uint256 amount1) = _getPairAmount(i);
+            effectiveAmount += (amount0 + amount1);
+        }
+        credit = effectiveAmount > totalSupply ? effectiveAmount - totalSupply : 0;
+        debt = totalSupply > effectiveAmount ? totalSupply - effectiveAmount : 0;
+    }
+
     /**
      * @inheritdoc IStableCoin
      */
@@ -128,21 +141,14 @@ contract StableCoin is ERC20, IStableCoin {
     /**
      * @inheritdoc IStableCoin
      */
-    function allowedPairs() public override view returns (address[] memory) {
-        return _allowedPairs;
+    function tierData() public override view returns (uint256[] memory, uint256[] memory) {
+        return (_timeWindows, _mintables);
     }
 
     // |------------------------------------------------------------------------------------------|
     // | ----- SETTERS ----- |
     // |------------------------------------------------------------------------------------------|
 
-    /**
-     * @inheritdoc IStableCoin
-     */
-    function setDoubleProxy(address newDoubleProxy) public override _byCommunity {
-        _doubleProxy = newDoubleProxy;
-    }
-
     /**
      * @inheritdoc IStableCoin
      */
@@ -153,17 +159,14 @@ contract StableCoin is ERC20, IStableCoin {
     /**
      * @inheritdoc IStableCoin
      */
-    function differences() public override view returns (uint256 credit, uint256 debt) {
-        uint256 totalSupply = totalSupply();
-        uint256 effectiveAmount = 0;
-        for (uint256 i = 0; i < _allowedPairs.length; i++) {
-            (uint256 amount0, uint256 amount1) = _getPairAmount(i);
-            effectiveAmount += (amount0 + amount1);
-        }
-        credit = effectiveAmount > totalSupply ? effectiveAmount - totalSupply : 0;
-        debt = totalSupply > effectiveAmount ? totalSupply - effectiveAmount : 0;
+    function setDoubleProxy(address newDoubleProxy) public override _byCommunity {
+        _doubleProxy = newDoubleProxy;
     }
 
+    // |------------------------------------------------------------------------------------------|
+    // | ----- CORE FUNCTIONS ----- |
+    // |------------------------------------------------------------------------------------------|
+
     /**
      * @inheritdoc IStableCoin
      */
@@ -264,13 +267,16 @@ contract StableCoin is ERC20, IStableCoin {
     }
 
     /**
+     * @dev Rebalance by Credit is triggered when the total amount of source tokens is greater
+     * than uSD circulating supply. Rebalancing is done by withdrawing the excess from the pool.
+     *
      * @inheritdoc IStableCoin
      */
     function rebalanceByCredit(
         uint256 pairIndex,
         uint256 pairAmount,
-        uint256 amount0,
-        uint256 amount1
+        uint256 amountA,
+        uint256 amountB
     ) public override _forAllowedPair(pairIndex) returns (uint256 redeemed) {
         // NOTE: Use DFO Protocol to check for authorization
         require(
@@ -284,18 +290,18 @@ contract StableCoin is ERC20, IStableCoin {
         );
         _lastRedeemBlock = block.number;
         (uint256 credit, ) = differences();
-        (address token0, address token1, address pairAddress) = _getPairData(pairIndex);
+        (address tokenA, address tokenB, address pairAddress) = _getPairData(pairIndex);
         _checkAllowance(pairAddress, pairAmount);
         (uint256 removed0, uint256 removed1) = IUniswapV2Router(UNISWAP_V2_ROUTER).removeLiquidity(
-            token0,
-            token1,
+            tokenA,
+            tokenB,
             pairAmount,
-            amount0,
-            amount1,
+            amountA,
+            amountB,
             IMVDProxy(IDoubleProxy(_doubleProxy).proxy()).getMVDWalletAddress(),
             block.timestamp + 1000
         );
-        redeemed = fromTokenToStable(token0, removed0) + fromTokenToStable(token1, removed1);
+        redeemed = fromTokenToStable(tokenA, removed0) + fromTokenToStable(tokenB, removed1);
         require(redeemed <= credit, "Cannot redeem given pair amount");
     }
 
@@ -313,6 +319,8 @@ contract StableCoin is ERC20, IStableCoin {
         );
     }
 
+    // -------------------------------------------------------------------------------------------|
+
     /**
      * // DOCUMENT
      */
@@ -335,6 +343,8 @@ contract StableCoin is ERC20, IStableCoin {
         _;
     }
 
+    // -------------------------------------------------------------------------------------------|
+
     /**
      * // DOCUMENT
      */
@@ -374,38 +384,55 @@ contract StableCoin is ERC20, IStableCoin {
     }
 
     /**
-     * @dev Use the Uniswap Protocol to add liquidity to a pool.
+     * @dev Utility Function: Use the Uniswap Router to add liquidity to a pool.
+     *
+     * @param tokenA A pool token
+     * @param tokenB A pool token
+     * @param liquidity The amount of liquidity tokens to remove
+     * @param amountADesired The amount of tokenA to add as liquidity if the B/A price is <=
+     *  amountBDesired/amountADesired (A depreciates).
+     * @param amountBDesired The amount of tokenB to add as liquidity if the A/B price is <=
+     *  amountADesired/amountBDesired (B depreciates).
+     * @param amountAMin Bounds the extent to which the B/A price can go up before the transaction reverts. Must be <= amountADesired.
+     * @param amountBMin Bounds the extent to which the A/B price can go up before the transaction reverts. Must be <= amountBDesired.
+     *
+     * =====
+     *
+     * @return amountA The amount of tokenA sent to the pool
+     * @return amountB The amount of tokenB sent to the pool
+     * @return liquidity The amount of liquidity tokens minted
+     *
      */
     function _createPoolToken(
-        address firstToken,
-        address secondToken,
-        uint256 originalFirstAmount,
-        uint256 originalSecondAmount,
-        uint256 firstAmountMin,
-        uint256 secondAmountMin
+        address tokenA,
+        address tokenB,
+        uint256 amountADesired,
+        uint256 amountBDesired,
+        uint256 amountAMin,
+        uint256 amountBMin
     )
         private
         returns (
-            uint256 firstAmount,
-            uint256 secondAmount,
-            uint256 poolAmount
+            uint256 amountA,
+            uint256 amountB,
+            uint256 liquidity
         )
     {
-        (firstAmount, secondAmount, poolAmount) = IUniswapV2Router(UNISWAP_V2_ROUTER).addLiquidity(
-            firstToken,
-            secondToken,
-            originalFirstAmount,
-            originalSecondAmount,
-            firstAmountMin,
-            secondAmountMin,
+        (amountA, amountB, liquidity) = IUniswapV2Router(UNISWAP_V2_ROUTER).addLiquidity(
+            tokenA,
+            tokenB,
+            amountADesired,
+            amountBDesired,
+            amountAMin,
+            amountBMin,
             address(this),
             block.timestamp + 1000
         );
-        if (firstAmount < originalFirstAmount) {
-            IERC20(firstToken).transfer(msg.sender, originalFirstAmount - firstAmount);
+        if (amountA < amountADesired) {
+            IERC20(tokenA).transfer(msg.sender, amountADesired - amountA);
         }
-        if (secondAmount < originalSecondAmount) {
-            IERC20(secondToken).transfer(msg.sender, originalSecondAmount - secondAmount);
+        if (amountB < amountBDesired) {
+            IERC20(tokenB).transfer(msg.sender, amountBDesired - amountB);
         }
     }