diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 5299384aee29..929c3f51525f 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -443,7 +443,13 @@ html { @apply text-6 font-bold leading-9 tracking-tight; } h3 { - @apply text-4 font-semibold leading-7 tracking-tight; + @apply text-4 font-semibold leading-8 tracking-tight; + } + h4 { + @apply text-3 font-semibold leading-7 tracking-tight; + } + h5 { + @apply text-3 font-semibold leading-6 tracking-wide; } p { @apply leading-relaxed; diff --git a/x/authz/README.md b/x/authz/README.md index ccd335f52780..19780aa9a76f 100644 --- a/x/authz/README.md +++ b/x/authz/README.md @@ -28,9 +28,9 @@ granting arbitrary privileges from one account (the granter) to another account * [gRPC](#grpc) * [REST](#rest) -# Concepts +## Concepts -## Authorization and Grant +### Authorization and Grant The `x/authz` module defines interfaces and messages grant authorizations to perform actions on behalf of one account to other accounts. The design is defined in the [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md). @@ -44,11 +44,11 @@ Authorization is an interface that must be implemented by a concrete authorizati https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/authz/authorizations.go#L11-L25 ``` -## Built-in Authorizations +### Built-in Authorizations The Cosmos SDK `x/authz` module comes with following authorization types: -### GenericAuthorization +#### GenericAuthorization `GenericAuthorization` implements the `Authorization` interface that gives unrestricted permission to execute the provided Msg on behalf of granter's account. @@ -62,7 +62,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/authz/generic_authorization. * `msg` stores Msg type URL. -### SendAuthorization +#### SendAuthorization `SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. It takes a (positive) `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. @@ -76,7 +76,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/bank/types/send_authorizatio * `spend_limit` keeps track of how many coins are left in the authorization. -### StakeAuthorization +#### 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 required `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` or a `DenyList`, which allows you to select which validators you allow or deny grantees to stake with. @@ -88,15 +88,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/a https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/staking/types/authz.go#L15-L35 ``` -## Gas +### Gas In order to prevent DoS attacks, granting `StakeAuthorization`s with `x/authz` incurs gas. `StakeAuthorization` allows you to authorize another account to delegate, undelegate, or redelegate to validators. The authorizer can define a list of validators they allow or deny delegations to. The Cosmos SDK iterates over these lists and charge 10 gas for each validator in both of the lists. Since the state maintaining a list for granter, grantee pair with same expiration, we are iterating over the list to remove the grant (incase of any revoke of paritcular `msgType`) from the list and we are charging 20 gas per iteration. -# State +## State -## Grant +### Grant 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. @@ -108,7 +108,7 @@ The grant object encapsulates an `Authorization` type and an expiration timestam https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/authz/v1beta1/authz.proto#L22-L30 ``` -## GrantQueue +### GrantQueue We are maintaining a queue for authz pruning. Whenever a grant is created, an item will be added to `GrantQueue` with a key of expiration, granter, grantee. @@ -122,11 +122,11 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/authz/keeper/keys.go#L78-L93 The `GrantQueueItem` object contains the list of type urls between granter and grantee that expire at the time indicated in the key. -# Messages +## Messages In this section we describe the processing of messages for the authz module. -## MsgGrant +### MsgGrant 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. @@ -142,7 +142,7 @@ The message handling should fail if: * 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 +### MsgRevoke A grant can be removed with the `MsgRevoke` message. @@ -157,7 +157,7 @@ The message handling should fail if: NOTE: The `MsgExec` message removes a grant if the grant has expired. -## MsgExec +### MsgExec When a grantee wants to execute a transaction on behalf of a granter, they must send `MsgExec`. @@ -171,17 +171,17 @@ The message handling should fail if: * grantee doesn't have permission to run the transaction. * if granted authorization is expired. -# Events +## Events The authz module emits proto events defined in [the Protobuf reference](https://buf.build/cosmos/cosmos-sdk/docs/main/cosmos.authz.v1beta1#cosmos.authz.v1beta1.EventGrant). -# Client +## Client -## CLI +### CLI A user can query and interact with the `authz` module using the CLI. -### Query +#### Query The `query` commands allow users to query `authz` state. @@ -189,7 +189,7 @@ The `query` commands allow users to query `authz` state. simd query authz --help ``` -#### grants +##### grants The `grants` command allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type. @@ -216,7 +216,7 @@ grants: pagination: null ``` -### Transactions +#### Transactions The `tx` commands allow users to interact with the `authz` module. @@ -224,7 +224,7 @@ The `tx` commands allow users to interact with the `authz` module. simd tx authz --help ``` -#### exec +##### exec The `exec` command allows a grantee to execute a transaction on behalf of granter. @@ -238,7 +238,7 @@ Example: simd tx authz exec tx.json --from=cosmos1.. ``` -#### grant +##### grant The `grant` command allows a granter to grant an authorization to a grantee. @@ -252,7 +252,7 @@ Example: simd tx authz grant cosmos1.. send --spend-limit=100stake --from=cosmos1.. ``` -#### revoke +##### revoke The `revoke` command allows a granter to revoke an authorization from a grantee. @@ -266,11 +266,11 @@ Example: simd tx authz revoke cosmos1.. /cosmos.bank.v1beta1.MsgSend --from=cosmos1.. ``` -## gRPC +### gRPC A user can query the `authz` module using gRPC endpoints. -### Grants +#### Grants The `Grants` endpoint allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type. @@ -308,7 +308,7 @@ Example Output: } ``` -## REST +### REST A user can query the `authz` module using REST endpoints. diff --git a/x/capability/README.md b/x/capability/README.md index 34619a004e0b..cdd1c0e70d69 100644 --- a/x/capability/README.md +++ b/x/capability/README.md @@ -77,9 +77,9 @@ func NewApp(...) *App { * [In persisted KV store](#in-persisted-kv-store) * [In-memory KV store](#in-memory-kv-store) -# Concepts +## Concepts -## Capabilities +### Capabilities Capabilities are multi-owner. A scoped keeper can create a capability via `NewCapability` which creates a new unique, unforgeable object-capability reference. The newly @@ -104,14 +104,14 @@ with which the calling module previously associated it. claimed by name. The module is not allowed to retrieve capabilities which it does not own. -## Stores +### Stores * MemStore * KeyStore -# State +## State -## In persisted KV store +### In persisted KV store 1. Global unique capability index 2. Capability owners @@ -121,7 +121,7 @@ Indexes: * Unique index: `[]byte("index") -> []byte(currentGlobalIndex)` * Capability Index: `[]byte("capability_index") | []byte(index) -> ProtocolBuffer(CapabilityOwners)` -## In-memory KV store +### In-memory KV store 1. Initialized flag 2. Mapping between the module and capability tuple and the capability name diff --git a/x/crisis/README.md b/x/crisis/README.md index 7ed4ec41abf8..fa354b59905e 100644 --- a/x/crisis/README.md +++ b/x/crisis/README.md @@ -19,9 +19,9 @@ application initialization process. * [Client](#client) * [CLI](#cli) -# State +## State -## ConstantFee +### ConstantFee Due to the anticipated large gas cost requirement to verify an invariant (and potential to exceed the maximum allowable block gas limit) a constant fee is @@ -34,12 +34,12 @@ it can be updated with governance or the address with authority. * Params: `mint/params -> legacy_amino(sdk.Coin)` -# Messages +## Messages In this section we describe the processing of the crisis messages and the corresponding updates to the state. -## MsgVerifyInvariant +### MsgVerifyInvariant Blockchain invariants can be checked using the `MsgVerifyInvariant` message. @@ -58,13 +58,13 @@ never deducted as the transaction is never committed to a block (equivalent to being refunded). However, if the invariant is not broken, the constant fee will not be refunded. -# Events +## Events The crisis module emits the following events: -## Handlers +### Handlers -### MsgVerifyInvariance +#### MsgVerifyInvariance | Type | Attribute Key | Attribute Value | |-----------|---------------|------------------| @@ -73,7 +73,7 @@ The crisis module emits the following events: | message | action | verify_invariant | | message | sender | {senderAddress} | -# Parameters +## Parameters The crisis module contains the following parameters: @@ -81,13 +81,13 @@ The crisis module contains the following parameters: |-------------|---------------|-----------------------------------| | ConstantFee | object (coin) | {"denom":"uatom","amount":"1000"} | -# Client +## Client -## CLI +### CLI A user can query and interact with the `crisis` module using the CLI. -### Transactions +#### Transactions The `tx` commands allow users to interact with the `crisis` module. @@ -95,7 +95,7 @@ The `tx` commands allow users to interact with the `crisis` module. simd tx crisis --help ``` -#### invariant-broken +##### invariant-broken The `invariant-broken` command submits proof when an invariant was broken to halt the chain diff --git a/x/distribution/README.md b/x/distribution/README.md index 56d1f24b31ff..df29ec99720d 100644 --- a/x/distribution/README.md +++ b/x/distribution/README.md @@ -94,7 +94,7 @@ to set up a script to periodically withdraw and rebond rewards. * [CLI](#cli) * [gRPC](#grpc) -# Concepts +## Concepts In Proof of Stake (PoS) blockchains, rewards gained from transaction fees are paid to validators. The fee distribution module fairly distributes the rewards to the validators' constituent delegators. @@ -108,7 +108,7 @@ The commission is calculated and incremented at every `BeginBlock` operation to The rewards to a delegator are distributed when the delegation is changed or removed, or a withdrawal is requested. Before rewards are distributed, all slashes to the validator that occurred during the current delegation are applied. -## Reference Counting in F1 Fee Distribution +### Reference Counting in F1 Fee Distribution In F1 fee distribution, the rewards a delegator receives are calculated when their delegation is withdrawn. This calculation must read the terms of the summation of rewards divided by the share of tokens from the period which they ended when they delegated, and the final period that was created for the withdrawal. @@ -125,9 +125,9 @@ is created which might need to reference the historical record, the reference co Each time one object which previously needed to reference the historical record is deleted, the reference count is decremented. If the reference count hits zero, the historical record is deleted. -# State +## State -## FeePool +### FeePool All globally tracked parameters for distribution are stored within `FeePool`. Rewards are collected and added to the reward pool and @@ -154,7 +154,7 @@ type DecCoin struct { https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/distribution/v1beta1/distribution.proto#L92-L96 ``` -## Validator Distribution +### Validator Distribution Validator distribution information for the relevant validator is updated each time: @@ -172,7 +172,7 @@ type ValidatorDistInfo struct { } ``` -## Delegation Distribution +### Delegation Distribution Each delegation distribution only needs to record the height at which it last withdrew fees. Because a delegation must withdraw fees each time it's @@ -188,7 +188,7 @@ type DelegationDistInfo struct { } ``` -## Params +### Params The distribution module stores it's params in state with the prefix of `0x09`, it can be updated with governance or the address with authority. @@ -199,7 +199,7 @@ it can be updated with governance or the address with authority. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/distribution/v1beta1/distribution.proto#L11-L30 ``` -# Begin Block +## Begin Block At each `BeginBlock`, all fees received in the previous block are transferred to the distribution `ModuleAccount` account. When a delegator or validator @@ -209,7 +209,7 @@ block, the different claims on the fees collected are updated as follows: * The reserve community tax is charged. * The remainder is distributed proportionally by voting power to all bonded validators -## The Distribution Scheme +### The Distribution Scheme See [params](#params) for description of parameters. @@ -221,13 +221,13 @@ rewards each account is entitled to are stored, and withdrawals can be triggered through the messages `FundCommunityPool`, `WithdrawValidatorCommission` and `WithdrawDelegatorReward`. -### Reward to the Community Pool +#### Reward to the Community Pool The community pool gets `community_tax * fees`, plus any remaining dust after validators get their rewards that are always rounded down to the nearest integer value. -### Reward To the Validators +#### Reward To the Validators The proposer receives no extra rewards. All fees are distributed among all the bonded validators, including the proposer, in proportion to their consensus power. @@ -239,7 +239,7 @@ voteMul = 1 - community_tax All validators receive `fees * voteMul * powFrac`. -### Rewards to Delegators +#### Rewards to Delegators Each validator's rewards are distributed to its delegators. The validator also has a self-delegation that is treated like a regular delegation in @@ -253,7 +253,7 @@ The outstanding rewards that the operator is entitled to are stored in to are stored in `ValidatorCurrentRewards`. The [F1 fee distribution scheme](#concepts) is used to calculate the rewards per delegator as they withdraw or update their delegation, and is thus not handled in `BeginBlock`. -### Example Distribution +#### Example Distribution For this example distribution, the underlying consensus engine selects block proposers in proportion to their power relative to the entire bonded power. @@ -270,9 +270,9 @@ the total rewards. Consequently, the reward for a single delegator is: community tax rate) * (1 - validator commission rate) ``` -# Messages +## Messages -## MsgSetWithdrawAddress +### MsgSetWithdrawAddress By default, the withdraw address is the delegator address. To change its withdraw address, a delegator must send a `MsgSetWithdrawAddress` message. Changing the withdraw address is possible only if the parameter `WithdrawAddrEnabled` is set to `true`. @@ -298,7 +298,7 @@ func (k Keeper) SetWithdrawAddr(ctx sdk.Context, delegatorAddr sdk.AccAddress, w k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr) ``` -## MsgWithdrawDelegatorReward +### MsgWithdrawDelegatorReward A delegator can withdraw its rewards. Internally in the distribution module, this transaction simultaneously removes the previous delegation with associated rewards, the same as if the delegator simply started a new delegation of the same value. @@ -337,14 +337,14 @@ Response: https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/distribution/v1beta1/tx.proto#L46-L56 ``` -## WithdrawValidatorCommission +### WithdrawValidatorCommission The validator can send the WithdrawValidatorCommission message to withdraw their accumulated commission. The commission is calculated in every block during `BeginBlock`, so no iteration is required to withdraw. The amount withdrawn is deducted from the `ValidatorOutstandingRewards` variable for the validator. Only integer amounts can be sent. If the accumulated awards have decimals, the amount is truncated before the withdrawal is sent, and the remainder is left to be withdrawn later. -## FundCommunityPool +### FundCommunityPool This message sends coins directly from the sender to the community pool. @@ -364,11 +364,11 @@ func (k Keeper) FundCommunityPool(ctx sdk.Context, amount sdk.Coins, sender sdk. } ``` -## Common distribution operations +### Common distribution operations These operations take place during many different messages. -### Initialize delegation +#### Initialize delegation Each time a delegation is changed, the rewards are withdrawn and the delegation is reinitialized. Initializing a delegation increments the validator period and keeps track of the starting period of the delegation. @@ -393,7 +393,7 @@ func (k Keeper) initializeDelegation(ctx sdk.Context, val sdk.ValAddress, del sd } ``` -## MsgUpdateParams +### MsgUpdateParams Distribution module params can be updated through `MsgUpdateParams`, which can be done using governance proposal and the signer will always be gov module account address. @@ -405,15 +405,15 @@ The message handling can fail if: * signer is not the gov module account address. -# Hooks +## Hooks Available hooks that can be called by and from this module. -## Create or modify delegation distribution +### Create or modify delegation distribution * triggered-by: `staking.MsgDelegate`, `staking.MsgBeginRedelegate`, `staking.MsgUndelegate` -### Before +#### Before * The delegation rewards are withdrawn to the withdraw address of the delegator. The rewards include the current period and exclude the starting period. @@ -421,12 +421,12 @@ Available hooks that can be called by and from this module. 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. -### After +#### After The starting height of the delegation is set to the previous period. Because of the `Before`-hook, this period is the last period for which the delegator was rewarded. -## Validator created +### Validator created * triggered-by: `staking.MsgCreateValidator` @@ -440,7 +440,7 @@ When a validator is created, the following validator variables are initialized: By default, all values are set to a `0`, except period, which is set to `1`. -## Validator removed +### Validator removed * triggered-by: `staking.RemoveValidator` @@ -451,7 +451,7 @@ Note: The validator gets removed only when it has no remaining delegations. At that time, all outstanding delegator rewards will have been withdrawn. Any remaining rewards are dust amounts. -## Validator is slashed +### Validator is slashed * triggered-by: `staking.Slash` @@ -461,11 +461,11 @@ Any remaining rewards are dust amounts. * The slash event is stored for later use. The slash event will be referenced when calculating delegator rewards. -# Events +## Events The distribution module emits the following events: -## BeginBlocker +### BeginBlocker | Type | Attribute Key | Attribute Value | |-----------------|---------------|--------------------| @@ -476,9 +476,9 @@ The distribution module emits the following events: | rewards | amount | {rewardAmount} | | rewards | validator | {validatorAddress} | -## Handlers +### Handlers -### MsgSetWithdrawAddress +#### MsgSetWithdrawAddress | Type | Attribute Key | Attribute Value | |----------------------|------------------|----------------------| @@ -487,7 +487,7 @@ The distribution module emits the following events: | message | action | set_withdraw_address | | message | sender | {senderAddress} | -### MsgWithdrawDelegatorReward +#### MsgWithdrawDelegatorReward | Type | Attribute Key | Attribute Value | |---------|---------------|---------------------------| @@ -497,7 +497,7 @@ The distribution module emits the following events: | message | action | withdraw_delegator_reward | | message | sender | {senderAddress} | -### MsgWithdrawValidatorCommission +#### MsgWithdrawValidatorCommission | Type | Attribute Key | Attribute Value | |------------|---------------|-------------------------------| @@ -506,7 +506,7 @@ The distribution module emits the following events: | message | action | withdraw_validator_commission | | message | sender | {senderAddress} | -# Parameters +## Parameters The distribution module contains the following parameters: @@ -520,13 +520,13 @@ The distribution module contains the following parameters: * [0] `communitytax`, `baseproposerreward` and `bonusproposerreward` must be positive and their sum cannot exceed 1.00. -# Client +## Client ## CLI A user can query and interact with the `distribution` module using the CLI. -### Query +#### Query The `query` commands allow users to query `distribution` state. @@ -534,7 +534,7 @@ The `query` commands allow users to query `distribution` state. simd query distribution --help ``` -#### commission +##### commission The `commission` command allows users to query validator commission rewards by address. @@ -556,7 +556,7 @@ commission: denom: stake ``` -#### community-pool +##### community-pool The `community-pool` command allows users to query all coin balances within the community pool. @@ -578,7 +578,7 @@ pool: denom: stake ``` -#### params +##### params The `params` command allows users to query the parameters of the `distribution` module. @@ -601,7 +601,7 @@ community_tax: "0.020000000000000000" withdraw_addr_enabled: true ``` -#### rewards +##### rewards The `rewards` command allows users to query delegator rewards. Users can optionally include the validator address to query rewards earned from a specific validator. @@ -628,7 +628,7 @@ total: denom: stake ``` -#### slashes +##### slashes The `slashes` command allows users to query all slashes for a given block range. @@ -653,7 +653,7 @@ slashes: fraction: "0.009999999999999999" ``` -#### validator-outstanding-rewards +##### validator-outstanding-rewards The `validator-outstanding-rewards` command allows users to query all outstanding (un-withdrawn) rewards for a validator and all their delegations. @@ -675,7 +675,7 @@ rewards: denom: stake ``` -### Transactions +#### Transactions The `tx` commands allow users to interact with the `distribution` module. @@ -683,7 +683,7 @@ The `tx` commands allow users to interact with the `distribution` module. simd tx distribution --help ``` -#### fund-community-pool +##### fund-community-pool The `fund-community-pool` command allows users to send funds to the community pool. @@ -697,7 +697,7 @@ Example: simd tx distribution fund-community-pool 100stake --from cosmos1.. ``` -#### set-withdraw-addr +##### set-withdraw-addr The `set-withdraw-addr` command allows users to set the withdraw address for rewards associated with a delegator address. @@ -711,7 +711,7 @@ Example: simd tx distribution set-withdraw-addr cosmos1.. --from cosmos1.. ``` -#### withdraw-all-rewards +##### withdraw-all-rewards The `withdraw-all-rewards` command allows users to withdraw all rewards for a delegator. @@ -725,7 +725,7 @@ Example: simd tx distribution withdraw-all-rewards --from cosmos1.. ``` -#### withdraw-rewards +##### withdraw-rewards 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. @@ -740,11 +740,11 @@ Example: simd tx distribution withdraw-rewards cosmosvaloper1.. --from cosmos1.. --commision ``` -## gRPC +### gRPC A user can query the `distribution` module using gRPC endpoints. -### Params +#### Params The `Params` endpoint allows users to query parameters of the `distribution` module. @@ -769,7 +769,7 @@ Example Output: } ``` -### ValidatorOutstandingRewards +#### ValidatorOutstandingRewards The `ValidatorOutstandingRewards` endpoint allows users to query rewards of a validator address. @@ -797,7 +797,7 @@ Example Output: } ``` -### ValidatorCommission +#### ValidatorCommission The `ValidatorCommission` endpoint allows users to query accumulated commission for a validator. @@ -825,7 +825,7 @@ Example Output: } ``` -### ValidatorSlashes +#### ValidatorSlashes The `ValidatorSlashes` endpoint allows users to query slash events of a validator. @@ -854,7 +854,7 @@ Example Output: } ``` -### DelegationRewards +#### DelegationRewards The `DelegationRewards` endpoint allows users to query the total rewards accrued by a delegation. @@ -880,7 +880,7 @@ Example Output: } ``` -### DelegationTotalRewards +#### DelegationTotalRewards The `DelegationTotalRewards` endpoint allows users to query the total rewards accrued by each validator. @@ -917,7 +917,7 @@ Example Output: } ``` -### DelegatorValidators +#### DelegatorValidators The `DelegatorValidators` endpoint allows users to query all validators for given delegator. @@ -940,7 +940,7 @@ Example Output: } ``` -### DelegatorWithdrawAddress +#### DelegatorWithdrawAddress The `DelegatorWithdrawAddress` endpoint allows users to query the withdraw address of a delegator. @@ -961,7 +961,7 @@ Example Output: } ``` -### CommunityPool +#### CommunityPool The `CommunityPool` endpoint allows users to query the community pool coins. diff --git a/x/evidence/README.md b/x/evidence/README.md index 0c28554593ee..ce74a2f5171b 100644 --- a/x/evidence/README.md +++ b/x/evidence/README.md @@ -36,9 +36,9 @@ Each corresponding handler must also fulfill the `Handler` interface contract. T `Handler` for a given `Evidence` type can perform any arbitrary state transitions such as slashing, jailing, and tombstoning. -# Concepts +## Concepts -## Evidence +### Evidence Any concrete type of evidence submitted to the `x/evidence` module must fulfill the `Evidence` contract outlined below. Not all concrete types of evidence will fulfill @@ -78,7 +78,7 @@ type ValidatorEvidence interface { } ``` -## Registration & Handling +### Registration & Handling The `x/evidence` module must first know about all types of evidence it is expected to handle. This is accomplished by registering the `Route` method in the `Evidence` @@ -112,7 +112,7 @@ type Handler func(sdk.Context, Evidence) error ``` -# State +## State Currently the `x/evidence` module only stores valid submitted `Evidence` in state. The evidence state is also stored and exported in the `x/evidence` module's `GenesisState`. @@ -129,9 +129,9 @@ message GenesisState { All `Evidence` is retrieved and stored via a prefix `KVStore` using prefix `0x00` (`KeyPrefixEvidence`). -# Messages +## Messages -## MsgSubmitEvidence +### MsgSubmitEvidence Evidence is submitted through a `MsgSubmitEvidence` message: @@ -182,13 +182,13 @@ type. Secondly, the `Evidence` is routed to the `Handler` and executed. Finally, if there is no error in handling the `Evidence`, an event is emitted and it is persisted to state. -# Events +## Events The `x/evidence` module emits the following events: -## Handlers +### Handlers -### MsgSubmitEvidence +#### MsgSubmitEvidence | Type | Attribute Key | Attribute Value | | --------------- | ------------- | --------------- | @@ -198,19 +198,19 @@ The `x/evidence` module emits the following events: | message | action | submit_evidence | -# Parameters +## Parameters The evidence module does not contain any parameters. -# BeginBlock +## BeginBlock -## Evidence Handling +### Evidence Handling Tendermint blocks can include [Evidence](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/blockchain.md#evidence) that indicates if a validator committed malicious behavior. The relevant information is forwarded to the application as ABCI Evidence in `abci.RequestBeginBlock` so that the validator can be punished accordingly. -### Equivocation +#### Equivocation The Cosmos SDK handles two types of evidence inside the ABCI `BeginBlock`: @@ -251,13 +251,13 @@ https://github.com/cosmos/cosmos-sdk/blob/83260b0c2f9afcc7ec94a102f83906e8e56ef1 that emits informative events and finally delegates calls to the `x/staking` module. See documentation on slashing and jailing in [State Transitions](../staking/README.md#state-transitions). -# Client +## Client -## CLI +### CLI A user can query and interact with the `evidence` module using the CLI. -### Query +#### Query The `query` commands allows users to query `evidence` state. @@ -265,7 +265,7 @@ The `query` commands allows users to query `evidence` state. simd query evidence --help ``` -### evidence +#### evidence The `evidence` command allows users to list all evidence or evidence by hash. @@ -314,16 +314,16 @@ pagination: total: "1" ``` -## REST +### REST A user can query the `evidence` module using REST endpoints. -### Evidence +#### Evidence Get evidence by hash ```bash -/cosmos/evidence/v1beta1/evidence/{evidence_hash} +/cosmos/evidence/v1beta1/evidence/{hash} ``` Example: @@ -345,7 +345,7 @@ Example Output: } ``` -### All evidence +#### All evidence Get all evidence @@ -377,11 +377,11 @@ Example Output: } ``` -## gRPC +### gRPC A user can query the `evidence` module using gRPC endpoints. -### Evidence +#### Evidence Get evidence by hash @@ -408,7 +408,7 @@ Example Output: } ``` -### All evidence +#### All evidence Get all evidence diff --git a/x/feegrant/README.md b/x/feegrant/README.md index b36b96a1dd73..cd0ab7aac55d 100644 --- a/x/feegrant/README.md +++ b/x/feegrant/README.md @@ -28,9 +28,9 @@ This module allows accounts to grant fee allowances and to use fees from their a * [CLI](#cli) * [gRPC](#grpc) -# Concepts +## Concepts -## Grant +### Grant `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. @@ -44,7 +44,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/feegrant/v1beta1/ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/feegrant/fees.go#L9-L32 ``` -## Fee Allowance types +### Fee Allowance types There are two types of fee allowances present at the moment: @@ -52,7 +52,7 @@ There are two types of fee allowances present at the moment: * `PeriodicAllowance` * `AllowedMsgAllowance` -## BasicAllowance +### 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. @@ -66,7 +66,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/feegrant/v1beta1/ * 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 coins from `granter` and it won't have any expiration. The only way to restrict the `grantee` is by revoking the grant. -## PeriodicAllowance +### 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. @@ -84,7 +84,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/feegrant/v1beta1/ * `period_reset` keeps track of when a next period reset should happen. -## AllowedMsgAllowance +### AllowedMsgAllowance `AllowedMsgAllowance` is a fee allowance, it can be any of `BasicFeeAllowance`, `PeriodicAllowance` but restricted only to the allowed messages mentioned by the granter. @@ -96,7 +96,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/feegrant/v1beta1/ * `allowed_messages` is array of messages allowed to execute the given allowance. -## FeeGranter flag +### 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. @@ -122,24 +122,24 @@ Example cmd: ./simd tx gov submit-proposal --title="Test Proposal" --description="My awesome proposal" --type="Text" --from validator-key --fee-granter=cosmos1xh44hxt7spr67hqaa7nyx5gnutrz5fraw6grxn --chain-id=testnet --fees="10stake" ``` -## Granted Fee Deductions +### Granted Fee Deductions Fees are deducted from grants in the `x/auth` ante handler. To learn more about how ante handlers work, read the [Auth Module AnteHandlers Guide](../auth/README.md#antehandlers). -## Gas +### Gas In order to prevent DoS attacks, using a filtered `x/feegrant` incurs gas. The SDK must assure that the `grantee`'s transactions all conform to the filter set by the `granter`. The SDK does this by iterating over the allowed messages in the filter and charging 10 gas per filtered message. The SDK will then iterate over the messages being sent by the `grantee` to ensure the messages adhere to the filter, also charging 10 gas per message. The SDK will stop iterating and fail the transaction if it finds a message that does not conform to the filter. **WARNING**: The gas is charged against the granted allowance. Ensure your messages conform to the filter, if any, before sending transactions using your allowance. -## Pruning +### 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. -# State +## State -## FeeAllowance +### FeeAllowance Fee Allowances are identified by combining `Grantee` (the account address of fee allowance grantee) with the `Granter` (the account address of fee allowance granter). @@ -151,7 +151,7 @@ Fee allowance grants are stored in the state as follows: https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/feegrant/feegrant.pb.go#L221-L229 ``` -## FeeAllowanceQueue +### FeeAllowanceQueue Fee Allowances queue items are identified by combining the `FeeAllowancePrefixQueue` (i.e., 0x01), `expiration`, `grantee` (the account address of fee allowance grantee), `granter` (the account address of fee allowance granter). Endblocker checks `FeeAllowanceQueue` state for the expired grants and prunes them from `FeeAllowance` if there are any found. @@ -159,9 +159,9 @@ 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` -# Messages +## Messages -## Msg/GrantAllowance +### Msg/GrantAllowance A fee allowance grant will be created with the `MsgGrantAllowance` message. @@ -169,7 +169,7 @@ A fee allowance grant will be created with the `MsgGrantAllowance` message. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/feegrant/v1beta1/tx.proto#L23-L36 ``` -## Msg/RevokeAllowance +### Msg/RevokeAllowance An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` message. @@ -177,13 +177,13 @@ An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` mess https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/feegrant/v1beta1/tx.proto#L41-L50 ``` -# Events +## Events The feegrant module emits the following events: -# Msg Server +## Msg Server -## MsgGrantAllowance +### MsgGrantAllowance | Type | Attribute Key | Attribute Value | | ------- | ------------- | ---------------- | @@ -191,7 +191,7 @@ The feegrant module emits the following events: | message | granter | {granterAddress} | | message | grantee | {granteeAddress} | -## MsgRevokeAllowance +### MsgRevokeAllowance | Type | Attribute Key | Attribute Value | | ------- | ------------- | ---------------- | @@ -199,7 +199,7 @@ The feegrant module emits the following events: | message | granter | {granterAddress} | | message | grantee | {granteeAddress} | -## Exec fee allowance +### Exec fee allowance | Type | Attribute Key | Attribute Value | | ------- | ------------- | ---------------- | @@ -207,13 +207,13 @@ The feegrant module emits the following events: | message | granter | {granterAddress} | | message | grantee | {granteeAddress} | -# Client +## Client -## CLI +### CLI A user can query and interact with the `feegrant` module using the CLI. -### Query +#### Query The `query` commands allow users to query `feegrant` state. @@ -221,7 +221,7 @@ The `query` commands allow users to query `feegrant` state. simd query feegrant --help ``` -#### grant +##### grant The `grant` command allows users to query a grant for a given granter-grantee pair. @@ -248,7 +248,7 @@ grantee: cosmos1.. granter: cosmos1.. ``` -#### grants +##### grants The `grants` command allows users to query all grants for a given grantee. @@ -279,7 +279,7 @@ pagination: total: "0" ``` -### Transactions +#### Transactions The `tx` commands allow users to interact with the `feegrant` module. @@ -287,7 +287,7 @@ The `tx` commands allow users to interact with the `feegrant` module. simd tx feegrant --help ``` -#### grant +##### grant 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. @@ -307,7 +307,7 @@ Example (periodic spend limit): simd tx feegrant grant cosmos1.. cosmos1.. --period 3600 --period-limit 10stake ``` -#### revoke +##### revoke The `revoke` command allows users to revoke a granted fee allowance. @@ -321,11 +321,11 @@ Example: simd tx feegrant revoke cosmos1.. cosmos1.. ``` -## gRPC +### gRPC A user can query the `feegrant` module using gRPC endpoints. -### Allowance +#### Allowance The `Allowance` endpoint allows users to query a granted fee allowance. @@ -354,7 +354,7 @@ Example Output: } ``` -### Allowances +#### Allowances The `Allowances` endpoint allows users to query all granted fee allowances for a given grantee. diff --git a/x/gov/README.md b/x/gov/README.md index 0d625bf601ea..15ea845bcc06 100644 --- a/x/gov/README.md +++ b/x/gov/README.md @@ -32,32 +32,15 @@ The following specification uses *ATOM* as the native staking token. The module can be adapted to any Proof-Of-Stake blockchain by replacing *ATOM* with the native staking token of the chain. + * [Concepts](#concepts) * [Proposal submission](#proposal-submission) - * [Right to submit a proposal](#right-to-submit-a-proposal) - * [Proposal Messages](#proposal-messages) * [Deposit](#deposit) - * [Deposit refund and burn](#deposit-refund-and-burn) * [Vote](#vote) - * [Participants](#participants) - * [Voting period](#voting-period) - * [Option set](#option-set) - * [Weighted Votes](#weighted-votes) - * [Quorum](#quorum) - * [Threshold](#threshold) - * [Inheritance](#inheritance) - * [Validator’s punishment for non-voting](#validators-punishment-for-non-voting) - * [Governance address](#governance-address) * [Software Upgrade](#software-upgrade) - * [Signal](#signal) - * [Switch](#switch) * [State](#state) * [Proposals](#proposals) - * [Writing a module that uses governance](#writing-a-module-that-uses-governance) * [Parameters and base types](#parameters-and-base-types) - * [DepositParams](#depositparams) - * [VotingParams](#votingparams) - * [TallyParams](#tallyparams) * [Deposit](#deposit-1) * [ValidatorGovInfo](#validatorgovinfo) * [Stores](#stores) @@ -70,56 +53,18 @@ staking token of the chain. * [Events](#events) * [EndBlocker](#endblocker) * [Handlers](#handlers) - * [MsgSubmitProposal](#msgsubmitproposal) - * [MsgVote](#msgvote) - * [MsgVoteWeighted](#msgvoteweighted) - * [MsgDeposit](#msgdeposit) -* [Future Improvements](#future-improvements) * [Parameters](#parameters) * [SubKeys](#subkeys) * [Client](#client) * [CLI](#cli) - * [Query](#query) - * [deposit](#deposit-3) - * [deposits](#deposits) - * [param](#param) - * [params](#params) - * [proposal](#proposal) - * [proposals](#proposals-1) - * [proposer](#proposer) - * [tally](#tally) - * [vote](#vote-2) - * [votes](#votes) - * [Transactions](#transactions) - * [deposit](#deposit-4) - * [draft-proposal](#draft-proposal) - * [submit-proposal](#submit-proposal) - * [submit-legacy-proposal](#submit-legacy-proposal) - * [vote](#vote-3) - * [weighted-vote](#weighted-vote) * [gRPC](#grpc) - * [Proposal](#proposal-1) - * [Proposals](#proposals-2) - * [Vote](#vote-4) - * [Votes](#votes-1) - * [Params](#params-1) - * [Deposit](#deposit-5) - * [deposits](#deposits-1) - * [TallyResult](#tallyresult) * [REST](#rest) - * [proposal](#proposal-2) - * [proposals](#proposals-3) - * [voter vote](#voter-vote) - * [votes](#votes-2) - * [params](#params-2) - * [deposits](#deposits-2) - * [proposal deposits](#proposal-deposits) - * [tally](#tally-1) * [Metadata](#metadata) * [Proposal](#proposal-3) * [Vote](#vote-5) +* [Future Improvements](#future-improvements) -# Concepts +## Concepts *Disclaimer: This is work in progress. Mechanisms are susceptible to change.* @@ -133,14 +78,14 @@ The governance process is divided in a few steps that are outlined below: * **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 +### Proposal submission -### Right to submit a proposal +#### Right to submit a proposal Every account can submit proposals by sending a `MsgSubmitProposal` transaction. Once a proposal is submitted, it is identified by its unique `proposalID`. -### Proposal Messages +#### Proposal Messages A proposal includes an array of `sdk.Msg`s which are executed automatically if the proposal passes. The messages are executed by the governance `ModuleAccount` itself. Modules @@ -150,7 +95,7 @@ module the right to execute the message once a quorum has been reached. The gove module uses the `MsgServiceRouter` to check that these messages are correctly constructed and have a respective path to execute on but do not perform a full validity check. -## Deposit +### Deposit To prevent spam, proposals must be submitted with a deposit in the coins defined by the `MinDeposit` param. @@ -170,7 +115,7 @@ submission) before the deposit end time, the proposal will be moved into the The deposit is kept in escrow and held by the governance `ModuleAccount` until the proposal is finalized (passed or rejected). -### Deposit refund and burn +#### Deposit refund and burn When a proposal is finalized, the coins from the deposit are either refunded or burned according to the final tally of the proposal: @@ -184,9 +129,9 @@ according to the final tally of the proposal: * All refunded or burned deposits are removed from the state. Events are issued when burning or refunding a deposit. -## Vote +### Vote -### Participants +#### Participants *Participants* are users that have the right to vote on proposals. On the Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and @@ -206,7 +151,7 @@ before a proposal entered voting period and other Atoms to validator B after proposal entered voting period, only the vote under validator B will be forbidden. -### Voting period +#### Voting period Once a proposal reaches `MinDeposit`, it immediately enters `Voting period`. We define `Voting period` as the interval between the moment the vote opens and @@ -214,7 +159,7 @@ the moment the vote closes. `Voting period` should always be shorter than `Unbonding period` to prevent double voting. The initial value of `Voting period` is 2 weeks. -### Option set +#### Option set The option set of a proposal refers to the set of choices a participant can choose from when casting its vote. @@ -230,10 +175,9 @@ The initial option set includes the following options: allows voters to signal that they do not intend to vote in favor or against the proposal but accept the result of the vote. -_Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’ -option that casts a `NoWithVeto` vote._ +*Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’ option that casts a `NoWithVeto` vote.* -### Weighted Votes +#### Weighted Votes [ADR-037](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-037-gov-split-vote.md) introduces the weighted vote feature which allows a staker to split their votes into several voting options. For example, it could use 70% of its voting power to vote Yes and 30% of its voting power to vote No. @@ -256,7 +200,7 @@ For a weighted vote to be valid, the `options` field must not contain duplicate Quorum is defined as the minimum percentage of voting power that needs to be cast on a proposal for the result to be valid. -### Threshold +#### Threshold Threshold is defined as the minimum proportion of `Yes` votes (excluding `Abstain` votes) for the proposal to be accepted. @@ -275,7 +219,7 @@ This means that proposals are accepted iff: * The proportion of `Yes` votes, excluding `Abstain` votes, at the end of the voting period is superior to 1/2. -### Inheritance +#### Inheritance If a delegator does not vote, it will inherit its validator vote. @@ -286,35 +230,34 @@ If a delegator does not vote, it will inherit its validator vote. 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. Because as little as 1/3 + 1 validation power could collude to censor transactions, non-collusion is already assumed for ranges exceeding this threshold. -### Validator’s punishment for non-voting +#### Validator’s punishment for non-voting At present, validators are not punished for failing to vote. -### Governance address +#### Governance address Later, we may add permissioned keys that could only sign txs from certain modules. For the MVP, the `Governance address` will be the main validator address generated at account creation. This address corresponds to a different PrivKey than the Tendermint PrivKey which is responsible for signing consensus messages. Validators thus do not have to sign governance transactions with the sensitive Tendermint PrivKey. -## Software Upgrade +### Software Upgrade If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade their software to the new version that was voted. This process is divided into two steps: -### Signal +#### Signal After a `SoftwareUpgradeProposal` is accepted, validators are expected to download and install the new version of the software while continuing to run the previous version. Once a validator has downloaded and installed the upgrade, it will start signaling to the network that it is ready to switch by -including the proposal's `proposalID` in its *precommits*.(_Note: Confirmation -that we want it in the precommit?_) +including the proposal's `proposalID` in its *precommits*. (*Note: Confirmation that we want it in the precommit?*) Note: There is only one signal slot per *precommit*. If several `SoftwareUpgradeProposals` are accepted in a short timeframe, a pipeline will form and they will be implemented one after the other in the order that they were accepted. -### Switch +#### Switch Once a block contains more than 2/3rd *precommits* where a common `SoftwareUpgradeProposal` is signaled, all the nodes (including validator @@ -323,9 +266,9 @@ new version of the software. Validators and full nodes can use an automation tool, such as [Cosmovisor](https://github.com/cosmos/cosmos-sdk/blob/main/tools/cosmovisor/README.md), for automatically switching version of the chain. -# State +## State -## Proposals +### Proposals `Proposal` objects are used to tally votes and generally track the proposal's state. They contain an array of arbitrary `sdk.Msg`'s which the governance module will attempt @@ -362,7 +305,7 @@ This makes it far easier for clients to support multiple networks. The metadata has a maximum length that is chosen by the app developer, and passed into the gov keeper as a config. The default maximum length in the SDK is 255 characters. -### Writing a module that uses governance +#### Writing a module that uses governance There are many aspects of a chain, or of the individual modules that you may want to use governance to perform such as changing various parameters. This is very simple @@ -372,26 +315,26 @@ governance module account: `govKeeper.GetGovernanceAccount().GetAddress()`. Then the methods in the `msg_server.go`, perform a check on the message that the signer matches `authority`. This will prevent any user from executing that message. -## Parameters and base types +### Parameters and base types `Parameters` define the rules according to which votes are run. There can only be one active parameter set at any given time. If governance wants to change a parameter set, either to modify a value or add/remove a parameter field, a new parameter set has to be created and the previous one rendered inactive. -### DepositParams +#### DepositParams ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/gov/v1/gov.proto#L102-L112 ``` -### VotingParams +#### VotingParams ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/gov/v1/gov.proto#L114-L118 ``` -### TallyParams +#### TallyParams ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/gov/v1/gov.proto#L120-L132 @@ -431,13 +374,13 @@ const ( ) ``` -## Deposit +### Deposit ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/gov/v1/gov.proto#L34-L40 ``` -## ValidatorGovInfo +### ValidatorGovInfo This type is used in a temp map when tallying @@ -468,7 +411,7 @@ For pseudocode purposes, here are the two function we will use to read or write * `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 +### Proposal Processing Queue **Store:** @@ -541,7 +484,7 @@ And the pseudocode for the `ProposalProcessingQueue`: store(Governance, , proposal) ``` -## Legacy Proposal +### Legacy Proposal A legacy proposal is the old implementation of governance proposal. Contrary to proposal that can contain any messages, a legacy proposal allows to submit a set of pre-defined proposals. @@ -551,9 +494,9 @@ While proposals should use the new implementation of the governance proposal, we More information on how to submit proposals in the [client section](#client). -# Messages +## Messages -## Proposal Submission +### Proposal Submission Proposals can be submitted by any account via a `MsgSubmitProposal` transaction. @@ -623,7 +566,7 @@ upon receiving txGovSubmitProposal from sender do return proposalID ``` -## Deposit +### Deposit Once a proposal is submitted, if `Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send @@ -691,7 +634,7 @@ upon receiving txGovDeposit from sender do store(Proposals, , proposal) ``` -## Vote +### Vote Once `ActiveParam.MinDeposit` is reached, voting period starts. From there, bonded Atom holders are able to send `MsgVote` transactions to cast their @@ -737,11 +680,11 @@ handled: store(Governance, , txGovVote.Vote) // Voters can vote multiple times. Re-voting overrides previous vote. This is ok because tallying is done once at the end. ``` -# Events +## Events The governance module emits the following events: -## EndBlocker +### EndBlocker | Type | Attribute Key | Attribute Value | | ----------------- | --------------- | ---------------- | @@ -750,9 +693,9 @@ The governance module emits the following events: | active_proposal | proposal_id | {proposalID} | | active_proposal | proposal_result | {proposalResult} | -## Handlers +### Handlers -### MsgSubmitProposal +#### MsgSubmitProposal | Type | Attribute Key | Attribute Value | | ------------------- | ------------------- | --------------- | @@ -766,7 +709,7 @@ The governance module emits the following events: * [0] Event only emitted if the voting period starts during the submission. -### MsgVote +#### MsgVote | Type | Attribute Key | Attribute Value | | ------------- | ------------- | --------------- | @@ -776,7 +719,7 @@ The governance module emits the following events: | message | action | vote | | message | sender | {senderAddress} | -### MsgVoteWeighted +#### MsgVoteWeighted | Type | Attribute Key | Attribute Value | | ------------- | ------------- | ------------------------ | @@ -786,7 +729,7 @@ The governance module emits the following events: | message | action | vote | | message | sender | {senderAddress} | -### MsgDeposit +#### MsgDeposit | Type | Attribute Key | Attribute Value | | -------------------- | ------------------- | --------------- | @@ -799,34 +742,7 @@ The governance module emits the following events: * [0] Event only emitted if the voting period starts during the submission. -# Future Improvements - -The current documentation only describes the minimum viable product for the -governance module. Future improvements may include: - -* **`BountyProposals`:** If accepted, a `BountyProposal` creates an open - bounty. The `BountyProposal` specifies how many Atoms will be given upon - completion. These Atoms will be taken from the `reserve pool`. After a - `BountyProposal` is accepted by governance, anybody can submit a - `SoftwareUpgradeProposal` with the code to claim the bounty. Note that once a - `BountyProposal` is accepted, the corresponding funds in the `reserve pool` - are locked so that payment can always be honored. In order to link a - `SoftwareUpgradeProposal` to an open bounty, the submitter of the - `SoftwareUpgradeProposal` will use the `Proposal.LinkedProposal` attribute. - If a `SoftwareUpgradeProposal` linked to an open bounty is accepted by - governance, the funds that were reserved are automatically transferred to the - submitter. -* **Complex delegation:** Delegators could choose other representatives than - their validators. Ultimately, the chain of representatives would always end - up to a validator, but delegators could inherit the vote of their chosen - representative before they inherit the vote of their validator. In other - words, they would only inherit the vote of their validator if their other - appointed representative did not vote. -* **Better process for proposal review:** There would be two parts to - `proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to - reward third party auditors. - -# Parameters +## Parameters The governance module contains the following parameters: @@ -836,7 +752,7 @@ The governance module contains the following parameters: | votingparams | object | {"voting_period":"172800000000000"} | | tallyparams | object | {"quorum":"0.334000000000000000","threshold":"0.500000000000000000","veto":"0.334000000000000000"} | -## SubKeys +### SubKeys | Key | Type | Example | |--------------------|------------------|-----------------------------------------| @@ -851,13 +767,13 @@ The governance module contains the following parameters: modules. If only a subset of parameters are desired to be changed, only they need to be included and not the entire parameter object structure. -# Client +## Client -## CLI +### CLI A user can query and interact with the `gov` module using the CLI. -### Query +#### Query The `query` commands allow users to query `gov` state. @@ -865,7 +781,7 @@ The `query` commands allow users to query `gov` state. simd query gov --help ``` -#### deposit +##### deposit The `deposit` command allows users to query a deposit for a given proposal from a given depositor. @@ -889,7 +805,7 @@ depositor: cosmos1.. proposal_id: "1" ``` -#### deposits +##### deposits The `deposits` command allows users to query all deposits for a given proposal. @@ -917,7 +833,7 @@ pagination: total: "0" ``` -#### param +##### param The `param` command allows users to query a given parameter for the `gov` module. @@ -937,7 +853,7 @@ Example Output: voting_period: "172800000000000" ``` -#### params +##### params The `params` command allows users to query all parameters for the `gov` module. @@ -967,7 +883,7 @@ voting_params: voting_period: "172800000000000" ``` -#### proposal +##### proposal The `proposal` command allows users to query a given proposal. @@ -1008,7 +924,7 @@ voting_end_time: null voting_start_time: null ``` -#### proposals +##### proposals The `proposals` command allows users to query all proposals with optional filters. @@ -1075,7 +991,7 @@ proposals: voting_start_time: null ``` -#### proposer +##### proposer The `proposer` command allows users to query the proposer for a given proposal. @@ -1096,7 +1012,7 @@ proposal_id: "1" proposer: cosmos1.. ``` -#### tally +##### tally The `tally` command allows users to query the tally of a given proposal vote. @@ -1119,7 +1035,7 @@ no_with_veto: "0" "yes": "1" ``` -#### vote +##### vote The `vote` command allows users to query a vote for a given proposal. @@ -1144,7 +1060,7 @@ proposal_id: "1" voter: cosmos1.. ``` -#### votes +##### votes The `votes` command allows users to query all votes for a given proposal. @@ -1173,7 +1089,7 @@ votes: voter: cosmos1.. ``` -### Transactions +#### Transactions The `tx` commands allow users to interact with the `gov` module. @@ -1181,7 +1097,7 @@ The `tx` commands allow users to interact with the `gov` module. simd tx gov --help ``` -#### deposit +##### deposit The `deposit` command allows users to deposit tokens for a given proposal. @@ -1195,7 +1111,7 @@ Example: simd tx gov deposit 1 10000000stake --from cosmos1.. ``` -#### draft-proposal +##### draft-proposal The `draft-proposal` command allows users to draft any type of proposal. The command returns a `draft_proposal.json`, to be used by `submit-proposal` after being completed. @@ -1205,7 +1121,7 @@ The `draft_metadata.json` is meant to be uploaded to [IPFS](#metadata). simd tx gov draft-proposal ``` -#### submit-proposal +##### submit-proposal The `submit-proposal` command allows users to submit a governance proposal along with some messages and metadata. Messages, metadata and deposit are defined in a JSON file. @@ -1237,7 +1153,7 @@ where `proposal.json` contains: } ``` -#### submit-legacy-proposal +##### submit-legacy-proposal The `submit-legacy-proposal` command allows users to submit a governance legacy proposal along with an initial deposit. @@ -1300,7 +1216,7 @@ Example (`software-upgrade`): simd tx gov submit-legacy-proposal software-upgrade v2 --title="Test Proposal" --description="testing, testing, 1, 2, 3" --upgrade-height 1000000 --from cosmos1.. ``` -#### vote +##### vote The `vote` command allows users to submit a vote for a given governance proposal. @@ -1314,7 +1230,7 @@ Example: simd tx gov vote 1 yes --from cosmos1.. ``` -#### weighted-vote +##### weighted-vote The `weighted-vote` command allows users to submit a weighted vote for a given governance proposal. @@ -1328,11 +1244,11 @@ Example: simd tx gov weighted-vote 1 yes=0.5,no=0.5 --from cosmos1.. ``` -## gRPC +### gRPC A user can query the `gov` module using gRPC endpoints. -### Proposal +#### Proposal The `Proposal` endpoint allows users to query a given proposal. @@ -1426,7 +1342,7 @@ Example Output: ``` -### Proposals +#### Proposals The `Proposals` endpoint allows users to query all proposals with optional filters. @@ -1569,7 +1485,7 @@ Example Output: } ``` -### Vote +#### Vote The `Vote` endpoint allows users to query a vote for a given proposal. @@ -1639,7 +1555,7 @@ Example Output: } ``` -### Votes +#### Votes The `Votes` endpoint allows users to query all votes for a given proposal. @@ -1717,7 +1633,7 @@ Example Output: } ``` -### Params +#### Params The `Params` endpoint allows users to query all parameters for the `gov` module. @@ -1781,7 +1697,7 @@ Example Output: } ``` -### Deposit +#### Deposit The `Deposit` endpoint allows users to query a deposit for a given proposal from a given depositor. @@ -1849,7 +1765,7 @@ Example Output: } ``` -### deposits +#### deposits The `Deposits` endpoint allows users to query all deposits for a given proposal. @@ -1927,7 +1843,7 @@ Example Output: } ``` -### TallyResult +#### TallyResult The `TallyResult` endpoint allows users to query the tally of a given proposal. @@ -1987,11 +1903,11 @@ Example Output: } ``` -## REST +### REST A user can query the `gov` module using REST endpoints. -### proposal +#### proposal The `proposals` endpoint allows users to query a given proposal. @@ -2088,7 +2004,7 @@ Example Output: } ``` -### proposals +#### proposals The `proposals` endpoint also allows users to query all proposals with optional filters. @@ -2252,7 +2168,7 @@ Example Output: } ``` -### voter vote +#### voter vote The `votes` endpoint allows users to query a vote for a given proposal. @@ -2316,7 +2232,7 @@ Example Output: } ``` -### votes +#### votes The `votes` endpoint allows users to query all votes for a given proposal. @@ -2392,7 +2308,7 @@ Example Output: } ``` -### params +#### params The `params` endpoint allows users to query all parameters for the `gov` module. @@ -2462,7 +2378,7 @@ Example Output: } ``` -### deposits +#### deposits The `deposits` endpoint allows users to query a deposit for a given proposal from a given depositor. @@ -2524,7 +2440,7 @@ Example Output: } ``` -### proposal deposits +#### proposal deposits The `deposits` endpoint allows users to query all deposits for a given proposal. @@ -2598,7 +2514,7 @@ Example Output: } ``` -### tally +#### tally The `tally` endpoint allows users to query the tally of a given proposal. @@ -2653,11 +2569,11 @@ Example Output: ``` -# Metadata +## Metadata The gov module has two locations for metadata where users can provide further context about the on-chain actions they are taking. By default all metadata fields have a 255 character length field where metadata can be stored in json format, either on-chain or off-chain depending on the amount of data required. Here we provide a recommendation for the json structure and where the data should be stored. There are two important factors in making these recommendations. First, that the gov and group modules are consistent with one another, note the number of proposals made by all groups may be quite large. Second, that client applications such as block explorers and governance interfaces have confidence in the consistency of metadata structure accross chains. -## Proposal +### Proposal Location: off-chain as json object stored on IPFS (mirrors [group proposal](../group/README.md#metadata)) @@ -2672,7 +2588,7 @@ Location: off-chain as json object stored on IPFS (mirrors [group proposal](../g } ``` -## Vote +### Vote Location: on-chain as json within 255 character limit (mirrors [group vote](../group/README.md#metadata)) @@ -2681,3 +2597,30 @@ Location: on-chain as json within 255 character limit (mirrors [group vote](../g "justification": "", } ``` + +## Future Improvements + +The current documentation only describes the minimum viable product for the +governance module. Future improvements may include: + +* **`BountyProposals`:** If accepted, a `BountyProposal` creates an open + bounty. The `BountyProposal` specifies how many Atoms will be given upon + completion. These Atoms will be taken from the `reserve pool`. After a + `BountyProposal` is accepted by governance, anybody can submit a + `SoftwareUpgradeProposal` with the code to claim the bounty. Note that once a + `BountyProposal` is accepted, the corresponding funds in the `reserve pool` + are locked so that payment can always be honored. In order to link a + `SoftwareUpgradeProposal` to an open bounty, the submitter of the + `SoftwareUpgradeProposal` will use the `Proposal.LinkedProposal` attribute. + If a `SoftwareUpgradeProposal` linked to an open bounty is accepted by + governance, the funds that were reserved are automatically transferred to the + submitter. +* **Complex delegation:** Delegators could choose other representatives than + their validators. Ultimately, the chain of representatives would always end + up to a validator, but delegators could inherit the vote of their chosen + representative before they inherit the vote of their validator. In other + words, they would only inherit the vote of their validator if their other + appointed representative did not vote. +* **Better process for proposal review:** There would be two parts to + `proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to + reward third party auditors. diff --git a/x/group/README.md b/x/group/README.md index 38d35c524745..802f438872c7 100644 --- a/x/group/README.md +++ b/x/group/README.md @@ -55,9 +55,9 @@ This module allows the creation and management of on-chain multisig accounts and * [REST](#rest) * [Metadata](#metadata) -# Concepts +## Concepts -## Group +### Group A group is simply an aggregation of accounts with associated weights. It is not an account and doesn't have a balance. It doesn't in and of itself have any @@ -66,7 +66,7 @@ the ability to add, remove and update members in the group. Note that a group policy account could be an administrator of a group, and that the administrator doesn't necessarily have to be a member of the group. -## Group Policy +### Group Policy A group policy is an account associated with a group and a decision policy. Group policies are abstracted from groups because a single group may have @@ -78,7 +78,7 @@ and then to create separate group policies with different decision policies and delegate the desired permissions from the master account to those "sub-accounts" using the `x/authz` module. -## Decision Policy +### Decision Policy A decision policy is the mechanism by which members of a group can vote on proposals, as well as the rules that dictate whether a proposal should pass @@ -103,13 +103,13 @@ interface: https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/types.go#L27-L41 ``` -### Threshold decision policy +#### Threshold decision policy A threshold decision policy defines a threshold of yes votes (based on a tally of voter weights) that must be achieved in order for a proposal to pass. For this decision policy, abstain and veto are simply treated as no's. -### Percentage decision policy +#### Percentage decision policy A percentage decision policy is similar to a threshold decision policy, except that the threshold is not defined as a constant weight, but as a percentage. @@ -117,27 +117,27 @@ It's more suited for groups where the group members' weights can be updated, as the percentage threshold stays the same, and doesn't depend on how those member weights get updated. -## Proposal +### Proposal Any member(s) of a group can submit a proposal for a group policy account to decide upon. A proposal consists of a set of messages that will be executed if the proposal passes as well as any metadata associated with the proposal. -### Voting +#### Voting There are four choices to choose while voting - yes, no, abstain and veto. Not all decision policies will take the four choices into account. Votes can contain some optional metadata. In the current implementation, the voting window begins as soon as a proposal is submitted, and the end is defined by the group policy's decision policy. -### Withdrawing Proposals +#### Withdrawing Proposals Proposals can be withdrawn any time before the voting period end, either by the admin of the group policy or by one of the proposers. Once withdrawn, it is marked as `PROPOSAL_STATUS_WITHDRAWN`, and no more voting or execution is allowed on it. -### Aborted Proposals +#### Aborted Proposals If the group policy is updated during the voting period of the proposal, then the proposal is marked as `PROPOSAL_STATUS_ABORTED`, and no more voting or @@ -145,7 +145,7 @@ execution is allowed on it. This is because the group policy defines the rules of proposal voting and execution, so if those rules change during the lifecycle of a proposal, then the proposal should be marked as stale. -### Tallying +#### Tallying Tallying is the counting of all votes on a proposal. It happens only once in the lifecycle of a proposal, but can be triggered by two factors, whichever @@ -162,7 +162,7 @@ marked as `PROPOSAL_STATUS_ACCEPTED`, or else it is marked as `PROPOSAL_STATUS_REJECTED`. In any case, no more voting is allowed anymore, and the tally result is persisted to state in the proposal's `FinalTallyResult`. -### Executing Proposals +#### Executing Proposals Proposals are executed only when the tallying is done, and the group account's decision policy allows the proposal to pass based on the tally outcome. They @@ -189,7 +189,7 @@ as `PROPOSAL_EXECUTOR_RESULT_FAILURE`. Such a proposal can be re-executed multiple times, until it expires after `MaxExecutionPeriod` after voting period end. -## Pruning +### Pruning Proposals and votes are automatically pruned to avoid state bloat. @@ -211,111 +211,111 @@ Proposals are pruned: whichever happens first. -# State +## State The `group` module uses the `orm` package which provides table storage with support for primary keys and secondary indexes. `orm` also defines `Sequence` which is a persistent unique key generator based on a counter that can be used along with `Table`s. Here's the list of tables and associated sequences and indexes stored as part of the `group` module. -## Group Table +### Group Table The `groupTable` stores `GroupInfo`: `0x0 | BigEndian(GroupId) -> ProtocolBuffer(GroupInfo)`. -### groupSeq +#### groupSeq The value of `groupSeq` is incremented when creating a new group and corresponds to the new `GroupId`: `0x1 | 0x1 -> BigEndian`. The second `0x1` corresponds to the ORM `sequenceStorageKey`. -### groupByAdminIndex +#### groupByAdminIndex `groupByAdminIndex` allows to retrieve groups by admin address: `0x2 | len([]byte(group.Admin)) | []byte(group.Admin) | BigEndian(GroupId) -> []byte()`. -## Group Member Table +### Group Member Table The `groupMemberTable` stores `GroupMember`s: `0x10 | BigEndian(GroupId) | []byte(member.Address) -> ProtocolBuffer(GroupMember)`. The `groupMemberTable` is a primary key table and its `PrimaryKey` is given by `BigEndian(GroupId) | []byte(member.Address)` which is used by the following indexes. -### groupMemberByGroupIndex +#### groupMemberByGroupIndex `groupMemberByGroupIndex` allows to retrieve group members by group id: `0x11 | BigEndian(GroupId) | PrimaryKey -> []byte()`. -### groupMemberByMemberIndex +#### groupMemberByMemberIndex `groupMemberByMemberIndex` allows to retrieve group members by member address: `0x12 | len([]byte(member.Address)) | []byte(member.Address) | PrimaryKey -> []byte()`. -## Group Policy Table +### Group Policy Table The `groupPolicyTable` stores `GroupPolicyInfo`: `0x20 | len([]byte(Address)) | []byte(Address) -> ProtocolBuffer(GroupPolicyInfo)`. The `groupPolicyTable` is a primary key table and its `PrimaryKey` is given by `len([]byte(Address)) | []byte(Address)` which is used by the following indexes. -### groupPolicySeq +#### groupPolicySeq The value of `groupPolicySeq` is incremented when creating a new group policy and is used to generate the new group policy account `Address`: `0x21 | 0x1 -> BigEndian`. The second `0x1` corresponds to the ORM `sequenceStorageKey`. -### groupPolicyByGroupIndex +#### groupPolicyByGroupIndex `groupPolicyByGroupIndex` allows to retrieve group policies by group id: `0x22 | BigEndian(GroupId) | PrimaryKey -> []byte()`. -### groupPolicyByAdminIndex +#### groupPolicyByAdminIndex `groupPolicyByAdminIndex` allows to retrieve group policies by admin address: `0x23 | len([]byte(Address)) | []byte(Address) | PrimaryKey -> []byte()`. -## Proposal Table +### Proposal Table The `proposalTable` stores `Proposal`s: `0x30 | BigEndian(ProposalId) -> ProtocolBuffer(Proposal)`. -### proposalSeq +#### proposalSeq The value of `proposalSeq` is incremented when creating a new proposal and corresponds to the new `ProposalId`: `0x31 | 0x1 -> BigEndian`. The second `0x1` corresponds to the ORM `sequenceStorageKey`. -### proposalByGroupPolicyIndex +#### proposalByGroupPolicyIndex `proposalByGroupPolicyIndex` allows to retrieve proposals by group policy account address: `0x32 | len([]byte(account.Address)) | []byte(account.Address) | BigEndian(ProposalId) -> []byte()`. -### ProposalsByVotingPeriodEndIndex +#### ProposalsByVotingPeriodEndIndex `proposalsByVotingPeriodEndIndex` allows to retrieve proposals sorted by chronological `voting_period_end`: `0x33 | sdk.FormatTimeBytes(proposal.VotingPeriodEnd) | BigEndian(ProposalId) -> []byte()`. This index is used when tallying the proposal votes at the end of the voting period, and for pruning proposals at `VotingPeriodEnd + MaxExecutionPeriod`. -## Vote Table +### Vote Table The `voteTable` stores `Vote`s: `0x40 | BigEndian(ProposalId) | []byte(voter.Address) -> ProtocolBuffer(Vote)`. The `voteTable` is a primary key table and its `PrimaryKey` is given by `BigEndian(ProposalId) | []byte(voter.Address)` which is used by the following indexes. -### voteByProposalIndex +#### voteByProposalIndex `voteByProposalIndex` allows to retrieve votes by proposal id: `0x41 | BigEndian(ProposalId) | PrimaryKey -> []byte()`. -### voteByVoterIndex +#### voteByVoterIndex `voteByVoterIndex` allows to retrieve votes by voter address: `0x42 | len([]byte(voter.Address)) | []byte(voter.Address) | PrimaryKey -> []byte()`. -# Msg Service +## Msg Service -## Msg/CreateGroup +### Msg/CreateGroup A new group can be created with the `MsgCreateGroup`, which has an admin address, a list of members and some optional metadata. @@ -332,7 +332,7 @@ It's expected to fail if config * members are not correctly set (e.g. wrong address format, duplicates, or with 0 weight). -## Msg/UpdateGroupMembers +### Msg/UpdateGroupMembers Group members can be updated with the `UpdateGroupMembers`. @@ -347,7 +347,7 @@ It's expected to fail if: * the signer is not the admin of the group. * for any one of the associated group policies, if its decision policy's `Validate()` method fails against the updated group. -## Msg/UpdateGroupAdmin +### Msg/UpdateGroupAdmin The `UpdateGroupAdmin` can be used to update a group admin. @@ -357,7 +357,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/group/v1/tx.proto It's expected to fail if the signer is not the admin of the group. -## Msg/UpdateGroupMetadata +### Msg/UpdateGroupMetadata The `UpdateGroupMetadata` can be used to update a group metadata. @@ -370,7 +370,7 @@ It's expected to fail if: * new metadata length is greater than `MaxMetadataLen` config. * the signer is not the admin of the group. -## Msg/CreateGroupPolicy +### 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. @@ -384,7 +384,7 @@ It's expected to fail if: * metadata length is greater than `MaxMetadataLen` config. * the decision policy's `Validate()` method doesn't pass against the group. -## Msg/CreateGroupWithPolicy +### Msg/CreateGroupWithPolicy A new group with policy can be created with the `MsgCreateGroupWithPolicy`, which has an admin address, a list of members, a decision policy, a `group_policy_as_admin` field to optionally set group and group policy admin with group policy address and some optional metadata for group and group policy. @@ -394,7 +394,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/group/v1/tx.proto It's expected to fail for the same reasons as `Msg/CreateGroup` and `Msg/CreateGroupPolicy`. -## Msg/UpdateGroupPolicyAdmin +### Msg/UpdateGroupPolicyAdmin The `UpdateGroupPolicyAdmin` can be used to update a group policy admin. @@ -404,7 +404,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/group/v1/tx.proto It's expected to fail if the signer is not the admin of the group policy. -## Msg/UpdateGroupPolicyDecisionPolicy +### Msg/UpdateGroupPolicyDecisionPolicy The `UpdateGroupPolicyDecisionPolicy` can be used to update a decision policy. @@ -417,7 +417,7 @@ It's expected to fail if: * the signer is not the admin of the group policy. * the new decision policy's `Validate()` method doesn't pass against the group. -## Msg/UpdateGroupPolicyMetadata +### Msg/UpdateGroupPolicyMetadata The `UpdateGroupPolicyMetadata` can be used to update a group policy metadata. @@ -430,7 +430,7 @@ It's expected to fail if: * new metadata length is greater than `MaxMetadataLen` config. * the signer is not the admin of the group. -## Msg/SubmitProposal +### Msg/SubmitProposal A new proposal can be created with the `MsgSubmitProposal`, 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. 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. @@ -444,7 +444,7 @@ It's expected to fail if: * metadata length is greater than `MaxMetadataLen` config. * if any of the proposers is not a group member. -## Msg/WithdrawProposal +### Msg/WithdrawProposal A proposal can be withdrawn using `MsgWithdrawProposal` which has an `address` (can be either a proposer or the group policy admin) and a `proposal_id` (which has to be withdrawn). @@ -457,7 +457,7 @@ It's expected to fail if: * the signer is neither the group policy admin nor proposer of the proposal. * the proposal is already closed or aborted. -## Msg/Vote +### 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. An optional `Exec` value can be provided to try to execute the proposal immediately after voting. @@ -471,7 +471,7 @@ It's expected to fail if: * metadata length is greater than `MaxMetadataLen` config. * the proposal is not in voting period anymore. -## Msg/Exec +### Msg/Exec A proposal can be executed with the `MsgExec`. @@ -484,7 +484,7 @@ The messages that are part of this proposal won't be executed if: * the proposal has not been accepted by the group policy. * the proposal has already been successfully executed. -## Msg/LeaveGroup +### Msg/LeaveGroup The `MsgLeaveGroup` allows group member to leave a group. @@ -497,53 +497,53 @@ It's expected to fail if: * the group member is not part of the group. * for any one of the associated group policies, if its decision policy's `Validate()` method fails against the updated group. -# Events +## Events The group module emits the following events: -## EventCreateGroup +### EventCreateGroup | Type | Attribute Key | Attribute Value | | -------------------------------- | ------------- | -------------------------------- | | message | action | /cosmos.group.v1.Msg/CreateGroup | | cosmos.group.v1.EventCreateGroup | group_id | {groupId} | -## EventUpdateGroup +### EventUpdateGroup | Type | Attribute Key | Attribute Value | | -------------------------------- | ------------- | ---------------------------------------------------------- | | message | action | /cosmos.group.v1.Msg/UpdateGroup{Admin\|Metadata\|Members} | | cosmos.group.v1.EventUpdateGroup | group_id | {groupId} | -## EventCreateGroupPolicy +### EventCreateGroupPolicy | Type | Attribute Key | Attribute Value | | -------------------------------------- | ------------- | -------------------------------------- | | message | action | /cosmos.group.v1.Msg/CreateGroupPolicy | | cosmos.group.v1.EventCreateGroupPolicy | address | {groupPolicyAddress} | -## EventUpdateGroupPolicy +### EventUpdateGroupPolicy | Type | Attribute Key | Attribute Value | | -------------------------------------- | ------------- | ----------------------------------------------------------------------- | | message | action | /cosmos.group.v1.Msg/UpdateGroupPolicy{Admin\|Metadata\|DecisionPolicy} | | cosmos.group.v1.EventUpdateGroupPolicy | address | {groupPolicyAddress} | -## EventCreateProposal +### EventCreateProposal | Type | Attribute Key | Attribute Value | | ----------------------------------- | ------------- | ----------------------------------- | | message | action | /cosmos.group.v1.Msg/CreateProposal | | cosmos.group.v1.EventCreateProposal | proposal_id | {proposalId} | -## EventWithdrawProposal +### EventWithdrawProposal | Type | Attribute Key | Attribute Value | | ------------------------------------- | ------------- | ------------------------------------- | | message | action | /cosmos.group.v1.Msg/WithdrawProposal | | cosmos.group.v1.EventWithdrawProposal | proposal_id | {proposalId} | -## EventVote +### EventVote | Type | Attribute Key | Attribute Value | | ------------------------- | ------------- | ------------------------- | @@ -558,7 +558,7 @@ The group module emits the following events: | cosmos.group.v1.EventExec | proposal_id | {proposalId} | | cosmos.group.v1.EventExec | logs | {logs_string} | -## EventLeaveGroup +### EventLeaveGroup | Type | Attribute Key | Attribute Value | | ------------------------------- | ------------- | ------------------------------- | @@ -567,13 +567,13 @@ The group module emits the following events: | cosmos.group.v1.EventLeaveGroup | address | {address} | -# Client +## Client -## CLI +### CLI A user can query and interact with the `group` module using the CLI. -### Query +#### Query The `query` commands allow users to query `group` state. @@ -581,7 +581,7 @@ The `query` commands allow users to query `group` state. simd query group --help ``` -#### group-info +##### group-info The `group-info` command allows users to query for group info by given group id. @@ -605,7 +605,7 @@ total_weight: "3" version: "1" ``` -#### group-policy-info +##### group-policy-info The `group-policy-info` command allows users to query for group policy info by account address of group policy . @@ -635,7 +635,7 @@ metadata: AQ== version: "1" ``` -#### group-members +##### group-members The `group-members` command allows users to query for group members by group id with pagination flags. @@ -668,7 +668,7 @@ pagination: total: "2" ``` -#### groups-by-admin +##### groups-by-admin The `groups-by-admin` command allows users to query for groups by admin account address with pagination flags. @@ -701,7 +701,7 @@ pagination: total: "2" ``` -#### group-policies-by-group +##### group-policies-by-group The `group-policies-by-group` command allows users to query for group policies by group id with pagination flags. @@ -746,7 +746,7 @@ pagination: total: "2" ``` -#### group-policies-by-admin +##### group-policies-by-admin The `group-policies-by-admin` command allows users to query for group policies by admin account address with pagination flags. @@ -791,7 +791,7 @@ pagination: total: "2" ``` -#### proposal +##### proposal The `proposal` command allows users to query for proposal by id. @@ -837,7 +837,7 @@ proposal: yes_count: "0" ``` -#### proposals-by-group-policy +##### proposals-by-group-policy The `proposals-by-group-policy` command allows users to query for proposals by account address of group policy with pagination flags. @@ -886,7 +886,7 @@ proposals: yes_count: "0" ``` -#### vote +##### vote The `vote` command allows users to query for vote by proposal id and voter account address. @@ -911,7 +911,7 @@ vote: voter: cosmos1.. ``` -#### votes-by-proposal +##### votes-by-proposal The `votes-by-proposal` command allows users to query for votes by proposal id with pagination flags. @@ -939,7 +939,7 @@ votes: voter: cosmos1.. ``` -#### votes-by-voter +##### votes-by-voter The `votes-by-voter` command allows users to query for votes by voter account address with pagination flags. @@ -975,7 +975,7 @@ The `tx` commands allow users to interact with the `group` module. simd tx group --help ``` -#### create-group +##### create-group The `create-group` command allows users to create a group which is an aggregation of member accounts with associated weights and an administrator account. @@ -990,7 +990,7 @@ Example: simd tx group create-group cosmos1.. "AQ==" members.json ``` -#### update-group-admin +##### update-group-admin The `update-group-admin` command allows users to update a group's admin. @@ -1004,7 +1004,7 @@ Example: simd tx group update-group-admin cosmos1.. 1 cosmos1.. ``` -#### update-group-members +##### update-group-members The `update-group-members` command allows users to update a group's members. @@ -1018,7 +1018,7 @@ Example: simd tx group update-group-members cosmos1.. 1 members.json ``` -#### update-group-metadata +##### update-group-metadata The `update-group-metadata` command allows users to update a group's metadata. @@ -1032,7 +1032,7 @@ Example: simd tx group update-group-metadata cosmos1.. 1 "AQ==" ``` -#### create-group-policy +##### create-group-policy The `create-group-policy` command allows users to create a group policy which is an account associated with a group and a decision policy. @@ -1046,7 +1046,7 @@ Example: simd tx group create-group-policy cosmos1.. 1 "AQ==" '{"@type":"/cosmos.group.v1.ThresholdDecisionPolicy", "threshold":"1", "windows": {"voting_period": "120h", "min_execution_period": "0s"}}' ``` -#### create-group-with-policy +##### create-group-with-policy The `create-group-with-policy` command allows users to create a group which is an aggregation of member accounts with associated weights and an administrator account with decision policy. If the `--group-policy-as-admin` flag is set to `true`, the group policy address becomes the group and group policy admin. @@ -1060,7 +1060,7 @@ Example: simd tx group create-group-with-policy cosmos1.. "AQ==" "AQ==" members.json '{"@type":"/cosmos.group.v1.ThresholdDecisionPolicy", "threshold":"1", "windows": {"voting_period": "120h", "min_execution_period": "0s"}}' ``` -#### update-group-policy-admin +##### update-group-policy-admin The `update-group-policy-admin` command allows users to update a group policy admin. @@ -1074,7 +1074,7 @@ Example: simd tx group update-group-policy-admin cosmos1.. cosmos1.. cosmos1.. ``` -#### update-group-policy-metadata +##### update-group-policy-metadata The `update-group-policy-metadata` command allows users to update a group policy metadata. @@ -1088,7 +1088,7 @@ Example: simd tx group update-group-policy-metadata cosmos1.. cosmos1.. "AQ==" ``` -#### update-group-policy-decision-policy +##### update-group-policy-decision-policy The `update-group-policy-decision-policy` command allows users to update a group policy's decision policy. @@ -1102,7 +1102,7 @@ Example: simd tx group update-group-policy-decision-policy cosmos1.. cosmos1.. '{"@type":"/cosmos.group.v1.ThresholdDecisionPolicy", "threshold":"2", "windows": {"voting_period": "120h", "min_execution_period": "0s"}}' ``` -#### create-proposal +##### create-proposal The `create-proposal` command allows users to submit a new proposal. @@ -1116,7 +1116,7 @@ Example: simd tx group create-proposal cosmos1.. cosmos1.. msg_tx.json "AQ==" ``` -#### withdraw-proposal +##### withdraw-proposal The `withdraw-proposal` command allows users to withdraw a proposal. @@ -1130,7 +1130,7 @@ Example: simd tx group withdraw-proposal 1 cosmos1.. ``` -#### vote +##### vote The `vote` command allows users to vote on a proposal. @@ -1144,7 +1144,7 @@ Example: simd tx group vote 1 cosmos1.. CHOICE_YES "AQ==" ``` -#### exec +##### exec The `exec` command allows users to execute a proposal. @@ -1158,7 +1158,7 @@ Example: simd tx group exec 1 ``` -#### leave-group +##### leave-group The `leave-group` command allows group member to leave the group. @@ -1172,11 +1172,11 @@ Example: simd tx group leave-group cosmos1... 1 ``` -## gRPC +### gRPC A user can query the `group` module using gRPC endpoints. -### GroupInfo +#### GroupInfo The `GroupInfo` endpoint allows users to query for group info by given group id. @@ -1205,7 +1205,7 @@ Example Output: } ``` -### GroupPolicyInfo +#### GroupPolicyInfo The `GroupPolicyInfo` endpoint allows users to query for group policy info by account address of group policy. @@ -1234,7 +1234,7 @@ Example Output: } ``` -### GroupMembers +#### GroupMembers The `GroupMembers` endpoint allows users to query for group members by group id with pagination flags. @@ -1275,7 +1275,7 @@ Example Output: } ``` -### GroupsByAdmin +#### GroupsByAdmin The `GroupsByAdmin` endpoint allows users to query for groups by admin account address with pagination flags. @@ -1316,7 +1316,7 @@ Example Output: } ``` -### GroupPoliciesByGroup +#### GroupPoliciesByGroup The `GroupPoliciesByGroup` endpoint allows users to query for group policies by group id with pagination flags. @@ -1357,7 +1357,7 @@ Example Output: } ``` -### GroupPoliciesByAdmin +#### GroupPoliciesByAdmin The `GroupPoliciesByAdmin` endpoint allows users to query for group policies by admin account address with pagination flags. @@ -1398,7 +1398,7 @@ Example Output: } ``` -### Proposal +#### Proposal The `Proposal` endpoint allows users to query for proposal by id. @@ -1446,7 +1446,7 @@ Example Output: } ``` -### ProposalsByGroupPolicy +#### ProposalsByGroupPolicy The `ProposalsByGroupPolicy` endpoint allows users to query for proposals by account address of group policy with pagination flags. @@ -1499,7 +1499,7 @@ Example Output: } ``` -### VoteByProposalVoter +#### VoteByProposalVoter The `VoteByProposalVoter` endpoint allows users to query for vote by proposal id and voter account address. @@ -1527,7 +1527,7 @@ Example Output: } ``` -### VotesByProposal +#### VotesByProposal The `VotesByProposal` endpoint allows users to query for votes by proposal id with pagination flags. @@ -1560,7 +1560,7 @@ Example Output: } ``` -### VotesByVoter +#### VotesByVoter The `VotesByVoter` endpoint allows users to query for votes by voter account address with pagination flags. @@ -1593,11 +1593,11 @@ Example Output: } ``` -## REST +### REST A user can query the `group` module using REST endpoints. -### GroupInfo +#### GroupInfo The `GroupInfo` endpoint allows users to query for group info by given group id. @@ -1625,7 +1625,7 @@ Example Output: } ``` -### GroupPolicyInfo +#### GroupPolicyInfo The `GroupPolicyInfo` endpoint allows users to query for group policy info by account address of group policy. @@ -1661,7 +1661,7 @@ Example Output: } ``` -### GroupMembers +#### GroupMembers The `GroupMembers` endpoint allows users to query for group members by group id with pagination flags. @@ -1703,7 +1703,7 @@ Example Output: } ``` -### GroupsByAdmin +#### GroupsByAdmin The `GroupsByAdmin` endpoint allows users to query for groups by admin account address with pagination flags. @@ -1744,7 +1744,7 @@ Example Output: } ``` -### GroupPoliciesByGroup +#### GroupPoliciesByGroup The `GroupPoliciesByGroup` endpoint allows users to query for group policies by group id with pagination flags. @@ -1801,7 +1801,7 @@ Example Output: } ``` -### GroupPoliciesByAdmin +#### GroupPoliciesByAdmin The `GroupPoliciesByAdmin` endpoint allows users to query for group policies by admin account address with pagination flags. @@ -1857,7 +1857,7 @@ Example Output: } ``` -### Proposal +#### Proposal The `Proposal` endpoint allows users to query for proposal by id. @@ -1915,7 +1915,7 @@ Example Output: } ``` -### ProposalsByGroupPolicy +#### ProposalsByGroupPolicy The `ProposalsByGroupPolicy` endpoint allows users to query for proposals by account address of group policy with pagination flags. @@ -1979,7 +1979,7 @@ Example Output: } ``` -### VoteByProposalVoter +#### VoteByProposalVoter The `VoteByProposalVoter` endpoint allows users to query for vote by proposal id and voter account address. @@ -2007,7 +2007,7 @@ Example Output: } ``` -### VotesByProposal +#### VotesByProposal The `VotesByProposal` endpoint allows users to query for votes by proposal id with pagination flags. @@ -2041,7 +2041,7 @@ Example Output: } ``` -### VotesByVoter +#### VotesByVoter The `VotesByVoter` endpoint allows users to query for votes by voter account address with pagination flags. @@ -2075,11 +2075,11 @@ Example Output: } ``` -# Metadata +## Metadata The group module has four locations for metadata where users can provide further context about the on-chain actions they are taking. By default all metadata fields have a 255 character length field where metadata can be stored in json format, either on-chain or off-chain depending on the amount of data required. Here we provide a recommendation for the json structure and where the data should be stored. There are two important factors in making these recommendations. First, that the group and gov modules are consistent with one another, note the number of proposals made by all groups may be quite large. Second, that client applications such as block explorers and governance interfaces have confidence in the consistency of metadata structure accross chains. -## Proposal +### Proposal Location: off-chain as json object stored on IPFS (mirrors [gov proposal](../gov/README.md#metadata)) @@ -2094,7 +2094,7 @@ Location: off-chain as json object stored on IPFS (mirrors [gov proposal](../gov } ``` -## Vote +### Vote Location: on-chain as json within 255 character limit (mirrors [gov vote](../gov/README.md#metadata)) @@ -2104,7 +2104,7 @@ Location: on-chain as json within 255 character limit (mirrors [gov vote](../gov } ``` -## Group +### Group Location: off-chain as json object stored on IPFS @@ -2117,7 +2117,7 @@ Location: off-chain as json object stored on IPFS } ``` -## Decision policy +### Decision policy Location: on-chain as json within 255 character limit diff --git a/x/group/internal/orm/README.md b/x/group/internal/orm/README.md index 95a7c0c6d7ec..05032d6c824a 100644 --- a/x/group/internal/orm/README.md +++ b/x/group/internal/orm/README.md @@ -1,4 +1,4 @@ -# Abstract +# Group ORM The orm package provides a framework for creating relational database tables with primary and secondary keys. @@ -16,7 +16,7 @@ The orm package provides a framework for creating relational database tables wit * [Iterator](#iterator) * [Pagination](#pagination) -# Table +## Table 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. @@ -37,7 +37,7 @@ The `table` struct is private, so that we only have custom tables built on top o `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. -## AutoUInt64Table +### AutoUInt64Table `AutoUInt64Table` is a table type with an auto incrementing `uint64` ID. @@ -47,11 +47,11 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/internal/orm/auto_uint It's based on the `Sequence` struct which is a persistent unique key generator based on a counter encoded using 8 byte big endian. -## PrimaryKeyTable +### PrimaryKeyTable `PrimaryKeyTable` provides simpler object style orm methods where are persisted and loaded with a reference to their unique primary key. -### PrimaryKeyed +#### PrimaryKeyed The model provided for creating a `PrimaryKeyTable` should implement the `PrimaryKeyed` interface: @@ -62,7 +62,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/internal/orm/primary_k `PrimaryKeyFields()` method returns the list of key parts for a given object. The primary key parts can be []byte, string, and `uint64` types. -### Key codec +#### Key codec Key parts, except the last part, follow these rules: @@ -70,7 +70,7 @@ Key parts, except the last part, follow these rules: * strings are null-terminated * `uint64` are encoded using 8 byte big endian. -# Secondary Index +## Secondary Index 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. @@ -78,7 +78,7 @@ Secondary indexes can be used on `Indexable` [tables](01_table.md). Indeed, thos https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/internal/orm/types.go#L88-L93 ``` -## MultiKeyIndex +### MultiKeyIndex A `MultiKeyIndex` is an index where multiple entries can point to the same underlying object. @@ -99,15 +99,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/internal/orm/indexer.g 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. -## UniqueIndex +### UniqueIndex As opposed to `MultiKeyIndex`, `UniqueIndex` is an index where duplicate keys are prohibited. -# Iterator and Pagination +## Iterator and Pagination Both [tables](01_table.md) and [secondary indexes](02_secondary_index.md) support iterating over a domain of keys, through `PrefixScan` or `ReversePrefixScan`, as well pagination. -## Iterator +### Iterator An `Iterator` allows iteration through a sequence of key value pairs. @@ -129,7 +129,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/x/group/internal/orm/index.go# Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`). -## Pagination +### Pagination 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. diff --git a/x/mint/README.md b/x/mint/README.md index 18e8c5229a48..00b16e7738ef 100644 --- a/x/mint/README.md +++ b/x/mint/README.md @@ -21,9 +21,9 @@ sidebar_position: 1 * [gRPC](#grpc) * [REST](#rest) -# Concepts +## Concepts -## The Minting Mechanism +### The Minting Mechanism The minting mechanism was designed to: @@ -47,9 +47,9 @@ It can be broken down in the following way: decrease until a minimum value is reached -# State +## State -## Minter +### Minter The minter is a space for holding current inflation information. @@ -59,7 +59,7 @@ The minter is a space for holding current inflation information. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/mint/v1beta1/mint.proto#L9-L23 ``` -## Params +### Params The mint module stores it's params in state with the prefix of `0x01`, it can be updated with governance or the address with authority. @@ -71,12 +71,12 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/mint/v1beta1/mint ``` -# Begin-Block +## Begin-Block Minting parameters are recalculated and inflation paid at the beginning of each block. -## Inflation rate calculation +### Inflation rate calculation Inflation rate is calculated using an "inflation calculation function" that's passed to the `NewAppModule` function. If no function is passed, then the SDK's @@ -88,7 +88,7 @@ passing a function that matches `InflationCalculationFn`'s signature. type InflationCalculationFn func(ctx sdk.Context, minter Minter, params Params, bondedRatio sdk.Dec) sdk.Dec ``` -### NextInflationRate +#### NextInflationRate The target annual inflation rate is recalculated each block. The inflation is also subject to a rate change (positive or negative) @@ -114,7 +114,7 @@ NextInflationRate(params Params, bondedRatio sdk.Dec) (inflation sdk.Dec) { } ``` -## NextAnnualProvisions +### NextAnnualProvisions Calculate the annual provisions based on current total supply and inflation rate. This parameter is calculated once per block. @@ -124,7 +124,7 @@ NextAnnualProvisions(params Params, totalSupply sdk.Dec) (provisions sdk.Dec) { return Inflation * totalSupply ``` -## BlockProvision +### BlockProvision 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`. @@ -135,7 +135,7 @@ BlockProvision(params Params) sdk.Coin { ``` -# Parameters +## Parameters The minting module contains the following parameters: @@ -149,11 +149,11 @@ The minting module contains the following parameters: | BlocksPerYear | string (uint64) | "6311520" | -# Events +## Events The minting module emits the following events: -## BeginBlocker +### BeginBlocker | Type | Attribute Key | Attribute Value | |------|-------------------|--------------------| @@ -163,13 +163,13 @@ The minting module emits the following events: | mint | amount | {amount} | -# Client +## Client -## CLI +### CLI A user can query and interact with the `mint` module using the CLI. -### Query +#### Query The `query` commands allow users to query `mint` state. @@ -177,7 +177,7 @@ The `query` commands allow users to query `mint` state. simd query mint --help ``` -#### annual-provisions +##### annual-provisions The `annual-provisions` command allow users to query the current minting annual provisions value @@ -197,7 +197,7 @@ Example Output: 22268504368893.612100895088410693 ``` -#### inflation +##### inflation The `inflation` command allow users to query the current minting inflation value @@ -217,7 +217,7 @@ Example Output: 0.199200302563256955 ``` -#### params +##### params The `params` command allow users to query the current minting parameters @@ -236,11 +236,11 @@ inflation_rate_change: "0.130000000000000000" mint_denom: stake ``` -## gRPC +### gRPC A user can query the `mint` module using gRPC endpoints. -### AnnualProvisions +#### AnnualProvisions The `AnnualProvisions` endpoint allow users to query the current minting annual provisions value @@ -262,7 +262,7 @@ Example Output: } ``` -### Inflation +#### Inflation The `Inflation` endpoint allow users to query the current minting inflation value @@ -284,7 +284,7 @@ Example Output: } ``` -### Params +#### Params The `Params` endpoint allow users to query the current minting parameters @@ -313,11 +313,11 @@ Example Output: } ``` -## REST +### REST A user can query the `mint` module using REST endpoints. -### annual-provisions +#### annual-provisions ```shell /cosmos/mint/v1beta1/annual_provisions @@ -337,7 +337,7 @@ Example Output: } ``` -### inflation +#### inflation ```shell /cosmos/mint/v1beta1/inflation @@ -357,7 +357,7 @@ Example Output: } ``` -### params +#### params ```shell /cosmos/mint/v1beta1/params diff --git a/x/nft/README.md b/x/nft/README.md index 63e457a22645..a084b28f9009 100644 --- a/x/nft/README.md +++ b/x/nft/README.md @@ -18,53 +18,53 @@ sidebar_position: 1 * [MsgSend](#msgsend) *[Events](#events) -# Concepts +## Concepts -## Class +### Class `x/nft` module defines a struct `Class` to describe the common characteristics of a class of nft, under this class, you can create a variety of nft, which is equivalent to an erc721 contract for Ethereum. The design is defined in the [ADR 043](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-043-nft-module.md). -## NFT +### NFT The full name of NFT is Non-Fungible Tokens. Because of the irreplaceable nature of NFT, it means that it can be used to represent unique things. The nft implemented by this module is fully compatible with Ethereum ERC721 standard. -# State +## State -## Class +### Class Class is mainly composed of `id`, `name`, `symbol`, `description`, `uri`, `uri_hash`,`data` where `id` is the unique identifier of the class, similar to the Ethereum ERC721 contract address, the others are optional. * Class: `0x01 | classID | -> ProtocolBuffer(Class)` -## NFT +### NFT NFT is mainly composed of `class_id`, `id`, `uri`, `uri_hash` and `data`. Among them, `class_id` and `id` are two-tuples that identify the uniqueness of nft, `uri` and `uri_hash` is optional, which identifies the off-chain storage location of the nft, and `data` is an Any type. Use Any chain of `x/nft` modules can be customized by extending this field * NFT: `0x02 | classID | 0x00 | nftID |-> ProtocolBuffer(NFT)` -## NFTOfClassByOwner +### NFTOfClassByOwner NFTOfClassByOwner is mainly to realize the function of querying all nfts using classID and owner, without other redundant functions. * NFTOfClassByOwner: `0x03 | owner | 0x00 | classID | 0x00 | nftID |-> 0x01` -## Owner +### Owner Since there is no extra field in NFT to indicate the owner of nft, an additional key-value pair is used to save the ownership of nft. With the transfer of nft, the key-value pair is updated synchronously. * OwnerKey: `0x04 | classID | 0x00 | nftID |-> owner` -## TotalSupply +### TotalSupply TotalSupply is responsible for tracking the number of all nfts under a certain class. Mint operation is performed under the changed class, supply increases by one, burn operation, and supply decreases by one. * OwnerKey: `0x05 | classID |-> totalSupply` -# Messages +## Messages In this section we describe the processing of messages for the nft module. -## MsgSend +### MsgSend You can use the `MsgSend` message to transfer the ownership of nft. This is a function provided by the `x/nft` module. Of course, you can use the `Transfer` method to implement your own transfer logic, but you need to pay extra attention to the transfer permissions. @@ -74,6 +74,6 @@ The message handling should fail if: * provided `Id` is not exist. * provided `Sender` is not the owner of nft. -# Events +## Events The nft module emits proto events defined in [the Protobuf reference](https://buf.build/cosmos/cosmos-sdk/docs/main:cosmos.nft.v1beta1). diff --git a/x/params/README.md b/x/params/README.md index c6a03de23dee..f8d374d0c28b 100644 --- a/x/params/README.md +++ b/x/params/README.md @@ -27,7 +27,7 @@ The following contents explains how to use params module for master and user mod * [KeyTable](#keytable) * [ParamSet](#paramset) -# Keeper +## Keeper In the app initialization stage, [subspaces](#subspace) can be allocated for other modules' keeper using `Keeper.Subspace` and are stored in `Keeper.spaces`. Then, those modules can have a reference to their specific parameter store through `Keeper.GetSubspace`. @@ -43,12 +43,12 @@ func (k ExampleKeeper) SetParams(ctx sdk.Context, params types.Params) { } ``` -# Subspace +## Subspace `Subspace` is a prefixed subspace of the parameter store. Each module which uses the parameter store will take a `Subspace` to isolate permission to access. -## Key +### Key Parameter keys are human readable alphanumeric strings. A parameter for the key `"ExampleParameter"` is stored under `[]byte("SubspaceName" + "/" + "ExampleParameter")`, @@ -57,7 +57,7 @@ Parameter keys are human readable alphanumeric strings. A parameter for the key Subkeys are secondary parameter keys those are used along with a primary parameter key. Subkeys can be used for grouping or dynamic parameter key generation during runtime. -## KeyTable +### KeyTable All of the parameter keys that will be used should be registered at the compile time. `KeyTable` is essentially a `map[string]attribute`, where the `string` is a parameter key. @@ -68,7 +68,7 @@ type to check that provided key and value are compatible and registered, as well Only primary keys have to be registered on the `KeyTable`. Subkeys inherit the attribute of the primary key. -## ParamSet +### ParamSet Modules often define parameters as a proto message. The generated struct can implement `ParamSet` interface to be used with the following methods: diff --git a/x/slashing/README.md b/x/slashing/README.md index 435c55999dfb..d481ff6a479a 100644 --- a/x/slashing/README.md +++ b/x/slashing/README.md @@ -42,9 +42,9 @@ This module will be used by the Cosmos Hub, the first hub in the Cosmos ecosyste * [gRPC](#grpc) * [REST](#rest) -# Concepts +## Concepts -## States +### States At any given time, there are any number of validators registered in the state machine. Each block, the top `MaxValidators` (defined by `x/staking`) validators @@ -56,7 +56,7 @@ For each of these validators we keep a `ValidatorSigningInfo` record that contai information partaining to validator's liveness and other infraction related attributes. -## Tombstone Caps +### Tombstone Caps In order to mitigate the impact of initially likely categories of non-malicious protocol faults, the Cosmos Hub implements for each validator @@ -67,7 +67,7 @@ somewhat blunt the economic impact of unintentional misconfiguration. Liveness faults do not have caps, as they can't stack upon each other. Liveness bugs are "detected" as soon as the infraction occurs, and the validators are immediately put in jail, so it is not possible for them to commit multiple liveness faults without unjailing in between. -## Infraction Timelines +### Infraction Timelines To illustrate how the `x/slashing` module handles submitted evidence through Tendermint consensus, consider the following examples: @@ -81,14 +81,14 @@ _Dn_ : infraction `n` discovered _Vb_ : validator bonded _Vu_ : validator unbonded -### Single Double Sign Infraction +#### Single Double Sign Infraction \[----------C1----D1,Vu-----\] A single infraction is committed then later discovered, at which point the validator is unbonded and slashed at the full amount for the infraction. -### Multiple Double Sign Infractions +#### Multiple Double Sign Infractions \[----------C1--C2---C3---D1,D2,D3Vu-----\] @@ -96,9 +96,9 @@ Multiple infractions are committed and then later discovered, at which point the validator is jailed and slashed for only one infraction. Because the validator is also tombstoned, they can not rejoin the validator set. -# State +## State -## Signing Info (Liveness) +### Signing Info (Liveness) Every block includes a set of precommits by the validators for the previous block, known as the `LastCommitInfo` provided by Tendermint. A `LastCommitInfo` is valid so @@ -146,7 +146,7 @@ The information stored for tracking validator liveness is as follows: https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/slashing/v1beta1/slashing.proto#L12-L33 ``` -## Params +### Params The slashing module stores it's params in state with the prefix of `0x00`, it can be updated with governance or the address with authority. @@ -157,11 +157,11 @@ it can be updated with governance or the address with authority. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc3/proto/cosmos/slashing/v1beta1/slashing.proto#L35-L45 ``` -# Messages +## Messages In this section we describe the processing of messages for the `slashing` module. -## Unjail +### Unjail If a validator was automatically unbonded due to downtime and wishes to come back online & possibly rejoin the bonded set, it must send `MsgUnjail`: @@ -205,9 +205,9 @@ If the validator has enough stake to be in the top `n = MaximumBondedValidators` and all delegators still delegated to the validator will be rebonded and begin to again collect provisions and rewards. -# BeginBlock +## BeginBlock -## Liveness Tracking +### Liveness Tracking At the beginning of each block, we update the `ValidatorSigningInfo` for each validator and check if they've crossed below the liveness threshold over a @@ -300,11 +300,11 @@ for vote in block.LastCommitInfo.Votes { } ``` -# Hooks +## Hooks This section contains a description of the module's `hooks`. Hooks are operations that are executed automatically when events are raised. -## Staking hooks +### Staking hooks The slashing module implements the `StakingHooks` defined in `x/staking` and are used as record-keeping of validators information. During the app initialization, these hooks should be registered in the staking module struct. @@ -314,7 +314,7 @@ The following hooks impact the slashing state: * `AfterValidatorCreated` stores a validator's consensus key. * `AfterValidatorRemoved` removes a validator's consensus key. -## Validator Bonded +### 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. @@ -342,22 +342,22 @@ onValidatorBonded(address sdk.ValAddress) return ``` -# Events +## Events The slashing module emits the following events: -## MsgServer +### MsgServer -### MsgUnjail +#### MsgUnjail | Type | Attribute Key | Attribute Value | | ------- | ------------- | ------------------ | | message | module | slashing | | message | sender | {validatorAddress} | -## Keeper +### Keeper -## BeginBlocker: HandleValidatorSignature +### BeginBlocker: HandleValidatorSignature | Type | Attribute Key | Attribute Value | | ----- | ------------- | --------------------------- | @@ -375,19 +375,19 @@ The slashing module emits the following events: | liveness | missed_blocks | {missedBlocksCounter} | | liveness | height | {blockHeight} | -### Slash +#### Slash * same as `"slash"` event from `HandleValidatorSignature`, but without the `jailed` attribute. -### Jail +#### Jail | Type | Attribute Key | Attribute Value | | ----- | ------------- | ------------------ | | slash | jailed | {validatorAddress} | -# Staking Tombstone +## Staking Tombstone -## Abstract +### Abstract In the current implementation of the `slashing` module, when the consensus engine informs the state machine of a validator's consensus fault, the validator is @@ -472,7 +472,7 @@ stay with them. Given that consensus safety faults are so egregious (way more so than liveness faults), it is probably prudent to have delegators not "auto-rebond" to the validator. -### Proposal: infinite jail +#### Proposal: infinite jail We propose setting the "jail time" for a validator who commits a consensus safety fault, to `infinite` (i.e. a tombstone state). @@ -487,7 +487,7 @@ will make the `slashing` module way simpler, especially because we can remove al of the hooks defined in the `slashing` module consumed by the `staking` module (the `slashing` module still consumes hooks defined in `staking`). -### Single slashing amount +#### Single slashing amount Another optimization that can be made is that if we assume that all ABCI faults for Tendermint consensus are slashed at the same level, we don't have to keep @@ -509,7 +509,7 @@ want to slash them equally, and thus we can enact the above change. > not for a different consensus algorithm or future versions of Tendermint that > may want to punish at different levels (for example, partial slashing). -# Parameters +## Parameters The slashing module contains the following parameters: @@ -521,11 +521,11 @@ The slashing module contains the following parameters: | SlashFractionDoubleSign | string (dec) | "0.050000000000000000" | | SlashFractionDowntime | string (dec) | "0.010000000000000000" | -# CLI +## CLI A user can query and interact with the `slashing` module using the CLI. -## Query +### Query The `query` commands allow users to query `slashing` state. @@ -533,7 +533,7 @@ The `query` commands allow users to query `slashing` state. simd query slashing --help ``` -### params +#### params The `params` command allows users to query genesis parameters for the slashing module. @@ -557,7 +557,7 @@ 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. @@ -583,7 +583,7 @@ start_height: "0" tombstoned: false ``` -### signing-infos +#### signing-infos The `signing-infos` command allows users to query signing infos of all validators. @@ -612,7 +612,7 @@ pagination: total: "0" ``` -## Transactions +### Transactions The `tx` commands allow users to interact with the `slashing` module. @@ -620,7 +620,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. @@ -634,11 +634,11 @@ Example: simd tx slashing unjail --from mykey ``` -## gRPC +### gRPC A user can query the `slashing` module using gRPC endpoints. -### Params +#### Params The `Params` endpoint allows users to query the parameters of slashing module. @@ -666,7 +666,7 @@ Example Output: } ``` -### SigningInfo +#### SigningInfo The SigningInfo queries the signing info of given cons address. @@ -692,7 +692,7 @@ Example Output: } ``` -### SigningInfos +#### SigningInfos The SigningInfos queries signing info of all validators. @@ -723,11 +723,11 @@ Example Output: } ``` -## REST +### REST A user can query the `slashing` module using REST endpoints. -### Params +#### Params ```shell /cosmos/slashing/v1beta1/params @@ -752,7 +752,7 @@ Example Output: } ``` -### signing_info +#### signing_info ```shell /cosmos/slashing/v1beta1/signing_infos/%s @@ -779,7 +779,7 @@ Example Output: } ``` -### signing_infos +#### signing_infos ```shell /cosmos/slashing/v1beta1/signing_infos diff --git a/x/staking/README.md b/x/staking/README.md index 0e4b87a09ad7..98097a6f4759 100644 --- a/x/staking/README.md +++ b/x/staking/README.md @@ -57,33 +57,33 @@ network. * [gRPC](#grpc) * [REST](#rest) -# State +## State -## Pool +### Pool Pool is used for tracking bonded and not-bonded token supply of the bond denomination. -## LastTotalPower +### LastTotalPower 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(math.Int)` -## ValidatorUpdates +### ValidatorUpdates ValidatorUpdates contains the validator updates returned to ABCI at the end of every block. The values are overwritten in every block. * ValidatorUpdates `0x61 -> []abci.ValidatorUpdate` -## UnbondingID +### UnbondingID UnbondingID stores the ID of the latest unbonding operation. It enables to create unique IDs for unbonding operation, i.e., UnbondingID is incremented every time a new unbonding operation (validator unbonding, unbonding delegation, redelegation) is initiated. * UnbondingID: `0x37 -> uint64` -## Params +### Params The staking module stores its params in state with the prefix of `0x51`, it can be updated with governance or the address with authority. @@ -94,7 +94,7 @@ it can be updated with governance or the address with authority. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L285-L306 ``` -## Validator +### Validator Validators can have one of three statuses @@ -157,7 +157,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/s https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L76 ``` -## Delegation +### Delegation Delegations are identified by combining `DelegatorAddr` (the address of the delegator) with the `ValidatorAddr` Delegators are indexed in the store as follows: @@ -173,7 +173,7 @@ the transaction is the owner of the bond. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L187-L205 ``` -### Delegator Shares +#### Delegator Shares When one Delegates tokens to a Validator they are issued a number of delegator shares based on a dynamic exchange rate, calculated as follows from the total number of tokens delegated to the @@ -192,7 +192,7 @@ this mechanism is to simplify the accounting around slashing. Rather than iterat tokens of every delegation entry, instead the Validators total bonded tokens can be slashed, effectively reducing the value of each issued delegator share. -## UnbondingDelegation +### UnbondingDelegation Shares in a `Delegation` can be unbonded, but they must for some time exist as an `UnbondingDelegation`, where shares can be reduced if Byzantine behavior is @@ -221,7 +221,7 @@ A UnbondingDelegation object is created every time an unbonding is initiated. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L207-L220 ``` -## Redelegation +### Redelegation The bonded tokens worth of a `Delegation` may be instantly redelegated from a source validator to a different validator (destination validator). However when @@ -263,7 +263,7 @@ A redelegation object is created every time a redelegation occurs. To prevent https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L245-L283 ``` -## Queues +### Queues All queues objects are sorted by timestamp. The time used within any queue is first rounded to the nearest nanosecond then sorted. The sortable time format @@ -276,7 +276,7 @@ used is a slight modification of the RFC3339Nano and uses the format string In all cases, the stored timestamp represents the maturation time of the queue element. -### UnbondingDelegationQueue +#### UnbondingDelegationQueue For the purpose of tracking progress of unbonding delegations the unbonding delegations queue is kept. @@ -287,7 +287,7 @@ delegations queue is kept. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L151-L161 ``` -### RedelegationQueue +#### RedelegationQueue For the purpose of tracking progress of redelegations the redelegation queue is kept. @@ -298,7 +298,7 @@ kept. https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/staking/v1beta1/staking.proto#L168-L179 ``` -### ValidatorQueue +#### ValidatorQueue For the purpose of tracking progress of unbonding validators the validator queue is kept. @@ -310,7 +310,7 @@ which the validator object can be accessed. Typically it is expected that only a single validator record will be associated with a given timestamp however it is possible that multiple validators exist in the queue at the same location. -## HistoricalInfo +### HistoricalInfo 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`. @@ -325,15 +325,9 @@ they are in a deterministic order. The oldest HistoricalEntries will be pruned to ensure that there only exist the parameter-defined number of historical entries. -# State Transitions - -This document describes the state transition operations pertaining to: +## State Transitions -1. [Validators](#validators) -2. [Delegations](#delegations) -3. [Slashing](#slashing) - -## Validators +### Validators State transitions in validators are performed on every [`EndBlock`](#validator-set-changes) in order to check for changes in the active `ValidatorSet`. @@ -342,7 +336,7 @@ A validator can be `Unbonded`, `Unbonding` or `Bonded`. `Unbonded` and `Unbonding` are collectively called `Not Bonded`. A validator can move directly between all the states, except for from `Bonded` to `Unbonded`. -### Not bonded to Bonded +#### Not bonded to Bonded The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses that of the `LastValidator`. @@ -354,7 +348,7 @@ that of the `LastValidator`. * update the `Validator` object for this validator * if it exists, delete any `ValidatorQueue` record for this validator -### Bonded to Unbonding +#### Bonded to Unbonding When a validator begins the unbonding process the following operations occur: @@ -365,7 +359,7 @@ When a validator begins the unbonding process the following operations occur: * update the `Validator` object for this validator * insert a new record into the `ValidatorQueue` for this validator -### Unbonding to Unbonded +#### Unbonding to Unbonded A validator moves from unbonding to unbonded when the `ValidatorQueue` object moves from bonded to unbonded @@ -373,7 +367,7 @@ moves from bonded to unbonded * update the `Validator` object for this validator * set `validator.Status` to `Unbonded` -### Jail/Unjail +#### 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: @@ -386,9 +380,9 @@ Jailed validators are not present in any of the following stores: * the power store (from consensus power to address) -## Delegations +### Delegations -### Delegate +#### Delegate When a delegation occurs both the validator and the delegation objects are affected @@ -400,7 +394,7 @@ When a delegation occurs both the validator and the delegation objects are affec * delete the existing record from `ValidatorByPowerIndex` * add an new updated record to the `ValidatorByPowerIndex` -### Begin Unbonding +#### Begin Unbonding As a part of the Undelegate and Complete Unbonding state transitions Unbond Delegation may be called. @@ -418,7 +412,7 @@ Delegation may be called. * call the `AfterUnbondingInitiated(unbondingId)` hook * add the unbonding delegation to `UnbondingDelegationQueue` with the completion time set to `UnbondingTime` -### Cancel an `UnbondingDelegation` Entry +#### Cancel an `UnbondingDelegation` Entry When a `cancel unbond delegation` occurs both the `validator`, the `delegation` and an `UnbondingDelegationQueue` state will be updated. @@ -426,7 +420,7 @@ When a `cancel unbond delegation` occurs both the `validator`, the `delegation` * if the `cancel unbonding delegation amount is less than the `UnbondingDelegation` entry balance, then the `UnbondingDelegation` entry will be updated with new balance in the `UnbondingDelegationQueue`. * cancel `amount` is [Delegated](#delegations) back to the original `validator`. -### Complete Unbonding +#### Complete Unbonding For undelegations which do not complete immediately, the following operations occur when the unbonding delegation queue element matures: @@ -434,7 +428,7 @@ 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` -### Begin Redelegation +#### Begin Redelegation Redelegations affect the delegation, source and destination validators. @@ -449,15 +443,15 @@ Redelegations affect the delegation, source and destination validators. 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 occurred before the redelegation began. -### Complete Redelegation +#### Complete Redelegation When a redelegations complete the following occurs: * remove the entry from the `Redelegation` object -## Slashing +### Slashing -### Slash Validator +#### Slash Validator When a Validator is slashed, the following occurs: @@ -474,14 +468,14 @@ In the case of a slash due to any infraction that requires evidence to submitted occurs at the block where the evidence is included, not at the block where the infraction occured. Put otherwise, validators are not slashed retroactively, only when they are caught. -### Slash Unbonding Delegation +#### Slash Unbonding Delegation When a validator is slashed, so are those unbonding delegations from the validator that began unbonding after the time of the infraction. Every entry in every unbonding delegation from the validator is slashed by `slashFactor`. The amount slashed is calculated from the `InitialBalance` of the delegation and is capped to prevent a resulting negative balance. Completed (or mature) unbondings are not slashed. -### Slash Redelegation +#### Slash Redelegation When a validator is slashed, so are all redelegations from the validator that began after the infraction. Redelegations are slashed by `slashFactor`. @@ -490,7 +484,7 @@ The amount slashed is calculated from the `InitialBalance` of the delegation and prevent a resulting negative balance. Mature redelegations (that have completed pseudo-unbonding) are not slashed. -## How Shares are calculated +### How Shares are calculated At any given point in time, each validator has a number of tokens, `T`, and has a number of shares issued, `S`. Each delegator, `i`, holds a number of shares, `S_i`. @@ -508,11 +502,11 @@ A special case is the initial delegation, when `T = 0` and `S = 0`, so `T_j / T` For the initial delegation, delegator `j` who delegates `T_j` tokens receive `S_j = T_j` shares. So a validator that hasn't received any rewards and has not been slashed will have `T = S`. -# Messages +## Messages In this section we describe the processing of the staking messages and the corresponding updates to the state. All created/modified state objects specified by each message are defined within the [state](#state) section. -## MsgCreateValidator +### MsgCreateValidator A validator is created using the `MsgCreateValidator` message. The validator must be created with an initial delegation from the operator. @@ -541,7 +535,7 @@ Additionally a self-delegation is made with the initial tokens delegation tokens `Delegation`. The validator always starts as unbonded but may be bonded in the first end-block. -## MsgEditValidator +### MsgEditValidator The `Description`, `CommissionRate` of a validator can be updated using the `MsgEditValidator` message. @@ -563,7 +557,7 @@ This message is expected to fail if: This message stores the updated `Validator` object. -## MsgDelegate +### MsgDelegate Within this message the delegator provides coins, and in return receives some amount of their validator's (newly created) delegator-shares that are @@ -600,7 +594,7 @@ will not be added to the power index until it is unjailed. ![Delegation sequence](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/delegation_sequence.svg) -## MsgUndelegate +### MsgUndelegate The `MsgUndelegate` message allows delegators to undelegate their tokens from validator. @@ -640,7 +634,7 @@ When this message is processed the following actions occur: ![Unbond sequence](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/unbond_sequence.svg) -## MsgCancelUnbondingDelegation +### MsgCancelUnbondingDelegation The `MsgCancelUnbondingDelegation` message allows delegators to cancel the `unbondingDelegation` entry and delegate back to a previous validator. @@ -665,7 +659,7 @@ When this message is processed the following actions occur: * otherwise `unbondingDelegationQueue` will be updated with new `unbondingDelegation` entry balance and initial balance * the validator's `DelegatorShares` and the delegation's `Shares` are both increased by the message `Amount`. -## MsgBeginRedelegate +### MsgBeginRedelegate The redelegation command allows delegators to instantly switch validators. Once the unbonding period has passed, the redelegation is automatically completed in @@ -709,7 +703,7 @@ When this message is processed the following actions occur: ![Begin redelegation sequence](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/begin_redelegation_sequence.svg) -## MsgUpdateParams +### MsgUpdateParams The `MsgUpdateParams` update the staking module parameters. The params are updated through a governance proposal where the signer is the gov module account address. @@ -722,12 +716,12 @@ The message handling can fail if: * signer is not the authority defined in the staking keeper (usually the gov module account). -# Begin-Block +## Begin-Block Each abci begin block call, the historical info will get stored and pruned according to the `HistoricalEntries` parameter. -## Historical Info Tracking +### Historical Info Tracking If the `HistoricalEntries` parameter is 0, then the `BeginBlock` performs a no-op. @@ -735,12 +729,12 @@ Otherwise, the latest historical info is stored under the key `historicalInfoKey In most cases, this results in a single entry being pruned per block. However, if the parameter `HistoricalEntries` has changed to a lower value there will be multiple entries in the store that must be pruned. -# End-Block +## End-Block Each abci end block call, the operations to update queues and validator set changes are specified to execute. -## Validator Set Changes +### Validator Set Changes The staking validator set is updated during this process by state transitions that run at the end of every block. As a part of this process any updated @@ -765,7 +759,7 @@ and validator power from the end of the last block, and are used to check for changes that have occurred in `ValidatorsByPower` and the total new power, which is calculated during `EndBlock`. -## Queues +### Queues Within staking, certain state-transitions are not instantaneous but take place over a duration of time (typically the unbonding period). When these @@ -773,7 +767,7 @@ transitions are mature certain operations must take place in order to complete the state operation. This is achieved through the use of queues which are checked/processed at the end of each block. -### Unbonding Validators +#### Unbonding Validators When a validator is kicked out of the bonded validator set (either through being jailed, or not having sufficient bonded tokens) it begins the unbonding @@ -796,7 +790,7 @@ Unbonding operations can be put on hold by external modules via the `PutUnbondin (after it reaches maturity), every call to `PutUnbondingOnHold(unbondingId)` must be matched by a call to `UnbondingCanComplete(unbondingId)`. -### Unbonding Delegations +#### Unbonding Delegations Complete the unbonding of all mature `UnbondingDelegations.Entries` within the `UnbondingDelegations` queue with the following procedure: @@ -806,7 +800,7 @@ Complete the unbonding of all mature `UnbondingDelegations.Entries` within the * remove the `UnbondingDelegation` object from the store if there are no remaining entries. -### Redelegations +#### Redelegations Complete the unbonding of all mature `Redelegation.Entries` within the `Redelegations` queue with the following procedure: @@ -815,7 +809,7 @@ Complete the unbonding of all mature `Redelegation.Entries` within the * remove the `Redelegation` object from the store if there are no remaining entries. -# Hooks +## Hooks Other modules may register operations to execute when a certain event has occurred within staking. These events can be registered to execute either @@ -844,11 +838,11 @@ following hooks can registered with staking: * called when an unbonding operation (validator unbonding, unbonding delegation, redelegation) was initiated -# Events +## Events The staking module emits the following events: -## EndBlocker +### EndBlocker | Type | Attribute Key | Attribute Value | | --------------------- | --------------------- | ------------------------- | @@ -931,7 +925,7 @@ The staking module emits the following events: * [0] Time is formatted in the RFC3339 standard -# Parameters +## Parameters The staking module contains the following parameters: @@ -944,13 +938,13 @@ The staking module contains the following parameters: | BondDenom | string | "stake" | | MinCommissionRate | string | "0.000000000000000000" | -# Client +## Client -## CLI +### CLI A user can query and interact with the `staking` module using the CLI. -### Query +#### Query The `query` commands allows users to query `staking` state. @@ -958,7 +952,7 @@ The `query` commands allows users to query `staking` state. simd query staking --help ``` -#### delegation +##### delegation The `delegation` command allows users to query delegations for an individual delegator on an individual validator. @@ -986,7 +980,7 @@ delegation: validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj ``` -#### delegations +##### delegations The `delegations` command allows users to query delegations for an individual delegator on all validators. @@ -1025,7 +1019,7 @@ pagination: total: "0" ``` -#### delegations-to +##### delegations-to The `delegations-to` command allows users to query delegations on an individual validator. @@ -1063,7 +1057,7 @@ pagination: total: "0" ``` -#### historical-info +##### historical-info The `historical-info` command allows users to query historical information at given height. @@ -1129,7 +1123,7 @@ valset: unbonding_time: "1970-01-01T00:00:00Z" ``` -#### params +##### params The `params` command allows users to query values set as staking parameters. @@ -1155,7 +1149,7 @@ max_validators: 50 unbonding_time: 1814400s ``` -#### pool +##### pool The `pool` command allows users to query values for amounts stored in the staking pool. @@ -1178,7 +1172,7 @@ bonded_tokens: "10000000" not_bonded_tokens: "0" ``` -#### redelegation +##### redelegation The `redelegation` command allows users to query a redelegation record based on delegator and a source and destination validator address. @@ -1219,7 +1213,7 @@ redelegation_responses: validator_src_address: cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm ``` -#### redelegations +##### redelegations The `redelegations` command allows users to query all redelegation records for an individual delegator. @@ -1274,7 +1268,7 @@ redelegation_responses: validator_src_address: cosmosvaloper1zppjyal5emta5cquje8ndkpz0rs046m7zqxrpp ``` -#### redelegations-from +##### redelegations-from The `redelegations-from` command allows users to query delegations that are redelegating _from_ a validator. @@ -1329,7 +1323,7 @@ redelegation_responses: validator_src_address: cosmosvaloper1y4rzzrgl66eyhzt6gse2k7ej3zgwmngeleucjy ``` -#### unbonding-delegation +##### unbonding-delegation The `unbonding-delegation` command allows users to query unbonding delegations for an individual delegator on an individual validator. @@ -1357,7 +1351,7 @@ entries: validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj ``` -#### unbonding-delegations +##### unbonding-delegations The `unbonding-delegations` command allows users to query all unbonding-delegations records for one delegator. @@ -1390,7 +1384,7 @@ unbonding_responses: ``` -#### unbonding-delegations-from +##### unbonding-delegations-from The `unbonding-delegations-from` command allows users to query delegations that are unbonding _from_ a validator. @@ -1429,7 +1423,7 @@ unbonding_responses: validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj ``` -#### validator +##### validator The `validator` command allows users to query details about an individual validator. @@ -1476,7 +1470,7 @@ unbonding_height: "0" unbonding_time: "1970-01-01T00:00:00Z" ``` -#### validators +##### validators The `validators` command allows users to query details about all validators on a network. @@ -1553,7 +1547,7 @@ description: unbonding_time: "1970-01-01T00:00:00Z" ``` -### Transactions +#### Transactions The `tx` commands allows users to interact with the `staking` module. @@ -1561,7 +1555,7 @@ The `tx` commands allows users to interact with the `staking` module. simd tx staking --help ``` -#### create-validator +##### create-validator The command `create-validator` allows users to create new validator initialized with a self-delegation to it. @@ -1591,7 +1585,7 @@ simd tx staking create-validator \ --from=mykey ``` -#### delegate +##### delegate The command `delegate` allows users to delegate liquid tokens to a validator. @@ -1607,7 +1601,7 @@ Example: simd tx staking delegate cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm 1000stake --from mykey ``` -#### edit-validator +##### edit-validator The command `edit-validator` allows users to edit an existing validator account. @@ -1623,7 +1617,7 @@ Example: simd tx staking edit-validator --moniker "new_moniker_name" --website "new_webiste_url" --from mykey ``` -#### redelegate +##### redelegate The command `redelegate` allows users to redelegate illiquid tokens from one validator to another. @@ -1639,7 +1633,7 @@ Example: simd tx staking redelegate cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm 100stake --from mykey ``` -#### unbond +##### unbond The command `unbond` allows users to unbond shares from a validator. @@ -1655,7 +1649,7 @@ Example: simd tx staking unbond cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj 100stake --from mykey ``` -#### cancel unbond +##### cancel unbond The command `cancel-unbond` allow users to cancel the unbonding delegation entry and delegate back to the original validator. @@ -1672,11 +1666,11 @@ simd tx staking cancel-unbond cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhf ``` -## gRPC +### gRPC A user can query the `staking` module using gRPC endpoints. -### Validators +#### Validators The `Validators` endpoint queries all validators that match the given status. @@ -1722,7 +1716,7 @@ Example Output: } ``` -### Validator +#### Validator The `Validator` endpoint queries validator information for given validator address. @@ -1764,7 +1758,7 @@ Example Output: } ``` -### ValidatorDelegations +#### ValidatorDelegations The `ValidatorDelegations` endpoint queries delegate information for given validator. @@ -1802,7 +1796,7 @@ Example Output: } ``` -### ValidatorUnbondingDelegations +#### ValidatorUnbondingDelegations The `ValidatorUnbondingDelegations` endpoint queries delegate information for given validator. @@ -1854,7 +1848,7 @@ Example Output: } ``` -### Delegation +#### Delegation The `Delegation` endpoint queries delegate information for given validator delegator pair. @@ -1891,7 +1885,7 @@ Example Output: } ``` -### UnbondingDelegation +#### UnbondingDelegation The `UnbondingDelegation` endpoint queries unbonding information for given validator delegator. @@ -1932,7 +1926,7 @@ Example Output: } ``` -### DelegatorDelegations +#### DelegatorDelegations The `DelegatorDelegations` endpoint queries all delegations of a given delegator address. @@ -1962,7 +1956,7 @@ Example Output: } ``` -### DelegatorUnbondingDelegations +#### DelegatorUnbondingDelegations The `DelegatorUnbondingDelegations` endpoint queries all unbonding delegations of a given delegator address. @@ -2009,7 +2003,7 @@ Example Output: } ``` -### Redelegations +#### Redelegations The `Redelegations` endpoint queries redelegations of given address. @@ -2054,7 +2048,7 @@ Example Output: } ``` -### DelegatorValidators +#### DelegatorValidators The `DelegatorValidators` endpoint queries all validators information for given delegator. @@ -2112,7 +2106,7 @@ Example Output: } ``` -### DelegatorValidator +#### DelegatorValidator The `DelegatorValidator` endpoint queries validator information for given delegator validator @@ -2164,7 +2158,7 @@ Example Output: } ``` -### HistoricalInfo +#### HistoricalInfo ```bash cosmos.staking.v1beta1.Query/HistoricalInfo @@ -2242,7 +2236,7 @@ Example Output: ``` -### Pool +#### Pool The `Pool` endpoint queries the pool information. @@ -2267,7 +2261,7 @@ Example Output: } ``` -### Params +#### Params The `Params` endpoint queries the pool information. @@ -2295,11 +2289,11 @@ Example Output: } ``` -## REST +### REST A user can query the `staking` module using REST endpoints. -### DelegatorDelegations +#### DelegatorDelegations The `DelegtaorDelegations` REST endpoint queries all delegations of a given delegator address. @@ -2348,7 +2342,7 @@ Example Output: } ``` -### Redelegations +#### Redelegations The `Redelegations` REST endpoint queries redelegations of given address. @@ -2393,7 +2387,7 @@ Example Output: } ``` -### DelegatorUnbondingDelegations +#### DelegatorUnbondingDelegations The `DelegatorUnbondingDelegations` REST endpoint queries all unbonding delegations of a given delegator address. @@ -2434,7 +2428,7 @@ Example Output: } ``` -### DelegatorValidators +#### DelegatorValidators The `DelegatorValidators` REST endpoint queries all validators information for given delegator address. @@ -2492,7 +2486,7 @@ Example Output: } ``` -### DelegatorValidator +#### DelegatorValidator The `DelegatorValidator` REST endpoint queries validator information for given delegator validator pair. @@ -2544,7 +2538,7 @@ Example Output: } ``` -### HistoricalInfo +#### HistoricalInfo The `HistoricalInfo` REST endpoint queries the historical information for given height. @@ -2652,7 +2646,7 @@ Example Output: } ``` -### Parameters +#### Parameters The `Parameters` REST endpoint queries the staking parameters. @@ -2680,7 +2674,7 @@ Example Output: } ``` -### Pool +#### Pool The `Pool` REST endpoint queries the pool information. @@ -2705,7 +2699,7 @@ Example Output: } ``` -### Validators +#### Validators The `Validators` REST endpoint queries all validators that match the given status. @@ -2790,7 +2784,7 @@ Example Output: } ``` -### Validator +#### Validator The `Validator` REST endpoint queries validator information for given validator address. @@ -2842,7 +2836,7 @@ Example Output: } ``` -### ValidatorDelegations +#### ValidatorDelegations The `ValidatorDelegations` REST endpoint queries delegate information for given validator. @@ -2924,7 +2918,7 @@ Example Output: } ``` -### Delegation +#### Delegation The `Delegation` REST endpoint queries delegate information for given validator delegator pair. @@ -2958,7 +2952,7 @@ Example Output: } ``` -### UnbondingDelegation +#### UnbondingDelegation The `UnbondingDelegation` REST endpoint queries unbonding information for given validator delegator pair. @@ -2993,7 +2987,7 @@ Example Output: } ``` -### ValidatorUnbondingDelegations +#### ValidatorUnbondingDelegations The `ValidatorUnbondingDelegations` REST endpoint queries unbonding delegations of a validator. diff --git a/x/upgrade/README.md b/x/upgrade/README.md index 7e682fb4bcb2..7e6ddfa135fe 100644 --- a/x/upgrade/README.md +++ b/x/upgrade/README.md @@ -27,9 +27,9 @@ recover from. * [gRPC](#grpc) * [Resources](#resources) -# Concepts +## Concepts -## Plan +### Plan The `x/upgrade` module defines a `Plan` type in which a live upgrade is scheduled to occur. A `Plan` can be scheduled at a specific block height. @@ -41,7 +41,7 @@ may contain various metadata about the upgrade, typically application specific upgrade info to be included on-chain such as a git commit that validators could automatically upgrade to. -### Sidecar Process +#### Sidecar Process If an operator running the application binary also runs a sidecar process to assist in the automatic download and upgrade of a binary, the `Info` allows this process to @@ -55,7 +55,7 @@ type Plan struct { } ``` -## Handler +### Handler The `x/upgrade` module facilitates upgrading from major version X to major version Y. To accomplish this, node operators must first upgrade their current binary to a new @@ -75,7 +75,7 @@ During each `EndBlock` execution, the `x/upgrade` module checks if there exists `Handler` is executed. If the `Plan` is expected to execute but no `Handler` is registered or if the binary was upgraded too early, the node will gracefully panic and exit. -## StoreLoader +### StoreLoader The `x/upgrade` module also facilitates store migrations as part of the upgrade. The `StoreLoader` sets the migrations that need to occur before the new binary can @@ -94,7 +94,7 @@ expected upgrade. It eliminiates the chances for the new binary to execute `Stor times everytime on restart. Also if there are multiple upgrades planned on same height, the `Name` will ensure these `StoreUpgrades` takes place only in planned upgrade handler. -## Proposal +### Proposal Typically, a `Plan` is proposed and submitted through governance via a proposal containing a `MsgSoftwareUpgrade` message. @@ -106,7 +106,7 @@ upgrade can be delayed or hastened by updating the `Plan.Height` in a new propos https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/proto/cosmos/upgrade/v1beta1/tx.proto#L24-L36 ``` -### Cancelling Upgrade Proposals +#### Cancelling Upgrade Proposals Upgrade proposals can be cancelled. There exists a gov-enabled `MsgCancelUpgrade` message type, which can be embedded in a proposal, voted on and, if passed, will @@ -127,7 +127,7 @@ A `MsgCancelUpgrade` proposal can also be made while the original `MsgSoftwareUpgrade` proposal is still being voted upon, as long as the `VotingPeriod` ends after the `MsgSoftwareUpgrade` proposal. -# State +## State The internal state of the `x/upgrade` module is relatively minimal and simple. The state contains the currently active upgrade `Plan` (if one exists) by key @@ -144,18 +144,18 @@ by the corresponding module name of type `string`. The state maintains a The `x/upgrade` module contains no genesis state. -# Events +## Events The `x/upgrade` does not emit any events by itself. Any and all proposal related events are emitted through the `x/gov` module. -# Client +## Client -## CLI +### CLI A user can query and interact with the `upgrade` module using the CLI. -### Query +#### Query The `query` commands allow users to query `upgrade` state. @@ -163,7 +163,7 @@ The `query` commands allow users to query `upgrade` state. simd query upgrade --help ``` -#### applied +##### applied The `applied` command allows users to query the block header for height at which a completed upgrade was applied. @@ -219,7 +219,7 @@ Example Output: } ``` -#### module versions +##### module versions The `module_versions` command gets a list of module names and their respective consensus versions. @@ -292,7 +292,7 @@ module_versions: version: "2" ``` -#### plan +##### plan The `plan` command gets the currently scheduled upgrade plan, if one exists. @@ -316,11 +316,11 @@ time: "0001-01-01T00:00:00Z" upgraded_client_state: null ``` -## REST +### REST A user can query the `upgrade` module using REST endpoints. -### Applied Plan +#### Applied Plan `AppliedPlan` queries a previously applied upgrade plan by its name. @@ -342,7 +342,7 @@ Example Output: } ``` -### Current Plan +#### Current Plan `CurrentPlan` queries the current upgrade plan. @@ -364,7 +364,7 @@ Example Output: } ``` -### Module versions +#### Module versions `ModuleVersions` queries the list of module versions from state. @@ -459,11 +459,11 @@ Example Output: } ``` -## gRPC +### gRPC A user can query the `upgrade` module using gRPC endpoints. -### Applied Plan +#### Applied Plan `AppliedPlan` queries a previously applied upgrade plan by its name. @@ -488,7 +488,7 @@ Example Output: } ``` -### Current Plan +#### Current Plan `CurrentPlan` queries the current upgrade plan. @@ -510,7 +510,7 @@ Example Output: } ``` -### Module versions +#### Module versions `ModuleVersions` queries the list of module versions from state. @@ -605,7 +605,7 @@ Example Output: } ``` -# Resources +## Resources A list of (external) resources to learn more about the `x/upgrade` module.