Merge branch 'main' into implementation-details-rewards

Author: pdyraga

test/rewardsTest.js

@@ -3,17 +3,13 @@ const expect = chai.expect
 const { ethers, helpers } = require("hardhat")
 
 describe("Rewards", () => {
-  let alice
-  let bob
-  let carol
+  const alice = 1
+  const bob = 2
+  const carol = 3
 
   let rewards
 
   beforeEach(async () => {
-    alice = 1
-    bob = 2
-    carol = 3
-
     const RewardsStub = await ethers.getContractFactory("RewardsStub")
     rewards = await RewardsStub.deploy()
     await rewards.deployed()
@@ -35,7 +31,11 @@ describe("Rewards", () => {
       await rewards.withdrawRewards(bob)
       const bobRewards = await rewards.getWithdrawnRewards(bob)
 
+      // Since alice makes up 10 / 100 = 10% of the pool weight, alice expects
+      // 10% of the rewards. 10% of 1000 is 100.
       expect(aliceRewards).to.be.equal(100)
+      // Since bob makes up 90 / 100 = 90% of the pool weight, bob expects 90%
+      // of the rewards. 90% of 1000 is 900.
       expect(bobRewards).to.be.equal(900)
     })
 
@@ -52,7 +52,13 @@ describe("Rewards", () => {
       await rewards.withdrawRewards(bob)
       const bobRewards = await rewards.getWithdrawnRewards(bob)
 
+      // Since alice made up 10 / 10 = 100% of the pool weight (as bob's weight
+      // was updated to 0 before rewards were paid), alice expects 100% of
+      // the rewards. 100% of 1000 is 1000.
       expect(aliceRewards).to.equal(1000)
+      // Since bob made up 0 / 10 = 0% of the pool weight (as bob's weight was
+      // updated to 0 before rewards were paid), bob expects 0% of the
+      // rewards. 0% of 1000 is 0.
       expect(bobRewards).to.equal(0)
     })
 
@@ -61,6 +67,13 @@ describe("Rewards", () => {
 
       await rewards.payReward(123)
 
+      // The way that reward state is tracked is through a global accumulator
+      // that simulates what a hypothetical 1-weight operator would receive in
+      // rewards for each payout, accompanied by roundingDust variable that
+      // stores integer division remainders. For this example, the pool has 10
+      // weight, and a reward of 123 was just granted, so a 1-weight operator
+      // would receive 12 rewards with 3 left over (12 * 10 + 3 = 123). The
+      // remainder is added to the next reward.
       const acc1 = await rewards.getGlobalAccumulator()
       expect(acc1).to.equal(12)
 
@@ -71,6 +84,10 @@ describe("Rewards", () => {
 
       await rewards.payReward(987)
 
+      // We previously had a remainder of 3, and just received 987 rewards for
+      // a total of 990. The total pool weight is 30, so our 1-weight operator
+      // receives 990 / 30 = 33 rewards with 0 left over. That 33 is added to
+      // the previous 12 to get to 45.
       const acc2 = await rewards.getGlobalAccumulator()
       expect(acc2).to.equal(45)
 
@@ -106,9 +123,12 @@ describe("Rewards", () => {
       const bobAcc1 = await rewards.getAccumulator(bob)
       expect(bobAcc1).to.equal(10)
 
+      // Accrued rewards only change when an operator is updated.
       const aliceRew1 = await rewards.getAccruedRewards(alice)
       expect(aliceRew1).to.equal(0)
 
+      // An operator's accumulator state only changes when an operator is
+      // updated.
       const aliceAcc1 = await rewards.getAccumulator(alice)
       expect(aliceAcc1).to.equal(0)
 
@@ -225,12 +245,15 @@ describe("Rewards", () => {
       // Alice: 10; Bob: 90
       await rewards.payReward(100)
 
+      // Make Bob ineligible for 10 units of time
       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.
       await helpers.time.increaseTime(11)
 
       await rewards.makeEligible(bob)