address more comments

README.md

@@ -1,23 +1,64 @@
-# sylo-ethereum-contracts
-Smart Contracts used for Sylo Incentivisation
+# Sylo Ethereum Contracts
 
-## Developing
+Smart Contracts used for the Sylo Network Protocol. These contracts
+define the mechanisms for:
+  - The ERC21 Sylo Token
+  - Staking of Sylos against Sylo Node operators
+  - Stake-weighted scan function used to allocate business
+  within the network
+  - Probabilistic Micro-payments for providing the Event Relay
+  Service
+  - Epochs and various network parameters
+
+## Documentation
+
+An [overview](docs/overview.md) is available for the Sylo Network Protocol.
+Additionally, read the [contract specification](docs/spec.md) to
+help understand the implementation of the contracts.
+
+## Development
 
 This project employs [Hardhat](https://hardhat.org/getting-started/) for development and testing.
 
 ### Setup
 
+Ensure Node.js (>=v12.0) is installed.
+
 `npm i`
 
 ### Build
 
 `npm run build`
 
-### Test
+This will compile the contracts and create typechain typescript definitions.
+
+### Running Tests
+
+Testing is done through a local hardhat network.
 
 `npm test`
 
-### Deploying to Ropsten
+Running this will also compile a `gasReport.txt`, which show gas costs
+for each contract call.
+
+#### Coverage
+
+`npm run coverage`
+
+This project attempts to maintain 100% code coverage at all times.
+
+### Deployment
+
+Deployment is supported by the `hardhat.config.ts` configuration. These
+contracts rely on [open-zeppelin's upgrade proxy plugin](https://docs.openzeppelin.com/upgrades-plugins/1.x/) in order to be able to update
+contracts post-deployment.
+
+`npx hardhat run deploy/00_deploy_phase_two.ts` can be used to deploy
+to a local hardhat network.
+
+Deployment configurations will be saved `.openzeppelin/${network}.json`
+
+#### Deploying to Ropsten
 
 Create a `.env` file in the root folder of this project with the following values
 

contracts/Listings.sol

@@ -37,8 +37,8 @@ contract Listings is Initializable, OwnableUpgradeable {
 
     /**
      * @notice Payout percentage refers to the portion of a tickets reward
-     * that will be allocated to the Node's stakers. This global, and is
-     * currently set for all Nodes for phase two.
+     * that will be allocated to the Node's stakers. This is global, and is
+     * currently set for all Nodes.
      */
     uint16 public defaultPayoutPercentage;
 

contracts/Payments/Ticketing.sol

@@ -14,8 +14,8 @@ import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
 import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 
 /**
- * @notice The SyloTicketing contract manages the Micro-Payment
- * Probabilistic Ticketing system that pays Nodes for providing the
+ * @notice The SyloTicketing contract manages the Probabilistic
+ * Micro-Payment Ticketing system that pays Nodes for providing the
  * Event Relay service.
  */
 contract SyloTicketing is Initializable, OwnableUpgradeable {
@@ -42,7 +42,7 @@ contract SyloTicketing is Initializable, OwnableUpgradeable {
         bytes32 redeemerCommit; // Hash of the secret random number of the redeemer
     }
 
-    /** ERC 20 compatible token we are dealing with */
+    /** ERC20 Sylo token contract.*/
     IERC20 public _token;
 
     /** Sylo Listings contract */
@@ -73,7 +73,7 @@ contract SyloTicketing is Initializable, OwnableUpgradeable {
     /** @notice Mapping of user deposits */
     mapping(address => Deposit) public deposits;
 
-    /** @notice Mapping of ticket hashes, used to check if ticket has been redeemed */
+    /** @notice Mapping of ticket hashes, used to check if a ticket has been redeemed */
     mapping (bytes32 => bool) public usedTickets;
 
     function initialize(
@@ -322,7 +322,7 @@ contract SyloTicketing is Initializable, OwnableUpgradeable {
     /**
      * @notice Use this function to check if a ticket is winning.
      * @param sig The signature of the sender of the ticket.
-     * @param ticket The ticket issued by the sender. which holds the various ticketing parameters.
+     * @param ticket The ticket issued by the sender, which holds the various ticketing parameters.
      * @param senderRand The sender random value, revealed on completing an event
      * relay.
      * @param redeemerRand The redeemer random value, generated by the Node prior
@@ -342,7 +342,7 @@ contract SyloTicketing is Initializable, OwnableUpgradeable {
     }
 
     /**
-     * @notice This function calculates that probability of a ticket winning at
+     * @notice This function calculates the probability of a ticket winning at
      * the block that this function was called. A ticket's winning probability
      * will decay every block since its issuance. The amount of decay will depend
      * on the decay rate parameter of the epoch the ticket was generated in.

contracts/Payments/Ticketing/Parameters.sol

@@ -25,7 +25,8 @@ contract TicketingParameters is Initializable, OwnableUpgradeable {
     /**
      * @notice The probability of a ticket winning after it has expired.
      * This is a uint128 value representing the numerator in the probability
-     * ratio where 2^128 - 1 is the denominator.
+     * ratio where 2^128 - 1 is the denominator. Note: Redeeming expired
+     * tickets is currently not supported.
      */
     uint128 public expiredWinProb;
 

contracts/Payments/Ticketing/RewardsManager.sol

@@ -22,7 +22,7 @@ contract RewardsManager is Initializable, OwnableUpgradeable {
     // 64x64 Fixed point representation of 1 SYLO (10**18 >> 64)
     int128 internal constant ONE_SYLO_FIXED = 18446744073709551616000000000000000000;
 
-    /** ERC 20 compatible token we are dealing with */
+    /** ERC20 Sylo token contract. */
     IERC20 public _token;
 
     /** Sylo Staking Manager contract. */
@@ -53,15 +53,15 @@ contract RewardsManager is Initializable, OwnableUpgradeable {
 
     /**
      * @notice Tracks the last epoch a delegated staker made a reward claim in.
-     * They key to this mapping is a hash of the Node's address and the delegated
+     * The key to this mapping is a hash of the Node's address and the delegated
      * stakers address.
      */
     mapping (bytes32 => uint256) public lastClaims;
 
     /**
      * @dev This type will hold the necessary information for delegated stakers
-     * to make reward claims against their Node. There should be an independent
-     * for every Node participating in an epoch.
+     * to make reward claims against their Node. Every Node will initialize
+     * and store a new Reward Pool for each they participate in.
      */
     struct RewardPool {
         // Tracks the balance of the reward pool owed to the stakers
@@ -84,7 +84,7 @@ contract RewardsManager is Initializable, OwnableUpgradeable {
 
     /**
      * @notice Tracks each reward pool initialized by a Node. The key to this map
-     * derived from the epochId and the Node's address.
+     * is derived from the epochId and the Node's address.
      */
     mapping (bytes32 => RewardPool) public rewardPools;
 
@@ -93,7 +93,7 @@ contract RewardsManager is Initializable, OwnableUpgradeable {
      * contracts, namely the Ticketing contract.
      * We use this mapping to restrict access to those functions in a similar
      * fashion to the onlyOwner construct. The stored value is the block the
-     * managing was contract was added in.
+     * managing contract was added in.
      */
     mapping (address => uint256) public managers;
 
@@ -153,7 +153,7 @@ contract RewardsManager is Initializable, OwnableUpgradeable {
     }
 
     /**
-     * @notice Retrieve the total accumulated that will be distributed to a Node's
+     * @notice Retrieve the total accumulated reward that will be distributed to a Node's
      * delegated stakers for a given epoch.
      * @param epochId The ID of the epoch the reward pool was initialized in.
      * @param stakee The address of the Node.
@@ -198,8 +198,8 @@ contract RewardsManager is Initializable, OwnableUpgradeable {
      * @notice This is used by Nodes to initialize their reward pool for
      * the next epoch. This function will revert if the caller has no stake, or
      * if the reward pool has already been initialized. The total active stake
-     * for the next reward pool by summing up the total managed stake held by
-     * the RewardsManager contract, plus any unclaimed staking rewards.
+     * for the next reward pool is calculated by summing up the total managed
+     * stake held by the RewardsManager contract, plus any unclaimed staking rewards.
      */
     function initializeNextRewardPool() public {
         uint256 nextEpochId = _epochsManager.getNextEpochId();

contracts/Staking/Directory.sol

@@ -60,7 +60,7 @@ contract Directory is Initializable, OwnableUpgradeable {
 
     /**
      * @notice This function should be called when a new epoch is initialized.
-     * This will set the current directory the specified epoch. This is only
+     * This will set the current directory to the specified epoch. This is only
      * callable by the owner of this contract, which should be the EpochsManager
      * contract.
      * @dev After deployment, the EpochsManager should immediately be set as

contracts/Staking/Manager.sol

@@ -89,7 +89,8 @@ contract StakingManager is Initializable, OwnableUpgradeable {
     /**
      * @notice Minimum amount of stake that a Node needs to stake
      * against itself in order to participate in the network. This is
-     * represented as a percentage of the Node's total stake.
+     * represented as a percentage of the Node's total stake, where
+     * the value is a ratio of 10000.
      */
     uint16 public minimumStakeProportion;
 
@@ -131,7 +132,7 @@ contract StakingManager is Initializable, OwnableUpgradeable {
      * this will trigger an automatic claim of any outstanding staking
      * rewards. This function will fail under the following conditions:
      *   - If the Node address is invalid
-     *   - If the the specified stake value is zero
+     *   - If the specified stake value is zero
      *   - If the additional stake causes the Node to fail to meet the
      *     minimum stake proportion requirement.
      * @param amount The amount of stake to add in SOLO.
@@ -184,7 +185,7 @@ contract StakingManager is Initializable, OwnableUpgradeable {
      *   - If the unlock amount is more than what is staked
      * Note: If calling as a Node, this function will *not* revert if it causes
      * the Node to fail to meet the minimum stake proportion. However it will still
-     * prevent the Node from participating in the network until the minimum is meet
+     * prevent the Node from participating in the network until the minimum is met
      * again.
      * @param amount The amount of stake to unlock in SOLO.
      * @param stakee The address of the staked Node.

docs/spec.md

@@ -9,7 +9,7 @@ Joshua Dawes            <josh@sylo.io> </br>
 * [Introduction](#introduction)
 * [Users](#users)
 * [Network Parameters](#network-parameters)
-* [Snart Contract Specification](#smart-contract-specification)
+* [Smart Contract Specification](#smart-contract-specification)
 	* [Data Types](#data-types)
 	* [Functions](#functions)
 * [Deployment Timeline](#deployment-timeline)