docs: estaking spec folder (#513)

x/estaking/spec/01_concepts.md

@@ -0,0 +1,7 @@
+<!--
+order: 1
+-->
+
+# Concepts
+
+The `estaking` module in the Elys Network extends basic staking capabilities, providing additional functionalities such as managing and distributing rewards from multiple validators, updating staking parameters, and handling Eden and EdenB token mechanics in relation to staking rewards. This module aims to enhance the staking experience and efficiency within the network.

x/estaking/spec/02_usage.md

@@ -0,0 +1,67 @@
+<!--
+order: 2
+-->
+
+# Usage
+
+## Commands
+
+### Querying Commitments and Balances
+
+```bash
+TREASURY=$(elysd keys show -a treasury --keyring-backend=test)
+
+elysd query commitment show-commitments $TREASURY
+elysd query bank balances $TREASURY
+```
+
+### Querying Staking and Validators
+
+```bash
+elysd query estaking params
+elysd query staking validators
+```
+
+### Delegating Tokens
+
+```bash
+VALIDATOR=elysvaloper12tzylat4udvjj56uuhu3vj2n4vgp7cf9pwcqcs
+elysd tx staking delegate $VALIDATOR 1000000000000uelys --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+```
+
+### Querying and Withdrawing Rewards
+
+```bash
+elysd query distribution rewards $TREASURY $VALIDATOR
+elysd query distribution rewards $TREASURY $EDEN_VAL
+elysd query distribution rewards $TREASURY $EDENB_VAL
+
+elysd tx distribution withdraw-rewards $VALIDATOR --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+elysd tx distribution withdraw-rewards $EDEN_VAL --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+elysd tx distribution withdraw-rewards $EDENB_VAL --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+```
+
+### Committing Claimed Rewards
+
+```bash
+elysd tx commitment commit-claimed-rewards 503544 ueden --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+elysd tx commitment commit-claimed-rewards 1678547 uedenb --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+```
+
+### Delegating
+
+```bash
+elysd tx staking delegate $VALIDATOR 1000uelys --fees=10000uusdc --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+```
+
+### Querying eStaking Rewards
+
+```bash
+elysd query estaking rewards $TREASURY
+```
+
+### Withdrawing All Rewards
+
+```bash
+elysd tx estaking withdraw-all-rewards --from=validator --chain-id=elystestnet-1
+```

x/estaking/spec/03_keeper.md

@@ -0,0 +1,115 @@
+<!--
+order: 3
+-->
+
+# Keeper
+
+## Rewards Distribution
+
+The `estaking` module's keeper handles rewards distribution and updates staking parameters. It ensures that rewards are properly calculated, distributed, and that necessary adjustments to staking parameters are made regularly.
+
+### EndBlocker
+
+The `EndBlocker` function is invoked at the end of each block. It is responsible for processing the distribution of rewards and burning EdenB tokens if there has been a reduction in Elys staking.
+
+```go
+func (k Keeper) EndBlocker(ctx sdk.Context) {
+    k.ProcessRewardsDistribution(ctx)
+    k.BurnEdenBIfElysStakingReduced(ctx)
+}
+```
+
+### Taking Delegation Snapshot
+
+The `TakeDelegationSnapshot` function captures the current state of a delegator's staked amount. This snapshot includes calculating the total delegation amount and storing it as an `ElysStaked` object.
+
+```go
+func (k Keeper) TakeDelegationSnapshot(ctx sdk.Context, addr string) {
+    delAmount := k.CalcDelegationAmount(ctx, addr)
+    elysStaked := types.ElysStaked{
+        Address: addr,
+        Amount:  delAmount,
+    }
+    k.SetElysStaked(ctx, elysStaked)
+}
+```
+
+### Burning EdenB Tokens
+
+The `BurnEdenBIfElysStakingReduced` function burns EdenB tokens if the Elys staking has decreased. It checks for addresses where staking changes have occurred and performs necessary actions to burn tokens and update snapshots.
+
+```go
+func (k Keeper) BurnEdenBIfElysStakingReduced(ctx sdk.Context) {
+    addrs := k.GetAllElysStakeChange(ctx)
+    for _, delAddr := range addrs {
+        k.BurnEdenBFromElysUnstaking(ctx, delAddr)
+        k.TakeDelegationSnapshot(ctx, delAddr.String())
+        k.RemoveElysStakeChange(ctx, delAddr)
+    }
+}
+```
+
+### Processing Rewards Distribution
+
+The `ProcessRewardsDistribution` function is responsible for distributing rewards to stakers. It updates incentive parameters and calculates the rewards to be distributed based on collected fees and staking conditions.
+
+```go
+func (k Keeper) ProcessRewardsDistribution(ctx sdk.Context) {
+    k.ProcessUpdateIncentiveParams(ctx)
+    err := k.UpdateStakersRewards(ctx)
+    if err != nil {
+        ctx.Logger().Error("Failed to update staker rewards unclaimed", "error", err)
+    }
+}
+```
+
+### Updating Stakers Rewards
+
+The `UpdateStakersRewards` function updates the rewards for stakers. It calculates the total rewards based on the collected fees and staking conditions, and then mints the appropriate amount of reward tokens.
+
+```go
+func (k Keeper) UpdateStakersRewards(ctx sdk.Context) error {
+    baseCurrency, found := k.assetProfileKeeper.GetUsdcDenom(ctx)
+    if !found {
+        return errorsmod.Wrapf(assetprofiletypes.ErrAssetProfileNotFound, "asset %s not found", ptypes.BaseCurrency)
+    }
+
+    feeCollectorAddr := authtypes.NewModuleAddress(authtypes.FeeCollectorName)
+    totalFeesCollected := k.commKeeper.GetAllBalances(ctx, feeCollectorAddr)
+    gasFeeCollectedDec := sdk.NewDecCoinsFromCoins(totalFeesCollected...)
+    dexRevenueStakersAmount := gasFeeCollectedDec.AmountOf(baseCurrency)
+
+    params := k.GetParams(ctx)
+    stakeIncentive := params.StakeIncentives
+    totalBlocksPerYear := k.parameterKeeper.GetParams(ctx).TotalBlocksPerYear
+
+    edenAmountPerYear := sdk.ZeroInt()
+    if stakeIncentive != nil && stakeIncentive.EdenAmountPerYear.IsPositive() {
+        edenAmountPerYear = stakeIncentive.EdenAmountPerYear
+    }
+    stakersEdenAmount := edenAmountPerYear.Quo(sdk.NewInt(totalBlocksPerYear))
+
+    totalElysEdenEdenBStake := k.TotalBondedTokens(ctx)
+
+    stakersMaxEdenAmount := params.MaxEdenRewardAprStakers.
+        MulInt(totalElysEdenEdenBStake).
+        QuoInt64(totalBlocksPerYear)
+
+    stakersEdenAmount = sdk.MinInt(stakersEdenAmount, stakersMaxEdenAmount.TruncateInt())
+
+    stakersEdenBAmount := sdk.NewDecFromInt(totalElysEdenEdenBStake).
+        Mul(params.EdenBoostApr).
+        QuoInt64(totalBlocksPerYear).
+        RoundInt()
+
+    params.DexRewardsStakers.NumBlocks = sdk.OneInt()
+    params.DexRewardsStakers.Amount = dexRevenueStakersAmount
+    k.SetParams(ctx, params)
+
+    coins := sdk.NewCoins(
+        sdk.NewCoin(ptypes.Eden, stakersEdenAmount),
+        sdk.NewCoin(ptypes.EdenB, stakersEdenBAmount),
+    )
+    return k.commKeeper.MintCoins(ctx, authtypes.FeeCollectorName, coins.Sort())
+}
+```