Added introductory comment for staking pool rewards

contracts/staking/contracts/src/core/MixinStakingPoolRewards.sol

@@ -37,8 +37,41 @@ contract MixinStakingPoolRewards is
 
     using LibSafeMath for uint256;
 
-    /// @dev This mixin contains logic for managing the rewards belonging to a staking pool.
-    ///  
+    /// @dev This mixin contains logic for staking pool rewards.
+    /// Rewards for a pool are generated by their market makers trading on the 0x protocol (MixinStakingPool).
+    /// The operator of a pool receives a fixed percentage of all rewards; generally, the operator is the
+    /// sole market maker of a pool. The remaining rewards are divided among the members of a pool; each member
+    /// gets an amount proportional to how much stake they have delegated to the pool.
+    ///
+    /// Note that members can freely join or leave a staking pool at any time, by delegating/undelegating their stake.
+    /// Moreover, there is no limit to how many members a pool can have. To limit the state-updates needed to track member balances,
+    /// we store only a single balance shared by all members. This state is updated every time a reward is paid to the pool - which
+    /// is currently at the end of each epoch. Additionally, each member has an associated "Shadow Balance" which is updated only
+    /// when a member delegates/undelegates stake to the pool, along with a "Total Shadow Balance" that represents the cumulative
+    /// Shadow Balances of all members in a pool.
+    /// 
+    /// -- Member Balances --
+    /// Terminology:
+    ///     Real Balance - The reward balance in ETH of a member.
+    ///     Cumulative Real Balance - The sum total of reward balances in ETH across all members of a pool.
+    ///     Shadow Balance - The realized reward balance of a member.
+    ///     Cumulative Shadow Balance - The sum total of realized reward balances across all members of a pool.
+    /// How it works:
+    /// 1. When a member delegates, their ownership of the pool increases; however, this new ownership applies
+    ///    only to future rewards and must not change the rewards currently owned by other members. Thus, when a
+    ///    member delegates stake, we *increase* their Shadow Balance and the Cumulative Shadow Balance of the pool.
+    ///
+    /// 2. When a member withdraws a portion of their reward, their realized balance increases but their ownership
+    ///    within the pool remains unchanged. Thus, we simultaneously *decrease* their Real Balance and 
+    ///    *increase* their Shadow Balance by the amount withdrawn. The cumulative balance decrease and increase, respectively.
+    ///
+    /// 3. When a member undelegates, the portion of their reward that corresponds to that stake is also withdrawn. Thus,
+    ///    their realized balance *increases* while their ownership of the pool *decreases*. To reflect this, we 
+    ///    decrease their Shadow Balance, the Cumulative Shadow Balance, their Real Balance, and the Cumulative Real Balance.
+
+    
+    
+
 
     function withdrawOperatorReward(bytes32 poolId, uint256 amount)
         external