From 8ac3bd26428d0f76e914e39129a942ce5235da4f Mon Sep 17 00:00:00 2001 From: atheeshp <59333759+atheeshp@users.noreply.github.com> Date: Mon, 11 Jan 2021 17:41:22 +0530 Subject: [PATCH] x/{auth, bank, distr} docs basic cleanup (#8268) * basic code clean up * revert MsgVerifyInvariant * review changes * review changes * review changes * review changes * review changes * review changes Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- x/auth/spec/01_concepts.md | 2 +- x/auth/spec/05_vesting.md | 50 +++++++----------------- x/auth/spec/07_params.md | 10 ++--- x/bank/spec/02_keepers.md | 2 +- x/bank/spec/03_messages.md | 11 +----- x/distribution/spec/02_state.md | 24 ++++-------- x/distribution/spec/04_messages.md | 61 +++++++++--------------------- x/distribution/spec/README.md | 6 +-- 8 files changed, 51 insertions(+), 115 deletions(-) diff --git a/x/auth/spec/01_concepts.md b/x/auth/spec/01_concepts.md index 47316b4cb..9f8c9b8d8 100644 --- a/x/auth/spec/01_concepts.md +++ b/x/auth/spec/01_concepts.md @@ -19,7 +19,7 @@ signature verification, as well as costs proportional to the tx size. Operators should set minimum gas prices when starting their nodes. They must set the unit costs of gas in each token denomination they wish to support: -`gaiad start ... --minimum-gas-prices=0.00001stake;0.05photinos` +`simd start ... --minimum-gas-prices=0.00001stake;0.05photinos` When adding transactions to mempool or gossipping transactions, validators check if the transaction's gas prices, which are determined by the provided fees, meet diff --git a/x/auth/spec/05_vesting.md b/x/auth/spec/05_vesting.md index 50bf70d03..a253f7de6 100644 --- a/x/auth/spec/05_vesting.md +++ b/x/auth/spec/05_vesting.md @@ -88,52 +88,28 @@ type VestingAccount interface { GetStartTime() int64 GetEndTime() int64 } +``` +### BaseVestingAccount ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L10-L33 -// BaseVestingAccount implements the VestingAccount interface. It contains all -// the necessary fields needed for any vesting account implementation. -type BaseVestingAccount struct { - BaseAccount +### ContinuousVestingAccount ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43 - OriginalVesting Coins // coins in account upon initialization - DelegatedFree Coins // coins that are vested and delegated - DelegatedVesting Coins // coins that vesting and delegated +### DelayedVestingAccount ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53 - EndTime int64 // when the coins become unlocked -} - -// ContinuousVestingAccount implements the VestingAccount interface. It -// continuously vests by unlocking coins linearly with respect to time. -type ContinuousVestingAccount struct { - BaseVestingAccount - - StartTime int64 // when the coins start to vest -} - -// DelayedVestingAccount implements the VestingAccount interface. It vests all -// coins after a specific time, but non prior. In other words, it keeps them -// locked until a specified time. -type DelayedVestingAccount struct { - BaseVestingAccount -} - -// VestingPeriod defines a length of time and amount of coins that will vest -type Period struct { - Length int64 // length of the period, in seconds - Amount Coins // amount of coins vesting during this period -} +### Period ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L56-L62 +```go // Stores all vesting periods passed as part of a PeriodicVestingAccount type Periods []Period -// PeriodicVestingAccount implements the VestingAccount interface. It -// periodically vests by unlocking coins during each specified period -type PeriodicVestingAccount struct { - BaseVestingAccount - StartTime int64 - Periods Periods // the vesting schedule -} ``` +### PeriodicVestingAccount ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L64-L73 + In order to facilitate less ad-hoc type checking and assertions and to support flexibility in account balance usage, the existing `x/bank` `ViewKeeper` interface is updated to contain the following: diff --git a/x/auth/spec/07_params.md b/x/auth/spec/07_params.md index 93ddc89c2..1bf24e7f6 100644 --- a/x/auth/spec/07_params.md +++ b/x/auth/spec/07_params.md @@ -8,8 +8,8 @@ The auth module contains the following parameters: | Key | Type | Example | | ---------------------- | --------------- | ------- | -| MaxMemoCharacters | string (uint64) | "256" | -| TxSigLimit | string (uint64) | "7" | -| TxSizeCostPerByte | string (uint64) | "10" | -| SigVerifyCostED25519 | string (uint64) | "590" | -| SigVerifyCostSecp256k1 | string (uint64) | "1000" | +| MaxMemoCharacters | uint64 | 256 | +| TxSigLimit | uint64 | 7 | +| TxSizeCostPerByte | uint64 | 10 | +| SigVerifyCostED25519 | uint64 | 590 | +| SigVerifyCostSecp256k1 | uint64 | 1000 | diff --git a/x/bank/spec/02_keepers.md b/x/bank/spec/02_keepers.md index ec74358fb..0032961b1 100644 --- a/x/bank/spec/02_keepers.md +++ b/x/bank/spec/02_keepers.md @@ -44,7 +44,7 @@ The base keeper provides full-permission access: the ability to arbitrary modify type Keeper interface { SendKeeper - InitGenesis(sdk.Context, types.GenesisState) + InitGenesis(sdk.Context, *types.GenesisState) ExportGenesis(sdk.Context) *types.GenesisState GetSupply(ctx sdk.Context) exported.SupplyI diff --git a/x/bank/spec/03_messages.md b/x/bank/spec/03_messages.md index ecb9dc695..07c42f5f7 100644 --- a/x/bank/spec/03_messages.md +++ b/x/bank/spec/03_messages.md @@ -6,18 +6,11 @@ order: 3 ## MsgSend -```go -// MsgSend represents a message to send coins from one account to another. -message MsgSend { - string from_address = 1; - string to_address = 2; - repeated cosmos.base.v1beta1.Coin amount = 3; -} -``` ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L19-L28 `handleMsgSend` just runs `inputOutputCoins`. -``` +```go handleMsgSend(msg MsgSend) inputSum = 0 for input in inputs diff --git a/x/distribution/spec/02_state.md b/x/distribution/spec/02_state.md index 624fb9f0f..b8dbde4a9 100644 --- a/x/distribution/spec/02_state.md +++ b/x/distribution/spec/02_state.md @@ -15,7 +15,7 @@ for fractions of coins to be received from operations like inflation. When coins are distributed from the pool they are truncated back to `sdk.Coins` which are non-decimal. -- FeePool: `0x00 -> amino(FeePool)` +- FeePool: `0x00 -> ProtocolBuffer(FeePool)` ```go // coins with decimal @@ -25,15 +25,10 @@ type DecCoin struct { Amount sdk.Dec Denom string } - -type FeePool struct { - TotalValAccumUpdateHeight int64 // last height which the total validator accum was updated - TotalValAccum sdk.Dec // total valdator accum held by validators - Pool DecCoins // funds for all validators which have yet to be withdrawn - CommunityPool DecCoins // pool for community funds yet to be spent -} ``` ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/distribution.proto#L94-L101 + ## Validator Distribution Validator distribution information for the relevant validator is updated each time: @@ -43,16 +38,13 @@ Validator distribution information for the relevant validator is updated each ti 3. any delegator withdraws from a validator, or 4. the validator withdraws it's commission. -- ValidatorDistInfo: `0x02 | ValOperatorAddr -> amino(validatorDistribution)` +- ValidatorDistInfo: `0x02 | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)` ```go type ValidatorDistInfo struct { - FeePoolWithdrawalHeight int64 // last height this validator withdrew from the global fee pool - Pool DecCoins // rewards owed to delegators, commission has already been charged (includes proposer reward) - PoolCommission DecCoins // commission collected by this validator (pending withdrawal) - - TotalDelAccumUpdateHeight int64 // last height which the total delegator accum was updated - TotalDelAccum sdk.Dec // total proposer pool accumulation factor held by delegators + OperatorAddress sdk.AccAddress + SelfBondRewards sdk.DecCoins + ValidatorCommission types.ValidatorAccumulatedCommission } ``` @@ -64,7 +56,7 @@ properties change (aka bonded tokens etc.) its properties will remain constant and the delegator's _accumulation_ factor can be calculated passively knowing only the height of the last withdrawal and its current properties. -- DelegationDistInfo: `0x02 | DelegatorAddr | ValOperatorAddr -> amino(delegatorDist)` +- DelegationDistInfo: `0x02 | DelegatorAddr | ValOperatorAddr -> ProtocolBuffer(delegatorDist)` ```go type DelegationDistInfo struct { diff --git a/x/distribution/spec/04_messages.md b/x/distribution/spec/04_messages.md index ef57cb4c3..4aff6b532 100644 --- a/x/distribution/spec/04_messages.md +++ b/x/distribution/spec/04_messages.md @@ -4,57 +4,35 @@ order: 4 # Messages -## MsgWithdrawDelegationRewardsAll +## MsgSetWithdrawAddress -When a delegator wishes to withdraw their rewards it must send -`MsgWithdrawDelegationRewardsAll`. Note that parts of this transaction logic are also -triggered each with any change in individual delegations, such as an unbond, -redelegation, or delegation of additional tokens to a specific validator. +By default a withdrawal address is delegator address. If a delegator wants to change it's +withdrawal address it must send `MsgSetWithdrawAddress`. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/tx.proto#L29-L37 ```go -type MsgWithdrawDelegationRewardsAll struct { - DelegatorAddr sdk.AccAddress -} -func WithdrawDelegationRewardsAll(delegatorAddr, withdrawAddr sdk.AccAddress) - height = GetHeight() - withdraw = GetDelegatorRewardsAll(delegatorAddr, height) - SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal()) +func (k Keeper) SetWithdrawAddr(ctx sdk.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error + if k.blockedAddrs[withdrawAddr.String()] { + fail with "`{withdrawAddr}` is not allowed to receive external funds" + } -func GetDelegatorRewardsAll(delegatorAddr sdk.AccAddress, height int64) DecCoins - - // get all distribution scenarios - delegations = GetDelegations(delegatorAddr) - - // collect all entitled rewards - withdraw = 0 - pool = staking.GetPool() - feePool = GetFeePool() - for delegation = range delegations - delInfo = GetDelegationDistInfo(delegation.DelegatorAddr, - delegation.ValidatorAddr) - valInfo = GetValidatorDistInfo(delegation.ValidatorAddr) - validator = GetValidator(delegation.ValidatorAddr) + if !k.GetWithdrawAddrEnabled(ctx) { + fail with `ErrSetWithdrawAddrDisabled` + } - feePool, diWithdraw = delInfo.WithdrawRewards(feePool, valInfo, height, pool.BondedTokens, - validator.Tokens, validator.DelegatorShares, validator.Commission) - withdraw += diWithdraw - - SetFeePool(feePool) - return withdraw + k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr) ``` -## MsgWithdrawDelegationReward +## MsgWithdrawDelegatorReward under special circumstances a delegator may wish to withdraw rewards from only a single validator. -```go -type MsgWithdrawDelegationReward struct { - DelegatorAddr sdk.AccAddress - ValidatorAddr sdk.ValAddress -} ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50 +```go func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.AccAddress) height = GetHeight() @@ -74,19 +52,16 @@ func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.Acc ``` -## MsgWithdrawValidatorRewardsAll +### Withdraw Validator Rewards All When a validator wishes to withdraw their rewards it must send -`MsgWithdrawValidatorRewardsAll`. Note that parts of this transaction logic are also +array of `MsgWithdrawDelegatorReward`. Note that parts of this transaction logic are also triggered each with any change in individual delegations, such as an unbond, redelegation, or delegation of additional tokens to a specific validator. This transaction withdraws the validators commission fee, as well as any rewards earning on their self-delegation. ```go -type MsgWithdrawValidatorRewardsAll struct { - OperatorAddr sdk.ValAddress // validator address to withdraw from -} func WithdrawValidatorRewardsAll(operatorAddr, withdrawAddr sdk.AccAddress) diff --git a/x/distribution/spec/README.md b/x/distribution/spec/README.md index 6d97f8fa3..fe5f5069d 100644 --- a/x/distribution/spec/README.md +++ b/x/distribution/spec/README.md @@ -89,9 +89,9 @@ to set up a script to periodically withdraw and rebond rewards. 2. **[State](02_state.md)** 3. **[End Block](03_end_block.md)** 4. **[Messages](04_messages.md)** - - [MsgWithdrawDelegationRewardsAll](04_messages.md#msgwithdrawdelegationrewardsall) - - [MsgWithdrawDelegationReward](04_messages.md#msgwithdrawdelegationreward) - - [MsgWithdrawValidatorRewardsAll](04_messages.md#msgwithdrawvalidatorrewardsall) + - [MsgSetWithdrawAddress](04_messages.md#msgsetwithdrawaddress) + - [MsgWithdrawDelegatorReward](04_messages.md#msgwithdrawdelegatorreward) + - [Withdraw Validator Rewards All](04_messages.md#withdraw-validator-rewards-all) - [Common calculations ](04_messages.md#common-calculations-) 5. **[Hooks](05_hooks.md)** - [Create or modify delegation distribution](05_hooks.md#create-or-modify-delegation-distribution)