Prepare for py-solidity-docgen integration

.gitignore

@@ -2,6 +2,7 @@
 /**/spa/**/style.css
 
 docs/md-build
+docs/tmp
 
 # Created by https://www.toptal.com/developers/gitignore/api/python,solidity,visualstudiocode,react
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,solidity,visualstudiocode,react

CONTRIBUTING.md

@@ -28,11 +28,11 @@
 New addition to the codebase must be fully documented.
 
 - JavaScript portions of the code should be annotated using JSDoc style docstrings.
-- Solidity portions of the code should be fully annotated using [NatSpec] and [Solidity Domain for Sphinx].
+- Solidity portions of the code should be fully annotated using [NatSpec].
 
-Documentation is generated using [solidity-docgen] and rendered via [mkdocs].
-[solidity-docgen] parses NatSpec and outputs `.md` files inside `docs/md-build` according
-to an Handlebars template located at `docs/solidity-docgen-templates/contract.hbs`.
+Documentation is generated using [py-solidity-docgen] and rendered via [mkdocs].
+[py-solidity-docgen] parses NatSpec and outputs `.md` files inside `docs/md-build` according
+to a pre-specified Jinja2 template.
 
 **NOTE:** Each `.sol` file should contain only one `Interface` or `Contract`.
 
@@ -50,7 +50,7 @@ yarn docs:serve
 
 ### mkdocs
 
