LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs(x/distribution): updates (backport #22148) (#22153)

Browse Source 
Co-authored-by: Julián Toledano <JulianToledano@users.noreply.github.com>
This commit is contained in:
mergify[bot] 2024-10-07 15:38:58 +02:00 committed by GitHub
parent 245434ef9f
commit 090efc9f3b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 14 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
x/distribution/README.md
View File

@ -74,7 +74,7 @@ which is considered computationally expensive.
In conclusion, we can only have Atom commission and unbonded atoms
provisions or bonded atom provisions with no Atom commission, and we elect to
implement the former. Stakeholders wishing to rebond their provisions may elect
implement the former. Stakeholders wishing to rebond their provisions, may elect
to set up a script to periodically withdraw and rebond rewards.
## Contents
@ -99,7 +99,7 @@ In Proof of Stake (PoS) blockchains, rewards gained from transaction fees are pa
Rewards are calculated per period. The period is updated each time a validator's delegation changes, for example, when the validator receives a new delegation.
The rewards for a single validator can then be calculated by taking the total rewards for the period before the delegation started, minus the current total rewards.
To learn more, see the [F1 Fee Distribution paper](https://github.com/cosmos/cosmos-sdk/tree/main/docs/spec/fee_distribution/f1_fee_distr.pdf).
To learn more, see the [F1 Fee Distribution paper](https://github.com/cosmos/cosmos-sdk/blob/release/v0.52.x/docs/spec/fee_distribution/f1_fee_distr.pdf).
The commission to the validator is paid when the validator is removed or when the validator requests a withdrawal.
The commission is calculated and incremented at every `BeginBlock` operation to update accumulated fee amounts.
@ -438,8 +438,6 @@ The distribution module emits the following events:
| Type | Attribute Key | Attribute Value |
|-----------------|---------------|--------------------|
| proposer_reward | validator | {validatorAddress} |
| proposer_reward | reward | {proposerReward} |
| commission | amount | {commissionAmount} |
| commission | validator | {validatorAddress} |
| rewards | amount | {rewardAmount} |

5
x/distribution/keeper/delegation.go
View File

@ -46,7 +46,7 @@ func (k Keeper) initializeDelegation(ctx context.Context, val sdk.ValAddress, de
return k.DelegatorStartingInfo.Set(ctx, collections.Join(val, del), types.NewDelegatorStartingInfo(previousPeriod, stake, uint64(headerinfo.Height)))
}
// calculate the rewards accrued by a delegation between two periods
// calculateDelegationRewardsBetween calculates the rewards accrued by a delegation between two periods
func (k Keeper) calculateDelegationRewardsBetween(ctx context.Context, val sdk.ValidatorI,
startingPeriod, endingPeriod uint64, stake math.LegacyDec,
) (sdk.DecCoins, error) {
@ -85,7 +85,7 @@ func (k Keeper) calculateDelegationRewardsBetween(ctx context.Context, val sdk.V
return rewards, nil
}
// calculate the total rewards accrued by a delegation
// CalculateDelegationRewards calculate the total rewards accrued by a delegation
func (k Keeper) CalculateDelegationRewards(ctx context.Context, val sdk.ValidatorI, del sdk.DelegationI, endingPeriod uint64) (rewards sdk.DecCoins, err error) {
addrCodec := k.authKeeper.AddressCodec()
delAddr, err := addrCodec.StringToBytes(del.GetDelegatorAddr())
@ -200,6 +200,7 @@ func (k Keeper) CalculateDelegationRewards(ctx context.Context, val sdk.Validato
return rewards, nil
}
// withdrawDelegationRewards withdraws the rewards accrued by a delegation.
func (k Keeper) withdrawDelegationRewards(ctx context.Context, val sdk.ValidatorI, del sdk.DelegationI) (sdk.Coins, error) {
addrCodec := k.authKeeper.AddressCodec()
delAddr, err := addrCodec.StringToBytes(del.GetDelegatorAddr())

14
x/distribution/keeper/hooks.go
View File

@ -20,12 +20,12 @@ type Hooks struct {
var _ stakingtypes.StakingHooks = Hooks{}
// Create new distribution hooks
// Hooks creates new distribution hooks
func (k Keeper) Hooks() Hooks {
return Hooks{k}
}
// initialize validator distribution record
// AfterValidatorCreated initialize validator distribution record
func (h Hooks) AfterValidatorCreated(ctx context.Context, valAddr sdk.ValAddress) error {
val, err := h.k.stakingKeeper.Validator(ctx, valAddr)
if err != nil {
@ -129,8 +129,8 @@ func (h Hooks) AfterValidatorRemoved(ctx context.Context, _ sdk.ConsAddress, val
return nil
}
// increment period
func (h Hooks) BeforeDelegationCreated(ctx context.Context, delAddr sdk.AccAddress, valAddr sdk.ValAddress) error {
// BeforeDelegationCreated increment period
func (h Hooks) BeforeDelegationCreated(ctx context.Context, _ sdk.AccAddress, valAddr sdk.ValAddress) error {
val, err := h.k.stakingKeeper.Validator(ctx, valAddr)
if err != nil {
return err
@ -140,7 +140,7 @@ func (h Hooks) BeforeDelegationCreated(ctx context.Context, delAddr sdk.AccAddre
return err
}
// withdraw delegation rewards (which also increments period)
// BeforeDelegationSharesModified withdraws delegation rewards (which also increments period)
func (h Hooks) BeforeDelegationSharesModified(ctx context.Context, delAddr sdk.AccAddress, valAddr sdk.ValAddress) error {
val, err := h.k.stakingKeeper.Validator(ctx, valAddr)
if err != nil {
@ -159,12 +159,12 @@ func (h Hooks) BeforeDelegationSharesModified(ctx context.Context, delAddr sdk.A
return nil
}
// create new delegation period record
// AfterDelegationModified create new delegation period record
func (h Hooks) AfterDelegationModified(ctx context.Context, delAddr sdk.AccAddress, valAddr sdk.ValAddress) error {
return h.k.initializeDelegation(ctx, valAddr, delAddr)
}
// record the slash event
// BeforeValidatorSlashed record the slash event
func (h Hooks) BeforeValidatorSlashed(ctx context.Context, valAddr sdk.ValAddress, fraction sdkmath.LegacyDec) error {
return h.k.updateValidatorSlashFraction(ctx, valAddr, fraction)
}

4
x/distribution/keeper/keeper.go
View File

@ -178,7 +178,7 @@ func (k Keeper) SetWithdrawAddr(ctx context.Context, delegatorAddr, withdrawAddr
return k.DelegatorsWithdrawAddress.Set(ctx, delegatorAddr, withdrawAddr)
}
// withdraw rewards from a delegation
// WithdrawDelegationRewards withdraw rewards from a delegation
func (k Keeper) WithdrawDelegationRewards(ctx context.Context, delAddr sdk.AccAddress, valAddr sdk.ValAddress) (sdk.Coins, error) {
val, err := k.stakingKeeper.Validator(ctx, valAddr)
if err != nil {
@ -212,7 +212,7 @@ func (k Keeper) WithdrawDelegationRewards(ctx context.Context, delAddr sdk.AccAd
return rewards, nil
}
// withdraw validator commission
// WithdrawValidatorCommission withdraw validator commission
func (k Keeper) WithdrawValidatorCommission(ctx context.Context, valAddr sdk.ValAddress) (sdk.Coins, error) {
// fetch validator accumulated commission
accumCommission, err := k.ValidatorsAccumulatedCommission.Get(ctx, valAddr)