Minor PR adding some code comments

x/superfluid/keeper/stake.go

@@ -20,12 +20,16 @@ func (k Keeper) GetTotalSyntheticAssetsLocked(ctx sdk.Context, denom string) sdk
 
 func (k Keeper) GetExpectedDelegationAmount(ctx sdk.Context, acc types.SuperfluidIntermediaryAccount) sdk.Int {
 	// Get total number of Osmo this account should have delegated after refresh
+	// (1) Find how many tokens total T are locked for (denom, validator) pair
 	totalSuperfluidDelegation := k.GetTotalSyntheticAssetsLocked(ctx, stakingSyntheticDenom(acc.Denom, acc.ValAddr))
+	// (2) Multiply the T tokens, by the number of superfluid osmo per token, to get the total amount
+	// of osmo we expect.
 	refreshedAmount := k.GetSuperfluidOSMOTokens(ctx, acc.Denom, totalSuperfluidDelegation)
 	return refreshedAmount
 }
 
 func (k Keeper) RefreshIntermediaryDelegationAmounts(ctx sdk.Context) {
+	// iterate over every (denom, validator) pair
 	accs := k.GetAllIntermediaryAccounts(ctx)
 	for _, acc := range accs {
 		mAddr := acc.GetAccAddress()

x/superfluid/spec/04_epoch.md

@@ -12,13 +12,15 @@ Overall Epoch sequence
     * Issue new Osmo, and send to various modules (distribution, incentives, etc.)
     * 25% currently goes to `x/distribution` which funds `Staking` and `Superfluid` rewards
     * Rewards for `Superfluid` are based on the just updated delegation amounts, and queued for payout in the next epoch
-* Epoch N ends, during BeginBlock **After** AfterEpochEnd:
+* BeginBlock for Distribution
+  * Distribute staking rewards to all of the 'lazy accounting' accumulators. (F1)
+* Epoch N ends, during BeginBlock for superfluid **After** AfterEpochEnd:
   * Claim staking rewards for every `Intermediary Account`, put them into gauges.
   * Distribute Superfluid staking rewards from gauges to bonded Synthetic Lock owners
   * Update `Osmo Equivalent Multiplier` value for each LP token
     * (Currently spot price at epoch)
   * Refresh delegation amounts for all `Intermediary Accounts`
-    * Calcultate the expected delegation for this account as `Osmo Equivalent Multipler` *`# LP Shares`* `Risk adjustment`
+    * Calculate the expected delegation for this account as `Osmo Equivalent Multipler` *`# LP Shares`* `Risk adjustment`
       * If this is less than 0.000001 `Osmo` it will be rounded to 0
     * Lookup current delegation amount for `Intermediary Account`
       * If there is no delegation, treat the current delegation as 0