Merge pull request #180 from keep-network/misc-test-cleanup

Miscellaneous Cleanup

This PR cleans up a round of feedback items from the following PRs:
Annotate Rewards Tests #177
Sortition Tree Tests #179
Rewards Documentation #176

Author: pdyraga

docs/rewards.md

@@ -36,15 +36,15 @@ carry-over, which is stored in (2) `rewardRoundingDust`.
 Finally, the (3) `operatorRewards` keep track of each operator's individual
 state indexed by their `id`. An operator's `accumulated` value represents a
 snapshot of the `globalRewardAccumulator` at the time they were last updated.
-Their `available` value represents how much reward is available for withdraw.
-Their `weight` is their weight in the pool.
+Their `available` value represents how much reward is available for withdraw,
+as of their most recent update. Their `weight` is their weight in the pool.
 
 To see how all of these pieces of state interact, we can go through some
 event logs.
 
 #### Join -> Reward -> Withdraw
 ```
-event 1) Alice (id 0) joins the pool with weight 10
+event 1) Alice (id 1) joins the pool with weight 10
 event 2) 123 rewards are granted to the pool
 event 3) Alice withdraws their rewards
 ```
@@ -56,7 +56,7 @@ rewardRoundingDust: 0
 operatorRewards: {}
 ```
 
-Joining the pool is handled with `updateOperatorRewards(0, 10)` (some
+Joining the pool is handled with `updateOperatorRewards(1, 10)` (some
 complexity abridged to be introduced later)
 ```
 function updateOperatorRewards(uint32 operator, uint32 newWeight) internal {
@@ -78,12 +78,12 @@ accruedRewards = (0 - 0) * 0 = 0
 o.available = 0 + 0 = 0
 o.accumulated = 0
 o.weight = 10
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 
 // new state
 globalRewardAccumulator: 0 
 rewardRoundingDust: 0
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 ```
 
 Ever time an operator is updated, they accrue rewards equal to however much the
@@ -118,7 +118,7 @@ rewardRoundingDust = 3
 // new state
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 ```
 
 Whenever rewards are distributed, we *only* update `globalRewardAccumulator`
@@ -127,7 +127,7 @@ lazily via `updateOperatorRewards`. Note that at this point, alice's
 accumulator is 12 rewards behind the global accumulator!
 
 In order to Alice to withdraw her rewards, she shoud *update* herself first,
-since her `available` state is `0`. So, first we call `updateOperatorRewards(0, 10)`
+since her `available` state is `0`. So, first we call `updateOperatorRewards(1, 10)`
 
 ```
 acc = 12
@@ -136,12 +136,12 @@ accruedRewards = (12 - 0) * 10 = 120
 o.available = 0 + 120 = 120
 o.accumulated = 12
 o.weight = 10
-operatorRewards: {0: {accumulated: 12, available: 120, weight: 10}}
+operatorRewards: {1: {accumulated: 12, available: 120, weight: 10}}
 
 // new state
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 12, available: 120, weight: 10}}
+operatorRewards: {1: {accumulated: 12, available: 120, weight: 10}}
 ```
 
 Some amount of reward (an amount between 0 and the total operator weight) will
@@ -150,7 +150,7 @@ threshold, the weight precision is 1 weight = 1 T, (1e18 divisor), but rewards
 are represented with full precision (1e18), so numerically, even small rewards
 should greatly exceed the total pool weight.
 
-Alice is now ready to withdraw! We call `withdrawOperatorRewards(0)`
+Alice is now ready to withdraw! We call `withdrawOperatorRewards(1)`
 
 ```
 function withdrawOperatorRewards(uint32 operator)
@@ -165,7 +165,7 @@ function withdrawOperatorRewards(uint32 operator)
 // new state
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 12, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 12, available: 0, weight: 10}}
 ```
 
 This returns `120` to the caller, and sets Alice's available rewards to 0. The
@@ -180,25 +180,25 @@ globalRewardAccumulator: 0
 rewardRoundingDust: 0
 operatorRewards: {}
 
-event 2) Alice (id 0) joins the pool with weight 10 
+event 2) Alice (id 1) joins the pool with weight 10 
 globalRewardAccumulator: 0 
 rewardRoundingDust: 0
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 
 event 3) 123 rewards are granted to the pool
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 
 event 4) Update Alice
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 12, available: 120, weight: 10}}
+operatorRewards: {1: {accumulated: 12, available: 120, weight: 10}}
 
 event 5) Withdraw Alice's Rewards
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 12, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 12, available: 0, weight: 10}}
 return: 120
 ```
 
@@ -210,63 +210,63 @@ globalRewardAccumulator: 0
 rewardRoundingDust: 0
 operatorRewards: {}
 
-event 2) Alice (id 0) joins the pool with weight 10
+event 2) Alice (id 1) joins the pool with weight 10
 globalRewardAccumulator: 0 
 rewardRoundingDust: 0
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 
 event 3) 123 rewards are granted to the pool
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10}}
 
-event 4) Bob (id 1) joins the pool with weight 20
+event 4) Bob (id 2) joins the pool with weight 20
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
 operatorRewards: {
-  0: {accumulated: 0, available: 0, weight: 10}
-  1: {accumulated: 12, available: 0, weight: 20}
+  1: {accumulated: 0, available: 0, weight: 10}
+  2: {accumulated: 12, available: 0, weight: 20}
 }
 
 event 5) 321 rewards are granted to the pool
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 operatorRewards: {
-  0: {accumulated: 0, available: 0, weight: 10}
-  1: {accumulated: 12, available: 0, weight: 20}
+  1: {accumulated: 0, available: 0, weight: 10}
+  2: {accumulated: 12, available: 0, weight: 20}
 }
 
 event 6) Update Alice
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 operatorRewards: {
-  0: {accumulated: 22, available: 220, weight: 10}
-  1: {accumulated: 12, available: 0, weight: 20}
+  1: {accumulated: 22, available: 220, weight: 10}
+  2: {accumulated: 12, available: 0, weight: 20}
 }
 
 event 7) Withdraw Alice's rewards
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 operatorRewards: {
-  0: {accumulated: 22, available: 0, weight: 10}
-  1: {accumulated: 12, available: 0, weight: 20}
+  1: {accumulated: 22, available: 0, weight: 10}
+  2: {accumulated: 12, available: 0, weight: 20}
 }
 return: 220
 
 event 8) Update Bob
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 operatorRewards: {
-  0: {accumulated: 22, available: 0, weight: 10}
-  1: {accumulated: 22, available: 200, weight: 20}
+  1: {accumulated: 22, available: 0, weight: 10}
+  2: {accumulated: 22, available: 200, weight: 20}
 }
 
 event 9) Withdraw Bob's Rewards
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 operatorRewards: {
-  0: {accumulated: 22, available: 0, weight: 10}
-  1: {accumulated: 22, available: 0, weight: 20}
+  1: {accumulated: 22, available: 0, weight: 10}
+  2: {accumulated: 22, available: 0, weight: 20}
 }
 return 200
 ```
