LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs: Improve markdownlint configuration (#11104)

Browse Source 
## Description

Closes: #9404



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
This commit is contained in:
Julien Robert
2022-02-10 12:07:01 +00:00
committed by GitHub
parent b1f9a117f7
commit 58597139fa
212 changed files with 3792 additions and 3755 deletions
Download Patch File Download Diff File Expand all files Collapse all files
x/README.md
+15 -15
View File
@@ -6,21 +6,21 @@ order: 0
Here are some production-grade modules that can be used in Cosmos SDK applications, along with their respective documentation:
- [Auth](auth/spec/README.md) - Authentication of accounts and transactions for Cosmos SDK applications.
- [Authz](authz/spec/README.md) - Authorization for accounts to perform actions on behalf of other accounts.
- [Bank](bank/spec/README.md) - Token transfer functionalities.
- [Capability](capability/spec/README.md) - Object capability implementation.
- [Crisis](crisis/spec/README.md) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken).
- [Distribution](distribution/spec/README.md) - Fee distribution, and staking token provision distribution.
- [Epoching](epoching/spec/README.md) - Allows modules to queue messages for execution at a certain block height.
- [Evidence](evidence/spec/README.md) - Evidence handling for double signing, misbehaviour, etc.
- [Feegrant](feegrant/spec/README.md) - Grant fee allowances for executing transactions.
- [Governance](gov/spec/README.md) - On-chain proposals and voting.
- [Mint](mint/spec/README.md) - Creation of new units of staking token.
- [Params](params/spec/README.md) - Globally available parameter store.
- [Slashing](slashing/spec/README.md) - Validator punishment mechanisms.
- [Staking](staking/spec/README.md) - Proof-of-Stake layer for public blockchains.
- [Upgrade](upgrade/spec/README.md) - Software upgrades handling and coordination.
* [Auth](auth/spec/README.md) - Authentication of accounts and transactions for Cosmos SDK applications.
* [Authz](authz/spec/README.md) - Authorization for accounts to perform actions on behalf of other accounts.
* [Bank](bank/spec/README.md) - Token transfer functionalities.
* [Capability](capability/spec/README.md) - Object capability implementation.
* [Crisis](crisis/spec/README.md) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken).
* [Distribution](distribution/spec/README.md) - Fee distribution, and staking token provision distribution.
* [Epoching](epoching/spec/README.md) - Allows modules to queue messages for execution at a certain block height.
* [Evidence](evidence/spec/README.md) - Evidence handling for double signing, misbehaviour, etc.
* [Feegrant](feegrant/spec/README.md) - Grant fee allowances for executing transactions.
* [Governance](gov/spec/README.md) - On-chain proposals and voting.
* [Mint](mint/spec/README.md) - Creation of new units of staking token.
* [Params](params/spec/README.md) - Globally available parameter store.
* [Slashing](slashing/spec/README.md) - Validator punishment mechanisms.
* [Staking](staking/spec/README.md) - Proof-of-Stake layer for public blockchains.
* [Upgrade](upgrade/spec/README.md) - Software upgrades handling and coordination.
To learn more about the process of building modules, visit the [building modules reference documentation](../docs/building-modules/README.md).
x/auth/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Auth
- [Auth](spec/README.md) - Authentication of accounts and transactions for Cosmos SDK applications.
* [Auth](spec/README.md) - Authentication of accounts and transactions for Cosmos SDK applications.
x/auth/spec/02_state.md
+1 -1
View File
@@ -15,7 +15,7 @@ Accounts are exposed externally as an interface, and stored internally as
either a base account or vesting account. Module clients wishing to add more
account types may do so.
- `0x01 | Address -> ProtocolBuffer(account)`
* `0x01 | Address -> ProtocolBuffer(account)`
### Account Interface
x/auth/spec/03_antehandlers.md
+13 -13
View File
@@ -13,28 +13,28 @@ Note that the `AnteHandler` is called on both `CheckTx` and `DeliverTx`, as Tend
The auth module provides `AnteDecorator`s that are recursively chained together into a single `AnteHandler` in the following order:
- `SetUpContextDecorator`: Sets the `GasMeter` in the `Context` and wraps the next `AnteHandler` with a defer clause to recover from any downstream `OutOfGas` panics in the `AnteHandler` chain to return an error with information on gas provided and gas used.
* `SetUpContextDecorator`: Sets the `GasMeter` in the `Context` and wraps the next `AnteHandler` with a defer clause to recover from any downstream `OutOfGas` panics in the `AnteHandler` chain to return an error with information on gas provided and gas used.
- `RejectExtensionOptionsDecorator`: Rejects all extension options which can optionally be included in protobuf transactions.
* `RejectExtensionOptionsDecorator`: Rejects all extension options which can optionally be included in protobuf transactions.
- `MempoolFeeDecorator`: Checks if the `tx` fee is above local mempool `minFee` parameter during `CheckTx`.
* `MempoolFeeDecorator`: Checks if the `tx` fee is above local mempool `minFee` parameter during `CheckTx`.
- `ValidateBasicDecorator`: Calls `tx.ValidateBasic` and returns any non-nil error.
* `ValidateBasicDecorator`: Calls `tx.ValidateBasic` and returns any non-nil error.
- `TxTimeoutHeightDecorator`: Check for a `tx` height timeout.
* `TxTimeoutHeightDecorator`: Check for a `tx` height timeout.
- `ValidateMemoDecorator`: Validates `tx` memo with application parameters and returns any non-nil error.
* `ValidateMemoDecorator`: Validates `tx` memo with application parameters and returns any non-nil error.
- `ConsumeGasTxSizeDecorator`: Consumes gas proportional to the `tx` size based on application parameters.
* `ConsumeGasTxSizeDecorator`: Consumes gas proportional to the `tx` size based on application parameters.
- `DeductFeeDecorator`: Deducts the `FeeAmount` from first signer of the `tx`. If the `x/feegrant` module is enabled and a fee granter is set, it deducts fees from the fee granter account.
* `DeductFeeDecorator`: Deducts the `FeeAmount` from first signer of the `tx`. If the `x/feegrant` module is enabled and a fee granter is set, it deducts fees from the fee granter account.
- `SetPubKeyDecorator`: Sets the pubkey from a `tx`'s signers that does not already have its corresponding pubkey saved in the state machine and in the current context.
* `SetPubKeyDecorator`: Sets the pubkey from a `tx`'s signers that does not already have its corresponding pubkey saved in the state machine and in the current context.
- `ValidateSigCountDecorator`: Validates the number of signatures in `tx` based on app-parameters.
* `ValidateSigCountDecorator`: Validates the number of signatures in `tx` based on app-parameters.
- `SigGasConsumeDecorator`: Consumes parameter-defined amount of gas for each signature. This requires pubkeys to be set in context for all signers as part of `SetPubKeyDecorator`.
* `SigGasConsumeDecorator`: Consumes parameter-defined amount of gas for each signature. This requires pubkeys to be set in context for all signers as part of `SetPubKeyDecorator`.
- `SigVerificationDecorator`: Verifies all signatures are valid. This requires pubkeys to be set in context for all signers as part of `SetPubKeyDecorator`.
* `SigVerificationDecorator`: Verifies all signatures are valid. This requires pubkeys to be set in context for all signers as part of `SetPubKeyDecorator`.
- `IncrementSequenceDecorator`: Increments the account sequence for each signer to prevent replay attacks.
* `IncrementSequenceDecorator`: Increments the account sequence for each signer to prevent replay attacks.
x/auth/spec/05_vesting.md
+70 -64
View File
@@ -4,28 +4,34 @@ order: 5
# Vesting
- [Vesting](#vesting)
- [Intro and Requirements](#intro-and-requirements)
- [Note](#note)
- [Vesting Account Types](#vesting-account-types)
- [Vesting Account Specification](#vesting-account-specification)
- [Determining Vesting & Vested Amounts](#determining-vesting--vested-amounts)
- [Continuously Vesting Accounts](#continuously-vesting-accounts)
- [Periodic Vesting Accounts](#periodic-vesting-accounts)
- [Delayed/Discrete Vesting Accounts](#delayeddiscrete-vesting-accounts)
- [Transferring/Sending](#transferringsending)
- [Keepers/Handlers](#keepershandlers)
- [Delegating](#delegating)
- [Keepers/Handlers](#keepershandlers-1)
- [Undelegating](#undelegating)
- [Keepers/Handlers](#keepershandlers-2)
- [Keepers & Handlers](#keepers--handlers)
- [Genesis Initialization](#genesis-initialization)
- [Examples](#examples)
- [Simple](#simple)
- [Slashing](#slashing)
- [Periodic Vesting](#periodic-vesting)
- [Glossary](#glossary)
* [Vesting](#vesting)
* [Intro and Requirements](#intro-and-requirements)
* [Note](#note)
* [Vesting Account Types](#vesting-account-types)
* [BaseVestingAccount](#basevestingaccount)
* [ContinuousVestingAccount](#continuousvestingaccount)
* [DelayedVestingAccount](#delayedvestingaccount)
* [Period](#period)
* [PeriodicVestingAccount](#periodicvestingaccount)
* [PermanentLockedAccount](#permanentlockedaccount)
* [Vesting Account Specification](#vesting-account-specification)
* [Determining Vesting & Vested Amounts](#determining-vesting--vested-amounts)
* [Continuously Vesting Accounts](#continuously-vesting-accounts)
* [Periodic Vesting Accounts](#periodic-vesting-accounts)
* [Delayed/Discrete Vesting Accounts](#delayeddiscrete-vesting-accounts)
* [Transferring/Sending](#transferringsending)
* [Keepers/Handlers](#keepershandlers)
* [Delegating](#delegating)
* [Keepers/Handlers](#keepershandlers-1)
* [Undelegating](#undelegating)
* [Keepers/Handlers](#keepershandlers-2)
* [Keepers & Handlers](#keepers--handlers)
* [Genesis Initialization](#genesis-initialization)
* [Examples](#examples)
* [Simple](#simple)
* [Slashing](#slashing)
* [Periodic Vesting](#periodic-vesting)
* [Glossary](#glossary)
## Intro and Requirements
@@ -42,10 +48,10 @@ and undelegate from validators, however they cannot transfer coins to another
account until those coins are vested. This specification allows for four
different kinds of vesting:
- Delayed vesting, where all coins are vested once `ET` is reached.
- Continous vesting, where coins begin to vest at `ST` and vest linearly with
* Delayed vesting, where all coins are vested once `ET` is reached.
* Continous vesting, where coins begin to vest at `ST` and vest linearly with
respect to time until `ET` is reached
- Periodic vesting, where coins begin to vest at `ST` and vest periodically
* Periodic vesting, where coins begin to vest at `ST` and vest periodically
according to number of periods and the vesting amount per period.
The number of periods, length per period, and amount per period are
configurable. A periodic vesting account is distinguished from a continuous
@@ -53,7 +59,7 @@ vesting account in that coins can be released in staggered tranches. For
example, a periodic vesting account could be used for vesting arrangements
where coins are relased quarterly, yearly, or over any other function of
tokens over time.
- Permanent locked vesting, where coins are locked forever. Coins in this account can
* Permanent locked vesting, where coins are locked forever. Coins in this account can
still be used for delegating and for governance votes even while locked.
## Note
@@ -94,19 +100,19 @@ type VestingAccount interface {
### BaseVestingAccount
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L10-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L10-L33>
### ContinuousVestingAccount
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43>
### DelayedVestingAccount
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53>
### Period
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L56-L62
+++ <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
@@ -116,7 +122,7 @@ type Periods []Period
### PeriodicVestingAccount
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L64-L73
+++ <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
@@ -136,23 +142,23 @@ type ViewKeeper interface {
### PermanentLockedAccount
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L78-L83
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L78-L83>
## Vesting Account Specification
Given a vesting account, we define the following in the proceeding operations:
- `OV`: The original vesting coin amount. It is a constant value.
- `V`: The number of `OV` coins that are still _vesting_. It is derived by
* `OV`: The original vesting coin amount. It is a constant value.
* `V`: The number of `OV` coins that are still _vesting_. It is derived by
`OV`, `StartTime` and `EndTime`. This value is computed on demand and not on a
per-block basis.
- `V'`: The number of `OV` coins that are _vested_ (unlocked). This value is
* `V'`: The number of `OV` coins that are _vested_ (unlocked). This value is
computed on demand and not a per-block basis.
- `DV`: The number of delegated _vesting_ coins. It is a variable value. It is
* `DV`: The number of delegated _vesting_ coins. It is a variable value. It is
stored and modified directly in the vesting account.
- `DF`: The number of delegated _vested_ (unlocked) coins. It is a variable
* `DF`: The number of delegated _vested_ (unlocked) coins. It is a variable
value. It is stored and modified directly in the vesting account.
- `BC`: The number of `OV` coins less any coins that are transferred
* `BC`: The number of `OV` coins less any coins that are transferred
(which can be negative or delegated). It is considered to be balance of the
embedded base account. It is stored and modified directly in the vesting account.
@@ -461,7 +467,7 @@ func ToAccount(gacc GenesisAccount) Account {
Given a continuous vesting account with 10 vesting coins.
```
```text
OV = 10
DF = 0
DV = 0
@@ -472,33 +478,33 @@ V' = 0
1. Immediately receives 1 coin
```
```text
BC = 11
```
2. Time passes, 2 coins vest
```
```text
V = 8
V' = 2
```
3. Delegates 4 coins to validator A
```
```text
DV = 4
BC = 7
```
4. Sends 3 coins
```
```text
BC = 4
```
5. More time passes, 2 more coins vest
```
```text
V = 6
V' = 4
```
@@ -506,7 +512,7 @@ V' = 0
6. Sends 2 coins. At this point the account cannot send anymore until further
coins vest or it receives additional coins. It can still however, delegate.
```
```text
BC = 2
```
@@ -516,21 +522,21 @@ Same initial starting conditions as the simple example.
1. Time passes, 5 coins vest
```
```text
V = 5
V' = 5
```
2. Delegate 5 coins to validator A
```
```text
DV = 5
BC = 5
```
3. Delegate 5 coins to validator B
```
```text
DF = 5
BC = 0
```
@@ -538,7 +544,7 @@ Same initial starting conditions as the simple example.
4. Validator A gets slashed by 50%, making the delegation to A now worth 2.5 coins
5. Undelegate from validator A (2.5 coins)
```
```text
DF = 5 - 2.5 = 2.5
BC = 0 + 2.5 = 2.5
```
@@ -547,7 +553,7 @@ Same initial starting conditions as the simple example.
send 2.5 coins unless it receives more coins or until more coins vest.
It can still however, delegate.
```
```text
DV = 5 - 2.5 = 2.5
DF = 2.5 - 2.5 = 0
BC = 2.5 + 5 = 7.5
@@ -568,7 +574,7 @@ Periods:
- amount: 25stake, length: 7884000
```
```
```text
OV = 100
DF = 0
DV = 0
@@ -579,46 +585,46 @@ V' = 0
1. Immediately receives 1 coin
```
```text
BC = 101
```
2. Vesting period 1 passes, 25 coins vest
```
```text
V = 75
V' = 25
```
3. During vesting period 2, 5 coins are transfered and 5 coins are delegated
```
```text
DV = 5
BC = 91
```
4. Vesting period 2 passes, 25 coins vest
```
```text
V = 50
V' = 50
```
## Glossary
- OriginalVesting: The amount of coins (per denomination) that are initially
* OriginalVesting: The amount of coins (per denomination) that are initially
part of a vesting account. These coins are set at genesis.
- StartTime: The BFT time at which a vesting account starts to vest.
- EndTime: The BFT time at which a vesting account is fully vested.
- DelegatedFree: The tracked amount of coins (per denomination) that are
* StartTime: The BFT time at which a vesting account starts to vest.
* EndTime: The BFT time at which a vesting account is fully vested.
* DelegatedFree: The tracked amount of coins (per denomination) that are
delegated from a vesting account that have been fully vested at time of delegation.
- DelegatedVesting: The tracked amount of coins (per denomination) that are
* DelegatedVesting: The tracked amount of coins (per denomination) that are
delegated from a vesting account that were vesting at time of delegation.
- ContinuousVestingAccount: A vesting account implementation that vests coins
* ContinuousVestingAccount: A vesting account implementation that vests coins
linearly over time.
- DelayedVestingAccount: A vesting account implementation that only fully vests
* DelayedVestingAccount: A vesting account implementation that only fully vests
all coins at a given time.
- PeriodicVestingAccount: A vesting account implementation that vests coins
* PeriodicVestingAccount: A vesting account implementation that vests coins
according to a custom vesting schedule.
- PermanentLockedAccount: It does not ever release coins, locking them indefinitely.
* PermanentLockedAccount: It does not ever release coins, locking them indefinitely.
Coins in this account can still be used for delegating and for governance votes even while locked.
x/auth/spec/README.md
+17 -17
View File
@@ -21,26 +21,26 @@ This module is used in the Cosmos Hub.
## Contents
1. **[Concepts](01_concepts.md)**
- [Gas & Fees](01_concepts.md#gas-&-fees)
* [Gas & Fees](01_concepts.md#gas-&-fees)
2. **[State](02_state.md)**
- [Accounts](02_state.md#accounts)
* [Accounts](02_state.md#accounts)
3. **[AnteHandlers](03_antehandlers.md)**
- [Handlers](03_antehandlers.md#handlers)
* [Handlers](03_antehandlers.md#handlers)
4. **[Keepers](04_keepers.md)**
- [Account Keeper](04_keepers.md#account-keeper)
* [Account Keeper](04_keepers.md#account-keeper)
5. **[Vesting](05_vesting.md)**
- [Intro and Requirements](05_vesting.md#intro-and-requirements)
- [Vesting Account Types](05_vesting.md#vesting-account-types)
- [Vesting Account Specification](05_vesting.md#vesting-account-specification)
- [Keepers & Handlers](05_vesting.md#keepers-&-handlers)
- [Genesis Initialization](05_vesting.md#genesis-initialization)
- [Examples](05_vesting.md#examples)
- [Glossary](05_vesting.md#glossary)
* [Intro and Requirements](05_vesting.md#intro-and-requirements)
* [Vesting Account Types](05_vesting.md#vesting-account-types)
* [Vesting Account Specification](05_vesting.md#vesting-account-specification)
* [Keepers & Handlers](05_vesting.md#keepers-&-handlers)
* [Genesis Initialization](05_vesting.md#genesis-initialization)
* [Examples](05_vesting.md#examples)
* [Glossary](05_vesting.md#glossary)
6. **[Parameters](06_params.md)**
7. **[Client](07_client.md)**
- **[Auth](07_client.md#auth)**
- [CLI](07_client.md#cli)
- [gRPC](07_client.md#grpc)
- [REST](07_client.md#rest)
- **[Vesting](07_client.md#vesting)**
- [CLI](07_client.md#vesting#cli)
* **[Auth](07_client.md#auth)**
* [CLI](07_client.md#cli)
* [gRPC](07_client.md#grpc)
* [REST](07_client.md#rest)
* **[Vesting](07_client.md#vesting)**
* [CLI](07_client.md#vesting#cli)
x/authz/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Authz
- [Authz](spec/README.md) - Authorization for accounts to perform actions on behalf of other accounts.
* [Authz](spec/README.md) - Authorization for accounts to perform actions on behalf of other accounts.
x/authz/spec/01_concepts.md
+9 -9
View File
@@ -14,7 +14,7 @@ Authorization is an interface that must be implemented by a concrete authorizati
**Note:** The authz module is different from the [auth (authentication)](../modules/auth/) module that is responsible for specifying the base transaction and account types.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/authorizations.go#L11-L25
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/authorizations.go#L11-L25>
## Built-in Authorizations
@@ -24,29 +24,29 @@ The Cosmos SDK `x/authz` module comes with following authorization types:
`GenericAuthorization` implements the `Authorization` interface that gives unrestricted permission to execute the provided Msg on behalf of granter's account.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L14-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L14-L19>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/generic_authorization.go#L18-L31
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/generic_authorization.go#L18-L31>
- `msg` stores Msg type URL.
* `msg` stores Msg type URL.
### SendAuthorization
`SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. It takes a `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/types/send_authorization.go#L25-L40
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/types/send_authorization.go#L25-L40>
- `spend_limit` keeps track of how many coins are left in the authorization.
* `spend_limit` keeps track of how many coins are left in the authorization.
### StakeAuthorization
`StakeAuthorization` implements the `Authorization` interface for messages in the [staking module](https://docs.cosmos.network/v0.44/modules/staking/). It takes an `AuthorizationType` to specify whether you want to authorise delegating, undelegating or redelegating (i.e. these have to be authorised seperately). It also takes a `MaxTokens` that keeps track of a limit to the amount of tokens that can be delegated/undelegated/redelegated. If left empty, the amount is unlimited. Additionally, this Msg takes an `AllowList` and a `DenyList`, which allows you to select which validators you allow grantees to stake with.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/staking/v1beta1/authz.proto#L11-L31
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/staking/v1beta1/authz.proto#L11-L31>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/staking/types/authz.go#L18-L38
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/staking/types/authz.go#L18-L38>
## Gas
x/authz/spec/02_state.md
+2 -2
View File
@@ -8,8 +8,8 @@ order: 2
Grants are identified by combining granter address (the address bytes of the granter), grantee address (the address bytes of the grantee) and Authorization type (its type URL). Hence we only allow one grant for the (granter, grantee, Authorization) triple.
- Grant: `0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes-> ProtocolBuffer(AuthorizationGrant)`
* Grant: `0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes-> ProtocolBuffer(AuthorizationGrant)`
The grant object encapsulates an `Authorization` type and an expiration timestamp:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L21-L26
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L21-L26>
x/authz/spec/03_messages.md
+12 -12
View File
@@ -11,25 +11,25 @@ In this section we describe the processing of messages for the authz module.
An authorization grant is created using the `MsgGrant` message.
If there is already a grant for the `(granter, grantee, Authorization)` triple, then the new grant overwrites the previous one. To update or extend an existing grant, a new grant with the same `(granter, grantee, Authorization)` triple should be created.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L32-L37
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L32-L37>
The message handling should fail if:
- both granter and grantee have the same address.
- provided `Expiration` time is less than current unix timestamp.
- provided `Grant.Authorization` is not implemented.
- `Authorization.MsgTypeURL()` is not defined in the router (there is no defined handler in the app router to handle that Msg types).
* both granter and grantee have the same address.
* provided `Expiration` time is less than current unix timestamp.
* provided `Grant.Authorization` is not implemented.
* `Authorization.MsgTypeURL()` is not defined in the router (there is no defined handler in the app router to handle that Msg types).
## MsgRevoke
A grant can be removed with the `MsgRevoke` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L60-L64
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L60-L64>
The message handling should fail if:
- both granter and grantee have the same address.
- provided `MsgTypeUrl` is empty.
* both granter and grantee have the same address.
* provided `MsgTypeUrl` is empty.
NOTE: The `MsgExec` message removes a grant if the grant has expired.
@@ -37,10 +37,10 @@ NOTE: The `MsgExec` message removes a grant if the grant has expired.
When a grantee wants to execute a transaction on behalf of a granter, they must send `MsgExec`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L47-L53
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L47-L53>
The message handling should fail if:
- provided `Authorization` is not implemented.
- grantee doesn't have permission to run the transaction.
- if granted authorization is expired.
* provided `Authorization` is not implemented.
* grantee doesn't have permission to run the transaction.
* if granted authorization is expired.
x/authz/spec/README.md
+9 -9
View File
@@ -15,16 +15,16 @@ parent:
granting arbitrary privileges from one account (the granter) to another account (the grantee). Authorizations must be granted for a particular Msg service method one by one using an implementation of the `Authorization` interface.
1. **[Concept](01_concepts.md)**
- [Authorization and Grant](01_concepts.md#Authorization-and-Grant)
- [Built-in Authorizations](01_concepts.md#Built-in-Authorizations)
- [Gas](01_concepts.md#gas)
* [Authorization and Grant](01_concepts.md#Authorization-and-Grant)
* [Built-in Authorizations](01_concepts.md#Built-in-Authorizations)
* [Gas](01_concepts.md#gas)
2. **[State](02_state.md)**
3. **[Messages](03_messages.md)**
- [MsgGrant](03_messages.md#MsgGrant)
- [MsgRevoke](03_messages.md#MsgRevoke)
- [MsgExec](03_messages.md#MsgExec)
* [MsgGrant](03_messages.md#MsgGrant)
* [MsgRevoke](03_messages.md#MsgRevoke)
* [MsgExec](03_messages.md#MsgExec)
4. **[Events](04_events.md)**
5. **[Client](05_client.md)**
- [CLI](05_client.md#cli)
- [gRPC](05_client.md#grpc)
- [REST](05_client.md#rest)
* [CLI](05_client.md#cli)
* [gRPC](05_client.md#grpc)
* [REST](05_client.md#rest)
x/bank/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Bank
- [Bank](spec/README.md) - Token transfer functionalities.
* [Bank](spec/README.md) - Token transfer functionalities.
x/bank/atlas/atlas-v0.39.1.md
+6 -6
View File
@@ -140,7 +140,7 @@ The `x/bank` supports the following transactional commands.
1. Send tokens via a `MsgSend` message.
```shell
```sh
app tx send [from_key_or_address] [to_address] [amount] [...flags]
```
@@ -155,8 +155,8 @@ endpoint.
1. Construct an unsigned `MsgSend` transaction.
| Method | Path |
| :----- | :----------------------- |
| Method | Path |
| :----- | :----------------------------------- |
| `POST` | `/bank/accounts/{address}/transfers` |
Sample payload:
@@ -185,9 +185,9 @@ endpoint.
2. Query for an account's balance.
| Method | Path |
| :----- | :----------------------- |
| `GET` | `/bank/balances/{address}` |
| Method | Path |
| :----- | :------------------------- |
| `GET` | `/bank/balances/{address}` |
Sample response:
x/bank/spec/01_state.md
+4 -4
View File
@@ -13,7 +13,7 @@ The `x/bank` module keeps state of three primary objects:
In addition, the `x/bank` module keeps the following indexes to manage the
aforementioned state:
- Supply Index: `0x0 | byte(denom) -> byte(amount)`
- Denom Metadata Index: `0x1 | byte(denom) -> ProtocolBuffer(Metadata)`
- Balances Index: `0x2 | byte(address length) | []byte(address) | []byte(balance.Denom) -> ProtocolBuffer(balance)`
- Reverse Denomination to Address Index: `0x03 | byte(denom) | 0x00 | []byte(address) -> 0`
* Supply Index: `0x0 | byte(denom) -> byte(amount)`
* Denom Metadata Index: `0x1 | byte(denom) -> ProtocolBuffer(Metadata)`
* Balances Index: `0x2 | byte(address length) | []byte(address) | []byte(balance.Denom) -> ProtocolBuffer(balance)`
* Reverse Denomination to Address Index: `0x03 | byte(denom) | 0x00 | []byte(address) -> 0`
x/bank/spec/03_messages.md
+8 -8
View File
@@ -7,21 +7,21 @@ order: 3
## MsgSend
Send coins from one address to another.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L19-L28
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L19-L28>
The message will fail under the following conditions:
- The coins do not have sending enabled
- The `to` address is restricted
* The coins do not have sending enabled
* The `to` address is restricted
## MsgMultiSend
Send coins from and to a series of different address. If any of the receiving addresses do not correspond to an existing account, a new account is created.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L33-L39
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L33-L39>
The message will fail under the following conditions:
- Any of the coins do not have sending enabled
- Any of the `to` addresses are restricted
- Any of the coins are locked
- The inputs and outputs do not correctly correspond to one another
* Any of the coins do not have sending enabled
* Any of the `to` addresses are restricted
* Any of the coins are locked
* The inputs and outputs do not correctly correspond to one another
x/bank/spec/06_client.md
+37 -37
View File
@@ -12,7 +12,7 @@ A user can query and interact with the `bank` module using the CLI.
The `query` commands allow users to query `bank` state.
```
```sh
simd query bank --help
```
@@ -20,19 +20,19 @@ simd query bank --help
The `balances` command allows users to query account balances by address.
```
```sh
simd query bank balances [address] [flags]
```
Example:
```
```sh
simd query bank balances cosmos1..
```
Example Output:
```
```yml
balances:
- amount: "1000000000"
denom: stake
@@ -45,19 +45,19 @@ pagination:
The `denom-metadata` command allows users to query metadata for coin denominations. A user can query metadata for a single denomination using the `--denom` flag or all denominations without it.
```
```sh
simd query bank denom-metadata [flags]
```
Example:
```
```sh
simd query bank denom-metadata --denom stake
```
Example Output:
```
```yml
metadata:
base: stake
denom_units:
@@ -74,19 +74,19 @@ metadata:
The `total` command allows users to query the total supply of coins. A user can query the total supply for a single coin using the `--denom` flag or all coins without it.
```
```sh
simd query bank total [flags]
```
Example:
```
```sh
simd query bank total --denom stake
```
Example Output:
```
```yml
amount: "10000000000"
denom: stake
```
@@ -95,7 +95,7 @@ denom: stake
The `tx` commands allow users to interact with the `bank` module.
```
```sh
simd tx bank --help
```
@@ -103,13 +103,13 @@ simd tx bank --help
The `send` command allows users to send funds from one account to another.
```
```sh
simd tx bank send [from_key_or_address] [to_address] [amount] [flags]
```
Example:
```
```sh
simd tx bank send cosmos1.. cosmos1.. 100stake
```
@@ -121,13 +121,13 @@ A user can query the `bank` module using gRPC endpoints.
The `Balance` endpoint allows users to query account balance by address for a given denomination.
```
```sh
cosmos.bank.v1beta1.Query/Balance
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"address":"cosmos1..","denom":"stake"}' \
localhost:9090 \
@@ -136,7 +136,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"balance": {
"denom": "stake",
@@ -149,13 +149,13 @@ Example Output:
The `AllBalances` endpoint allows users to query account balance by address for all denominations.
```
```sh
cosmos.bank.v1beta1.Query/AllBalances
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"address":"cosmos1.."}' \
localhost:9090 \
@@ -164,7 +164,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"balances": [
{
@@ -182,13 +182,13 @@ Example Output:
The `DenomMetadata` endpoint allows users to query metadata for a single coin denomination.
```
```sh
cosmos.bank.v1beta1.Query/DenomMetadata
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"denom":"stake"}' \
localhost:9090 \
@@ -197,7 +197,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"metadata": {
"description": "native staking token of simulation app",
@@ -221,13 +221,13 @@ Example Output:
The `DenomsMetadata` endpoint allows users to query metadata for all coin denominations.
```
```sh
cosmos.bank.v1beta1.Query/DenomsMetadata
```
Example:
```
```sh
grpcurl -plaintext \
localhost:9090 \
cosmos.bank.v1beta1.Query/DenomsMetadata
@@ -235,7 +235,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"metadatas": [
{
@@ -264,13 +264,13 @@ Example Output:
The `DenomOwners` endpoint allows users to query metadata for a single coin denomination.
```
```sh
cosmos.bank.v1beta1.Query/DenomOwners
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"denom":"stake"}' \
localhost:9090 \
@@ -279,7 +279,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"denomOwners": [
{
@@ -307,13 +307,13 @@ Example Output:
The `TotalSupply` endpoint allows users to query the total supply of all coins.
```
```sh
cosmos.bank.v1beta1.Query/TotalSupply
```
Example:
```
```sh
grpcurl -plaintext \
localhost:9090 \
cosmos.bank.v1beta1.Query/TotalSupply
@@ -321,7 +321,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"supply": [
{
@@ -339,13 +339,13 @@ Example Output:
The `SupplyOf` endpoint allows users to query the total supply of a single coin.
```
```sh
cosmos.bank.v1beta1.Query/SupplyOf
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"denom":"stake"}' \
localhost:9090 \
@@ -354,7 +354,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"amount": {
"denom": "stake",
@@ -367,13 +367,13 @@ Example Output:
The `Params` endpoint allows users to query the parameters of the `bank` module.
```
```sh
cosmos.bank.v1beta1.Query/Params
```
Example:
```
```sh
grpcurl -plaintext \
localhost:9090 \
cosmos.bank.v1beta1.Query/Params
@@ -381,7 +381,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"params": {
"defaultSendEnabled": true
x/bank/spec/README.md
+17 -17
View File
@@ -26,9 +26,9 @@ This module will be used in the Cosmos Hub.
The `supply` functionality:
- passively tracks the total supply of coins within a chain,
- provides a pattern for modules to hold/interact with `Coins`, and
- introduces the invariant check to verify a chain's total supply.
* passively tracks the total supply of coins within a chain,
* provides a pattern for modules to hold/interact with `Coins`, and
* introduces the invariant check to verify a chain's total supply.
### Total Supply
@@ -68,10 +68,10 @@ The supply `Keeper` also introduces new wrapper functions for the auth `Keeper`
and the bank `Keeper` that are related to `ModuleAccount`s in order to be able
to:
- Get and set `ModuleAccount`s by providing the `Name`.
- Send coins from and to other `ModuleAccount`s or standard `Account`s
* Get and set `ModuleAccount`s by providing the `Name`.
* Send coins from and to other `ModuleAccount`s or standard `Account`s
(`BaseAccount` or `VestingAccount`) by passing only the `Name`.
- `Mint` or `Burn` coins for a `ModuleAccount` (restricted to its permissions).
* `Mint` or `Burn` coins for a `ModuleAccount` (restricted to its permissions).
### Permissions
@@ -83,23 +83,23 @@ permissions to that specific account and perform or not the action.
The available permissions are:
- `Minter`: allows for a module to mint a specific amount of coins.
- `Burner`: allows for a module to burn a specific amount of coins.
- `Staking`: allows for a module to delegate and undelegate a specific amount of coins.
* `Minter`: allows for a module to mint a specific amount of coins.
* `Burner`: allows for a module to burn a specific amount of coins.
* `Staking`: allows for a module to delegate and undelegate a specific amount of coins.
## Contents
1. **[State](01_state.md)**
2. **[Keepers](02_keepers.md)**
- [Common Types](02_keepers.md#common-types)
- [BaseKeeper](02_keepers.md#basekeeper)
- [SendKeeper](02_keepers.md#sendkeeper)
- [ViewKeeper](02_keepers.md#viewkeeper)
* [Common Types](02_keepers.md#common-types)
* [BaseKeeper](02_keepers.md#basekeeper)
* [SendKeeper](02_keepers.md#sendkeeper)
* [ViewKeeper](02_keepers.md#viewkeeper)
3. **[Messages](03_messages.md)**
- [MsgSend](03_messages.md#msgsend)
* [MsgSend](03_messages.md#msgsend)
4. **[Events](04_events.md)**
- [Handlers](04_events.md#handlers)
* [Handlers](04_events.md#handlers)
5. **[Parameters](05_params.md)**
6. **[Client](06_client.md)**
- [CLI](06_client.md#cli)
- [gRPC](06_client.md#grpc)
* [CLI](06_client.md#cli)
* [gRPC](06_client.md#grpc)
x/capability/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Capability
- [Capability](spec/README.md) - Object capability implementation.
* [Capability](spec/README.md) - Object capability implementation.
x/capability/spec/01_concepts.md
+1 -1
View File
@@ -31,4 +31,4 @@ not own.
## Stores
- MemStore
* MemStore
x/crisis/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Crisis
- [Crisis](spec/README.md) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken).
* [Crisis](spec/README.md) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken).
x/crisis/spec/01_state.md
+1 -1
View File
@@ -14,4 +14,4 @@ with the standard gas consumption method.
The ConstantFee param is held in the global params store.
- Params: `mint/params -> legacy_amino(sdk.Coin)`
* Params: `mint/params -> legacy_amino(sdk.Coin)`
x/crisis/spec/02_messages.md
+3 -3
View File
@@ -11,12 +11,12 @@ corresponding updates to the state.
Blockchain invariants can be checked using the `MsgVerifyInvariant` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/crisis/v1beta1/tx.proto#L14-L22
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/crisis/v1beta1/tx.proto#L14-L22>
This message is expected to fail if:
- the sender does not have enough coins for the constant fee
- the invariant route is not registered
* the sender does not have enough coins for the constant fee
* the invariant route is not registered
This message checks the invariant provided, and if the invariant is broken it
panics, halting the blockchain. If the invariant is broken, the constant fee is
x/crisis/spec/README.md
+4 -4
View File
@@ -16,11 +16,11 @@ application initialization process.
## Contents
1. **[State](01_state.md)**
- [ConstantFee](01_state.md#constantfee)
* [ConstantFee](01_state.md#constantfee)
2. **[Messages](02_messages.md)**
- [MsgVerifyInvariant](02_messages.md#msgverifyinvariant)
* [MsgVerifyInvariant](02_messages.md#msgverifyinvariant)
3. **[Events](03_events.md)**
- [Handlers](03_events.md#handlers)
* [Handlers](03_events.md#handlers)
4. **[Parameters](04_params.md)**
5. **[Client](05_client.md)**
- [CLI](05_client.md#cli)
* [CLI](05_client.md#cli)
x/distribution/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Distribution
- [Distribution](spec/README.md) - Fee distribution, and staking token provision distribution.
* [Distribution](spec/README.md) - Fee distribution, and staking token provision distribution.
x/distribution/spec/02_state.md
+4 -4
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 -> ProtocolBuffer(FeePool)`
* FeePool: `0x00 -> ProtocolBuffer(FeePool)`
```go
// coins with decimal
@@ -27,7 +27,7 @@ type DecCoin struct {
}
```
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/distribution.proto#L94-L101
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/distribution.proto#L94-L101>
## Validator Distribution
@@ -38,7 +38,7 @@ Validator distribution information for the relevant validator is updated each ti
3. any delegator withdraws from a validator, or
4. the validator withdraws its commission.
- ValidatorDistInfo: `0x02 | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)`
* ValidatorDistInfo: `0x02 | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)`
```go
type ValidatorDistInfo struct {
@@ -56,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 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(delegatorDist)`
* DelegationDistInfo: `0x02 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(delegatorDist)`
```go
type DelegationDistInfo struct {
x/distribution/spec/03_begin_block.md
+5 -5
View File
@@ -9,9 +9,9 @@ the distribution `ModuleAccount` account. When a delegator or validator
withdraws their rewards, they are taken out of the `ModuleAccount`. During begin
block, the different claims on the fees collected are updated as follows:
- The block proposer of the previous height and its delegators receive between 1% and 5% of fee rewards.
- The reserve community tax is charged.
- The remainder is distributed proportionally by voting power to all bonded validators
* The block proposer of the previous height and its delegators receive between 1% and 5% of fee rewards.
* The reserve community tax is charged.
* The remainder is distributed proportionally by voting power to all bonded validators
To incentivize validators to wait and include additional pre-commits in the block, the block proposer reward is calculated from Tendermint pre-commit messages.
@@ -45,7 +45,7 @@ only bonded validators can supply valid precommits) and is always larger than
Any remaining fees are distributed among all the bonded validators, including
the proposer, in proportion to their consensus power.
```
```text
powFrac = validator power / total bonded validator power
proposerMul = baseproposerreward + bonusproposerreward * P
voteMul = 1 - communitytax - proposerMul
@@ -79,7 +79,7 @@ blocks. Then hold `(precommits included) / (total bonded validator power)`
constant so that the amortized block reward for the validator is `( validator power / total bonded power) * (1 - community tax rate)` of
the total rewards. Consequently, the reward for a single delegator is:
```
```text
(delegator proportion of the validator power / validator power) * (validator power / total bonded power)
* (1 - community tax rate) * (1 - validator commision rate)
= (delegator proportion of the validator power / total bonded power) * (1 -
x/distribution/spec/04_messages.md
+3 -3
View File
@@ -13,7 +13,7 @@ The withdraw address cannot be any of the module accounts. These accounts are bl
Response:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L29-L37
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L29-L37>
```go
func (k Keeper) SetWithdrawAddr(ctx sdk.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error
@@ -47,7 +47,7 @@ Taking the slashes into account requires iteration.
Let `F(X)` be the fraction a validator is to be slashed for a slashing event that happened at period `X`.
If the validator was slashed at periods `P1, ..., PN`, where `A < P1`, `PN < B`, the distribution module calculates the individual delegator's rewards, `T(A, B)`, as follows:
```
```go
stake := initial stake
rewards := 0
previous := A
@@ -63,7 +63,7 @@ The final calculated stake is equivalent to the actual staked coins in the deleg
Response:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50>
## WithdrawValidatorCommission
x/distribution/spec/05_hooks.md
+15 -15
View File
@@ -8,15 +8,15 @@ Available hooks that can be called by and from this module.
## Create or modify delegation distribution
- triggered-by: `staking.MsgDelegate`, `staking.MsgBeginRedelegate`, `staking.MsgUndelegate`
* triggered-by: `staking.MsgDelegate`, `staking.MsgBeginRedelegate`, `staking.MsgUndelegate`
### Before
- The delegation rewards are withdrawn to the withdraw address of the delegator.
* The delegation rewards are withdrawn to the withdraw address of the delegator.
The rewards include the current period and exclude the starting period.
- The validator period is incremented.
* The validator period is incremented.
The validator period is incremented because the validator's power and share distribution might have changed.
- The reference count for the delegator's starting period is decremented.
* The reference count for the delegator's starting period is decremented.
### After
@@ -25,21 +25,21 @@ Because of the `Before`-hook, this period is the last period for which the deleg
## Validator created
- triggered-by: `staking.MsgCreateValidator`
* triggered-by: `staking.MsgCreateValidator`
When a validator is created, the following validator variables are initialized:
- Historical rewards
- Current accumulated rewards
- Accumulated commission
- Total outstanding rewards
- Period
* Historical rewards
* Current accumulated rewards
* Accumulated commission
* Total outstanding rewards
* Period
By default, all values are set to a `0`, except period, which is set to `1`.
## Validator removed
- triggered-by: `staking.RemoveValidator`
* triggered-by: `staking.RemoveValidator`
Outstanding commission is sent to the validator's self-delegation withdrawal address.
Remaining delegator rewards get sent to the community fee pool.
@@ -50,10 +50,10 @@ Any remaining rewards are dust amounts.
## Validator is slashed
- triggered-by: `staking.Slash`
* triggered-by: `staking.Slash`
- The current validator period reference count is incremented.
* The current validator period reference count is incremented.
The reference count is incremented because the slash event has created a reference to it.
- The validator period is incremented.
- The slash event is stored for later use.
* The validator period is incremented.
* The slash event is stored for later use.
The slash event will be referenced when calculating delegator rewards.
x/distribution/spec/08_client.md
+46 -46
View File
@@ -12,7 +12,7 @@ A user can query and interact with the `distribution` module using the CLI.
The `query` commands allow users to query `distribution` state.
```
```sh
simd query distribution --help
```
@@ -20,19 +20,19 @@ simd query distribution --help
The `commission` command allows users to query validator commission rewards by address.
```
```sh
simd query distribution commission [address] [flags]
```
Example:
```
```sh
simd query distribution commission cosmosvaloper1..
```
Example Output:
```
```yml
commission:
- amount: "1000000.000000000000000000"
denom: stake
@@ -42,19 +42,19 @@ commission:
The `community-pool` command allows users to query all coin balances within the community pool.
```
```sh
simd query distribution community-pool [flags]
```
Example:
```
```sh
simd query distribution community-pool
```
Example Output:
```
```yml
pool:
- amount: "1000000.000000000000000000"
denom: stake
@@ -64,19 +64,19 @@ pool:
The `params` command allows users to query the parameters of the `distribution` module.
```
```sh
simd query distribution params [flags]
```
Example:
```
```sh
simd query distribution params
```
Example Output:
```
```yml
base_proposer_reward: "0.010000000000000000"
bonus_proposer_reward: "0.040000000000000000"
community_tax: "0.020000000000000000"
@@ -87,19 +87,19 @@ withdraw_addr_enabled: true
The `rewards` command allows users to query delegator rewards. Users can optionally include the validator address to query rewards earned from a specific validator.
```
```sh
simd query distribution rewards [delegator-addr] [validator-addr] [flags]
```
Example:
```
```sh
simd query distribution rewards cosmos1..
```
Example Output:
```
```yml
rewards:
- reward:
- amount: "1000000.000000000000000000"
@@ -114,19 +114,19 @@ total:
The `slashes` command allows users to query all slashes for a given block range.
```
```sh
simd query distribution slashes [validator] [start-height] [end-height] [flags]
```
Example:
```
```sh
simd query distribution slashes cosmosvaloper1.. 1 1000
```
Example Output:
```
```yml
pagination:
next_key: null
total: "0"
@@ -139,19 +139,19 @@ slashes:
The `validator-outstanding-rewards` command allows users to query all outstanding (un-withdrawn) rewards for a validator and all their delegations.
```
```sh
simd query distribution validator-outstanding-rewards [validator] [flags]
```
Example:
```
```sh
simd query distribution validator-outstanding-rewards cosmosvaloper1..
```
Example Output:
```
```yml
rewards:
- amount: "1000000.000000000000000000"
denom: stake
@@ -161,7 +161,7 @@ rewards:
The `tx` commands allow users to interact with the `distribution` module.
```
```sh
simd tx distribution --help
```
@@ -169,13 +169,13 @@ simd tx distribution --help
The `fund-community-pool` command allows users to send funds to the community pool.
```
```sh
simd tx distribution fund-community-pool [amount] [flags]
```
Example:
```
```sh
simd tx distribution fund-community-pool 100stake --from cosmos1..
```
@@ -183,13 +183,13 @@ simd tx distribution fund-community-pool 100stake --from cosmos1..
The `set-withdraw-addr` command allows users to set the withdraw address for rewards associated with a delegator address.
```
```sh
simd tx distribution set-withdraw-addr [withdraw-addr] [flags]
```
Example:
```
```sh
simd tx distribution set-withdraw-addr cosmos1.. --from cosmos1..
```
@@ -197,13 +197,13 @@ simd tx distribution set-withdraw-addr cosmos1.. --from cosmos1..
The `withdraw-all-rewards` command allows users to withdraw all rewards for a delegator.
```
```sh
simd tx distribution withdraw-all-rewards [flags]
```
Example:
```
```sh
simd tx distribution withdraw-all-rewards --from cosmos1..
```
@@ -212,13 +212,13 @@ simd tx distribution withdraw-all-rewards --from cosmos1..
The `withdraw-rewards` command allows users to withdraw all rewards from a given delegation address,
and optionally withdraw validator commission if the delegation address given is a validator operator and the user proves the `--commision` flag.
```
```sh
simd tx distribution withdraw-rewards [validator-addr] [flags]
```
Example:
```
```sh
simd tx distribution withdraw-rewards cosmosvaloper1.. --from cosmos1.. --commision
```
@@ -232,7 +232,7 @@ The `Params` endpoint allows users to query parameters of the `distribution` mod
Example:
```
```sh
grpcurl -plaintext \
localhost:9090 \
cosmos.distribution.v1beta1.Query/Params
@@ -240,7 +240,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"params": {
"communityTax": "20000000000000000",
@@ -257,7 +257,7 @@ The `ValidatorOutstandingRewards` endpoint allows users to query rewards of a va
Example:
```
```sh
grpcurl -plaintext \
-d '{"validator_address":"cosmosvalop1.."}' \
localhost:9090 \
@@ -266,7 +266,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"rewards": {
"rewards": [
@@ -285,7 +285,7 @@ The `ValidatorCommission` endpoint allows users to query accumulated commission
Example:
```
```sh
grpcurl -plaintext \
-d '{"validator_address":"cosmosvalop1.."}' \
localhost:9090 \
@@ -294,7 +294,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"commission": {
"commission": [
@@ -313,7 +313,7 @@ The `ValidatorSlashes` endpoint allows users to query slash events of a validato
Example:
```
```sh
grpcurl -plaintext \
-d '{"validator_address":"cosmosvalop1.."}' \
localhost:9090 \
@@ -322,7 +322,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"slashes": [
{
@@ -342,7 +342,7 @@ The `DelegationRewards` endpoint allows users to query the total rewards accrued
Example:
```
```sh
grpcurl -plaintext \
-d '{"delegator_address":"cosmos1..","validator_address":"cosmosvalop1.."}' \
localhost:9090 \
@@ -351,7 +351,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"rewards": [
{
@@ -368,7 +368,7 @@ The `DelegationTotalRewards` endpoint allows users to query the total rewards ac
Example:
```
```sh
grpcurl -plaintext \
-d '{"delegator_address":"cosmos1.."}' \
localhost:9090 \
@@ -377,7 +377,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"rewards": [
{
@@ -405,7 +405,7 @@ The `DelegatorValidators` endpoint allows users to query all validators for give
Example:
```
```sh
grpcurl -plaintext \
-d '{"delegator_address":"cosmos1.."}' \
localhost:9090 \
@@ -414,7 +414,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"validators": [
"cosmosvaloper1.."
@@ -428,7 +428,7 @@ The `DelegatorWithdrawAddress` endpoint allows users to query the withdraw addre
Example:
```
```sh
grpcurl -plaintext \
-d '{"delegator_address":"cosmos1.."}' \
localhost:9090 \
@@ -437,7 +437,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"withdrawAddress": "cosmos1.."
}
@@ -449,7 +449,7 @@ The `CommunityPool` endpoint allows users to query the community pool coins.
Example:
```
```sh
grpcurl -plaintext \
localhost:9090 \
cosmos.distribution.v1beta1.Query/CommunityPool
@@ -457,7 +457,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"pool": [
{
x/distribution/spec/README.md
+20 -20
View File
@@ -22,12 +22,12 @@ and validator proposer-reward pool. Due to the nature of passive accounting,
whenever changes to parameters which affect the rate of reward distribution
occurs, withdrawal of rewards must also occur.
- Whenever withdrawing, one must withdraw the maximum amount they are entitled
* Whenever withdrawing, one must withdraw the maximum amount they are entitled
to, leaving nothing in the pool.
- Whenever bonding, unbonding, or re-delegating tokens to an existing account, a
* Whenever bonding, unbonding, or re-delegating tokens to an existing account, a
full withdrawal of the rewards must occur (as the rules for lazy accounting
change).
- Whenever a validator chooses to change the commission on rewards, all accumulated
* Whenever a validator chooses to change the commission on rewards, all accumulated
commission rewards must be simultaneously withdrawn.
The above scenarios are covered in `hooks.md`.
@@ -35,10 +35,10 @@ The above scenarios are covered in `hooks.md`.
The distribution mechanism outlined herein is used to lazily distribute the
following rewards between validators and associated delegators:
- multi-token fees to be socially distributed
- proposer reward pool
- inflated atom provisions
- validator commission on all rewards earned by their delegators stake
* multi-token fees to be socially distributed
* proposer reward pool
* inflated atom provisions
* validator commission on all rewards earned by their delegators stake
Fees are pooled within a global pool, as well as validator specific
proposer-reward pools. The mechanisms used allow for validators and delegators
@@ -50,7 +50,7 @@ As a part of the lazy computations, each delegator holds an accumulation term
specific to each validator which is used to estimate what their approximate
fair portion of tokens held in the global fee pool is owed to them.
```
```text
entitlement = delegator-accumulation / all-delegators-accumulation
```
@@ -85,22 +85,22 @@ to set up a script to periodically withdraw and rebond rewards.
## Contents
1. **[Concepts](01_concepts.md)**
- [Reference Counting in F1 Fee Distribution](01_concepts.md#reference-counting-in-f1-fee-distribution)
* [Reference Counting in F1 Fee Distribution](01_concepts.md#reference-counting-in-f1-fee-distribution)
2. **[State](02_state.md)**
3. **[Begin Block](03_begin_block.md)**
4. **[Messages](04_messages.md)**
- [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-)
* [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)
- [Commission rate change](05_hooks.md#commission-rate-change)
- [Change in Validator State](05_hooks.md#change-in-validator-state)
* [Create or modify delegation distribution](05_hooks.md#create-or-modify-delegation-distribution)
* [Commission rate change](05_hooks.md#commission-rate-change)
* [Change in Validator State](05_hooks.md#change-in-validator-state)
6. **[Events](06_events.md)**
- [BeginBlocker](06_events.md#beginblocker)
- [Handlers](06_events.md#handlers)
* [BeginBlocker](06_events.md#beginblocker)
* [Handlers](06_events.md#handlers)
7. **[Parameters](07_params.md)**
8. **[Parameters](07_params.md)**
- [CLI](08_client.md#cli)
- [gRPC](08_client.md#grpc)
* [CLI](08_client.md#cli)
* [gRPC](08_client.md#grpc)
x/epoching/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Epoching
- [Epoching](epoching/spec/README.md) - Allows modules to queue messages for execution at a certain block height.
* [Epoching](epoching/spec/README.md) - Allows modules to queue messages for execution at a certain block height.
x/epoching/spec/01_state.md
+4 -4
View File
@@ -52,7 +52,7 @@ We execute epoch after execution of genesis transactions to see the changes inst
## Execution on epochs
- Try executing the message for the epoch
- If success, make changes as it is
- If failure, try making revert extra actions done on handlers (e.g. EpochDelegationPool deposit)
- If revert fail, panic
* Try executing the message for the epoch
* If success, make changes as it is
* If failure, try making revert extra actions done on handlers (e.g. EpochDelegationPool deposit)
* If revert fail, panic
x/epoching/spec/03_to_improve.md
+3 -3
View File
@@ -8,10 +8,10 @@ order: 3
Cases that trigger unbonding process
- Validator undelegate can unbond more tokens than his minimum_self_delegation and it will automatically turn the validator into unbonding
* Validator undelegate can unbond more tokens than his minimum_self_delegation and it will automatically turn the validator into unbonding
In this case, unbonding should start instantly.
- Validator miss blocks and get slashed
- Validator get slashed for double sign
* Validator miss blocks and get slashed
* Validator get slashed for double sign
**Note:** When a validator begins the unbonding process, it could be required to turn the validator into unbonding state instantly.
This is different than a specific delegator beginning to unbond. A validator beginning to unbond means that it's not in the set any more.
x/evidence/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Evidence
- [Evidence](spec/README.md) - Evidence handling for double signing, misbehaviour, etc.
* [Evidence](spec/README.md) - Evidence handling for double signing, misbehaviour, etc.
x/evidence/spec/06_begin_block.md
+4 -4
View File
@@ -13,8 +13,8 @@ Tendermint blocks can include
The Cosmos SDK handles two types of evidence inside the ABCI `BeginBlock`:
- `DuplicateVoteEvidence`,
- `LightClientAttackEvidence`.
* `DuplicateVoteEvidence`,
* `LightClientAttackEvidence`.
The evidence module handles these two evidence types the same way. First, the Cosmos SDK converts the Tendermint concrete evidence type to an SDK `Evidence` interface using `Equivocation` as the concrete type.
@@ -34,8 +34,8 @@ For some `Equivocation` submitted in `block` to be valid, it must satisfy:
Where:
- `Evidence.Timestamp` is the timestamp in the block at height `Evidence.Height`
- `block.Timestamp` is the current block timestamp.
* `Evidence.Timestamp` is the timestamp in the block at height `Evidence.Height`
* `block.Timestamp` is the current block timestamp.
If valid `Equivocation` evidence is included in a block, the validator's stake is
reduced (slashed) by `SlashFractionDoubleSign` as defined by the `x/slashing` module
x/feegrant/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Fee Grant
- [Fee Grant](spec/README.md) - Grant fee allowances for executing transactions.
* [Fee Grant](spec/README.md) - Grant fee allowances for executing transactions.
x/feegrant/spec/01_concepts.md
+19 -19
View File
@@ -8,58 +8,58 @@ order: 1
`Grant` is stored in the KVStore to record a grant with full context. Every grant will contain `granter`, `grantee` and what kind of `allowance` is granted. `granter` is an account address who is giving permission to `grantee` (the beneficiary account address) to pay for some or all of `grantee`'s transaction fees. `allowance` defines what kind of fee allowance (`BasicAllowance` or `PeriodicAllowance`, see below) is granted to `grantee`. `allowance` accepts an interface which implements `FeeAllowanceI`, encoded as `Any` type. There can be only one existing fee grant allowed for a `grantee` and `granter`, self grants are not allowed.
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L75-L81
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L75-L81>
`FeeAllowanceI` looks like:
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/fees.go#L9-L32
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/fees.go#L9-L32>
## Fee Allowance types
There are two types of fee allowances present at the moment:
- `BasicAllowance`
- `PeriodicAllowance`
* `BasicAllowance`
* `PeriodicAllowance`
## BasicAllowance
`BasicAllowance` is permission for `grantee` to use fee from a `granter`'s account. If any of the `spend_limit` or `expiration` reaches its limit, the grant will be removed from the state.
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26>
- `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available tokens from `granter` account address before the expiration.
* `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available tokens from `granter` account address before the expiration.
- `expiration` specifies an optional time when this allowance expires. If the value is left empty, there is no expiry for the grant.
* `expiration` specifies an optional time when this allowance expires. If the value is left empty, there is no expiry for the grant.
- When a grant is created with empty values for `spend_limit` and `expiration`, it is still a valid grant. It won't restrict the `grantee` to use any number of tokens from `granter` and it won't have any expiration. The only way to restrict the `grantee` is by revoking the grant.
* When a grant is created with empty values for `spend_limit` and `expiration`, it is still a valid grant. It won't restrict the `grantee` to use any number of tokens from `granter` and it won't have any expiration. The only way to restrict the `grantee` is by revoking the grant.
## PeriodicAllowance
`PeriodicAllowance` is a repeating fee allowance for the mentioned period, we can mention when the grant can expire as well as when a period can reset. We can also define the maximum number of coins that can be used in a mentioned period of time.
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L28-L73
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L28-L73>
- `basic` is the instance of `BasicAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`.
* `basic` is the instance of `BasicAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`.
- `period` is the specific period of time, after each period passes, `period_spend_limit` will be reset.
* `period` is the specific period of time, after each period passes, `period_spend_limit` will be reset.
- `period_spend_limit` specifies the maximum number of coins that can be spent in the period.
* `period_spend_limit` specifies the maximum number of coins that can be spent in the period.
- `period_can_spend` is the number of coins left to be spent before the period_reset time.
* `period_can_spend` is the number of coins left to be spent before the period_reset time.
- `period_reset` keeps track of when a next period reset should happen.
* `period_reset` keeps track of when a next period reset should happen.
## FeeGranter flag
`feegrant` module introduces a `FeeGranter` flag for CLI for the sake of executing transactions with fee granter. When this flag is set, `clientCtx` will append the granter account address for transactions generated through CLI.
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/cmd.go#L224-L235
+++ <https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/cmd.go#L224-L235>
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/tx/tx.go#L120
+++ <https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/tx/tx.go#L120>
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/auth/tx/builder.go#L268-L277
+++ <https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/auth/tx/builder.go#L268-L277>
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/tx/v1beta1/tx.proto#L160-L181
+++ <https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/tx/v1beta1/tx.proto#L160-L181>
Example cmd:
@@ -79,4 +79,4 @@ In order to prevent DoS attacks, using a filtered `x/feegrant` incurs gas. The S
## Pruning
A queue in the state maintained with the prefix of expiration of the grants and checks them on EndBlock with the current block time for every block to prune.
A queue in the state maintained with the prefix of expiration of the grants and checks them on EndBlock with the current block time for every block to prune.
x/feegrant/spec/02_state.md
+3 -3
View File
@@ -10,9 +10,9 @@ Fee Allowances are identified by combining `Grantee` (the account address of fee
Fee allowance grants are stored in the state as follows:
- Grant: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(Grant)`
* Grant: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(Grant)`
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/feegrant.pb.go#L221-L229
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/feegrant.pb.go#L221-L229>
## FeeAllowanceQueue
@@ -20,4 +20,4 @@ Fee Allowances queue items are identified by combining the `FeeAllowancePrefixQu
Fee allowance queue keys are stored in the state as follows:
- Grant: `0x01 | expiration_bytes | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> EmptyBytes`
* Grant: `0x01 | expiration_bytes | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> EmptyBytes`
x/feegrant/spec/03_messages.md
+2 -2
View File
@@ -8,10 +8,10 @@ order: 3
A fee allowance grant will be created with the `MsgGrantAllowance` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L22-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L22-L33>
## Msg/RevokeAllowance
An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L38-L45
+++ <https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L38-L45>
x/feegrant/spec/04_events.md
+18 -18
View File
@@ -8,26 +8,26 @@ The feegrant module emits the following events:
# Msg Server
### MsgGrantAllowance
## MsgGrantAllowance
| Type | Attribute Key | Attribute Value |
| -------- | ------------- | ------------------ |
| message | action | set_feegrant |
| message | granter | {granterAddress} |
| message | grantee | {granteeAddress} |
| Type | Attribute Key | Attribute Value |
| ------- | ------------- | ---------------- |
| message | action | set_feegrant |
| message | granter | {granterAddress} |
| message | grantee | {granteeAddress} |
### MsgRevokeAllowance
## MsgRevokeAllowance
| Type | Attribute Key | Attribute Value |
| -------- | ------------- | ------------------ |
| message | action | revoke_feegrant |
| message | granter | {granterAddress} |
| message | grantee | {granteeAddress} |
| Type | Attribute Key | Attribute Value |
| ------- | ------------- | ---------------- |
| message | action | revoke_feegrant |
| message | granter | {granterAddress} |
| message | grantee | {granteeAddress} |
### Exec fee allowance
## Exec fee allowance
| Type | Attribute Key | Attribute Value |
| -------- | ------------- | ------------------ |
| message | action | use_feegrant |
| message | granter | {granterAddress} |
| message | grantee | {granteeAddress} |
| Type | Attribute Key | Attribute Value |
| ------- | ------------- | ---------------- |
| message | action | use_feegrant |
| message | granter | {granterAddress} |
| message | grantee | {granteeAddress} |
x/feegrant/spec/05_client.md
+19 -19
View File
@@ -12,7 +12,7 @@ A user can query and interact with the `feegrant` module using the CLI.
The `query` commands allow users to query `feegrant` state.
```
```sh
simd query feegrant --help
```
@@ -20,19 +20,19 @@ simd query feegrant --help
The `grant` command allows users to query a grant for a given granter-grantee pair.
```
```sh
simd query feegrant grant [granter] [grantee] [flags]
```
Example:
```
```sh
simd query feegrant grant cosmos1.. cosmos1..
```
Example Output:
```
```yml
allowance:
'@type': /cosmos.feegrant.v1beta1.BasicAllowance
expiration: null
@@ -47,19 +47,19 @@ granter: cosmos1..
The `grants` command allows users to query all grants for a given grantee.
```
```sh
simd query feegrant grants [grantee] [flags]
```
Example:
```
```sh
simd query feegrant grants cosmos1..
```
Example Output:
```
```yml
allowances:
- allowance:
'@type': /cosmos.feegrant.v1beta1.BasicAllowance
@@ -78,7 +78,7 @@ pagination:
The `tx` commands allow users to interact with the `feegrant` module.
```
```sh
simd tx feegrant --help
```
@@ -86,19 +86,19 @@ simd tx feegrant --help
The `grant` command allows users to grant fee allowances to another account. The fee allowance can have an expiration date, a total spend limit, and/or a periodic spend limit.
```
```sh
simd tx feegrant grant [granter] [grantee] [flags]
```
Example (one-time spend limit):
```
```sh
simd tx feegrant grant cosmos1.. cosmos1.. --spend-limit 100stake
```
Example (periodic spend limit):
```
```sh
simd tx feegrant grant cosmos1.. cosmos1.. --period 3600 --period-limit 10stake
```
@@ -106,13 +106,13 @@ simd tx feegrant grant cosmos1.. cosmos1.. --period 3600 --period-limit 10stake
The `revoke` command allows users to revoke a granted fee allowance.
```
```sh
simd tx feegrant revoke [granter] [grantee] [flags]
```
Example:
```
```sh
simd tx feegrant revoke cosmos1.. cosmos1..
```
@@ -124,13 +124,13 @@ A user can query the `feegrant` module using gRPC endpoints.
The `Allowance` endpoint allows users to query a granted fee allowance.
```
```sh
cosmos.feegrant.v1beta1.Query/Allowance
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"grantee":"cosmos1..","granter":"cosmos1.."}' \
localhost:9090 \
@@ -139,7 +139,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"allowance": {
"granter": "cosmos1..",
@@ -153,13 +153,13 @@ Example Output:
The `Allowances` endpoint allows users to query all granted fee allowances for a given grantee.
```
```sh
cosmos.feegrant.v1beta1.Query/Allowances
```
Example:
```
```sh
grpcurl -plaintext \
-d '{"address":"cosmos1.."}' \
localhost:9090 \
@@ -168,7 +168,7 @@ grpcurl -plaintext \
Example Output:
```
```json
{
"allowances": [
{
x/feegrant/spec/README.md
+17 -15
View File
@@ -5,6 +5,8 @@ parent:
title: "feegrant"
-->
# Fee grant
## Abstract
This document specifies the fee grant module. For the full ADR, please see [Fee Grant ADR-029](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/docs/architecture/adr-029-fee-grant-module.md).
@@ -14,22 +16,22 @@ This module allows accounts to grant fee allowances and to use fees from their a
## Contents
1. **[Concepts](01_concepts.md)**
- [Grant](01_concepts.md#grant)
- [Fee Allowance types](01_concepts.md#fee-allowance-types)
- [BasicAllowance](01_concepts.md#basicallowance)
- [PeriodicAllowance](01_concepts.md#periodicallowance)
- [FeeAccount flag](01_concepts.md#feeaccount-flag)
- [Granted Fee Deductions](01_concepts.md#granted-fee-deductions)
- [Gas](01_concepts.md#gas)
* [Grant](01_concepts.md#grant)
* [Fee Allowance types](01_concepts.md#fee-allowance-types)
* [BasicAllowance](01_concepts.md#basicallowance)
* [PeriodicAllowance](01_concepts.md#periodicallowance)
* [FeeAccount flag](01_concepts.md#feeaccount-flag)
* [Granted Fee Deductions](01_concepts.md#granted-fee-deductions)
* [Gas](01_concepts.md#gas)
2. **[State](02_state.md)**
- [FeeAllowance](02_state.md#feeallowance)
* [FeeAllowance](02_state.md#feeallowance)
3. **[Messages](03_messages.md)**
- [Msg/GrantAllowance](03_messages.md#msggrantallowance)
- [Msg/RevokeAllowance](03_messages.md#msgrevokeallowance)
* [Msg/GrantAllowance](03_messages.md#msggrantallowance)
* [Msg/RevokeAllowance](03_messages.md#msgrevokeallowance)
4. **[Events](04_events.md)**
- [MsgGrantAllowance](04_events.md#msggrantallowance)
- [MsgRevokeAllowance](04_events.md#msgrevokeallowance)
- [Exec fee allowance](04_events.md#exec-fee-allowance)
* [MsgGrantAllowance](04_events.md#msggrantallowance)
* [MsgRevokeAllowance](04_events.md#msgrevokeallowance)
* [Exec fee allowance](04_events.md#exec-fee-allowance)
5. **[Client](05_client.md)**
- [CLI](05_client.md#cli)
- [gRPC](05_client.md#grpc)
* [CLI](05_client.md#cli)
* [gRPC](05_client.md#grpc)
x/gov/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Governance
- [Governance](spec/README.md) - On-chain proposals and voting.
* [Governance](spec/README.md) - On-chain proposals and voting.
x/gov/spec/01_concepts.md
+17 -17
View File
@@ -8,12 +8,12 @@ _Disclaimer: This is work in progress. Mechanisms are susceptible to change._
The governance process is divided in a few steps that are outlined below:
- **Proposal submission:** Proposal is submitted to the blockchain with a
* **Proposal submission:** Proposal is submitted to the blockchain with a
deposit.
- **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is
* **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is
confirmed and vote opens. Bonded Atom holders can then send `TxGovVote`
transactions to vote on the proposal.
- **Execution** After a period of time, the votes are tallied and depending
* **Execution** After a period of time, the votes are tallied and depending
on the result, the messages in the proposal will be executed.
## Proposal submission
@@ -58,13 +58,13 @@ proposal is finalized (passed or rejected).
When a proposal is finalized, the coins from the deposit are either refunded or burned
according to the final tally of the proposal:
- If the proposal is approved or rejected but _not_ vetoed, each deposit will be
* If the proposal is approved or rejected but _not_ vetoed, each deposit will be
automatically refunded to its respective depositor (transferred from the governance
`ModuleAccount`).
- When the proposal is vetoed with greater than 1/3, deposits will be burned from the
* When the proposal is vetoed with greater than 1/3, deposits will be burned from the
governance `ModuleAccount` and the proposal information along with its deposit
information will be removed from state.
- All refunded or burned deposits are removed from the state. Events are issued when
* All refunded or burned deposits are removed from the state. Events are issued when
burning or refunding a deposit.
## Voting
@@ -79,9 +79,9 @@ can submit and deposit on proposals.
Note that some _participants_ can be forbidden to vote on a proposal under a
certain validator if:
- _participant_ bonded or unbonded Atoms to said validator after proposal
* _participant_ bonded or unbonded Atoms to said validator after proposal
entered voting period.
- _participant_ became validator after proposal entered voting period.
* _participant_ became validator after proposal entered voting period.
This does not prevent _participant_ to vote with Atoms bonded to other
validators. For example, if a _participant_ bonded some Atoms to validator A
@@ -104,10 +104,10 @@ choose from when casting its vote.
The initial option set includes the following options:
- `Yes`
- `No`
- `NoWithVeto`
- `Abstain`
* `Yes`
* `No`
* `NoWithVeto`
* `Abstain`
`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option
allows voters to signal that they do not intend to vote in favor or against the
@@ -124,9 +124,9 @@ Often times the entity owning that address might not be a single individual. For
To represent weighted vote on chain, we use the following Protobuf message.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L32-L40
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L32-L40>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L126-L137
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L126-L137>
For a weighted vote to be valid, the `options` field must not contain duplicate vote options, and the sum of weights of all options must be equal to 1.
@@ -151,9 +151,9 @@ votes).
If a delegator does not vote, it will inherit its validator vote.
- If the delegator votes before its validator, it will not inherit from the
* If the delegator votes before its validator, it will not inherit from the
validator's vote.
- If the delegator votes after its validator, it will override its validator
* If the delegator votes after its validator, it will override its validator
vote with its own. If the proposal is urgent, it is possible
that the vote will close before delegators have a chance to react and
override their validator's vote. This is not a problem, as proposals require more than 2/3rd of the total voting power to pass before the end of the voting period. If more than 2/3rd of validators collude, they can censor the votes of delegators anyway.
@@ -193,4 +193,4 @@ Once a block contains more than 2/3rd _precommits_ where a common
nodes, non-validating full nodes and light-nodes) are expected to switch to the
new version of the software.
_Note: Not clear how the flip is handled programmatically_
_Note: Not clear how the flip is handled programmatically._
x/gov/spec/02_state.md
+10 -10
View File
@@ -12,7 +12,7 @@ to resolve and then execute if the proposal passes. `Proposal`'s are identified
unique id and contains a series of timestamps: `submit_time`, `deposit_end_time`,
`voting_start_time`, `voting_end_time` which track the lifecycle of a proposal
+++ https://github.com/cosmos/cosmos-sdk/blob/4a129832eb16f37a89e97652a669f0cdc9196ca9/proto/cosmos/gov/v1beta2/gov.proto#L42-L52
+++ <https://github.com/cosmos/cosmos-sdk/blob/4a129832eb16f37a89e97652a669f0cdc9196ca9/proto/cosmos/gov/v1beta2/gov.proto#L42-L52>
A proposal will generally require more than just a set of messages to explain its
purpose but need some greater justification and allow a means for interested participants
@@ -58,15 +58,15 @@ parameter set has to be created and the previous one rendered inactive.
### DepositParams
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L127-L145
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L127-L145>
### VotingParams
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L147-L156
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L147-L156>
### TallyParams
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L158-L183
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L158-L183>
Parameters are stored in a global `GlobalParams` KVStore.
@@ -104,7 +104,7 @@ const (
## Deposit
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L43-L53
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L43-L53>
## ValidatorGovInfo
@@ -124,21 +124,21 @@ parameter in the list_`
We will use one KVStore `Governance` to store two mappings:
- A mapping from `proposalID|'proposal'` to `Proposal`.
- A mapping from `proposalID|'addresses'|address` to `Vote`. This mapping allows
* A mapping from `proposalID|'proposal'` to `Proposal`.
* A mapping from `proposalID|'addresses'|address` to `Vote`. This mapping allows
us to query all addresses that voted on the proposal along with their vote by
doing a range query on `proposalID:addresses`.
For pseudocode purposes, here are the two function we will use to read or write in stores:
- `load(StoreKey, Key)`: Retrieve item stored at key `Key` in store found at key `StoreKey` in the multistore
- `store(StoreKey, Key, value)`: Write value `Value` at key `Key` in store found at key `StoreKey` in the multistore
* `load(StoreKey, Key)`: Retrieve item stored at key `Key` in store found at key `StoreKey` in the multistore
* `store(StoreKey, Key, value)`: Write value `Value` at key `Key` in store found at key `StoreKey` in the multistore
## Proposal Processing Queue
**Store:**
- `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the
* `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the
`ProposalIDs` of proposals that reached `MinDeposit`. During each `EndBlock`,
all the proposals that have reached the end of their voting period are processed.
To process a finished proposal, the application tallies the votes, computes the
x/gov/spec/03_messages.md
+18 -18
View File
@@ -9,7 +9,7 @@ order: 3
Proposals can be submitted by any account via a `MsgSubmitProposal`
transaction.
+++ https://github.com/cosmos/cosmos-sdk/blob/ab9545527d630fe38761aa61cc5c95eabd68e0e6/proto/cosmos/gov/v1beta2/tx.proto#L34-L44
+++ <https://github.com/cosmos/cosmos-sdk/blob/ab9545527d630fe38761aa61cc5c95eabd68e0e6/proto/cosmos/gov/v1beta2/tx.proto#L34-L44>
All `sdk.Msgs` passed into the `messages` field of a `MsgSubmitProposal` message
must be registered in the app's `MsgServiceRouter`. Each of these messages must
@@ -18,13 +18,13 @@ must not be larger than the `maxMetadataLen` config passed into the gov keeper.
**State modifications:**
- Generate new `proposalID`
- Create new `Proposal`
- Initialise `Proposal`'s attributes
- Decrease balance of sender by `InitialDeposit`
- If `MinDeposit` is reached:
- Push `proposalID` in `ProposalProcessingQueue`
- Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount`
* Generate new `proposalID`
* Create new `Proposal`
* Initialise `Proposal`'s attributes
* Decrease balance of sender by `InitialDeposit`
* If `MinDeposit` is reached:
* Push `proposalID` in `ProposalProcessingQueue`
* Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount`
A `MsgSubmitProposal` transaction can be handled according to the following
pseudocode.
@@ -78,16 +78,16 @@ Once a proposal is submitted, if
`Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send
`MsgDeposit` transactions to increase the proposal's deposit.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L61-L72
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L61-L72>
**State modifications:**
- Decrease balance of sender by `deposit`
- Add `deposit` of sender in `proposal.Deposits`
- Increase `proposal.TotalDeposit` by sender's `deposit`
- If `MinDeposit` is reached:
- Push `proposalID` in `ProposalProcessingQueueEnd`
- Transfer `Deposit` from the `proposer` to the governance `ModuleAccount`
* Decrease balance of sender by `deposit`
* Add `deposit` of sender in `proposal.Deposits`
* Increase `proposal.TotalDeposit` by sender's `deposit`
* If `MinDeposit` is reached:
* Push `proposalID` in `ProposalProcessingQueueEnd`
* Transfer `Deposit` from the `proposer` to the governance `ModuleAccount`
A `MsgDeposit` transaction has to go through a number of checks to be valid.
These checks are outlined in the following pseudocode.
@@ -144,13 +144,13 @@ Once `ActiveParam.MinDeposit` is reached, voting period starts. From there,
bonded Atom holders are able to send `MsgVote` transactions to cast their
vote on the proposal.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L46-L56
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L46-L56>
**State modifications:**
- Record `Vote` of sender
* Record `Vote` of sender
_Note: Gas cost for this message has to take into account the future tallying of the vote in EndBlocker_
_Note: Gas cost for this message has to take into account the future tallying of the vote in EndBlocker._
Next is a pseudocode outline of the way `MsgVote` transactions are
handled:
x/gov/spec/04_events.md
+2 -2
View File
@@ -29,7 +29,7 @@ The governance module emits the following events:
| message | action | submit_proposal |
| message | sender | {senderAddress} |
- [0] Event only emitted if the voting period starts during the submission.
* [0] Event only emitted if the voting period starts during the submission.
### MsgVote
@@ -62,4 +62,4 @@ The governance module emits the following events:
| message | action | deposit |
| message | sender | {senderAddress} |
- [0] Event only emitted if the voting period starts during the submission.
* [0] Event only emitted if the voting period starts during the submission.
x/gov/spec/README.md
+21 -21
View File
@@ -18,12 +18,12 @@ system. In this system, holders of the native staking token of the chain can vot
on proposals on a 1 token 1 vote basis. Next is a list of features the module
currently supports:
- **Proposal submission:** Users can submit proposals with a deposit. Once the
* **Proposal submission:** Users can submit proposals with a deposit. Once the
minimum deposit is reached, proposal enters voting period
- **Vote:** Participants can vote on proposals that reached MinDeposit
- **Inheritance and penalties:** Delegators inherit their validator's vote if
* **Vote:** Participants can vote on proposals that reached MinDeposit
* **Inheritance and penalties:** Delegators inherit their validator's vote if
they don't vote themselves.
- **Claiming deposit:** Users that deposited on proposals can recover their
* **Claiming deposit:** Users that deposited on proposals can recover their
deposits if the proposal was accepted OR if the proposal never entered voting period.
This module will be used in the Cosmos Hub, the first Hub in the Cosmos network.
@@ -36,26 +36,26 @@ can be adapted to any Proof-Of-Stake blockchain by replacing *ATOM* with the nat
staking token of the chain.
1. **[Concepts](01_concepts.md)**
- [Proposal submission](01_concepts.md#proposal-submission)
- [Vote](01_concepts.md#vote)
- [Software Upgrade](01_concepts.md#software-upgrade)
* [Proposal submission](01_concepts.md#proposal-submission)
* [Vote](01_concepts.md#vote)
* [Software Upgrade](01_concepts.md#software-upgrade)
2. **[State](02_state.md)**
- [Parameters and base types](02_state.md#parameters-and-base-types)
- [Deposit](02_state.md#deposit)
- [ValidatorGovInfo](02_state.md#validatorgovinfo)
- [Proposals](02_state.md#proposals)
- [Stores](02_state.md#stores)
- [Proposal Processing Queue](02_state.md#proposal-processing-queue)
* [Parameters and base types](02_state.md#parameters-and-base-types)
* [Deposit](02_state.md#deposit)
* [ValidatorGovInfo](02_state.md#validatorgovinfo)
* [Proposals](02_state.md#proposals)
* [Stores](02_state.md#stores)
* [Proposal Processing Queue](02_state.md#proposal-processing-queue)
3. **[Messages](03_messages.md)**
- [Proposal Submission](03_messages.md#proposal-submission)
- [Deposit](03_messages.md#deposit)
- [Vote](03_messages.md#vote)
* [Proposal Submission](03_messages.md#proposal-submission)
* [Deposit](03_messages.md#deposit)
* [Vote](03_messages.md#vote)
4. **[Events](04_events.md)**
- [EndBlocker](04_events.md#endblocker)
- [Handlers](04_events.md#handlers)
* [EndBlocker](04_events.md#endblocker)
* [Handlers](04_events.md#handlers)
5. **[Future Improvements](05_future_improvements.md)**
6. **[Parameters](06_params.md)**
7. **[Client](07_client.md)**
- [CLI](07_client.md#cli)
- [gRPC](07_client.md#grpc)
- [REST](07_client.md#rest)
* [CLI](07_client.md#cli)
* [gRPC](07_client.md#grpc)
* [REST](07_client.md#rest)
x/group/internal/orm/spec/01_table.md
+9 -9
View File
@@ -2,17 +2,17 @@
A table can be built given a `codec.ProtoMarshaler` model type, a prefix to access the underlying prefix store used to store table data as well as a `Codec` for marshalling/unmarshalling.
+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/table.go#L24-L30
+++ <https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/table.go#L24-L30>
In the prefix store, entities should be stored by an unique identifier called `RowID` which can be based either on an `uint64` auto-increment counter, string or dynamic size bytes.
Regular CRUD operations can be performed on a table, these methods take a `sdk.KVStore` as parameter to get the table prefix store.
The `table` struct does not:
- enforce uniqueness of the `RowID`
- enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix
* enforce uniqueness of the `RowID`
* enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix
of another
- optimize Gas usage conditions
* optimize Gas usage conditions
The `table` struct is private, so that we only have custom tables built on top of it, that do satisfy these requirements.
`table` provides methods for exporting (using a [`PrefixScan` `Iterator`](03_iterator_pagination.md#iterator)) and importing genesis data. For the import to be successful, objects have to be aware of their primary key by implementing the [`PrimaryKeyed`](#primarykeyed) interface.
@@ -21,7 +21,7 @@ The `table` struct is private, so that we only have custom tables built on top o
`AutoUInt64Table` is a table type with an auto incrementing `uint64` ID.
+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/auto_uint64.go#L11-L14
+++ <https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/auto_uint64.go#L11-L14>
It's based on the `Sequence` struct which is a persistent unique key generator based on a counter encoded using 8 byte big endian.
@@ -33,7 +33,7 @@ It's based on the `Sequence` struct which is a persistent unique key generator b
The model provided for creating a `PrimaryKeyTable` should implement the `PrimaryKeyed` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41
+++ <https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41>
`PrimaryKeyFields()` method returns the list of key parts for a given object.
The primary key parts can be []byte, string, and `uint64` types.
@@ -42,6 +42,6 @@ The primary key parts can be []byte, string, and `uint64` types.
Key parts, except the last part, follow these rules:
- []byte is encoded with a single byte length prefix
- strings are null-terminated
- `uint64` are encoded using 8 byte big endian.
* []byte is encoded with a single byte length prefix
* strings are null-terminated
* `uint64` are encoded using 8 byte big endian.
x/group/internal/orm/spec/02_secondary_index.md
+4 -4
View File
@@ -2,19 +2,19 @@
Secondary indexes can be used on `Indexable` [tables](01_table.md). Indeed, those tables implement the `Indexable` interface that provides a set of functions that can be called by indexes to register and interact with the tables, like callback functions that are called on entries creation, update or deletion to create, update or remove corresponding entries in the table secondary indexes.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L88-L92
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L88-L92>
## MultiKeyIndex
A `MultiKeyIndex` is an index where multiple entries can point to the same underlying object.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L25-L31
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L25-L31>
Internally, it uses an `Indexer` that manages the persistence of the index based on searchable keys and create/update/delete operations.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L15-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L15-L19>
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/indexer.go#L15-L18
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/indexer.go#L15-L18>
The currently used implementation of an `indexer`, `Indexer`, relies on an `IndexerFunc` that should be provided when instantiating the index. Based on the source object, this function returns one or multiple index keys as `[]interface{}`. Such secondary index keys should be bytes, string or `uint64` in order to be handled properly by the [key codec](01_table.md#key-codec) which defines specific encoding for those types.
In the index prefix store, the keys are built based on the source object's `RowID` and its secondary index key(s) using the key codec and the values are set as empty bytes.
x/group/internal/orm/spec/03_iterator_pagination.md
+4 -4
View File
@@ -6,15 +6,15 @@ Both [tables](01_table.md) and [secondary indexes](02_secondary_index.md) suppor
An `Iterator` allows iteration through a sequence of key value pairs.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L77-L83
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L77-L83>
Tables rely on a `typeSafeIterator` that is used by `PrefixScan` and `ReversePrefixScan` `table` methods to iterate through a range of `RowID`s.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/table.go#235-L239
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/table.go#235-L239>
Secondary indexes rely on an `indexIterator` that can strip the `RowID` from the full index key in order to get the underlying value in the table prefix store.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L227-L232
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L227-L232>
Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`).
@@ -23,6 +23,6 @@ Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`).
The `Paginate` function does pagination given an [`Iterator`](#iterator) and a `query.PageRequest`, and returns a `query.PageResponse`.
It unmarshals the results into the provided dest interface that should be a pointer to a slice of models.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/iterator.go#L117-L216
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/iterator.go#L117-L216>
Secondary indexes have a `GetPaginated` method that returns an `Iterator` for the given searched secondary index key, starting from the `query.PageRequest` key if provided. It's important to note that this `query.PageRequest` key should be a `RowID` (that could have been returned by a previous paginated request). The returned `Iterator` can then be used with the `Paginate` function and the same `query.PageRequest`.
x/group/internal/orm/spec/README.md
+6 -6
View File
@@ -5,11 +5,11 @@ The orm package provides a framework for creating relational database tables wit
## Contents
1. **[Table](01_table.md)**
- [AutoUInt64Table](01_table.md#autouint64table)
- [PrimaryKeyTable](01_table.md#primarykeytable)
* [AutoUInt64Table](01_table.md#autouint64table)
* [PrimaryKeyTable](01_table.md#primarykeytable)
2. **[Secondary Index](02_secondary_index.md)**
- [MultiKeyIndex](02_secondary_index.md#multikeyindex)
- [UniqueIndex](02_secondary_index.md#uniqueindex)
* [MultiKeyIndex](02_secondary_index.md#multikeyindex)
* [UniqueIndex](02_secondary_index.md#uniqueindex)
3. **[Iterator and Pagination](03_iterator_pagination.md)**
- [Iterator](03_iterator_pagination.md#iterator)
- [Pagination](03_iterator_pagination.md#pagination)
* [Iterator](03_iterator_pagination.md#iterator)
* [Pagination](03_iterator_pagination.md#pagination)
x/group/spec/01_concepts.md
+1 -1
View File
@@ -71,4 +71,4 @@ could be executed later on.
In the current implementation, changing a group's membership (adding or removing members or changing their weight)
will cause all existing proposals for group policy accounts linked to this group
to be invalidated. They will simply fail if someone calls `Msg/Exec` and will
eventually be garbage collected.
eventually be garbage collected.
x/group/spec/03_messages.md
+27 -23
View File
@@ -11,7 +11,7 @@ A new group can be created with the `MsgCreateGroup`, which has an admin address
The metadata has a maximum length that is chosen by the app developer, and
passed into the group keeper as a config.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L54-L65
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L54-L65>
It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
@@ -19,7 +19,7 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi
Group members can be updated with the `UpdateGroupMembers`.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L74-L86
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L74-L86>
In the list of `MemberUpdates`, an existing member can be removed by setting its weight to 0.
@@ -29,7 +29,7 @@ It's expecting to fail if the signer is not the admin of the group.
The `UpdateGroupAdmin` can be used to update a group admin.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L91-L102
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L91-L102>
It's expecting to fail if the signer is not the admin of the group.
@@ -37,17 +37,18 @@ It's expecting to fail if the signer is not the admin of the group.
The `UpdateGroupMetadata` can be used to update a group metadata.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L107-L118
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L107-L118>
It's expecting to fail if:
- new metadata length is greater than `MaxMetadataLen` config.
- the signer is not the admin of the group.
* new metadata length is greater than `MaxMetadataLen` config.
* the signer is not the admin of the group.
## Msg/CreateGroupPolicy
A new group policy can be created with the `MsgCreateGroupPolicy`, which has an admin address, a group id, a decision policy and some optional metadata bytes.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L121-L142
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L121-L142>
It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
@@ -55,7 +56,7 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi
The `UpdateGroupPolicyAdmin` can be used to update a group policy admin.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L151-L162
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L151-L162>
It's expecting to fail if the signer is not the admin of the group policy.
@@ -63,7 +64,7 @@ It's expecting to fail if the signer is not the admin of the group policy.
The `UpdateGroupPolicyDecisionPolicy` can be used to update a decision policy.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L167-L179
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L167-L179>
It's expecting to fail if the signer is not the admin of the group policy.
@@ -71,18 +72,19 @@ It's expecting to fail if the signer is not the admin of the group policy.
The `UpdateGroupPolicyMetadata` can be used to update a group policy metadata.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L184-L195
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L184-L195>
It's expecting to fail if:
- new metadata length is greater than `MaxMetadataLen` config.
- the signer is not the admin of the group.
* new metadata length is greater than `MaxMetadataLen` config.
* the signer is not the admin of the group.
## Msg/CreateProposal
A new proposal can be created with the `MsgCreateProposal`, which has a group policy account address, a list of proposers addresses, a list of messages to execute if the proposal is accepted and some optional metadata bytes.
An optional `Exec` value can be provided to try to execute the proposal immediately after proposal creation. Proposers signatures are considered as yes votes in this case.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L218-L239
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L218-L239>
It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
@@ -90,18 +92,19 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi
A proposal can be withdrawn using `MsgWithdrawProposal` which has a `address` (can be either proposer or policy admin) and a `proposal_id` (which has to be withdrawn).
+++ https://github.com/cosmos/cosmos-sdk/blob/f2d6f0e4bb1a9bd7f7ae3cdc4702c9d3d1fc0329/proto/cosmos/group/v1beta1/tx.proto#L251-L258
+++ <https://github.com/cosmos/cosmos-sdk/blob/f2d6f0e4bb1a9bd7f7ae3cdc4702c9d3d1fc0329/proto/cosmos/group/v1beta1/tx.proto#L251-L258>
It's expecting to fail if:
- the signer is neither policy address nor proposer of the proposal.
- the proposal is already closed or aborted.
* the signer is neither policy address nor proposer of the proposal.
* the proposal is already closed or aborted.
## Msg/Vote
A new vote can be created with the `MsgVote`, given a proposal id, a voter address, a choice (yes, no, veto or abstain) and some optional metadata bytes.
An optional `Exec` value can be provided to try to execute the proposal immediately after voting.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L248-L265
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L248-L265>
It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
@@ -109,11 +112,12 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi
A proposal can be executed with the `MsgExec`.
+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L270-L278
+++ <https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L270-L278>
The messages that are part of this proposal won't be executed if:
- the group has been modified before tally.
- the group policy has been modified before tally.
- the proposal has not been accepted.
- the proposal status is not closed.
- the proposal has already been successfully executed.
* the group has been modified before tally.
* the group policy has been modified before tally.
* the proposal has not been accepted.
* the proposal status is not closed.
* the proposal has already been successfully executed.
x/group/spec/04_events.md
+1 -1
View File
@@ -60,4 +60,4 @@ The group module emits the following events:
| Type | Attribute Key | Attribute Value |
|--------------------------------|---------------|--------------------------------|
| message | action | /cosmos.group.v1beta1.Msg/Exec |
| cosmos.group.v1beta1.EventExec | proposal_id | {proposalId} |
| cosmos.group.v1beta1.EventExec | proposal_id | {proposalId} |
x/group/spec/README.md
+34 -34
View File
@@ -16,41 +16,41 @@ This module allows the creation and management of on-chain multisig accounts and
## Contents
1. **[Concepts](01_concepts.md)**
- [Group](01_concepts.md#group)
- [Group Policy](01_concepts.md#group-policy)
- [Decision Policy](01_concepts.md#decision-policy)
- [Proposal](01_concepts.md#proposal)
- [Voting](01_concepts.md#voting)
- [Executing Proposals](01_concepts.md#executing-proposals)
* [Group](01_concepts.md#group)
* [Group Policy](01_concepts.md#group-policy)
* [Decision Policy](01_concepts.md#decision-policy)
* [Proposal](01_concepts.md#proposal)
* [Voting](01_concepts.md#voting)
* [Executing Proposals](01_concepts.md#executing-proposals)
2. **[State](02_state.md)**
- [Group Table](02_state.md#group-table)
- [Group Member Table](02_state.md#group-member-table)
- [Group Policy Table](02_state.md#group-policy-table)
- [Proposal](02_state.md#proposal-table)
- [Vote Table](02_state.md#vote-table)
* [Group Table](02_state.md#group-table)
* [Group Member Table](02_state.md#group-member-table)
* [Group Policy Table](02_state.md#group-policy-table)
* [Proposal](02_state.md#proposal-table)
* [Vote Table](02_state.md#vote-table)
3. **[Msg Service](03_messages.md)**
- [Msg/CreateGroup](03_messages.md#msgcreategroup)
- [Msg/UpdateGroupMembers](03_messages.md#msgupdategroupmembers)
- [Msg/UpdateGroupAdmin](03_messages.md#msgupdategroupadmin)
- [Msg/UpdateGroupMetadata](03_messages.md#msgupdategroupmetadata)
- [Msg/CreateGroupPolicy](03_messages.md#msgcreategrouppolicy)
- [Msg/UpdateGroupPolicyAdmin](03_messages.md#msgupdategrouppolicyadmin)
- [Msg/UpdateGroupPolicyDecisionPolicy](03_messages.md#msgupdategrouppolicydecisionpolicy)
- [Msg/UpdateGroupPolicyMetadata](03_messages.md#msgupdategrouppolicymetadata)
- [Msg/CreateProposal](03_messages.md#msgcreateproposal)
- [Msg/WithdrawProposal](03_messages.md#msgwithdrawproposal)
- [Msg/Vote](03_messages.md#msgvote)
- [Msg/Exec](03_messages.md#msgexec)
* [Msg/CreateGroup](03_messages.md#msgcreategroup)
* [Msg/UpdateGroupMembers](03_messages.md#msgupdategroupmembers)
* [Msg/UpdateGroupAdmin](03_messages.md#msgupdategroupadmin)
* [Msg/UpdateGroupMetadata](03_messages.md#msgupdategroupmetadata)
* [Msg/CreateGroupPolicy](03_messages.md#msgcreategrouppolicy)
* [Msg/UpdateGroupPolicyAdmin](03_messages.md#msgupdategrouppolicyadmin)
* [Msg/UpdateGroupPolicyDecisionPolicy](03_messages.md#msgupdategrouppolicydecisionpolicy)
* [Msg/UpdateGroupPolicyMetadata](03_messages.md#msgupdategrouppolicymetadata)
* [Msg/CreateProposal](03_messages.md#msgcreateproposal)
* [Msg/WithdrawProposal](03_messages.md#msgwithdrawproposal)
* [Msg/Vote](03_messages.md#msgvote)
* [Msg/Exec](03_messages.md#msgexec)
4. **[Events](04_events.md)**
- [EventCreateGroup](04_events.md#eventcreategroup)
- [EventUpdateGroup](04_events.md#eventupdategroup)
- [EventCreateGroupPolicy](04_events.md#eventcreategrouppolicy)
- [EventUpdateGroupPolicy](04_events.md#eventupdategrouppolicy)
- [EventCreateProposal](04_events.md#eventcreateproposal)
- [EventWithdrawProposal](04_events.md#eventwithdrawproposal)
- [EventVote](04_events.md#eventvote)
- [EventExec](04_events.md#eventexec)
* [EventCreateGroup](04_events.md#eventcreategroup)
* [EventUpdateGroup](04_events.md#eventupdategroup)
* [EventCreateGroupPolicy](04_events.md#eventcreategrouppolicy)
* [EventUpdateGroupPolicy](04_events.md#eventupdategrouppolicy)
* [EventCreateProposal](04_events.md#eventcreateproposal)
* [EventWithdrawProposal](04_events.md#eventwithdrawproposal)
* [EventVote](04_events.md#eventvote)
* [EventExec](04_events.md#eventexec)
5. **[Client](05_client.md)**
- [CLI](05_client.md#cli)
- [gRPC](05_client.md#grpc)
- [REST](05_client.md#rest)
* [CLI](05_client.md#cli)
* [gRPC](05_client.md#grpc)
* [REST](05_client.md#rest)
x/mint/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Mint
- [Mint](spec/README.md) - Creation of new units of staking token.
* [Mint](spec/README.md) - Creation of new units of staking token.
x/mint/spec/01_concepts.md
+5 -5
View File
@@ -8,8 +8,8 @@ order: 1
The minting mechanism was designed to:
- allow for a flexible inflation rate determined by market demand targeting a particular bonded-stake ratio
- effect a balance between market liquidity and staked supply
* allow for a flexible inflation rate determined by market demand targeting a particular bonded-stake ratio
* effect a balance between market liquidity and staked supply
In order to best determine the appropriate market rate for inflation rewards, a
moving change rate is used. The moving change rate mechanism ensures that if
@@ -20,9 +20,9 @@ which should help provide some liquidity.
It can be broken down in the following way:
- If the inflation rate is below the goal %-bonded the inflation rate will
* If the inflation rate is below the goal %-bonded the inflation rate will
increase until a maximum value is reached
- If the goal % bonded (67% in Cosmos-Hub) is maintained, then the inflation
* If the goal % bonded (67% in Cosmos-Hub) is maintained, then the inflation
rate will stay constant
- If the inflation rate is above the goal %-bonded the inflation rate will
* If the inflation rate is above the goal %-bonded the inflation rate will
decrease until a minimum value is reached
x/mint/spec/02_state.md
+4 -4
View File
@@ -8,14 +8,14 @@ order: 2
The minter is a space for holding current inflation information.
- Minter: `0x00 -> ProtocolBuffer(minter)`
* Minter: `0x00 -> ProtocolBuffer(minter)`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L8-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L8-L19>
## Params
Minting params are held in the global params store.
- Params: `mint/params -> legacy_amino(params)`
* Params: `mint/params -> legacy_amino(params)`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L21-L53
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L21-L53>
x/mint/spec/03_begin_block.md
+3 -3
View File
@@ -15,7 +15,7 @@ depending on the distance from the desired ratio (67%). The maximum rate change
possible is defined to be 13% per year, however the annual inflation is capped
as between 7% and 20%.
```
```go
NextInflationRate(params Params, bondedRatio sdk.Dec) (inflation sdk.Dec) {
inflationRateChangePerYear = (1 - bondedRatio/params.GoalBonded) * params.InflationRateChange
inflationRateChange = inflationRateChangePerYear/blocksPerYr
@@ -38,7 +38,7 @@ NextInflationRate(params Params, bondedRatio sdk.Dec) (inflation sdk.Dec) {
Calculate the annual provisions based on current total supply and inflation
rate. This parameter is calculated once per block.
```
```go
NextAnnualProvisions(params Params, totalSupply sdk.Dec) (provisions sdk.Dec) {
return Inflation * totalSupply
```
@@ -47,7 +47,7 @@ NextAnnualProvisions(params Params, totalSupply sdk.Dec) (provisions sdk.Dec) {
Calculate the provisions generated for each block based on current annual provisions. The provisions are then minted by the `mint` module's `ModuleMinterAccount` and then transferred to the `auth`'s `FeeCollector` `ModuleAccount`.
```
```go
BlockProvision(params Params) sdk.Coin {
provisionAmt = AnnualProvisions/ params.BlocksPerYear
return sdk.NewCoin(params.MintDenom, provisionAmt.Truncate())
x/mint/spec/06_client.md
+27 -27
View File
@@ -12,7 +12,7 @@ A user can query and interact with the `mint` module using the CLI.
The `query` commands allow users to query `mint` state.
```
```sh
simd query mint --help
```
@@ -20,19 +20,19 @@ simd query mint --help
The `annual-provisions` command allow users to query the current minting annual provisions value
```
```sh
simd query mint annual-provisions [flags]
```
Example:
```
```sh
simd query mint annual-provisions
```
Example Output:
```
```sh
22268504368893.612100895088410693
```
@@ -40,19 +40,19 @@ Example Output:
The `inflation` command allow users to query the current minting inflation value
```
```sh
simd query mint inflation [flags]
```
Example:
```
```sh
simd query mint inflation
```
Example Output:
```
```sh
0.199200302563256955
```
@@ -60,13 +60,13 @@ Example Output:
The `params` command allow users to query the current minting parameters
```
```sh
simd query mint params [flags]
```
Example:
```
```yml
blocks_per_year: "4360000"
goal_bonded: "0.670000000000000000"
inflation_max: "0.200000000000000000"
@@ -83,19 +83,19 @@ A user can query the `mint` module using gRPC endpoints.
The `AnnualProvisions` endpoint allow users to query the current minting annual provisions value
```
```sh
/cosmos.mint.v1beta1.Query/AnnualProvisions
```
Example:
```
```sh
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/AnnualProvisions
```
Example Output:
```
```json
{
"annualProvisions": "1432452520532626265712995618"
}
@@ -105,19 +105,19 @@ Example Output:
The `Inflation` endpoint allow users to query the current minting inflation value
```
```sh
/cosmos.mint.v1beta1.Query/Inflation
```
Example:
```
```sh
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Inflation
```
Example Output:
```
```json
{
"inflation": "130197115720711261"
}
@@ -127,19 +127,19 @@ Example Output:
The `Params` endpoint allow users to query the current minting parameters
```
```sh
/cosmos.mint.v1beta1.Query/Params
```
Example:
```
```sh
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Params
```
Example Output:
```
```json
{
"params": {
"mintDenom": "stake",
@@ -158,19 +158,19 @@ A user can query the `mint` module using REST endpoints.
### annual-provisions
```
```sh
/cosmos/mint/v1beta1/annual_provisions
```
Example:
```
```sh
curl "localhost:1317/cosmos/mint/v1beta1/annual_provisions"
```
Example Output:
```
```json
{
"annualProvisions": "1432452520532626265712995618"
}
@@ -178,19 +178,19 @@ Example Output:
### inflation
```
```sh
/cosmos/mint/v1beta1/inflation
```
Example:
```
```sh
curl "localhost:1317/cosmos/mint/v1beta1/inflation"
```
Example Output:
```
```json
{
"inflation": "130197115720711261"
}
@@ -198,19 +198,19 @@ Example Output:
### params
```
```sh
/cosmos/mint/v1beta1/params
```
Example:
```
```sh
curl "localhost:1317/cosmos/mint/v1beta1/params"
```
Example Output:
```
```json
{
"params": {
"mintDenom": "stake",
x/mint/spec/README.md
+9 -9
View File
@@ -11,16 +11,16 @@ parent:
1. **[Concept](01_concepts.md)**
2. **[State](02_state.md)**
- [Minter](02_state.md#minter)
- [Params](02_state.md#params)
* [Minter](02_state.md#minter)
* [Params](02_state.md#params)
3. **[Begin-Block](03_begin_block.md)**
- [NextInflationRate](03_begin_block.md#nextinflationrate)
- [NextAnnualProvisions](03_begin_block.md#nextannualprovisions)
- [BlockProvision](03_begin_block.md#blockprovision)
* [NextInflationRate](03_begin_block.md#nextinflationrate)
* [NextAnnualProvisions](03_begin_block.md#nextannualprovisions)
* [BlockProvision](03_begin_block.md#blockprovision)
4. **[Parameters](04_params.md)**
5. **[Events](05_events.md)**
- [BeginBlocker](05_events.md#beginblocker)
* [BeginBlocker](05_events.md#beginblocker)
6. **[Client](06_client.md)**
- [CLI](06_client.md#cli)
- [gRPC](06_client.md#grpc)
- [REST](06_client.md#rest)
* [CLI](06_client.md#cli)
* [gRPC](06_client.md#grpc)
* [REST](06_client.md#rest)
x/params/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Params
- [Params](spec/README.md) - Globally available parameter store.
* [Params](spec/README.md) - Globally available parameter store.
x/params/spec/README.md
+3 -3
View File
@@ -24,6 +24,6 @@ The following contents explains how to use params module for master and user mod
1. **[Keeper](01_keeper.md)**
2. **[Subspace](02_subspace.md)**
- [Key](02_subspace.md#key)
- [KeyTable](02_subspace.md#keytable)
- [ParamSet](02_subspace.md#paramset)
* [Key](02_subspace.md#key)
* [KeyTable](02_subspace.md#keytable)
* [ParamSet](02_subspace.md#paramset)
x/slashing/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Slashing
- [Slashing](spec/README.md) - validator punishment mechanisms.
* [Slashing](spec/README.md) - validator punishment mechanisms.
x/slashing/spec/02_state.md
+4 -4
View File
@@ -14,7 +14,7 @@ Proposers are incentivized to include precommits from all validators in the Tend
by receiving additional fees proportional to the difference between the voting
power included in the `LastCommitInfo` and +2/3 (see [fee distribution](x/distribution/spec/03_begin_block.md)).
```
```go
type LastCommitInfo struct {
Round int32
Votes []VoteInfo
@@ -27,8 +27,8 @@ number of blocks by being automatically jailed, potentially slashed, and unbonde
Information about validator's liveness activity is tracked through `ValidatorSigningInfo`.
It is indexed in the store as follows:
- ValidatorSigningInfo: `0x01 | ConsAddrLen (1 byte) | ConsAddress -> ProtocolBuffer(ValSigningInfo)`
- MissedBlocksBitArray: `0x02 | ConsAddrLen (1 byte) | ConsAddress | LittleEndianUint64(signArrayIndex) -> VarInt(didMiss)` (varint is a number encoding format)
* ValidatorSigningInfo: `0x01 | ConsAddrLen (1 byte) | ConsAddress -> ProtocolBuffer(ValSigningInfo)`
* MissedBlocksBitArray: `0x02 | ConsAddrLen (1 byte) | ConsAddress | LittleEndianUint64(signArrayIndex) -> VarInt(didMiss)` (varint is a number encoding format)
The first mapping allows us to easily lookup the recent signing info for a
validator based on the validator's consensus address.
@@ -48,4 +48,4 @@ bonded validator. The `SignedBlocksWindow` parameter defines the size
The information stored for tracking validator liveness is as follows:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/slashing/v1beta1/slashing.proto#L11-L33
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/slashing/v1beta1/slashing.proto#L11-L33>
x/slashing/spec/03_messages.md
+1 -1
View File
@@ -22,7 +22,7 @@ message MsgUnjail {
Below is a pseudocode of the `MsgSrv/Unjail` RPC:
```
```go
unjail(tx MsgUnjail)
validator = getValidator(tx.ValidatorAddr)
if validator == nil
x/slashing/spec/05_hooks.md
+4 -4
View File
@@ -12,16 +12,16 @@ The slashing module implements the `StakingHooks` defined in `x/staking` and are
The following hooks impact the slashing state:
+ `AfterValidatorBonded` creates a `ValidatorSigningInfo` instance as described in the following section.
+ `AfterValidatorCreated` stores a validator's consensus key.
+ `AfterValidatorRemoved` removes a validator's consensus key.
* `AfterValidatorBonded` creates a `ValidatorSigningInfo` instance as described in the following section.
* `AfterValidatorCreated` stores a validator's consensus key.
* `AfterValidatorRemoved` removes a validator's consensus key.
## Validator Bonded
Upon successful first-time bonding of a new validator, we create a new `ValidatorSigningInfo` structure for the
now-bonded validator, which `StartHeight` of the current block.
```
```go
onValidatorBonded(address sdk.ValAddress)
signingInfo, found = GetValidatorSigningInfo(address)
x/slashing/spec/06_events.md
+5 -5
View File
@@ -10,9 +10,9 @@ The slashing module emits the following events:
### MsgUnjail
| Type | Attribute Key | Attribute Value |
| ------- | ------------- | --------------- |
| message | module | slashing |
| Type | Attribute Key | Attribute Value |
| ------- | ------------- | ------------------ |
| message | module | slashing |
| message | sender | {validatorAddress} |
## Keeper
@@ -27,7 +27,7 @@ The slashing module emits the following events:
| slash | jailed [0] | {validatorConsensusAddress} |
| slash | burned coins | {sdk.Int} |
- [0] Only included if the validator is jailed.
* [0] Only included if the validator is jailed.
| Type | Attribute Key | Attribute Value |
| -------- | ------------- | --------------------------- |
@@ -37,7 +37,7 @@ The slashing module emits the following events:
### Slash
+ same as `"slash"` event from `HandleValidatorSignature`, but without the `jailed` attribute.
* same as `"slash"` event from `HandleValidatorSignature`, but without the `jailed` attribute.
### Jail
x/slashing/spec/07_tombstone.md
+2 -2
View File
@@ -113,11 +113,11 @@ comparing potential future ones to find the max.
Currently the only Tendermint ABCI fault is:
- Unjustified precommits (double signs)
* Unjustified precommits (double signs)
It is currently planned to include the following fault in the near future:
- Signing a precommit when you're in unbonding phase (needed to make light client bisection safe)
* Signing a precommit when you're in unbonding phase (needed to make light client bisection safe)
Given that these faults are both attributable byzantine faults, we will likely
want to slash them equally, and thus we can enact the above change.
x/slashing/spec/09_client.md
+34 -34
View File
@@ -6,31 +6,31 @@ order: 9
A user can query and interact with the `slashing` module using the CLI.
### Query
## Query
The `query` commands allow users to query `slashing` state.
```bash
```sh
simd query slashing --help
```
#### params
### params
The `params` command allows users to query genesis parameters for the slashing module.
```bash
```sh
simd query slashing params [flags]
```
Example:
```bash
```sh
simd query slashing params
```
Example Output:
```bash
```yml
downtime_jail_duration: 600s
min_signed_per_window: "0.500000000000000000"
signed_blocks_window: "100"
@@ -38,24 +38,24 @@ slash_fraction_double_sign: "0.050000000000000000"
slash_fraction_downtime: "0.010000000000000000"
```
#### signing-info
### signing-info
The `signing-info` command allows users to query signing-info of the validator using consensus public key.
```bash
```sh
simd query slashing signing-infos [flags]
```
Example:
```bash
```sh
simd query slashing signing-info '{"@type":"/cosmos.crypto.ed25519.PubKey","key":"Auxs3865HpB/EfssYOzfqNhEJjzys6jD5B6tPgC8="}'
```
Example Output:
```bash
```yml
address: cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c
index_offset: "2068"
jailed_until: "1970-01-01T00:00:00Z"
@@ -64,23 +64,23 @@ start_height: "0"
tombstoned: false
```
#### signing-infos
### signing-infos
The `signing-infos` command allows users to query signing infos of all validators.
```bash
```sh
simd query slashing signing-infos [flags]
```
Example:
```bash
```sh
simd query slashing signing-infos
```
Example Output:
```bash
```yml
info:
- address: cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c
index_offset: "2075"
@@ -93,7 +93,7 @@ pagination:
total: "0"
```
### Transactions
## Transactions
The `tx` commands allow users to interact with the `slashing` module.
@@ -101,7 +101,7 @@ The `tx` commands allow users to interact with the `slashing` module.
simd tx slashing --help
```
#### unjail
### unjail
The `unjail` command allows users to unjail a validator previously jailed for downtime.
@@ -123,19 +123,19 @@ A user can query the `slashing` module using gRPC endpoints.
The `Params` endpoint allows users to query the parameters of slashing module.
```bash
```sh
cosmos.slashing.v1beta1.Query/Params
```
Example:
```bash
```sh
grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/Params
```
Example Output:
```bash
```json
{
"params": {
"signedBlocksWindow": "100",
@@ -151,19 +151,19 @@ Example Output:
The SigningInfo queries the signing info of given cons address.
```bash
```sh
cosmos.slashing.v1beta1.Query/SigningInfo
```
Example:
```bash
```sh
grpcurl -plaintext -d '{"cons_address":"cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c"}' localhost:9090 cosmos.slashing.v1beta1.Query/SigningInfo
```
Example Output:
```bash
```json
{
"valSigningInfo": {
"address": "cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c",
@@ -177,19 +177,19 @@ Example Output:
The SigningInfos queries signing info of all validators.
```bash
```sh
cosmos.slashing.v1beta1.Query/SigningInfos
```
Example:
```bash
```sh
grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/SigningInfos
```
Example Output:
```bash
```json
{
"info": [
{
@@ -210,19 +210,19 @@ A user can query the `slashing` module using REST endpoints.
### Params
```bash
```sh
/cosmos/slashing/v1beta1/params
```
Example:
```bash
```sh
curl "localhost:1317/cosmos/slashing/v1beta1/params"
```
Example Output:
```bash
```json
{
"params": {
"signed_blocks_window": "100",
@@ -235,19 +235,19 @@ Example Output:
### signing_info
```bash
```sh
/cosmos/slashing/v1beta1/signing_infos/%s
```
Example:
```bash
```sh
curl "localhost:1317/cosmos/slashing/v1beta1/signing_infos/cosmosvalcons1nrqslkwd3pz096lh6t082frdqc84uwxn0t958c"
```
Example Output:
```bash
```json
{
"val_signing_info": {
"address": "cosmosvalcons1nrqslkwd3pz096lh6t082frdqc84uwxn0t958c",
@@ -262,19 +262,19 @@ Example Output:
### signing_infos
```bash
```sh
/cosmos/slashing/v1beta1/signing_infos
```
Example:
```bash
```sh
curl "localhost:1317/cosmos/slashing/v1beta1/signing_infos
```
Example Output:
```bash
```json
{
"info": [
{
x/slashing/spec/README.md
+16 -16
View File
@@ -17,33 +17,33 @@ by a protocol-recognized actor with value at stake by penalizing them ("slashing
Penalties may include, but are not limited to:
- Burning some amount of their stake
- Removing their ability to vote on future blocks for a period of time.
* Burning some amount of their stake
* Removing their ability to vote on future blocks for a period of time.
This module will be used by the Cosmos Hub, the first hub in the Cosmos ecosystem.
## Contents
1. **[Concepts](01_concepts.md)**
- [States](01_concepts.md#states)
- [Tombstone Caps](01_concepts.md#tombstone-caps)
- [ASCII timelines](01_concepts.md#ascii-timelines)
* [States](01_concepts.md#states)
* [Tombstone Caps](01_concepts.md#tombstone-caps)
* [ASCII timelines](01_concepts.md#ascii-timelines)
2. **[State](02_state.md)**
- [Signing Info](02_state.md#signing-info)
* [Signing Info](02_state.md#signing-info)
3. **[Messages](03_messages.md)**
- [Unjail](03_messages.md#unjail)
* [Unjail](03_messages.md#unjail)
4. **[Begin-Block](04_begin_block.md)**
- [Evidence handling](04_begin_block.md#evidence-handling)
- [Uptime tracking](04_begin_block.md#uptime-tracking)
* [Evidence handling](04_begin_block.md#evidence-handling)
* [Uptime tracking](04_begin_block.md#uptime-tracking)
5. **[05_hooks.md](05_hooks.md)**
- [Hooks](05_hooks.md#hooks)
* [Hooks](05_hooks.md#hooks)
6. **[Events](06_events.md)**
- [BeginBlocker](06_events.md#beginblocker)
- [Handlers](06_events.md#handlers)
* [BeginBlocker](06_events.md#beginblocker)
* [Handlers](06_events.md#handlers)
7. **[Staking Tombstone](07_tombstone.md)**
- [Abstract](07_tombstone.md#abstract)
* [Abstract](07_tombstone.md#abstract)
8. **[Parameters](08_params.md)**
9. **[Client](09_client.md)**
- [CLI](09_client.md#cli)
- [gRPC](09_client.md#grpc)
- [REST](09_client.md#rest)
* [CLI](09_client.md#cli)
* [gRPC](09_client.md#grpc)
* [REST](09_client.md#rest)
x/staking/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Staking
- [Staking](spec/README.md) - Proof-of-Stake layer for public blockchains.
* [Staking](spec/README.md) - Proof-of-Stake layer for public blockchains.
x/staking/spec/01_state.md
+31 -31
View File
@@ -13,31 +13,31 @@ Pool is used for tracking bonded and not-bonded token supply of the bond denomin
LastTotalPower tracks the total amounts of bonded tokens recorded during the previous end block.
Store entries prefixed with "Last" must remain unchanged until EndBlock.
- LastTotalPower: `0x12 -> ProtocolBuffer(sdk.Int)`
* LastTotalPower: `0x12 -> ProtocolBuffer(sdk.Int)`
## Params
Params is a module-wide configuration structure that stores system parameters
and defines overall functioning of the staking module.
- Params: `Paramsspace("staking") -> legacy_amino(params)`
* Params: `Paramsspace("staking") -> legacy_amino(params)`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.1/proto/cosmos/staking/v1beta1/staking.proto#L230-L241
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.1/proto/cosmos/staking/v1beta1/staking.proto#L230-L241>
## Validator
Validators can have one of three statuses
- `Unbonded`: The validator is not in the active set. They cannot sign blocks and do not earn
* `Unbonded`: The validator is not in the active set. They cannot sign blocks and do not earn
rewards. They can receive delegations.
- `Bonded`": Once the validator receives sufficient bonded tokens they automtically join the
* `Bonded`": Once the validator receives sufficient bonded tokens they automtically join the
active set during [`EndBlock`](./05_end_block.md#validator-set-changes) and their status is updated to `Bonded`.
They are signing blocks and receiving rewards. They can receive further delegations.
They can be slashed for misbehavior. Delegators to this validator who unbond their delegation
must wait the duration of the UnbondingTime, a chain-specific param, during which time
they are still slashable for offences of the source validator if those offences were committed
during the period of time that the tokens were bonded.
- `Unbonding`: When a validator leaves the active set, either by choice or due to slashing, jailing or
* `Unbonding`: When a validator leaves the active set, either by choice or due to slashing, jailing or
tombstoning, an unbonding of all their delegations begins. All delegations must then wait the UnbondingTime
before their tokens are moved to their accounts from the `BondedPool`.
@@ -49,10 +49,10 @@ required lookups for slashing and validator-set updates. A third special index
throughout each block, unlike the first two indices which mirror the validator
records within a block.
- Validators: `0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator)`
- ValidatorsByConsAddr: `0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr`
- ValidatorsByPower: `0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr`
- LastValidatorsPower: `0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower)`
* Validators: `0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator)`
* ValidatorsByConsAddr: `0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr`
* ValidatorsByPower: `0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr`
* LastValidatorsPower: `0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower)`
`Validators` is the primary index - it ensures that each operator can have only one
associated validator, where the public key of that validator can change in the
@@ -75,23 +75,23 @@ is updated during the validator set update process which takes place in [`EndBlo
Each validator's state is stored in a `Validator` struct:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L65-L99
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L65-L99>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L63
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L63>
## Delegation
Delegations are identified by combining `DelegatorAddr` (the address of the delegator)
with the `ValidatorAddr` Delegators are indexed in the store as follows:
- Delegation: `0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)`
* Delegation: `0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)`
Stake holders may delegate coins to validators; under this circumstance their
funds are held in a `Delegation` data structure. It is owned by one
delegator, and is associated with the shares for one validator. The sender of
the transaction is the owner of the bond.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L159-L170
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L159-L170>
### Delegator Shares
@@ -120,8 +120,8 @@ detected.
`UnbondingDelegation` are indexed in the store as:
- UnbondingDelegation: `0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation)`
- UnbondingDelegationsFromValidator: `0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* UnbondingDelegation: `0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation)`
* UnbondingDelegationsFromValidator: `0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
The first map here is used in queries, to lookup all unbonding delegations for
a given delegator, while the second map is used in slashing, to lookup all
@@ -130,7 +130,7 @@ slashed.
A UnbondingDelegation object is created every time an unbonding is initiated.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L172-L198
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L172-L198>
## Redelegation
@@ -142,9 +142,9 @@ committed by the source validator.
`Redelegation` are indexed in the store as:
- Redelegations: `0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation)`
- RedelegationsBySrc: `0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
- RedelegationsByDst: `0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* Redelegations: `0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation)`
* RedelegationsBySrc: `0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
* RedelegationsByDst: `0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil`
The first map here is used for queries, to lookup all redelegations for a given
delegator. The second map is used for slashing based on the `ValidatorSrcAddr`,
@@ -153,12 +153,12 @@ while the third map is for slashing based on the `ValidatorDstAddr`.
A redelegation object is created every time a redelegation occurs. To prevent
"redelegation hopping" redelegations may not occur under the situation that:
- the (re)delegator already has another immature redelegation in progress
* the (re)delegator already has another immature redelegation in progress
with a destination to a validator (let's call it `Validator X`)
- and, the (re)delegator is attempting to create a _new_ redelegation
* and, the (re)delegator is attempting to create a _new_ redelegation
where the source validator for this new redelegation is `Validator X`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228>
## Queues
@@ -167,8 +167,8 @@ first rounded to the nearest nanosecond then sorted. The sortable time format
used is a slight modification of the RFC3339Nano and uses the the format string
`"2006-01-02T15:04:05.000000000"`. Notably this format:
- right pads all zeros
- drops the time zone info (uses UTC)
* right pads all zeros
* drops the time zone info (uses UTC)
In all cases, the stored timestamp represents the maturation time of the queue
element.
@@ -178,25 +178,25 @@ element.
For the purpose of tracking progress of unbonding delegations the unbonding
delegations queue is kept.
- UnbondingDelegation: `0x41 | format(time) -> []DVPair`
* UnbondingDelegation: `0x41 | format(time) -> []DVPair`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L123-L133
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L123-L133>
### RedelegationQueue
For the purpose of tracking progress of redelegations the redelegation queue is
kept.
- RedelegationQueue: `0x42 | format(time) -> []DVVTriplet`
* RedelegationQueue: `0x42 | format(time) -> []DVVTriplet`
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152>
### ValidatorQueue
For the purpose of tracking progress of unbonding validators the validator
queue is kept.
- ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`
* ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`
The stored object as each key is an array of validator operator addresses from
which the validator object can be accessed. Typically it is expected that only
@@ -208,7 +208,7 @@ that multiple validators exist in the queue at the same location.
HistoricalInfo objects are stored and pruned at each block such that the staking keeper persists
the `n` most recent historical info defined by staking module parameter: `HistoricalEntries`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L15-L22
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L15-L22>
At each BeginBlock, the staking keeper will persist the current Header and the Validators that committed
the current block in a `HistoricalInfo` object. The Validators are sorted on their address to ensure that
x/staking/spec/02_state_transitions.md
+45 -45
View File
@@ -24,44 +24,44 @@ directly between all the states, except for from `Bonded` to `Unbonded`.
The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses
that of the `LastValidator`.
- set `validator.Status` to `Bonded`
- send the `validator.Tokens` from the `NotBondedTokens` to the `BondedPool` `ModuleAccount`
- delete the existing record from `ValidatorByPowerIndex`
- add a new updated record to the `ValidatorByPowerIndex`
- update the `Validator` object for this validator
- if it exists, delete any `ValidatorQueue` record for this validator
* set `validator.Status` to `Bonded`
* send the `validator.Tokens` from the `NotBondedTokens` to the `BondedPool` `ModuleAccount`
* delete the existing record from `ValidatorByPowerIndex`
* add a new updated record to the `ValidatorByPowerIndex`
* update the `Validator` object for this validator
* if it exists, delete any `ValidatorQueue` record for this validator
### Bonded to Unbonding
When a validator begins the unbonding process the following operations occur:
- send the `validator.Tokens` from the `BondedPool` to the `NotBondedTokens` `ModuleAccount`
- set `validator.Status` to `Unbonding`
- delete the existing record from `ValidatorByPowerIndex`
- add a new updated record to the `ValidatorByPowerIndex`
- update the `Validator` object for this validator
- insert a new record into the `ValidatorQueue` for this validator
* send the `validator.Tokens` from the `BondedPool` to the `NotBondedTokens` `ModuleAccount`
* set `validator.Status` to `Unbonding`
* delete the existing record from `ValidatorByPowerIndex`
* add a new updated record to the `ValidatorByPowerIndex`
* update the `Validator` object for this validator
* insert a new record into the `ValidatorQueue` for this validator
### Unbonding to Unbonded
A validator moves from unbonding to unbonded when the `ValidatorQueue` object
moves from bonded to unbonded
- update the `Validator` object for this validator
- set `validator.Status` to `Unbonded`
* update the `Validator` object for this validator
* set `validator.Status` to `Unbonded`
### Jail/Unjail
when a validator is jailed it is effectively removed from the Tendermint set.
this process may be also be reversed. the following operations occur:
- set `Validator.Jailed` and update object
- if jailed delete record from `ValidatorByPowerIndex`
- if unjailed add record to `ValidatorByPowerIndex`
* set `Validator.Jailed` and update object
* if jailed delete record from `ValidatorByPowerIndex`
* if unjailed add record to `ValidatorByPowerIndex`
Jailed validators are not present in any of the following stores:
- the power store (from consensus power to address)
* the power store (from consensus power to address)
## Delegations
@@ -69,49 +69,49 @@ Jailed validators are not present in any of the following stores:
When a delegation occurs both the validator and the delegation objects are affected
- determine the delegators shares based on tokens delegated and the validator's exchange rate
- remove tokens from the sending account
- add shares the delegation object or add them to a created validator object
- add new delegator shares and update the `Validator` object
- transfer the `delegation.Amount` from the delegator's account to the `BondedPool` or the `NotBondedPool` `ModuleAccount` depending if the `validator.Status` is `Bonded` or not
- delete the existing record from `ValidatorByPowerIndex`
- add an new updated record to the `ValidatorByPowerIndex`
* determine the delegators shares based on tokens delegated and the validator's exchange rate
* remove tokens from the sending account
* add shares the delegation object or add them to a created validator object
* add new delegator shares and update the `Validator` object
* transfer the `delegation.Amount` from the delegator's account to the `BondedPool` or the `NotBondedPool` `ModuleAccount` depending if the `validator.Status` is `Bonded` or not
* delete the existing record from `ValidatorByPowerIndex`
* add an new updated record to the `ValidatorByPowerIndex`
### Begin Unbonding
As a part of the Undelegate and Complete Unbonding state transitions Unbond
Delegation may be called.
- subtract the unbonded shares from delegator
- if the validator is `Unbonding` or `Bonded` add the tokens to an `UnbondingDelegation` Entry
- if the validator is `Unbonded` send the tokens directly to the withdraw
* subtract the unbonded shares from delegator
* if the validator is `Unbonding` or `Bonded` add the tokens to an `UnbondingDelegation` Entry
* if the validator is `Unbonded` send the tokens directly to the withdraw
account
- update the delegation or remove the delegation if there are no more shares
- if the delegation is the operator of the validator and no more shares exist then trigger a jail validator
- update the validator with removed the delegator shares and associated coins
- if the validator state is `Bonded`, transfer the `Coins` worth of the unbonded
* update the delegation or remove the delegation if there are no more shares
* if the delegation is the operator of the validator and no more shares exist then trigger a jail validator
* update the validator with removed the delegator shares and associated coins
* if the validator state is `Bonded`, transfer the `Coins` worth of the unbonded
shares from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
- remove the validator if it is unbonded and there are no more delegation shares.
* remove the validator if it is unbonded and there are no more delegation shares.
### Complete Unbonding
For undelegations which do not complete immediately, the following operations
occur when the unbonding delegation queue element matures:
- remove the entry from the `UnbondingDelegation` object
- transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account`
* remove the entry from the `UnbondingDelegation` object
* transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account`
### Begin Redelegation
Redelegations affect the delegation, source and destination validators.
- perform an `unbond` delegation from the source validator to retrieve the tokens worth of the unbonded shares
- using the unbonded tokens, `Delegate` them to the destination validator
- if the `sourceValidator.Status` is `Bonded`, and the `destinationValidator` is not,
* perform an `unbond` delegation from the source validator to retrieve the tokens worth of the unbonded shares
* using the unbonded tokens, `Delegate` them to the destination validator
* if the `sourceValidator.Status` is `Bonded`, and the `destinationValidator` is not,
transfer the newly delegated tokens from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
- otherwise, if the `sourceValidator.Status` is not `Bonded`, and the `destinationValidator`
* otherwise, if the `sourceValidator.Status` is not `Bonded`, and the `destinationValidator`
is `Bonded`, transfer the newly delegated tokens from the `NotBondedPool` to the `BondedPool` `ModuleAccount`
- record the token amount in an new entry in the relevant `Redelegation`
* record the token amount in an new entry in the relevant `Redelegation`
From when a redelegation begins until it completes, the delegator is in a state of "pseudo-unbonding", and can still be
slashed for infractions that occured before the redelegation began.
@@ -120,7 +120,7 @@ slashed for infractions that occured before the redelegation began.
When a redelegations complete the following occurs:
- remove the entry from the `Redelegation` object
* remove the entry from the `Redelegation` object
## Slashing
@@ -128,13 +128,13 @@ When a redelegations complete the following occurs:
When a Validator is slashed, the following occurs:
- The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) \* `TokensFromConsensusPower`,
* The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) \* `TokensFromConsensusPower`,
the total number of tokens bonded to the validator at the time of the infraction.
- Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occured before the unbonding or
* Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occured before the unbonding or
redelegation began from the validator are slashed by the `slashFactor` percentage of the initialBalance.
- Each amount slashed from redelegations and unbonding delegations is subtracted from the
* Each amount slashed from redelegations and unbonding delegations is subtracted from the
total slash amount.
- The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or
* The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or
`NonBondedPool` depending on the validator's status. This reduces the total supply of tokens.
In the case of a slash due to any infraction that requires evidence to submitted (for example double-sign), the slash
x/staking/spec/03_messages.md
+56 -56
View File
@@ -11,20 +11,20 @@ In this section we describe the processing of the staking messages and the corre
A validator is created using the `MsgCreateValidator` message.
The validator must be created with an initial delegation from the operator.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51>
This message is expected to fail if:
- another validator with this operator address is already registered
- another validator with this pubkey is already registered
- the initial self-delegation tokens are of a denom not specified as the bonding denom
- the commission parameters are faulty, namely:
- `MaxRate` is either > 1 or < 0
- the initial `Rate` is either negative or > `MaxRate`
- the initial `MaxChangeRate` is either negative or > `MaxRate`
- the description fields are too large
* another validator with this operator address is already registered
* another validator with this pubkey is already registered
* the initial self-delegation tokens are of a denom not specified as the bonding denom
* the commission parameters are faulty, namely:
* `MaxRate` is either > 1 or < 0
* the initial `Rate` is either negative or > `MaxRate`
* the initial `MaxChangeRate` is either negative or > `MaxRate`
* the description fields are too large
This message creates and stores the `Validator` object at appropriate indexes.
Additionally a self-delegation is made with the initial tokens delegation
@@ -36,16 +36,16 @@ in the first end-block.
The `Description`, `CommissionRate` of a validator can be updated using the
`MsgEditValidator` message.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76>
This message is expected to fail if:
- the initial `CommissionRate` is either negative or > `MaxRate`
- the `CommissionRate` has already been updated within the previous 24 hours
- the `CommissionRate` is > `MaxChangeRate`
- the description fields are too large
* the initial `CommissionRate` is either negative or > `MaxRate`
* the `CommissionRate` has already been updated within the previous 24 hours
* the `CommissionRate` is > `MaxChangeRate`
* the description fields are too large
This message stores the updated `Validator` object.
@@ -55,16 +55,16 @@ Within this message the delegator provides coins, and in return receives
some amount of their validator's (newly created) delegator-shares that are
assigned to `Delegation.Shares`.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90>
This message is expected to fail if:
- the validator does not exist
- the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
- the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
- the amount delegated is less than the minimum allowed delegation
* the validator does not exist
* the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
* the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
* the amount delegated is less than the minimum allowed delegation
If an existing `Delegation` object for provided addresses does not already
exist then it is created as part of this message otherwise the existing
@@ -87,32 +87,32 @@ will not be added to the power index until it is unjailed.
The `MsgUndelegate` message allows delegators to undelegate their tokens from
validator.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121>
This message returns a response containing the completion time of the undelegation:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126>
This message is expected to fail if:
- the delegation doesn't exist
- the validator doesn't exist
- the delegation has less shares than the ones worth of `Amount`
- existing `UnbondingDelegation` has maximum entries as defined by `params.MaxEntries`
- the `Amount` has a denomination different than one defined by `params.BondDenom`
* the delegation doesn't exist
* the validator doesn't exist
* the delegation has less shares than the ones worth of `Amount`
* existing `UnbondingDelegation` has maximum entries as defined by `params.MaxEntries`
* the `Amount` has a denomination different than one defined by `params.BondDenom`
When this message is processed the following actions occur:
- validator's `DelegatorShares` and the delegation's `Shares` are both reduced by the message `SharesAmount`
- calculate the token worth of the shares remove that amount tokens held within the validator
- with those removed tokens, if the validator is:
- `Bonded` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares.
- `Unbonding` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
- `Unbonded` - then send the coins the message `DelegatorAddr`
- if there are no more `Shares` in the delegation, then the delegation object is removed from the store
- under this situation if the delegation is the validator's self-delegation then also jail the validator.
* validator's `DelegatorShares` and the delegation's `Shares` are both reduced by the message `SharesAmount`
* calculate the token worth of the shares remove that amount tokens held within the validator
* with those removed tokens, if the validator is:
* `Bonded` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares.
* `Unbonding` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
* `Unbonded` - then send the coins the message `DelegatorAddr`
* if there are no more `Shares` in the delegation, then the delegation object is removed from the store
* under this situation if the delegation is the validator's self-delegation then also jail the validator.
![Unbond sequence](../../../docs/uml/svg/unbond_sequence.svg)
@@ -122,33 +122,33 @@ The redelegation command allows delegators to instantly switch validators. Once
the unbonding period has passed, the redelegation is automatically completed in
the EndBlocker.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105>
This message returns a response containing the completion time of the redelegation:
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110
+++ <https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110>
This message is expected to fail if:
- the delegation doesn't exist
- the source or destination validators don't exist
- the delegation has less shares than the ones worth of `Amount`
- the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive)
- existing `Redelegation` has maximum entries as defined by `params.MaxEntries`
- the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
* the delegation doesn't exist
* the source or destination validators don't exist
* the delegation has less shares than the ones worth of `Amount`
* the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive)
* existing `Redelegation` has maximum entries as defined by `params.MaxEntries`
* the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
When this message is processed the following actions occur:
- the source validator's `DelegatorShares` and the delegations `Shares` are both reduced by the message `SharesAmount`
- calculate the token worth of the shares remove that amount tokens held within the source validator.
- if the source validator is:
- `Bonded` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares (this may be effectively reversed in the next step however).
- `Unbonding` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
- `Unbonded` - no action required in this step
- Delegate the token worth to the destination validator, possibly moving tokens back to the bonded state.
- if there are no more `Shares` in the source delegation, then the source delegation object is removed from the store
- under this situation if the delegation is the validator's self-delegation then also jail the validator.
* the source validator's `DelegatorShares` and the delegations `Shares` are both reduced by the message `SharesAmount`
* calculate the token worth of the shares remove that amount tokens held within the source validator.
* if the source validator is:
* `Bonded` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares (this may be effectively reversed in the next step however).
* `Unbonding` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
* `Unbonded` - no action required in this step
* Delegate the token worth to the destination validator, possibly moving tokens back to the bonded state.
* if there are no more `Shares` in the source delegation, then the source delegation object is removed from the store
* under this situation if the delegation is the validator's self-delegation then also jail the validator.
![Begin redelegation sequence](../../../docs/uml/svg/begin_redelegation_sequence.svg)
x/staking/spec/05_end_block.md
+9 -9
View File
@@ -15,12 +15,12 @@ validators are also returned back to Tendermint for inclusion in the Tendermint
validator set which is responsible for validating Tendermint messages at the
consensus layer. Operations are as following:
- the new validator set is taken as the top `params.MaxValidators` number of
* the new validator set is taken as the top `params.MaxValidators` number of
validators retrieved from the `ValidatorsByPower` index
- the previous validator set is compared with the new validator set:
- missing validators begin unbonding and their `Tokens` are transferred from the
* the previous validator set is compared with the new validator set:
* missing validators begin unbonding and their `Tokens` are transferred from the
`BondedPool` to the `NotBondedPool` `ModuleAccount`
- new validators are instantly bonded and their `Tokens` are transferred from the
* new validators are instantly bonded and their `Tokens` are transferred from the
`NotBondedPool` to the `BondedPool` `ModuleAccount`
In all cases, any validators leaving or entering the bonded validator set or
@@ -62,9 +62,9 @@ switched from `types.Unbonding` to
Complete the unbonding of all mature `UnbondingDelegations.Entries` within the
`UnbondingDelegations` queue with the following procedure:
- transfer the balance coins to the delegator's wallet address
- remove the mature entry from `UnbondingDelegation.Entries`
- remove the `UnbondingDelegation` object from the store if there are no
* transfer the balance coins to the delegator's wallet address
* remove the mature entry from `UnbondingDelegation.Entries`
* remove the `UnbondingDelegation` object from the store if there are no
remaining entries.
### Redelegations
@@ -72,6 +72,6 @@ Complete the unbonding of all mature `UnbondingDelegations.Entries` within the
Complete the unbonding of all mature `Redelegation.Entries` within the
`Redelegations` queue with the following procedure:
- remove the mature entry from `Redelegation.Entries`
- remove the `Redelegation` object from the store if there are no
* remove the mature entry from `Redelegation.Entries`
* remove the `Redelegation` object from the store if there are no
remaining entries.
x/staking/spec/06_hooks.md
+16 -16
View File
@@ -9,19 +9,19 @@ occurred within staking. These events can be registered to execute either
right `Before` or `After` the staking event (as per the hook name). The
following hooks can registered with staking:
- `AfterValidatorCreated(Context, ValAddress) error`
- called when a validator is created
- `BeforeValidatorModified(Context, ValAddress) error`
- called when a validator's state is changed
- `AfterValidatorRemoved(Context, ConsAddress, ValAddress) error`
- called when a validator is deleted
- `AfterValidatorBonded(Context, ConsAddress, ValAddress) error`
- called when a validator is bonded
- `AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error`
- called when a validator begins unbonding
- `BeforeDelegationCreated(Context, AccAddress, ValAddress) error`
- called when a delegation is created
- `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error`
- called when a delegation's shares are modified
- `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error`
- called when a delegation is removed
* `AfterValidatorCreated(Context, ValAddress) error`
* called when a validator is created
* `BeforeValidatorModified(Context, ValAddress) error`
* called when a validator's state is changed
* `AfterValidatorRemoved(Context, ConsAddress, ValAddress) error`
* called when a validator is deleted
* `AfterValidatorBonded(Context, ConsAddress, ValAddress) error`
* called when a validator is bonded
* `AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error`
* called when a validator begins unbonding
* `BeforeDelegationCreated(Context, AccAddress, ValAddress) error`
* called when a delegation is created
* `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error`
* called when a delegation's shares are modified
* `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error`
* called when a delegation is removed
x/staking/spec/07_events.md
+2 -2
View File
@@ -61,7 +61,7 @@ The staking module emits the following events:
| message | action | begin_unbonding |
| message | sender | {senderAddress} |
- [0] Time is formatted in the RFC3339 standard
* [0] Time is formatted in the RFC3339 standard
### MsgBeginRedelegate
@@ -75,4 +75,4 @@ The staking module emits the following events:
| message | action | begin_redelegate |
| message | sender | {senderAddress} |
- [0] Time is formatted in the RFC3339 standard
* [0] Time is formatted in the RFC3339 standard
x/staking/spec/README.md
+22 -22
View File
@@ -24,32 +24,32 @@ network.
## Contents
1. **[State](01_state.md)**
- [Pool](01_state.md#pool)
- [LastTotalPower](01_state.md#lasttotalpower)
- [Params](01_state.md#params)
- [Validator](01_state.md#validator)
- [Delegation](01_state.md#delegation)
- [UnbondingDelegation](01_state.md#unbondingdelegation)
- [Redelegation](01_state.md#redelegation)
- [Queues](01_state.md#queues)
- [HistoricalInfo](01_state.md#historicalinfo)
* [Pool](01_state.md#pool)
* [LastTotalPower](01_state.md#lasttotalpower)
* [Params](01_state.md#params)
* [Validator](01_state.md#validator)
* [Delegation](01_state.md#delegation)
* [UnbondingDelegation](01_state.md#unbondingdelegation)
* [Redelegation](01_state.md#redelegation)
* [Queues](01_state.md#queues)
* [HistoricalInfo](01_state.md#historicalinfo)
2. **[State Transitions](02_state_transitions.md)**
- [Validators](02_state_transitions.md#validators)
- [Delegations](02_state_transitions.md#delegations)
- [Slashing](02_state_transitions.md#slashing)
* [Validators](02_state_transitions.md#validators)
* [Delegations](02_state_transitions.md#delegations)
* [Slashing](02_state_transitions.md#slashing)
3. **[Messages](03_messages.md)**
- [MsgCreateValidator](03_messages.md#msgcreatevalidator)
- [MsgEditValidator](03_messages.md#msgeditvalidator)
- [MsgDelegate](03_messages.md#msgdelegate)
- [MsgUndelegate](03_messages.md#msgundelegate)
- [MsgBeginRedelegate](03_messages.md#msgbeginredelegate)
* [MsgCreateValidator](03_messages.md#msgcreatevalidator)
* [MsgEditValidator](03_messages.md#msgeditvalidator)
* [MsgDelegate](03_messages.md#msgdelegate)
* [MsgUndelegate](03_messages.md#msgundelegate)
* [MsgBeginRedelegate](03_messages.md#msgbeginredelegate)
4. **[Begin-Block](04_begin_block.md)**
- [Historical Info Tracking](04_begin_block.md#historical-info-tracking)
* [Historical Info Tracking](04_begin_block.md#historical-info-tracking)
5. **[End-Block](05_end_block.md)**
- [Validator Set Changes](05_end_block.md#validator-set-changes)
- [Queues](05_end_block.md#queues-)
* [Validator Set Changes](05_end_block.md#validator-set-changes)
* [Queues](05_end_block.md#queues-)
6. **[Hooks](06_hooks.md)**
7. **[Events](07_events.md)**
- [EndBlocker](07_events.md#endblocker)
- [Msg's](07_events.md#msg's)
* [EndBlocker](07_events.md#endblocker)
* [Msg's](07_events.md#msg's)
8. **[Parameters](08_params.md)**
x/upgrade/README.md
+1 -1
View File
@@ -4,4 +4,4 @@ order: 0
# Upgrade
- [Upgrade](spec/README.md) - Software upgrades handling and coordination.
* [Upgrade](spec/README.md) - Software upgrades handling and coordination.
x/upgrade/spec/02_state.md
+4 -4
View File
@@ -12,9 +12,9 @@ are stored as big endian `uint64`, and can be accessed with prefix `0x2` appende
by the corresponding module name of type `string`. The state maintains a
`Protocol Version` which can be accessed by key `0x3`.
- Plan: `0x0 -> Plan`
- Done: `0x1 | byte(plan name) -> BigEndian(Block Height)`
- ConsensusVersion: `0x2 | byte(module name) -> BigEndian(Module Consensus Version)`
- ProtocolVersion: `0x3 -> BigEndian(Protocol Version)`
* Plan: `0x0 -> Plan`
* Done: `0x1 | byte(plan name) -> BigEndian(Block Height)`
* ConsensusVersion: `0x2 | byte(module name) -> BigEndian(Module Consensus Version)`
* ProtocolVersion: `0x3 -> BigEndian(Protocol Version)`
The `x/upgrade` module contains no genesis state.
x/upgrade/spec/README.md
+3 -3
View File
@@ -26,6 +26,6 @@ recover from.
2. **[State](02_state.md)**
3. **[Events](03_events.md)**
4. **[Client](04_client.md)**
- [CLI](04_client.md#cli)
- [REST](04_client.md#rest)
- [gRPC](04_client.md#grpc)
* [CLI](04_client.md#cli)
* [REST](04_client.md#rest)
* [gRPC](04_client.md#grpc)