From b520d1f64632fcce13e67ee3e6a3f16154c908b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juli=C3=A1n=20Toledano?= Date: Mon, 7 Oct 2024 15:16:20 +0200 Subject: [PATCH] docs(x/distribution): updates (#22148) (cherry picked from commit 6211be616da8786872681b815b32e182f1386b1b) --- x/distribution/README.md | 6 ++---- x/distribution/keeper/delegation.go | 5 +++-- x/distribution/keeper/hooks.go | 14 +++++++------- x/distribution/keeper/keeper.go | 4 ++-- 4 files changed, 14 insertions(+), 15 deletions(-) diff --git a/x/distribution/README.md b/x/distribution/README.md index d49b309f50fe..8cd03dc5e459 100644 --- a/x/distribution/README.md +++ b/x/distribution/README.md @@ -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} | diff --git a/x/distribution/keeper/delegation.go b/x/distribution/keeper/delegation.go index 7bf2091edb89..1959d3a109f2 100644 --- a/x/distribution/keeper/delegation.go +++ b/x/distribution/keeper/delegation.go @@ -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()) diff --git a/x/distribution/keeper/hooks.go b/x/distribution/keeper/hooks.go index 46605690c26f..47a21d32dec4 100644 --- a/x/distribution/keeper/hooks.go +++ b/x/distribution/keeper/hooks.go @@ -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) } diff --git a/x/distribution/keeper/keeper.go b/x/distribution/keeper/keeper.go index 0ded047e93d6..6ee76320f982 100644 --- a/x/distribution/keeper/keeper.go +++ b/x/distribution/keeper/keeper.go @@ -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)