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
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

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

@ -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:

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

@ -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 |

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 {
SendKeeper
InitGenesis(sdk.Context, types.GenesisState)
InitGenesis(sdk.Context, *types.GenesisState)
ExportGenesis(sdk.Context) *types.GenesisState
GetSupply(ctx sdk.Context) exported.SupplyI

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

@ -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

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
`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 {

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

@ -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
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,
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)

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)**
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)