backport: x/{auth, bank, distr} docs basic cleanup (#8268) (#8304)

cosmos · Feb 22, 2021 · ba8de90 · ba8de90
1 parent bdec113
commit ba8de90
Show file tree

Hide file tree

Showing 8 changed files with 87 additions and 152 deletions.
diff --git 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
@@ -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
-
-  OriginalVesting  Coins // coins in account upon initialization
-  DelegatedFree    Coins // coins that are vested and delegated
-  DelegatedVesting Coins // coins that vesting and delegated
-
-  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
-}
+### ContinuousVestingAccount
++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43
 
-// 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
-}
+### DelayedVestingAccount
++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53
 
-// 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -4,108 +4,82 @@ 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)
-
-        feePool, diWithdraw = delInfo.WithdrawRewards(feePool, valInfo, height, pool.BondedTokens, 
-                   validator.Tokens, validator.DelegatorShares, validator.Commission)
-        withdraw += diWithdraw
-
-    SetFeePool(feePool) 
-    return withdraw
+	if !k.GetWithdrawAddrEnabled(ctx) {
+		fail with `ErrSetWithdrawAddrDisabled`
+	}
+
+	k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr)
 ```
 
-## MsgWithdrawDelegationReward
+## MsgWithdrawDelegatorReward
 
-under special circumstances a delegator may wish to withdraw rewards from only
+Under special circumstances a delegator may wish to withdraw rewards from only
 a single validator. 
 
++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50
+
 ```go
-type MsgWithdrawDelegationReward struct {
-    DelegatorAddr sdk.AccAddress
-    ValidatorAddr sdk.ValAddress
+// withdraw rewards from a delegation
+func (k Keeper) WithdrawDelegationRewards(ctx sdk.Context, delAddr sdk.AccAddress, valAddr sdk.ValAddress) (sdk.Coins, error) {
+	val := k.stakingKeeper.Validator(ctx, valAddr)
+	if val == nil {
+		return nil, types.ErrNoValidatorDistInfo
+	}
+
+	del := k.stakingKeeper.Delegation(ctx, delAddr, valAddr)
+	if del == nil {
+		return nil, types.ErrEmptyDelegationDistInfo
+	}
+
+	// withdraw rewards
+	rewards, err := k.withdrawDelegationRewards(ctx, val, del)
+	if err != nil {
+		return nil, err
+	}
+
+	// reinitialize the delegation
+	k.initializeDelegation(ctx, valAddr, delAddr)
+	return rewards, nil
 }
-
-func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.AccAddress) 
-    height = GetHeight()
-
-    // get all distribution scenarios
-    pool = staking.GetPool() 
-    feePool = GetFeePool() 
-    delInfo = GetDelegationDistInfo(delegatorAddr,
-                    validatorAddr)
-    valInfo = GetValidatorDistInfo(validatorAddr)
-    validator = GetValidator(validatorAddr)
-
-    feePool, withdraw = delInfo.WithdrawRewards(feePool, valInfo, height, pool.BondedTokens, 
-               validator.Tokens, validator.DelegatorShares, validator.Commission)
-
-    SetFeePool(feePool) 
-    SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal())
 ```
 
+## Withdraw Validator Rewards All
 
-## MsgWithdrawValidatorRewardsAll
-
-When a validator wishes to withdraw their rewards it must send
-`MsgWithdrawValidatorRewardsAll`. Note that parts of this transaction logic are also
+When a validator wishes to withdraw their rewards it must send an
+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)
-
-    height = GetHeight()
-    feePool = GetFeePool() 
-    pool = GetPool() 
-    ValInfo = GetValidatorDistInfo(delegation.ValidatorAddr)
-    validator = GetValidator(delegation.ValidatorAddr)
 
-    // withdraw self-delegation
-    withdraw = GetDelegatorRewardsAll(validator.OperatorAddr, height)
-
-    // withdrawal validator commission rewards
-    feePool, commission = valInfo.WithdrawCommission(feePool, valInfo, height, pool.BondedTokens, 
-               validator.Tokens, validator.Commission)
-    withdraw += commission
-    SetFeePool(feePool) 
-
-    SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal())
+for _, valAddr := range validators {
+    val, err := sdk.ValAddressFromBech32(valAddr)
+    if err != nil {
+        return err
+    }
+
+    msg := types.NewMsgWithdrawDelegatorReward(delAddr, val)
+    if err := msg.ValidateBasic(); err != nil {
+        return err
+    }
+    msgs = append(msgs, msg)
+}
 ```
 
 ## Common calculations 

diff --git 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)