-To install [mkdocs] Python must be installed in the system.
+To install [mkdocs] and [py-solidity-docgen] Python must be installed in the system.
 
 ```
 pip install docs/requirements.in
@@ -63,5 +63,5 @@ pip install docs/requirements.in
 [Solidity Styleguide]: https://solidity.readthedocs.io/en/v0.7.0/style-guide.html
 [NatSpec]: https://solidity.readthedocs.io/en/v0.7.0/style-guide.html#natspec
 [Write the Docs!]: docs/source/write_the_docs.rst
-[solidity-docgen]: https://github.com/OpenZeppelin/solidity-docgen
+[py-solidity-docgen]: https://github.com/b-u-i-d-l/py-solidity-docgen
 [mkdocs]: https://www.mkdocs.org/

contracts/stableCoin/farming/IUnifiedStableFarming.sol

@@ -2,6 +2,10 @@
 
 pragma solidity >=0.7.0 <0.8.0;
 
+/**
+ * @title UnifiedStableFarming
+ * @dev Arbitrage helper
+ */
 interface IUnifiedStableFarming {
     function percentage() external view returns (uint256[] memory);
 
@@ -51,3 +55,73 @@ interface IUnifiedStableFarming {
         uint256[] calldata stableCoinAmounts
     ) external;
 }
+
+interface IStableCoin {
+    function allowedPairs() external view returns (address[] memory);
+
+    function fromTokenToStable(address tokenAddress, uint256 amount)
+        external
+        view
+        returns (uint256);
+
+    function mint(
+        uint256 pairIndex,
+        uint256 amount0,
+        uint256 amount1,
+        uint256 amount0Min,
+        uint256 amount1Min
+    ) external returns (uint256);
+
+    function burn(
+        uint256 pairIndex,
+        uint256 pairAmount,
+        uint256 amount0,
+        uint256 amount1
+    ) external returns (uint256, uint256);
+}
+
+interface IUniswapV2Pair {
+    function token0() external view returns (address);
+
+    function token1() external view returns (address);
+}
+
+interface IUniswapV2Router02 {
+    function WETH() external pure returns (address);
+
+    function getAmountsOut(uint256 amountIn, address[] calldata path)
+        external
+        view
+        returns (uint256[] memory amounts);
+
+    function swapExactTokensForTokens(
+        uint256 amountIn,
+        uint256 amountOutMin,
+        address[] calldata path,
+        address to,
+        uint256 deadline
+    ) external returns (uint256[] memory amounts);
+
+    function swapExactETHForTokens(
+        uint256 amountOutMin,
+        address[] calldata path,
+        address to,
+        uint256 deadline
+    ) external payable returns (uint256[] memory amounts);
+}
+
+interface IERC20 {
+    function balanceOf(address account) external view returns (uint256);
+
+    function transfer(address recipient, uint256 amount) external returns (bool);
+
+    function allowance(address owner, address spender) external view returns (uint256);
+
+    function approve(address spender, uint256 amount) external returns (bool);
+
+    function transferFrom(
+        address sender,
+        address recipient,
+        uint256 amount
+    ) external returns (bool);
+}

contracts/stableCoin/farming/UnifiedStableFarming.sol

@@ -1,20 +1,18 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity >=0.7.0 <0.8.0;
+pragma solidity ^0.7.0;
 
 import "./IUnifiedStableFarming.sol";
-import "../standalone/IStableCoin.sol";
-import "@uniswap/v2-core/contracts/interfaces/IUniswapV2Pair.sol";
-import "@uniswap/v2-periphery/contracts/interfaces/IUniswapV2Router02.sol";
 
 contract UnifiedStableFarming is IUnifiedStableFarming {
-    address private constant UNISWAP_V2_ROUTER = 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D;
+    address
+        private constant UNISWAP_V2_ROUTER = 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D;
 
     address private WETH_ADDRESS;
 
     uint256[] private _percentage;
 
-    constructor(uint256[] memory percentage) public {
+    constructor(uint256[] memory percentage) {
         WETH_ADDRESS = IUniswapV2Router02(UNISWAP_V2_ROUTER).WETH();
         assert(percentage.length == 2);
         _percentage = percentage;
@@ -42,7 +40,12 @@ contract UnifiedStableFarming is IUnifiedStableFarming {
         uint256 realTokenValue = tokenAddress == WETH_ADDRESS ? msg.value : tokenValue;
         _swap(tokenAddress, stableCoinAddress, realTokenValue, address(this));
         // Swap stablecoin for $uSD
-        IStableCoin(stableCoinAddress).burn(pairIndex, pairAmount, amountAMin, amountBMin);
+        IStableCoin(stableCoinAddress).burn(
+            pairIndex,
+            pairAmount,
+            amountAMin,
+            amountBMin
+        );
         (address tokenA, address tokenB, ) = _getPairData(stableCoinAddress, pairIndex);
         // Send the tokens back to their owner
         _flushToSender(tokenA, tokenB, stableCoinAddress, address(0));
@@ -77,7 +80,13 @@ contract UnifiedStableFarming is IUnifiedStableFarming {
             amountB
         );
         // Mint $uSD
-        IStableCoin(stableCoinAddress).mint(pairIndex, amountA, amountB, amountAMin, amountBMin);
+        IStableCoin(stableCoinAddress).mint(
+            pairIndex,
+            amountA,
+            amountB,
+            amountAMin,
+            amountBMin
+        );
         // For each of the chosen output pair swap $uSD to obtain the desired amount of stablecoin
         for (uint256 i = 0; i < tokenIndices.length; i++) {
             _swap(
@@ -204,7 +213,7 @@ contract UnifiedStableFarming is IUnifiedStableFarming {
         path[1] = tokenOut;
         if (path[0] == WETH_ADDRESS) {
             return
-                uniswapV2Router.swapExactETHForTokens{value: amountIn}(
+                uniswapV2Router.swapExactETHForTokens{ value: amountIn }(
                     uniswapV2Router.getAmountsOut(amountIn, path)[1],
                     path,
                     receiver,

contracts/stableCoin/microservices/MintNewVotingTokensForStableCoinFunctionality.sol

@@ -1,42 +1,29 @@
-/* Discussion:
- * https://github.com/b-u-i-d-l/unifi
- */
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.7.0 <0.8.0;
 
 /* Description:
- * When a stablecoin loses value, the Uniswap Tier pools rebalance to an uneven disparity (≠ 50/50).
- * If the stablecoin totally fails, the other stablecoins effectively pump in correlation.
+ * When a stablecoin loses value, the Uniswap Tier pools rebalance to an uneven disparity (≠ 50/50). If the stablecoin totally fails, the other stablecoins effectively pump in correlation.
  *
- * DFO Debit resolves this issue on-chain by rebalancing uSD, creating debt which the UniFi DFO
- * then pays off by minting UniFi. Let’s look at how this plays out, step by step:
+ * DFO Debit resolves this issue on-chain by rebalancing uSD, creating debt which the UniFi DFO then pays off by minting UniFi. Let’s look at how this plays out, step by step:
  *
  * 1 - A stablecoin collateralized by uSD loses value or fails altogether.
  *
- * 2 - $UniFi holders vote to remove the tiers containing the failed stablecoin from the whitelist.
- * The uSD supply becomes grater than the supply of the collateralized pooled stablecoins.
+ * 2 - $UniFi holders vote to remove the tiers containing the failed stablecoin from the whitelist.The uSD supply becomes grater than the supply of the collateralized pooled stablecoins.
  *
- * 3 - To restore 1:1 equilibrium, anyone holding uSD can burn it to receive new UniFi, minted at a
- * 50% discount of the uSD/UniFi Uniswap pool mid-price ratio.
+ * 3 - To restore 1:1 equilibrium, anyone holding uSD can burn it to receive new UniFi, minted at a 50% discount of the uSD/UniFi Uniswap pool mid-price ratio.
  *
- * The goal of $UniFi holders, which aligns with their self-interest, is to ensure uSD's security.
- * Thus there is an economic disincentive to whitelist insecure stablecoins.
+ * The goal of $UniFi holders, which aligns with their self-interest, is to ensure uSD’s security. Thus there is an economic disincentive to whitelist insecure stablecoins.
  */
-// SPDX-License-Identifier: MIT
-
-pragma solidity >=0.7.0 <0.8.0;
-
-import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
-
-import "./IMVDFunctionalitiesManager.sol";
-import "./IMVDProxy.sol";
-import "./IStateHolder.sol";
 
 /**
  * @title Mint Voting Tokens ($unifi) by burning Stable Coin ($uSD)
  * @dev This contract adds unifi minting capabilities to uSD
  */
 contract MintNewVotingTokensForStableCoinFunctionality {
     function onStart(address, address) public {
-        IStateHolder stateHolder = IStateHolder(IMVDProxy(msg.sender).getStateHolderAddress());
+        IStateHolder stateHolder = IStateHolder(
+            IMVDProxy(msg.sender).getStateHolderAddress()
+        );
         address stablecoinauthorized = 0x44086035439E676c02D411880FcCb9837CE37c57;
         stateHolder.setBool(
             _toStateHolderKey("stablecoin.authorized", _toString(stablecoinauthorized)),
@@ -45,7 +32,9 @@ contract MintNewVotingTokensForStableCoinFunctionality {
     }
 
     function onStop(address) public {
-        IStateHolder stateHolder = IStateHolder(IMVDProxy(msg.sender).getStateHolderAddress());
+        IStateHolder stateHolder = IStateHolder(
+            IMVDProxy(msg.sender).getStateHolderAddress()
+        );
         address stablecoinauthorized = 0x44086035439E676c02D411880FcCb9837CE37c57;
         stateHolder.clear(
             _toStateHolderKey("stablecoin.authorized", _toString(stablecoinauthorized))
@@ -105,8 +94,53 @@ contract MintNewVotingTokensForStableCoinFunctionality {
     function _toLowerCase(string memory str) private pure returns (string memory) {
         bytes memory bStr = bytes(str);
         for (uint256 i = 0; i < bStr.length; i++) {
-            bStr[i] = bStr[i] >= 0x41 && bStr[i] <= 0x5A ? bytes1(uint8(bStr[i]) + 0x20) : bStr[i];
+            bStr[i] = bStr[i] >= 0x41 && bStr[i] <= 0x5A
+                ? bytes1(uint8(bStr[i]) + 0x20)
+                : bStr[i];
         }
         return string(bStr);
     }
 }
+
+interface IMVDProxy {
+    function getToken() external view returns (address);
+
+    function getStateHolderAddress() external view returns (address);
+
+    function getMVDFunctionalitiesManagerAddress() external view returns (address);
+
+    function transfer(
+        address receiver,
+        uint256 value,
+        address token
+    ) external;
+
+    function flushToWallet(
+        address tokenAddress,
+        bool is721,
+        uint256 tokenId
+    ) external;
+}
+
+interface IMVDFunctionalitiesManager {
+    function isAuthorizedFunctionality(address functionality)
+        external
+        view
+        returns (bool);
+}
+
+interface IStateHolder {
+    function clear(string calldata varName)
+        external
+        returns (string memory oldDataType, bytes memory oldVal);
+
+    function setBool(string calldata varName, bool val) external returns (bool);
+
+    function getBool(string calldata varName) external view returns (bool);
+}
+
+interface IERC20 {
+    function mint(uint256 amount) external;
+
+    function balanceOf(address account) external view returns (uint256);
+}