diff --git a/SUMMARY.md b/SUMMARY.md index 767acbaf..2c8b1807 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -128,10 +128,7 @@ * [Modules](cronos-chain-protocol/module\_overview/README.md) * [module\_bank](cronos-chain-protocol/module\_overview/module\_bank.md) * [module\_distribution](cronos-chain-protocol/module\_overview/module\_distribution.md) - * [module\_gov](cronos-chain-protocol/module\_overview/module\_gov.md) - * [module\_mint](cronos-chain-protocol/module\_overview/module\_mint.md) * [module\_slashing](cronos-chain-protocol/module\_overview/module\_slashing.md) - * [module\_staking](cronos-chain-protocol/module\_overview/module\_staking.md) * [module\_feemarket](cronos-chain-protocol/module\_overview/module\_feemarket.md) * [Chain Details](cronos-chain-protocol/chain-details/README.md) * [List of parameters](cronos-chain-protocol/chain-details/parameters.md) diff --git a/cronos-chain-protocol/module_overview/module_gov.md b/cronos-chain-protocol/module_overview/module_gov.md deleted file mode 100644 index e40330d0..00000000 --- a/cronos-chain-protocol/module_overview/module_gov.md +++ /dev/null @@ -1,195 +0,0 @@ -# module\_gov - -#### `gov` module - -#### Introduction - -The `gov` module enables on-chain governance which allows Crypto.org Chain token holder to participate in the decision-making processes. For example, users can: - -* Form an idea and seek the feedback; -* Create the proposal and adjust according to feedback as needed; -* Submit a proposal along with an initial deposit; -* Deposit tokens and fund an active proposal; -* Vote for an active proposal. - -The details about the governance proposal process are available on [The Proposal Process page](https://crypto.org/docs/chain-details/govprocess.html). - -#### Overview - -**Network parameters** - -Below are all the network parameters for the `gov` module: - -* `deposit_params` - Deposit related parameters: - * `min_deposit`: Minimum deposit for a proposal to enter voting period; and - * `max_deposit_period`: Maximum period for Cro holders to deposit on a proposal. -* `voting_params` - Voting related parameters - * `voting_period`: The length of the voting period. -* `tally_params` - Tally related parameters - * `quorum`: The minimum percentage of voting power that needs to be casted on a proposal for the result to be valid; - * `threshold`: Minimum proportion of `Yes` votes (excluding `Abstain` votes) for the proposal to be accepted; and - * `veto`: Minimum proportion of `Veto` votes to total votes ratio for proposal to be vetoed. - -**The Governance Procedure** - -**Phase 0 - Submit a proposal along with an initial deposit:** - -Users can submit a proposal with an initial deposit. The proposal will then become "active" and entre the _deposit period_. - -**Phase 1 - Deposit period** - -During the _deposit period_, users can deposit and support an active proposal. Once the deposit of the proposal reached `min_deposit`, it will enter the _voting period_. Otherwise, if the proposal is not successfully funded within `max_deposit_period`, it will become inactive and the deposit will not be refunded. - -**Phase 2 - Voting period** - -During the _voting period_, staked (bonded) token will be able to participate in the voting. Users can choose one of the following option: `"yes"`, `"no"`, `"no_with_veto"` and `"abstain"` - -After the `voting_period` has passed, there are several scenarios that a proposal will consider to be fail, for example, if - -* No one votes (everyone `"abstain"`); -* Votes did not reach the `quorum`; -* More than `veto` of voters vote for `"no_with_veto"`; -* More than `threshold` that non-abstaining voters vote `"no"`. - -Otherwise, the proposal will be accepted and changes will be implemented according to the proposal. - -#### Transactions and Queries - -#### Transactions - -**`tx gov submit-proposal` - Submit a proposal along with an initial deposit** - -* Submit a parameter change proposal - `param-change [proposal-file]` - - Users can submit a proposal to modify network parameters during run time, here is a demon proposal if we would like to change the parameter `MaxValidators` (maximum number of validator) in the `staking` module, - - ```json - { - "title": "Staking Param Change", - "description": "Update max validators", - "changes": [ - { - "subspace": "staking", - "key": "MaxValidators", - "value": 151 - } - ] - } - ``` -* Submit a community pool spend proposal - `community-pool-spend [proposal-file]` - - Users can submit a proposal and request funds from the community pool to support their projects or other usages. -* Submit a software upgrade proposal- `software-upgrade [name] (--upgrade-height [height] | --upgrade-time [time]) (--upgrade-info [info])` - - Users can submit an upgrade proposal and suggest a software upgrade at a specific block height. -* Cancel the current software upgrade proposal - `cancel-software-upgrade` - - On the other hand, users can submit a proposal to cancel the planned software upgrade. - -**`tx gov deposit [proposal-id] [deposit]` - Deposit tokens for an active proposal** - -Users can submit a deposit transaction to fund and support an active proposal. - -**`tx gov vote [proposal-id] [option]` - Vote for an active proposal** - -Users can vote for an active proposal. Valid value of `"option"` field can be `"yes"`, `"no"`, `"no_with_veto"` and `"abstain"`. - -#### Queries - -**`query gov proposals [proposal-id]` - Query proposals with optional filters** - -We can check the proposal with optional filters by: - -```json -$ cronosd query gov proposals -o json | jq -``` - -**`query gov proposal [proposal-id]` Query details of a single proposal** - -Similarly, we can check the details of a proposal with a given `"proposal_id"`. - -**`query gov tally [proposal-id]` Get the tally of a proposal vote** - -We can also the tally of a proposal with a given `"proposal_id"`. - -**`query gov params` - Query the current gov parameters** - -We can query the current gov parameters by - -```json -$ cronosd query gov params --output json | jq - -{ - "voting_params": { - "voting_period": "172800000000000" - }, - "tally_params": { - "quorum": "0.334000000000000000", - "threshold": "0.500000000000000000", - "veto_threshold": "0.334000000000000000" - }, - "deposit_params": { - "min_deposit": [ - { - "denom": "basetcro", - "amount": "10000000" - } - ], - "max_deposit_period": "172800000000000" - } -} -``` - - - -**REST endpoint** - -The parameters can also be checked by browsing to the following REST endpoint on Mainnet: - -[https://rest.cronos.org/cosmos/gov/v1beta1/params](https://rest.cronos.org/cosmos/bank/v1beta1/params)/{params\_type} - -where the `params_type` can be one of "voting", "tallying" or "deposit". - - - -{% code title="e.g. voting" %} -```json -{ - "voting_params": { - "voting_period": "259200s" - }, - "deposit_params": { - "min_deposit": [ - ], - "max_deposit_period": "0s" - }, - "tally_params": { - "quorum": "0.000000000000000000", - "threshold": "0.000000000000000000", - "veto_threshold": "0.000000000000000000" - } -} -``` -{% endcode %} - -#### Appendix - -**`gov` module: Network Parameters and configuration** - -The following tables show overall effects on different configurations of the gov related network parameters: - -| | `min_deposit` | `max_deposit_period` | `voting_period` | -| -------------------- | ------------------------------------------- | ---------------------------- | ---------------------------- | -| Type | array (coins) | string (time ns) | string (time ns) | -| Higher | Larger window for calculating the downtime | Longer deposit period | Longer voting period | -| Lower | Smaller window for calculating the downtime | Shorter deposit period | Shorter voting period | -| Constraints | Value has to be a positive integer | Value has to be positive | Value has to be positive | -| Sample configuration | `100000` (100000 cro) | `1209600000000000` (2 weeks) | `1209600000000000` (2 weeks) | - -| | `quorum` | `threshold` | `veto` | -| -------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------ | -| Type | string (dec) | string (dec) | string (dec) | -| Higher | Easier for a proposal to be passed | Easier for a proposal to be passed | Easier for a proposal to be passed | -| Lower | Harder for a proposal to be passed | Harder for a proposal to be passed | Harder for a proposal to be passed | -| Constraints | Value has to be less or equal to `1` | Value has to be less or equal to `1` | Value has to be less or equal to `1` | -| Sample configuration | `0.15` (15%) | `0.5` (50%) | `0.33` (33%) | diff --git a/cronos-chain-protocol/module_overview/module_mint.md b/cronos-chain-protocol/module_overview/module_mint.md deleted file mode 100644 index 805d48c4..00000000 --- a/cronos-chain-protocol/module_overview/module_mint.md +++ /dev/null @@ -1,99 +0,0 @@ -# module\_mint - -#### `mint` module - -#### Introduction - -The `mint` module is responsible for creating token in a flexible way to reward the validator who participate in the proof of stake consensus process (see also the [distribution module](module\_distribution.md)). It is also designed in a way to bring a balance between market liquidity and staked supply. - -#### Overview - -**Network parameters** - -Below are all the network parameters for the `mint` module: - -* `"blocks_per_year"` - The expected number of blocks being produced per year; -* `"goal_bonded"` - Goal of bonded token in percentage; -* `"inflation_max"` - Maximum annual inflation rate; -* `"inflation_min"` - Minimum annual inflation rate; -* `"inflation_rate_change"` - Maximum annual change in inflation rate; -* `"mint_denom"` - Token type being minted. - -The target annual inflation rate is recalculated for each previsions cycle. The inflation is also subject to a rate change (positive or negative) depending on the distance from the desired ratio (`"goal_bonded"`). The maximum rate change possible is defined to be `"inflation_rate_change"` per year, where the annual inflation is capped as between `"inflation_min"` and `"inflation_max"`. - -#### `mint` module: Queries - -#### Queries - -**`query mint params` - Query the current minting annual provisions value** - -We can query the current minting annual provisions value, for example: - -```json - $ cronosd query mint annual-provisions - 109573801550200370 -``` - -implies that the current minting annual provisions will be `109573801550200370` basetcro ( i.e. `1,095,738,015` cro) - -**`query mint inflation` - Query the current minting inflation value** - -We can query the current minting inflation value, for example: - -```json - $ cronosd query mint inflation - 0.013687008526984104 -``` - -implies that the current minting annual provisions will be `0.013687008526984104`( i.e. `1.368%`) - -**`query mint annual-provisions` - Query the current minting parameters** - -We can query the current query parameters by - -```json -$ cronosd query mint params --output json | jq -``` - - - -**REST endpoint** - -The parameters can also be checked by browsing to the following REST endpoint on Mainnet: - -[https://rest.cronos.org/cosmos/mint/v1beta1/params](https://rest.cronos.org/cosmos/bank/v1beta1/params) - -```json -{ - "params": { - "mint_denom": "stake", - "inflation_rate_change": "0.000000000000000000", - "inflation_max": "0.000000000000000000", - "inflation_min": "0.000000000000000000", - "goal_bonded": "1.000000000000000000", - "blocks_per_year": "6311520" - } -} -``` - -#### Appendix - -**`gov` module: Network Parameters and configuration** - -The following tables show overall effects on different configurations of the mint related network parameters: - -| | `blocks_per_year` | `goal_bonded` | `mint_denom` | -| -------------------- | ---------------------------------- | ------------------------------------ | ------------ | -| Type | array (coins) | string (dec) | string | -| Higher | More expected blocks per year | Higher target bonding ratio | N/A | -| Lower | Less expected blocks per year | Lower target bonding ratio | N/A | -| Constraints | Value has to be a positive integer | Value has to be less or equal to `1` | N/A | -| Sample configuration | `5256000` (5,256,000 blocks) | `0.66` (66%) | `basetcro` | - -| | `inflation_max` | `inflation_min` | `inflation_rate_change` | -| -------------------- | ------------------------------------- | ------------------------------------ | --------------------------------------------- | -| Type | string (dec) | string (dec) | string (dec) (dec) | -| Higher | Higher ceiling for the inflation rate | Higher floor for the inflation rate | Higher yearly rate of change to the inflation | -| Lower | Lower ceiling for the inflation rate | Lower floor for the inflation rate | Lower yearly rate of change to the inflation | -| Constraints | Value has to be less or equal to `1` | Value has to be less or equal to `1` | Value has to be less or equal to `1` | -| Sample configuration | `0.02` (2%) | `0.01` (1%) | `0.01` (1%) | diff --git a/cronos-chain-protocol/module_overview/module_staking.md b/cronos-chain-protocol/module_overview/module_staking.md deleted file mode 100644 index 5770f8fd..00000000 --- a/cronos-chain-protocol/module_overview/module_staking.md +++ /dev/null @@ -1,295 +0,0 @@ -# module\_staking - -#### `staking` module - -#### Introduction - -The `staking` module handles Proof-of-Stake related logics, which plays a very import part to the underneath consensus protocol. - -#### Overview - -Crypto.org Chain is based on Tendermint Core's consensus engine, it relies on a set of validators to participate in the proof of stake (PoS) consensus protocol, and they are responsible for committing new blocks in the blockchain. - -* `unbonding_time`: The time duration of unbonding; -* `max_validators`: The maximum number of validator; -* `max_entries`: The max entries for either unbonding delegation or redelegation; -* `historical_entries`: The number of historical entries to persist; and -* `bond_denom`: Coin denomination for staking. - -#### Validator - -Validators are responsible for signing or proposing block at each consensus round. It is important that the validators maintain excellent availability and network connectivity to perform their tasks. To incentivise the validator nodes to run the network, rewards are distributed to the validators according to their performance and amount of staked token (see [distribution](module\_distribution.md) and [mint](module\_mint.md)). On the other hand, a penalty should be imposed on validators' misbehavior (see [slashing](module\_slashing.md)). - -#### Delegator - -The `staking` module enables CRO owners to delegate their tokens to active validators and share part of the reward obtained by the validator during the proof of stake protocol(see [distribution](module\_distribution.md) module). Specifically, It allows token owners to take part in the consensus process without running a validator themselves. - -It is important to point out that the delegator and the validator are on the same boat: They share the reward and the risk. In particular, part of their delegated token could be slashed due to validator's misbehaviour (see [slashing](module\_slashing.md)). Therefore, It is very important to choose a reliable validator to delegate. Kindly refer to this [link](https://docs.cosmos.network/v0.40/modules/staking/02\_state\_transitions.html#delegations) for detailed specification and state transitions of delegation. - -#### Transactions and Queries - -#### Transactions - -**`tx staking create-validator` - Create new validator initialized with a self-delegation** - -First of all, we can create a validator with the `create-validator` transaction, for example: - -```bash -$ cronosd tx staking create-validator \ ---from=[name_of_your_key] \ ---amount=[staking_amount] \ ---pubkey=[trocnclconspub...] \ ---moniker="[moniker_id_of_your_node]" \ ---security-contact="[security contact email/contact method]" \ ---chain-id="[chain-id]" \ ---commission-rate="[commission_rate]" \ ---commission-max-rate="[maximum_commission_rate]" \ ---commission-max-change-rate="[maximum_rate_of_change_of_commission]" \ ---min-self-delegation="[min_self_delegation_amount]" - -## Transactions payload## -{"body":{"messages":[{"@type":"/cosmos.staking.v1beta1.MsgCreateValidator"...} -confirm transaction before signing and broadcasting [y/N]: y -``` - -**`tx staking delegate [validator-addr] [amount]` - Delegate liquid tokens to a validator** - -As discussed in the delegator section, one can delegate their tokens to an active validator by: - -```bash -$ tx staking delegate [validator-addr] [amount] - -## Transactions payload## -{"body":{"messages":[{"@type":"/cosmos.staking.v1beta1.MsgDelegate"...} -``` - -**`tx staking unbond [validator-addr] [amount]` - Unbond shares from a validator** - -Delegator can unbond their staked tokens by - -```bash -$ cronosd tx staking unbond [validator-addr] [amount] - -## Transactions payload## -{"body":{"messages":[{"@type":"/cosmos.staking.v1beta1.MsgUndelegate"...} -``` - -_Remark:_ Note that funds will only be available after the `unbonding_time` has passed. - -**`tx staking redelegate [src-validator-addr] [dst-validator-addr] [amount]` - Redelegate illiquid tokens from one validator to another** - -We can also move our staked tokens from one validator to another by: - -```bash -$ cronosd tx staking redelegate [src-validator-addr] [dst-validator-addr] [amount] - -## Transactions payload## -{"body":{"messages":[{"@type":"/cosmos.staking.v1beta1.MsgBeginRedelegate"...} -``` - -#### Queries - -We will be covering most of the commonly used queries here. Meanwhile, you can use - -```bash -cronosd query staking -h -``` - -to check all the supported sub-commands. - -**`query staking delegation [delegator-addr] [validator-addr]` - Query a delegation based on address and validator address** - -With a given delegator address and the validator account that it is associated with, we can check the by: - -```json -$ cronosd query staking delegation [delegator-addr] [validator-addr] --output json | jq - - { - "delegation": { - "delegator_address": "[delegator-addr]", - "validator_address": "[validator-addr]", - "shares": "[delegator_shares]" - }, - "balance": { - "denom": "basetcro", - "amount": "[delegator_balance]" - } - } -``` - -**`query staking delegations-to [validator-addr]` - Query all delegations made to one validator** - -We can check all the delegations made to a specific validator: - -```json -$ cronosd query staking delegations-to [validator-addr] --output json | jq - - { - "delegation_responses": [ - { - "delegation": { - "delegator_address": "[delegator-addr-1]", - "validator_address": "[validator-addr]", - "shares": "[delegator_shares]" - }, - "balance": { - "denom": "basetcro", - "amount": "[delegator_balance_1]" - } - }, - { - "delegation": { - "delegator_address": "[delegator-addr-2]", - "validator_address": "[validator-addr]", - "shares": "[delegator_shares-2]" - }, - "balance": { - "denom": "basetcro", - "amount": "[delegator_balance_2]" - } - } - ....... - ], - "pagination": { - "next_key": null, - "total": "0" - } - } -``` - -**`query staking pool` - Query the current staking pool values** - -We can check the amount of bonded and unbonded amount in the staking pool: - -```json -$ cronosd query staking pool --output json | jq - - { - "not_bonded_tokens": "[not_bonded_amount]", - "bonded_tokens": "[bonded_amount]", - } -``` - -**`query staking unbonding-delegation [delegator-addr] [validator-addr]` - Query an unbonding-delegation record based on delegator and validator address** - -```json -$ cronosd query staking unbonding-delegation [delegator-addr] [validator-addr] --output json | jq - - { - "delegator_address": "[delegator-addr]", - "validator_address": "[validator-addr]", - "entries": [ - { - "creation_height": "[height_of_unbonding]", - "completion_time": "[completion_time]", - "initial_balance": "[unbonding_initial_balance]", - "balance": "[unbonding_balance]" - } - ] - } -``` - -**`query staking validator [validator-addr]` - Query a specific validator** - -We can query the details of a specific validator with its validator address (crocncl...) by: - -```json -$ cronosd query staking validator [validator-addr] --output json | jq - - { - "operator_address": "[validator_address (crocncl...)]", - // address of the validator's operator - "consensus_pubkey": "[consensus_pubkey (crocnclconspub...)]", - // the consensus public key of the validator - "jailed": "[jailed_or_not]", - // if it has been jailed from bonded status? - "status": "[validator_statuses]", - // validator status (bonded/unbonding/unbonded) - "tokens": "[total_tokens]", - // total delegated tokens - "delegator_shares": "[delegator_shares]", - // total shares issued to a validator's delegators - "description": { - "moniker": "[validator_moniker_id]", - "identity": "", - "website": "", - "security_contact": "[security_contact]", - "details": "" - }, - // description terms for the validator - "unbonding_height": "[unbonding_height]", - "unbonding_time": "[unbonding_time]", - "commission": { - "commission_rates": { - "rate": "[commission_rates]", - // the commission rate charged to delegators - "max_rate": "[maximum_commission_rates]", - // maximum commission rate which validator can ever charge - "max_change_rate": "[maximum_rate_of_change_of_commission]" - // maximum daily increase of the validator commission - }, - "update_time": "[last_update_time]" - // the last time the commission rate was changed - }, - "min_self_delegation": "[min_self_delegation_amount]" - // validator's self declared minimum self delegation - } -``` - -**`query staking validators` - Query all validators** - -A full list of validators and their details can be found by this query. - -**`query staking params` - Query the current staking parameters** - -Finally, we can query the current staking parameters by - -```json -$ cronosd query staking params --output json | jq -``` - - - -**REST endpoint** - -The parameters can also be checked by browsing to the following REST endpoint on Mainnet: - -[https://rest.cronos.org/cosmos/staking/v1beta1/params](https://rest.cronos.org/cosmos/bank/v1beta1/params) - -```json -{ - "params": { - "unbonding_time": "2419200s", - "max_validators": 50, - "max_entries": 7, - "historical_entries": 10000, - "bond_denom": "stake" - } -} -``` - - - -#### Appendix - -**`staking` module: Network Parameters Configuration** - -The following tables show overall effects on different configurations of the staking related network parameters: - -| | `bond_denom` | `historical_entries` | `max_entries` | -| -------------------- | ------------ | ---------------------------------- | ------------------------------------------------------------- | -| Type | string | uint16 | uint16 | -| Higher | N/A | More historical entries to persist | More entries for either unbonding delegation or redelegation | -| Lower | N/A | Less historical entries to persist | Fewer entries for either unbonding delegation or redelegation | -| Constraints | N/A | Value has to be positive | Value has to be a positive | -| Sample configuration | `basetcro` | `100` (50%) | `7` | - -*** - -| | `max_validators` | `unbonding_time` | -| -------------------- | ------------------------------------ | ------------------------------------ | -| Type | uint16 | string | -| Higher | More active validators | Longer waiting period for unbonding | -| Lower | Fewer active validators | Shorter waiting period for unbonding | -| Constraints | Value has to be less or equal to `1` | Positive value in seconds | -| Sample configuration | `100` (maximum 100 active validator) | `"1814400s"` (3 weeks) |