@@ -350,61 +350,61 @@ rewardRoundingDust: 0
 ineligibleEarnedRewards: 0
 operatorRewards: {}
 
-event 2) Alice (id 0) joins the pool with weight 10
+event 2) Alice (id 1) joins the pool with weight 10
 globalRewardAccumulator: 0 
 rewardRoundingDust: 0
 ineligibleEarnedRewards: 0
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}}
 
 event 3) 123 rewards are granted to the pool
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
 ineligibleEarnedRewards: 0
-operatorRewards: {0: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}}
+operatorRewards: {1: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}}
 
-event 4) Bob (id 1) joins the pool with weight 20
+event 4) Bob (id 2) joins the pool with weight 20
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
 ineligibleEarnedRewards: 0
 operatorRewards: {
-  0: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: 0}
+  1: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: 0}
 }
 
 event 5) Bob is set as ineligable until 100000 seconds from now
 globalRewardAccumulator: 12 
 rewardRoundingDust: 3
 ineligibleEarnedRewards: 0
 operatorRewards: {
-  0: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
+  1: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
 }
 
 event 6) 321 rewards are granted to the pool
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 ineligibleEarnedRewards: 0
 operatorRewards: {
-  0: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
+  1: {accumulated: 0, available: 0, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
 }
 
 event 7) Update Alice
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 ineligibleEarnedRewards: 0
 operatorRewards: {
-  0: {accumulated: 22, available: 220, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
+  1: {accumulated: 22, available: 220, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
 }
 
 event 8) Withdraw Alice's rewards
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 ineligibleEarnedRewards: 0
 operatorRewards: {
-  0: {accumulated: 22, available: 0, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
+  1: {accumulated: 22, available: 0, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 12, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
 }
 return: 220
 
@@ -413,17 +413,17 @@ globalRewardAccumulator: 22
 rewardRoundingDust: 24
 ineligibleEarnedRewards: 200
 operatorRewards: {
-  0: {accumulated: 22, available: 0, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 22, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
+  1: {accumulated: 22, available: 0, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 22, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
 }
 
 event 10) Withdraw Ineligable Rewards
 globalRewardAccumulator: 22
 rewardRoundingDust: 24
 ineligibleEarnedRewards: 0
 operatorRewards: {
-  0: {accumulated: 22, available: 0, weight: 10, ineligibleUntil: 0}
-  1: {accumulated: 22, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
+  1: {accumulated: 22, available: 0, weight: 10, ineligibleUntil: 0}
+  2: {accumulated: 22, available: 0, weight: 20, ineligibleUntil: event5-time + 10000}
 }
 return: 200
 ```

test/rewardsTest.js

@@ -245,15 +245,16 @@ describe("Rewards", () => {
       // Alice: 10; Bob: 90
       await rewards.payReward(100)
 
-      // Make Bob ineligible for 10 units of time
+      // Make Bob ineligible for 10 seconds
       await rewards.makeIneligible(bob, 10)
 
       // Reward only to Alice
       // Alice: 20; Bob: 90; Ineligible: 90
       await rewards.payReward(100)
 
-      // Ineligibility is set for a duration. Bob was ineligible for 10 units,
-      // so we move forward 11 units to allow us to make him eligible again.
+      // Ineligibility is set for a duration. Bob was ineligible for 10
+      // seconds, so we move forward 11 seconds to allow us to make him
+      // eligible again.
       await helpers.time.increaseTime(11)
 
       await rewards.makeEligible(bob)

test/sortitionTreeTest.js

@@ -19,7 +19,7 @@ describe("SortitionTree", () => {
 
   describe("setLeaf", async () => {
     context("when one leaf is set", () => {
-      it("should return correct value for the tree", async () => {
+      it("should return correct value for the tree with a leaf in the first slot", async () => {
         const weight = 0x1234
         const position = 42798
 
@@ -128,7 +128,7 @@ describe("SortitionTree", () => {
         // 0x00000000,00000000,00000000,00000000,00000000,00000000,00000000,1000fff1
         //  slot 7     slot 6   slot 5   slot 4   slot 3   slot 2   slot 1   slot 0
         // without the commas added for readability. All the padding zeros are
-        // dropped when we hexlify, which simplifies to 0x1100000000.
+        // dropped when we hexlify, which simplifies to 0x1000fff1.
       })
     })