certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
atheeshp 2021-01-11 17:41:22 +05:30 committed by GitHub
parent 834688f6d4
commit 8ac3bd2642
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 51 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
x/auth/spec/01_concepts.md
View File

@ -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 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: 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 When adding transactions to mempool or gossipping transactions, validators check
if the transaction's gas prices, which are determined by the provided fees, meet if the transaction's gas prices, which are determined by the provided fees, meet

50
x/auth/spec/05_vesting.md
View File

@ -88,52 +88,28 @@ type VestingAccount interface {
GetStartTime() int64 GetStartTime() int64
GetEndTime() 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 ### ContinuousVestingAccount
// the necessary fields needed for any vesting account implementation. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43
type BaseVestingAccount struct {
BaseAccount
OriginalVesting Coins // coins in account upon initialization ### DelayedVestingAccount
DelegatedFree Coins // coins that are vested and delegated +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53
DelegatedVesting Coins // coins that vesting and delegated
EndTime int64 // when the coins become unlocked ### Period
} +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L56-L62
// 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
}
```go
// Stores all vesting periods passed as part of a PeriodicVestingAccount // Stores all vesting periods passed as part of a PeriodicVestingAccount
type Periods []Period 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 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 flexibility in account balance usage, the existing `x/bank` `ViewKeeper` interface
is updated to contain the following: is updated to contain the following:

10
x/auth/spec/07_params.md
View File

@ -8,8 +8,8 @@ The auth module contains the following parameters:
| Key | Type | Example | | Key | Type | Example |
| ---------------------- | --------------- | ------- | | ---------------------- | --------------- | ------- |
| MaxMemoCharacters | string (uint64) | "256" | | MaxMemoCharacters | uint64 | 256 |
| TxSigLimit | string (uint64) | "7" | | TxSigLimit | uint64 | 7 |
| TxSizeCostPerByte | string (uint64) | "10" | | TxSizeCostPerByte | uint64 | 10 |
| SigVerifyCostED25519 | string (uint64) | "590" | | SigVerifyCostED25519 | uint64 | 590 |
| SigVerifyCostSecp256k1 | string (uint64) | "1000" | | SigVerifyCostSecp256k1 | uint64 | 1000 |

2
x/bank/spec/02_keepers.md
View File

@ -44,7 +44,7 @@ The base keeper provides full-permission access: the ability to arbitrary modify
type Keeper interface { type Keeper interface {
SendKeeper SendKeeper
InitGenesis(sdk.Context, types.GenesisState) InitGenesis(sdk.Context, *types.GenesisState)
ExportGenesis(sdk.Context) *types.GenesisState ExportGenesis(sdk.Context) *types.GenesisState
GetSupply(ctx sdk.Context) exported.SupplyI GetSupply(ctx sdk.Context) exported.SupplyI

11
x/bank/spec/03_messages.md
View File

@ -6,18 +6,11 @@ order: 3
## MsgSend ## MsgSend
```go +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L19-L28
// 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;
}
```
`handleMsgSend` just runs `inputOutputCoins`. `handleMsgSend` just runs `inputOutputCoins`.
``` ```go
handleMsgSend(msg MsgSend) handleMsgSend(msg MsgSend)
inputSum = 0 inputSum = 0
for input in inputs for input in inputs

24
x/distribution/spec/02_state.md
View File

@ -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 When coins are distributed from the pool they are truncated back to
`sdk.Coins` which are non-decimal. `sdk.Coins` which are non-decimal.
- FeePool: `0x00 -> amino(FeePool)` - FeePool: `0x00 -> ProtocolBuffer(FeePool)`
```go ```go
// coins with decimal // coins with decimal
@ -25,15 +25,10 @@ type DecCoin struct {
Amount sdk.Dec Amount sdk.Dec
Denom string 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
Validator distribution information for the relevant validator is updated each time: 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 3. any delegator withdraws from a validator, or
4. the validator withdraws it's commission. 4. the validator withdraws it's commission.
- ValidatorDistInfo: `0x02 | ValOperatorAddr -> amino(validatorDistribution)` - ValidatorDistInfo: `0x02 | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)`
```go ```go
type ValidatorDistInfo struct { type ValidatorDistInfo struct {
FeePoolWithdrawalHeight int64 // last height this validator withdrew from the global fee pool OperatorAddress sdk.AccAddress
Pool DecCoins // rewards owed to delegators, commission has already been charged (includes proposer reward) SelfBondRewards sdk.DecCoins
PoolCommission DecCoins // commission collected by this validator (pending withdrawal) ValidatorCommission types.ValidatorAccumulatedCommission
TotalDelAccumUpdateHeight int64 // last height which the total delegator accum was updated
TotalDelAccum sdk.Dec // total proposer pool accumulation factor held by delegators
} }
``` ```
@ -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 and the delegator's _accumulation_ factor can be calculated passively knowing
only the height of the last withdrawal and its current properties. only the height of the last withdrawal and its current properties.
- DelegationDistInfo: `0x02 | DelegatorAddr | ValOperatorAddr -> amino(delegatorDist)` - DelegationDistInfo: `0x02 | DelegatorAddr | ValOperatorAddr -> ProtocolBuffer(delegatorDist)`
```go ```go
type DelegationDistInfo struct { type DelegationDistInfo struct {

61
x/distribution/spec/04_messages.md
View File

@ -4,57 +4,35 @@ order: 4
# Messages # Messages
## MsgWithdrawDelegationRewardsAll ## MsgSetWithdrawAddress
When a delegator wishes to withdraw their rewards it must send By default a withdrawal address is delegator address. If a delegator wants to change it's
`MsgWithdrawDelegationRewardsAll`. Note that parts of this transaction logic are also withdrawal address it must send `MsgSetWithdrawAddress`.
triggered each with any change in individual delegations, such as an unbond,
redelegation, or delegation of additional tokens to a specific validator. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/tx.proto#L29-L37
```go ```go
type MsgWithdrawDelegationRewardsAll struct {
DelegatorAddr sdk.AccAddress
}
func WithdrawDelegationRewardsAll(delegatorAddr, withdrawAddr sdk.AccAddress) func (k Keeper) SetWithdrawAddr(ctx sdk.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error
height = GetHeight() if k.blockedAddrs[withdrawAddr.String()] {
withdraw = GetDelegatorRewardsAll(delegatorAddr, height) fail with "`{withdrawAddr}` is not allowed to receive external funds"
SendCoins(distributionModuleAcc, withdrawAddr, withdraw.TruncateDecimal()) }
func GetDelegatorRewardsAll(delegatorAddr sdk.AccAddress, height int64) DecCoins if !k.GetWithdrawAddrEnabled(ctx) {
fail with `ErrSetWithdrawAddrDisabled`
// 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, k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr)
validator.Tokens, validator.DelegatorShares, validator.Commission)
withdraw += diWithdraw
SetFeePool(feePool)
return withdraw
``` ```
## 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. a single validator.
```go +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50
type MsgWithdrawDelegationReward struct {
DelegatorAddr sdk.AccAddress
ValidatorAddr sdk.ValAddress
}
```go
func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.AccAddress) func WithdrawDelegationReward(delegatorAddr, validatorAddr, withdrawAddr sdk.AccAddress)
height = GetHeight() 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 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, triggered each with any change in individual delegations, such as an unbond,
redelegation, or delegation of additional tokens to a specific validator. This redelegation, or delegation of additional tokens to a specific validator. This
transaction withdraws the validators commission fee, as well as any rewards transaction withdraws the validators commission fee, as well as any rewards
earning on their self-delegation. earning on their self-delegation.
```go ```go
type MsgWithdrawValidatorRewardsAll struct {
OperatorAddr sdk.ValAddress // validator address to withdraw from
}
func WithdrawValidatorRewardsAll(operatorAddr, withdrawAddr sdk.AccAddress) func WithdrawValidatorRewardsAll(operatorAddr, withdrawAddr sdk.AccAddress)

6
x/distribution/spec/README.md
View File

@ -89,9 +89,9 @@ to set up a script to periodically withdraw and rebond rewards.
2. **[State](02_state.md)** 2. **[State](02_state.md)**
3. **[End Block](03_end_block.md)** 3. **[End Block](03_end_block.md)**
4. **[Messages](04_messages.md)** 4. **[Messages](04_messages.md)**
- [MsgWithdrawDelegationRewardsAll](04_messages.md#msgwithdrawdelegationrewardsall) - [MsgSetWithdrawAddress](04_messages.md#msgsetwithdrawaddress)
- [MsgWithdrawDelegationReward](04_messages.md#msgwithdrawdelegationreward) - [MsgWithdrawDelegatorReward](04_messages.md#msgwithdrawdelegatorreward)
- [MsgWithdrawValidatorRewardsAll](04_messages.md#msgwithdrawvalidatorrewardsall) - [Withdraw Validator Rewards All](04_messages.md#withdraw-validator-rewards-all)
- [Common calculations ](04_messages.md#common-calculations-) - [Common calculations ](04_messages.md#common-calculations-)
5. **[Hooks](05_hooks.md)** 5. **[Hooks](05_hooks.md)**
- [Create or modify delegation distribution](05_hooks.md#create-or-modify-delegation-distribution) - [Create or modify delegation distribution](05_hooks.md#create-or-modify-delegation-distribution)