@venusprotocol/governance-contracts 1.0.1-dev.1 → 1.0.1-dev.2

package/contracts/Governance/AccessControlManager.sol

@@ -4,11 +4,50 @@ import "@openzeppelin/contracts/access/AccessControl.sol";
 import "./IAccessControlManagerV8.sol";
 
 /**
- * @title Venus Access Control Contract
- * @author venus
- * @dev This contract is a wrapper of OpenZeppelin AccessControl
- *		extending it in a way to standartize access control
- *		within Venus Smart Contract Ecosystem
+ * @title AccessControlManager
+ * @author Venus
+ * @dev This contract is a wrapper of OpenZeppelin AccessControl extending it in a way to standartize access control within Venus Smart Contract Ecosystem.
+ * @notice Access control plays a crucial role in the Venus governance model. It is used to restrict functions so that they can only be called from one
+ * account or list of accounts (EOA or Contract Accounts).
+ *
+ * The implementation of `AccessControlManager`(https://github.com/VenusProtocol/governance-contracts/blob/main/contracts/Governance/AccessControlManager.sol)
+ * inherits the [Open Zeppelin AccessControl](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/access/AccessControl.sol)
+ * contract as a base for role management logic. There are two role types: admin and granular permissions.
+ * 
+ * ## Granular Roles
+ * 
+ * Granular roles are built by hashing the contract address and its function signature. For example, given contract `Foo` with function `Foo.bar()` which
+ * is guarded by ACM, calling `giveRolePermission` for account B do the following:
+ * 
+ * 1. Compute `keccak256(contractFooAddress,functionSignatureBar)`
+ * 1. Add the computed role to the roles of account B
+ * 1. Account B now can call `ContractFoo.bar()`
+ * 
+ * ## Admin Roles
+ * 
+ * Admin roles allow for an address to call a function signature on any contract guarded by the `AccessControlManager`. This is particularly useful for
+ * contracts created by factories.
+ * 
+ * For Admin roles a null address is hashed in place of the contract address (`keccak256(0x0000000000000000000000000000000000000000,functionSignatureBar)`.
+ * 
+ * In the previous example, giving account B the admin role, account B will have permissions to call the `bar()` function on any contract that is guarded by
+ * ACM, not only contract A.
+ * 
+ * ## Protocol Integration
+ * 
+ * All restricted functions in Venus Protocol use a hook to ACM in order to check if the caller has the right permission to call the guarded function.
+ * `AccessControlledV5` and `AccessControlledV8` abstract contract makes this integration easier. They call ACM's external method
+ * `isAllowedToCall(address caller, string functionSig)`. Here is an example of how `setCollateralFactor` function in `Comptroller` is integrated with ACM:
+
+```
+    contract Comptroller is [...] AccessControlledV8 {
+        [...]
+        function setCollateralFactor(VToken vToken, uint256 newCollateralFactorMantissa, uint256 newLiquidationThresholdMantissa) external {
+            _checkAccessAllowed("setCollateralFactor(address,uint256,uint256)");
+            [...]
+        }
+    }
+```
  */
 contract AccessControlManager is AccessControl, IAccessControlManagerV8 {
     /// @notice Emitted when an account is given a permission to a certain contract function

package/contracts/Governance/AccessControlledV5.sol

@@ -4,12 +4,11 @@ pragma solidity 0.5.16;
 import "./IAccessControlManagerV5.sol";
 
 /**
- * @title Venus Access Control Contract.
- * @dev This contract is helper between access control manager and actual contract
- * This contract further inherited by other contract to integrate access controlled mechanism
- * It provides initialise methods and verifying access methods
+ * @title AccessControlledV5
+ * @author Venus
+ * @notice This contract is helper between access control manager and actual contract. This contract further inherited by other contract (using solidity 0.5.16)
+ * to integrate access controlled mechanism. It provides initialise methods and verifying access methods.
  */
-
 contract AccessControlledV5 {
     /// @notice Access control manager contract
     IAccessControlManagerV5 private _accessControlManager;

package/contracts/Governance/AccessControlledV8.sol

@@ -7,13 +7,11 @@ import "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
 import "./IAccessControlManagerV8.sol";
 
 /**
- * @title Venus Access Control Contract.
- * @dev The AccessControlledV8 contract is a wrapper around the OpenZeppelin AccessControl contract
- *      It provides a standardized way to control access to methods within the Venus Smart Contract Ecosystem.
- *      The contract allows the owner to set an AccessControlManager contract address.
- *      It can restrict method calls based on the sender's role and the method's signature.
+ * @title AccessControlledV8
+ * @author Venus
+ * @notice This contract is helper between access control manager and actual contract. This contract further inherited by other contract (using solidity 0.8.13)
+ * to integrate access controlled mechanism. It provides initialise methods and verifying access methods.
  */
-
 abstract contract AccessControlledV8 is Initializable, Ownable2StepUpgradeable {
     /// @notice Access control manager contract
     IAccessControlManagerV8 private _accessControlManager;

package/contracts/Governance/GovernorBravoDelegate.sol

@@ -3,6 +3,73 @@ pragma experimental ABIEncoderV2;
 
 import "./GovernorBravoInterfaces.sol";
 
+/**
+ * @title GovernorBravoDelegate
+ * @notice Venus Governance latest on chain governance includes several new features including variable proposal routes and fine grained pause control.
+ * Variable routes for proposals allows for governance paramaters such as voting threshold and timelocks to be customized based on the risk level and
+ * impact of the proposal. Added granularity to the pause control mechanism allows governance to pause individual actions on specific markets,
+ * which reduces impact on the protocol as a whole. This is particularly useful when applied to isolated pools.
+ *
+ * The goal of **Governance** is to increase governance efficiency, while mitigating and eliminating malicious or erroneous proposals.
+ *
+ * ## Details
+ *
+ * Governance has **3 main contracts**: **GovernanceBravoDelegate, XVSVault, XVS** token.
+ *
+ * - XVS token is the protocol token used for protocol users to cast their vote on submitted proposals.
+ * - XVSVault is the main staking contract for XVS. Users first stake their XVS in the vault and receive voting power proportional to their staked
+ * tokens that they can use to vote on proposals. Users also can choose to delegate their voting power to other users.
+ *
+ * # Governor Bravo
+ *
+ * `GovernanceBravoDelegate` is main Venus Governance contract. Users interact with it to:
+ * - Submit new proposal
+ * - Vote on a proposal
+ * - Cancel a proposal
+ * - Queue a proposal for execution with a timelock executor contract.
+ * `GovernanceBravoDelegate` uses the XVSVault to get restrict certain actions based on a user's voting power. The governance rules it inforces are:
+ * - A user's voting power must be greater than the `proposalThreshold` to submit a proposal
+ * - If a user's voting power drops below certain amount, anyone can cancel the the proposal. The governance guardian and proposal creator can also
+ * cancel a proposal at anytime before it is queued for execution.
+ *
+ * ## Venus Improvement Proposal
+ *
+ * Venus Governance allows for Venus Improvement Proposals (VIPs) to be categorized based on their impact and risk levels. This allows for optimizing proposals
+ * execution to allow for things such as expediting interest rate changes and quickly updating risk parameters, while moving slower on other types of proposals
+ * that can prevent a larger risk to the protocol and are not urgent. There are three different types of VIPs with different proposal paramters:
+ *
+ * - `NORMAL`
+ * - `FASTTRACK`
+ * - `CRITICAL`
+ *
+ * When initializing the `GovernorBravo` contract, the parameters for the three routes are set. The parameters are:
+ *
+ * - `votingDelay`: The delay in blocks between submitting a proposal and when voting begins
+ * - `votingPeriod`: The number of blocks where voting will be open
+ * - `proposalThreshold`: The number of votes required in order submit a proposal
+ *
+ * There is also a separate timelock executor contract for each route, which is used to dispatch the VIP for execution, giving even more control over the
+ * flow of each type of VIP.
+ *
+ * ## Voting
+ *
+ * After a VIP is proposed, voting is opened after the `votingDelay` has passed. For example, if `votingDelay = 0`, then voting will begin in the next block
+ * after the proposal has been submitted. After the delay, the proposal state is `ACTIVE` and users can cast their vote `for`, `against`, or `abstain`,
+ * weighted by their total voting power (tokens + delegated voting power). Abstaining from a voting allows for a vote to be cast and optionally include a
+ * comment, without the incrementing for or against vote count. The total voting power for the user is obtained by calling XVSVault's `getPriorVotes`.
+ *
+ * `GovernorBravoDelegate` also accepts [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signatures for voting on proposals via the external function
+ * `castVoteBySig`.
+ *
+ * ## Delegating
+ *
+ * A users voting power includes the amount of staked XVS the have staked as well as the votes delegate to them. Delegating is the process of a user loaning
+ * their voting power to another, so that the latter has the combined voting power of both users. This is an important feature because it allows for a user
+ * to let another user who they trust propose or vote in their place.
+ *
+ * The delegation of votes happens through the `XVSVault` contract by calling the `delegate` or `delegateBySig` functions. These same functions can revert
+ * vote delegation by calling the same function with a value of `0`.
+ */
 contract GovernorBravoDelegate is GovernorBravoDelegateStorageV2, GovernorBravoEvents {
     /// @notice The name of this contract
     string public constant name = "Venus Governor Bravo";

package/contracts/Governance/GovernorBravoDelegator.sol

@@ -3,6 +3,11 @@ pragma experimental ABIEncoderV2;
 
 import "./GovernorBravoInterfaces.sol";
 
+/**
+ * @title GovernorBravoDelegator
+ * @author Venus
+ * @notice The `GovernorBravoDelegator` contract.
+ */
 contract GovernorBravoDelegator is GovernorBravoDelegatorStorage, GovernorBravoEvents {
     constructor(
         address timelock_,

package/contracts/Governance/GovernorBravoInterfaces.sol

@@ -1,6 +1,11 @@
 pragma solidity ^0.5.16;
 pragma experimental ABIEncoderV2;
 
+/**
+ * @title GovernorBravoEvents
+ * @author Venus
+ * @notice Set of events emitted by the GovernorBravo contracts.
+ */
 contract GovernorBravoEvents {
     /// @notice An event emitted when a new proposal is created
     event ProposalCreated(
@@ -58,6 +63,11 @@ contract GovernorBravoEvents {
     event ProposalMaxOperationsUpdated(uint oldMaxOperations, uint newMaxOperations);
 }
 
+/**
+ * @title GovernorBravoDelegatorStorage
+ * @author Venus
+ * @notice Storage layout of the `GovernorBravoDelegator` contract
+ */
 contract GovernorBravoDelegatorStorage {
     /// @notice Administrator for this contract
     address public admin;
@@ -70,8 +80,8 @@ contract GovernorBravoDelegatorStorage {
 }
 
 /**
- * @title Storage for Governor Bravo Delegate
- * @notice For future upgrades, do not change GovernorBravoDelegateStorageV1. Create a new
+ * @title GovernorBravoDelegateStorageV1
+ * @dev For future upgrades, do not change GovernorBravoDelegateStorageV1. Create a new
  * contract which implements GovernorBravoDelegateStorageV1 and following the naming convention
  * GovernorBravoDelegateStorageVX.
  */
@@ -167,6 +177,12 @@ contract GovernorBravoDelegateStorageV1 is GovernorBravoDelegatorStorage {
     address public guardian;
 }
 
+/**
+ * @title GovernorBravoDelegateStorageV2
+ * @dev For future upgrades, do not change GovernorBravoDelegateStorageV1. Create a new
+ * contract which implements GovernorBravoDelegateStorageV2 and following the naming convention
+ * GovernorBravoDelegateStorageVX.
+ */
 contract GovernorBravoDelegateStorageV2 is GovernorBravoDelegateStorageV1 {
     enum ProposalType {
         NORMAL,
@@ -190,6 +206,11 @@ contract GovernorBravoDelegateStorageV2 is GovernorBravoDelegateStorageV1 {
     mapping(uint => TimelockInterface) public proposalTimelocks;
 }
 
+/**
+ * @title TimelockInterface
+ * @author Venus
+ * @notice Interface implemented by the Timelock contract.
+ */
 interface TimelockInterface {
     function delay() external view returns (uint);
 

package/contracts/Governance/IAccessControlManagerV5.sol

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.5.16;
 
+/**
+ * @title IAccessControlManagerV5
+ * @author Venus
+ * @notice Interface implemented by the `AccessControlManagerV5` contract.
+ */
 interface IAccessControlManagerV5 {
     /**
      * @dev Emitted when `newAdminRole` is set as ``role``'s admin role, replacing `previousAdminRole`

package/contracts/Governance/IAccessControlManagerV8.sol

@@ -3,6 +3,11 @@ pragma solidity 0.8.13;
 
 import "@openzeppelin/contracts/access/IAccessControl.sol";
 
+/**
+ * @title IAccessControlManagerV8
+ * @author Venus
+ * @notice Interface implemented by the `AccessControlManagerV8` contract.
+ */
 interface IAccessControlManagerV8 is IAccessControl {
     function giveCallPermission(address contractAddress, string calldata functionSig, address accountToPermit) external;
 

package/contracts/Governance/Timelock.sol

@@ -2,6 +2,11 @@ pragma solidity ^0.5.16;
 
 import "../Utils/SafeMath.sol";
 
+/**
+ * @title Timelock
+ * @author Venus
+ * @notice The Timelock contract.
+ */
 contract Timelock {
     using SafeMath for uint;
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@venusprotocol/governance-contracts",
   "description": "",
-  "version": "1.0.1-dev.1",
+  "version": "1.0.1-dev.2",
   "author": "",
   "files": [
     "artifacts",

package/artifacts/@openzeppelin/contracts/access/AccessControl.sol/AccessControl.dbg.json

@@ -1,4 +0,0 @@
-{
-  "_format": "hh-sol-dbg-1",
-  "buildInfo": "../../../../build-info/0ed8a45a04a58741f8391cb7a77f7ff9.json"
-}

package/artifacts/@openzeppelin/contracts/access/AccessControl.sol/AccessControl.json

@@ -1,215 +0,0 @@
-{
-  "_format": "hh-sol-artifact-1",
-  "contractName": "AccessControl",
-  "sourceName": "@openzeppelin/contracts/access/AccessControl.sol",
-  "abi": [
-    {
-      "anonymous": false,
-      "inputs": [
-        {
-          "indexed": true,
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "indexed": true,
-          "internalType": "bytes32",
-          "name": "previousAdminRole",
-          "type": "bytes32"
-        },
-        {
-          "indexed": true,
-          "internalType": "bytes32",
-          "name": "newAdminRole",
-          "type": "bytes32"
-        }
-      ],
-      "name": "RoleAdminChanged",
-      "type": "event"
-    },
-    {
-      "anonymous": false,
-      "inputs": [
-        {
-          "indexed": true,
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "indexed": true,
-          "internalType": "address",
-          "name": "account",
-          "type": "address"
-        },
-        {
-          "indexed": true,
-          "internalType": "address",
-          "name": "sender",
-          "type": "address"
-        }
-      ],
-      "name": "RoleGranted",
-      "type": "event"
-    },
-    {
-      "anonymous": false,
-      "inputs": [
-        {
-          "indexed": true,
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "indexed": true,
-          "internalType": "address",
-          "name": "account",
-          "type": "address"
-        },
-        {
-          "indexed": true,
-          "internalType": "address",
-          "name": "sender",
-          "type": "address"
-        }
-      ],
-      "name": "RoleRevoked",
-      "type": "event"
-    },
-    {
-      "inputs": [],
-      "name": "DEFAULT_ADMIN_ROLE",
-      "outputs": [
-        {
-          "internalType": "bytes32",
-          "name": "",
-          "type": "bytes32"
-        }
-      ],
-      "stateMutability": "view",
-      "type": "function"
-    },
-    {
-      "inputs": [
-        {
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        }
-      ],
-      "name": "getRoleAdmin",
-      "outputs": [
-        {
-          "internalType": "bytes32",
-          "name": "",
-          "type": "bytes32"
-        }
-      ],
-      "stateMutability": "view",
-      "type": "function"
-    },
-    {
-      "inputs": [
-        {
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "internalType": "address",
-          "name": "account",
-          "type": "address"
-        }
-      ],
-      "name": "grantRole",
-      "outputs": [],
-      "stateMutability": "nonpayable",
-      "type": "function"
-    },
-    {
-      "inputs": [
-        {
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "internalType": "address",
-          "name": "account",
-          "type": "address"
-        }
-      ],
-      "name": "hasRole",
-      "outputs": [
-        {
-          "internalType": "bool",
-          "name": "",
-          "type": "bool"
-        }
-      ],
-      "stateMutability": "view",
-      "type": "function"
-    },
-    {
-      "inputs": [
-        {
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "internalType": "address",
-          "name": "account",
-          "type": "address"
-        }
-      ],
-      "name": "renounceRole",
-      "outputs": [],
-      "stateMutability": "nonpayable",
-      "type": "function"
-    },
-    {
-      "inputs": [
-        {
-          "internalType": "bytes32",
-          "name": "role",
-          "type": "bytes32"
-        },
-        {
-          "internalType": "address",
-          "name": "account",
-          "type": "address"
-        }
-      ],
-      "name": "revokeRole",
-      "outputs": [],
-      "stateMutability": "nonpayable",
-      "type": "function"
-    },
-    {
-      "inputs": [
-        {
-          "internalType": "bytes4",
-          "name": "interfaceId",
-          "type": "bytes4"
-        }
-      ],
-      "name": "supportsInterface",
-      "outputs": [
-        {
-          "internalType": "bool",
-          "name": "",
-          "type": "bool"
-        }
-      ],
-      "stateMutability": "view",
-      "type": "function"
-    }
-  ],
-  "bytecode": "0x",
-  "deployedBytecode": "0x",
-  "linkReferences": {},
-  "deployedLinkReferences": {}
-}

package/artifacts/@openzeppelin/contracts/access/IAccessControl.sol/IAccessControl.dbg.json

@@ -1,4 +0,0 @@
-{
-  "_format": "hh-sol-dbg-1",
-  "buildInfo": "../../../../build-info/0ed8a45a04a58741f8391cb7a77f7ff9.json"
-}