Add: natspec for contract declarations

meTokens · Apr 16, 2021 · bf25039 · bf25039
1 parent 46fee5e
commit bf25039
Show file tree

Hide file tree

Showing 15 changed files with 72 additions and 78 deletions.
diff --git a/contracts/curves/BancorZeroFormula.sol b/contracts/curves/BancorZeroFormula.sol
@@ -2,14 +2,11 @@ pragma solidity ^0.8.0;
 
 import "../utils/Power.sol";
 
-/**
-* @title Bancor formula by Bancor
-* @dev Modified from the original by Slava Balasanov
-* https://github.com/bancorprotocol/contracts
-* Split Power.sol out from BancorFormula.sol and replace SafeMath formulas with zeppelin's SafeMath
-* Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements;
-* and to You under the Apache License, Version 2.0. "
-*/
+/// @title Bancor formula by Bancor
+/// @author Carl Farterson (@carlfarterson), originally by Slava Blasanov
+/// @notice All private methods used for BancorZeroValueSet.sol
+/// Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements;
+/// and to You under the Apache License, Version 2.0. "
 contract BancorZeroFormula is Power {
 
    uint32 public MAX_WEIGHT = 1000000;

diff --git a/contracts/curves/BancorZeroValueSet.sol b/contracts/curves/BancorZeroValueSet.sol
@@ -4,6 +4,10 @@ import "./BancorZeroFormula.sol";
 
 // example of a contract `curves.libraryParameterSet` that can be registered in CurveRegistry.sol
 // specifically paired with BancorFormulaFromZero.sol
+
+/// @title Bancor curve registry and calculator
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Uses BancorZeroFormula.sol for private methods
 contract BancorZeroFormulaValues is BancorZeroFormula {
 
     // NOTE: each valueSet is for a curve

diff --git a/contracts/curves/SigmoidalFormula.sol b/contracts/curves/SigmoidalFormula.sol
@@ -1,5 +1,8 @@
 pragma solidity ^0.8.0;
 
+/// @title Sigmoidal curve private methods
+/// @author Carl Farterson (@carlfarterson)
+/// @notice All private methods used for SigmoidalValueSet.sol
 contract SigmoidalFormula {
 
 }
diff --git a/contracts/curves/SigmoidalValueSet.sol b/contracts/curves/SigmoidalValueSet.sol
@@ -1,8 +1,10 @@
-// example of a contract `curves.libraryParameterSet` that can be registered in CurveRegistry.sol
-// specifically paired with BancorFormulaFromZero.sol
+pragma solidity ^0.8.0;
 
 import "./SigmoidalFormula.sol";
 
+/// @title Sigmoidal curve registry and calculator
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Uses SigmoidalFormula.sol for private methods
 contract SigmoidalValues is SigmoidalFormula {
 
     struct ValueSet{

diff --git a/contracts/factories/MeTokenFactory.sol b/contracts/factories/MeTokenFactory.sol
@@ -3,7 +3,9 @@ pragma solidity ^0.8.0;
 import "../MeToken.sol";
 import "../interfaces/I_MeTokenRegistry.sol";
 
-
+/// @title meToken factory
+/// @author Carl Farterson (@carlfarterson)
+/// @notice This contract creates and deploys a users' meToken
 contract MeTokenFactory {
 
     I_MeTokenRegistry public meTokenRegistry;

diff --git a/contracts/factories/VaultFactories/SingleAssetFactory.sol b/contracts/factories/VaultFactories/SingleAssetFactory.sol
@@ -3,14 +3,16 @@ pragma solidity ^0.8.0;
 import "../../vaults/SingleAsset.sol";
 import "../../interfaces/I_VaultRegistry.sol";
 
-
+/// @title Factory contract to erc20-collateral vaults
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Deploys a single collateral vault (non-LP token)
 contract SingleAssetFactory {
 
     I_VaultRegistry public vaultRegistry;
     Vault public vault;
 
-    constructor(address _vaultRegistry) public {
-        require(_vaultRegistry != address(0), "Cannot be 0 address");
+    constructor(address _hub, address _vaultRegistry) public {
+        hub = _hub;
         vaultRegistry = _vaultRegistry;
     }
 
@@ -20,15 +22,10 @@ contract SingleAssetFactory {
         address _owner,
         uint256 _hub,
         address _valueSetAddress,
-        // address[] _collateralAssets[], // TODO
-        bytes4 _encodedVaultAdditionalArgs // NOTE: this is _refundRatio and _collateralAsset hashed
+        address _collateralAsset,
+        bytes4 _encodedVaultAdditionalArgs // NOTE: this is _refundRatio, base_x, & base_y
     ) public returns (address) {
 
-        require(
-            _collateralAssets.length > 0 && _collateralAssets.length <= MAX_NUM_COLLATERAL_ASSETS, 
-            "Invalid number of collateral assets"
-        );
-
         // create our vault
         // TODO: create2 shit
         Vault memory vault = new Vault_SingleAsset();

diff --git a/contracts/migrations/EXAMPLE - MigrationVault_SingleAsset_to_SingleAsset.sol b/contracts/migrations/EXAMPLE - MigrationVault_SingleAsset_to_SingleAsset.sol
@@ -1,3 +1,9 @@
+pragma solidity ^0.8.0;
+
+/// @title Vault migrator from erc20 to erc20 (non-lp)
+/// @author Carl Farterson (@carlfarterson)
+/// @notice This contract moves the pooled/locked balances from
+///     one erc20 to another
 contract MigrationVault_SingleAsset_to_SingleAsset {
 
 }
diff --git a/contracts/registries/CurveRegistry.sol b/contracts/registries/CurveRegistry.sol
@@ -1,5 +1,8 @@
 pragma solidity ^0.8.0;
 
+/// @title Curve registry
+/// @author Carl Farterson (@carlfarterson)
+/// @notice This contract keeps track of active curve types and their base values
 contract CurveRegistry {
 
     event RegisterCurve(string name, address formula, address values);

diff --git a/contracts/registries/HubRegistry.sol b/contracts/registries/HubRegistry.sol
@@ -7,6 +7,10 @@ import "../interfaces/I_CurveValueSet.sol";
 import "../interfaces/I_Vault.sol";
 
 
+/// @title meToken hub
+/// @author Carl Farterson (@carlfarterson)
+/// @notice This contract tracks all combinations of vaults and curves,
+///     and their respective subscribed meTokens 
 contract HubRegistry {
 
     event RegisterHub(string name, address indexed vault);  // TODO: decide on arguments
@@ -163,6 +167,7 @@ contract HubRegistry {
         );
 
         // TODO: Update balance pooled
+
 
         I_MeToken(_meToken).transfer(fees.feeRecipient(), fee);
         I_MeToken(_meToken).burn(msg.sender, meTokensBurnedAfterFees);

diff --git a/contracts/registries/MeTokenRegistry.sol b/contracts/registries/MeTokenRegistry.sol
@@ -5,6 +5,9 @@ import "../interfaces/I_MeTokenFactory.sol";
 import "../interfaces/I_HubRegistry.sol";
 
 
+/// @title meToken registry
+/// @author Carl Farterson (@carlfarterson)
+/// @notice This contract tracks basic information about all meTokens
 contract MeTokenRegistry{
 
     event RegisterMeToken(
@@ -14,8 +17,6 @@ contract MeTokenRegistry{
         string symbol,
         uint256 hub
     );
-    // event ApproveCollateralAsset(address asset);
-    // event UnapproveCollateralAsset(address asset);
 
     I_MeTokenFactory public meTokenFactory;
     I_HubRegistry public hubRegistry;
@@ -69,56 +70,15 @@ contract MeTokenRegistry{
         return meTokenOwners[_owner];
     }
 
-    function getMeTokenOwner(address _meToken) external view returns (address) {
-        // TODO: validate MeTokenDetails struct wwill revert for missing meToken address
-        MeTokenDetails memory meTokenDetails = meTokens[_meToken];
-        return meTokenDetails.owner;
-    }
-
     function getMeTokenHub(address _meToken) external view returns (uint256) {
         MeTokenDetails memory meTokenDetails = meTokens[_meToken];
         return meTokenDetails.hub;
     }
 
-    function getMeTokenBalancePooled(address _meToken) external view returns (uint256) {
-        MeTokenDetails memory meTokenDetails = meTokens[_meToken];
-        return meTokenDetails.balancePooled;
-    }
-
-    function getMeTokenBalanceLocked(address _meToken) external view returns (uint256) {
-        MeTokenDetails memory meTokenDetails = meTokens[_meToken];
-        return meTokenDetails.balanceLocked;
-    }
-
-    function isMeTokenMigrating(address _meToken) external view returns (uint256) { 
-        MeTokenDetails memory MeTokenDetails = meTokens[_meToken];
-        return meTokenDetails.migrating;
-    }
-
     function getMeTokenDetails(address _meToken) external view returns (MeTokenDetails calldata) {
         MeTokenDetails memory meTokenDetails = meTokens[_meToken];
         return meTokenDetails;
     }
-
-    /*
-    function approveCollateralAsset(address _asset) external {
-        // TODO: access control
-        require(!approvedCollateralAssets[_asset], "Asset already approved");
-        approvedCollateralAssets[_asset] = true;
-        emit ApproveCollateralAsset(_asset);
-    }
-
-    function unapproveCollateralAsset(address _asset) external {
-        require(approvedCollateralAssets[_asset], "Asset not approved");
-        approvedCollateralAssets[_asset] = false;
-        emit UnapproveCollateralAsset(_asset);
-    }
-
-    function isApprovedCollateralAsset(address _asset) external view returns (bool) {
-        return approvedCollateralAssets[_asset];
-    }
-    */
-
     // TODO
     // function migrate(uint256 meTokenAddress) external onlyOwner(meTokenAddress) returns(bool) {}
 }
diff --git a/contracts/registries/MigrationRegistry.sol b/contracts/registries/MigrationRegistry.sol
@@ -1,5 +1,9 @@
 pragma solidity ^0.8.0;
 
+
+/// @title Migration registry
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Keeps track of all used migration strategies 
 contract MigrationRegistry {
 
 	mapping (uint256 => MigrationDetails) migrations;

diff --git a/contracts/registries/VaultRegistry.sol b/contracts/registries/VaultRegistry.sol
@@ -1,5 +1,9 @@
 pragma solidity ^0.8.0;
 
+
+/// @title vault registry
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Keeps track of all active vaults and available vault factories 
 contract VaultRegistry {
 
     event RegisterVault(string name, address vault, address factory);
@@ -13,14 +17,12 @@ contract VaultRegistry {
     struct VaultDetails {
         string name;
         address factory; // NOTE: references factories/VaultFactories/{}.sol
-        bool active;
+        bool active;  // NOTE: can be inactive after vault migration
     }
 
     // TODO: argument check
     function registerVault(string calldata _name, address _vault, address _factory) external {
         // TODO: access control
-        require(approvedVaultFactories[_factory], "Factory not approved");
-
         // Add vault details to storage
         // TODO: validate memory vs. storage usage
         VaultDetails memory vaultDetails = VaultDetails(_name, _factory, true);

diff --git a/contracts/utils/Power.sol b/contracts/utils/Power.sol
@@ -1,14 +1,8 @@
 pragma solidity ^0.8.0;
 
- /**
- * @title Power function by Bancor
- * @dev https://github.com/bancorprotocol/contracts
- *
- * Modified from the original by Slava Balasanov & Tarrence van As
- *
- * Split Power.sol out from BancorFormula.sol
- * https://github.com/bancorprotocol/contracts/blob/c9adc95e82fdfb3a0ada102514beb8ae00147f5d/solidity/contracts/converter/BancorFormula.sol
- */
+/// @title Power function by Bancor
+/// @dev https://github.com/bancorprotocol/contracts
+/// @notice Modified from the original by Slava Balasanov & Tarrence van As
 contract Power {
   string public version = "0.3";
 

diff --git a/contracts/vaults/SingleAsset.sol b/contracts/vaults/SingleAsset.sol
@@ -12,13 +12,17 @@ import "../interfaces/I_CurveValueSet.sol";
 import "../interfaces/I_ERC20.sol"; // TODO
 import "../interfaces/I_MeToken.sol";
 
-contract SingleAsset is Fees, MeTokenRegistry, HubRegistry, CurveRegistry {
+
+/// @title ERC-20 (non-LP) token vault
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Base single asset vault contract
+/// @dev Only callable by the vault factory
+contract SingleAsset is Vault {
 
     event SetCurve(address curveValueSet);
 
     bytes4 private encodedInitializeFunc = bytes(keccak256("_initialize(uint256,address)"));
 
-    uint256 private PRECISION = 10**18;
     uint256 public id;
     address public owner;
     uint256 public collateralBalance;

diff --git a/contracts/vaults/Vault.sol b/contracts/vaults/Vault.sol
@@ -1,8 +1,16 @@
 pragma solidity ^0.8.0;
 
+
+/// @title Vault
+/// @author Carl Farterson (@carlfarterson)
+/// @notice Base vault contract inherited by all vaults
 contract Vault {
 
+    uint256 private PRECISION = 10**18;
 	address private collateralAsset;
+    bool private initialized;
+
+    event SetCollateralAsset(address asset);
 
     function getCollateralAsset() external view returns (address) {
         return collateralAsset;
@@ -11,4 +19,7 @@ contract Vault {
 	//  TODO - figure out governance of updating the collateralAsset in a vault
 	function setCollateralAsset(address _collateralAsset) public onlyGov {
         require(initialized, "!initialized");
+        require(_collateralAsset != collateralAsset, "Cannot change asset to same asset");
+        collateralAsset = _collateralAsset;
+        emit setCollateralAsset(_collateralAsset);
     }