Basic epoch spec + minor change to message spec (#913)

x/superfluid/spec/03_messages.md

@@ -50,6 +50,6 @@ type MsgSuperfluidUndelegate struct {
 - Delete the `SyntheticLockup` associated to this `lockID` + `ValAddr` pair
 - Create a new `SyntheticLockup` which is unbonding
 - Calculate the amount of `Osmo` delegated on behalf of this `lock`
-- Undelegate `Osmo` from `IntermediaryAccount` to `Validator`
-  - `Osmo` will be burned from `IntermediaryAccount` on epoch after unbonding finishes
+- Use `InstantUndelegate` to instantly remove delegation from `IntermediaryAccount` to `Validator`
+- Immediately burn undelegated `Osmo`
 - Delete the connection betweene `lockID` and `IntermediaryAccount`

x/superfluid/spec/04_epoch.md

@@ -4,14 +4,21 @@ order: 4
 
 # Epochs
 
-At the Osmosis rewards distribution epoch time, all superfluid staking rewards get distributed.
-The envisioned flow of how this works is as follows:
-
-* (Epochs) AfterEpochEnd hook runs for epoch N
-* (Mint) distributes rewards to all stakers at the epoch that just endeds prices
-* (Superfluid) Claim all staking rewards to every intermediary module accounts
-* (Superfluid) Update all Osmo Equivalent Multiplier values [updateEpochEnd][./../keeper/hooks.go]
-  <!-- * Here we are setting the multuplier value for epoch N+1, as the TWAP from the duration of epoch N. -->
-  * Currently using spot price at epoch time.
-* (Superfluid) Update all the intermediary accounts staked amounts. (Mint/Burn coins as needed as well)
-  * TODO: Consider if this is wrong for burn, should that come before reward distrbution?
+Overall Epoch sequence:
+* Superfluid
+  * Claim staking rewards for every `Intermediary Account`
+  * Put rewards into gauges for payout to owner's of `Synthetic Locks`
+  * Update `Osmo Equivalent Multiplier` value for each LP token
+    * (Currently spot price at epoch)
+  * Refresh delegation amounts for all `Intermediary Accounts`
+    * If expected amount > current delegation:
+      * Mint new `Osmo` and `Delegate`
+    * If expected amount < current delegation:
+      * Use `InstantUndelegate` and burn the extra `Osmo`
+* Incentives
+  * Payout rewards from gagues to `Synthetic Lock` owners
+  * (Also pay out regular LP incentives)
+* Mint
+  * 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