diff --git a/docs/cli-client/gov/README.md b/docs/cli-client/gov/README.md index deb544f77..9921f50e6 100644 --- a/docs/cli-client/gov/README.md +++ b/docs/cli-client/gov/README.md @@ -12,6 +12,10 @@ This module provides the basic functions as described below: ```shell iriscli gov [command] ``` +Print all supported subcommands and flags: +``` +iriscli distribution --help +``` ## Available Commands @@ -30,20 +34,6 @@ iriscli gov [command] | [deposit](deposit.md) | Deposit tokens for activing proposal | | [vote](vote.md) | vote for an active proposal, options: Yes/No/NoWithVeto/Abstain | -## Flags - -| Name, shorthand | Default | Description | Required | -| --------------- | ------- | ------------- | -------- | -| --help, -h | | help for gov | | - -## Global Flags - -| Name, shorthand | Default | Description | Required | -| --------------- | -------------- | -------------------------------------- | -------- | -| --encoding, -e | hex | [string] Binary encoding (hex ¦ b64 ¦ btc) | | -| --home | $HOME/.iriscli | [string] directory for config and data | | -| --output, -o | text | [string] Output format (text ¦ json) | | -| --trace | | print out full stack trace on errors | | ## Extended description diff --git a/docs/features/stake.md b/docs/features/stake.md index 2189c8edd..34a847a42 100644 --- a/docs/features/stake.md +++ b/docs/features/stake.md @@ -1,94 +1,121 @@ -# Delegators +# Stake User Guide -## What is a delegator? -People that cannot, or do not want to run validator operations, can still participate in the staking process as delegators. Indeed, validators are not chosen based on their own stake -but based on their total stake, which is the sum of their own stake and of the stake that is delegated to them. This is an important property, as it makes delegators a safeguard against - validators that exhibit bad behavior. If a validator misbehaves, its delegators will move their Atoms away from it, thereby reducing its stake. Eventually, if a validator's stake falls - under the top 100 addresses with highest stake, it will exit the validator set. +## Introduction -## States for a Delegator +This specification briefly introduces the functionality of stake module and what user should do with the provided commands. -Delegators have the same state as their validator. +## Core Concept +1. Voting power -Note that delegation are not necessarily bonded. Tokens of each delegator can be delegated and bonded, delegated and unbonding, delegated and unbonded, or loose. + Voting power is a consensus concept. IRISHUB is a Byzantine-fault-tolerant POS blockchain network. During the consensus process, a set of validators will vote the proposal block. If a validator thinks the proposal block is valid, it will vote `yes`, otherwise, it will vote nil. The votes from different validator don't have the same weight. The weight of a vote is called the voting power of the corresponding validator. + +2. Validator -## Common operation for Delegators + Validator is a full IRISHUB node. As a full nodes, it will sync all blocks and execute all transactions, which will consume much storage and computation resoure. If its voting power is zero, it is just a normal full node or a validator candidate. Once its voting power is positive, then it is a real validator. + +3. Delegator && Delegation -* Delegation - -To delegate some IRIS token to a validator, you could run the following command: -```$xslt -iriscli stake delegate --address-delegator= --address-validator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris --amount=10000000000000000000iris -``` -> Please notice that the amount is under unit iris-atto, 1iris=10^18 iris-atto - -* Query Delegations - -You could query your delegation amount with the following command: - -```$xslt -iriscli stake delegation --address-delegator= --address-validator= --chain-id=fuxi-3001 -``` - -The example output is the following: -```$xslt -Delegation -Delegator: faa1je9qyff4qate4e0kthum0p8v7q7z8lr7eczsv6 -Validator: faa1dmp6eyjw94u0wzc67qa03cmgl92qwqaph28lxq -Shares: 10000000000000000000/1Height: 215307 -``` - -> Please notice that the share amount is also correspond to iris-atto, 1iris=10^18 iris-atto - - -* Re-delegate - -Once a delegator has delegated his own IRIS to certain validator, he/she could change the destination of delegation at anytime. If the transaction is executed, the -delegation will be placed at the other's pool after 10 minutes. - -The redelegation operation is composed of two phases: - * redelegate begin - * redelegate complete + People that cannot, or do not want to run validator nodes, can still participate in the staking process as delegators. After delegating some tokens to validators, delegators will gain delegations from corresponding validators. Delegating tokens is also called bonding tokens to validators. Later we will have detailed description on it. Besides, a validator operator is also a delegator. Usually, a validator operator only has delegation on its own validator. But it can also have delegation on other validators. + +4. Validator Candidates - To start, you should run the following command: -```$xslt -iriscli stake redelegate begin --addr-validator-dest= --addr-validator-source= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris --shares-percent=1.0 -``` - -Please note that you have to wait 10 minute to run the next command: - -```$xslt -iriscli stake redelegate complete --addr-validator-dest= --addr-validator-source= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris -``` - -The example output is the following: -```$xslt -Delegation -Delegator: faa1je9qyff4qate4e0kthum0p8v7q7z8lr7eczsv6 -Validator: faa1kepndxvjr6gnc8tjcnelp9hqz8jdcs8mvz7m86 -Shares: 10000000000000000000/1Height: 215459 -``` - -* Unbond Delegation - - -Once a delegator has delegated his own IRIS to certain validator, he/she could withdraw the delegation at anytime. If the transaction is executed, the -delegation will become liquid after 10 minutes. - -The redelegation operation is composed of two phases: - * unbond begin - * unbond complete - - To start, you should run the following command: -```$xslt -iriscli stake unbond begin --address-validator= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris --shares-percent=1.0 -``` - -Please note that you have to wait 10 minute to run the next command: - -```$xslt -iriscli stake unbond complete --address-validator= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris -``` - -You could check that the balance of delegator has increased. \ No newline at end of file + The quantity of validators can't increase without limit. Too many validators may result in inefficent consensus which slows down the blockchain TPS. So Byzantine-fault-tolerant POS blockchain network will have a limiation to the validator quantity. Usually, the value is 100. If more than 100 full nodes apply to join validator set. Then only these nodes with top 100 most bounded tokens will be real validators. Others will be validator candidates and will be descending sorted according to their bonded token amount. Once the one or more validators are kicked out from validator set, then the top candidates will be added into validator set automatically. + +5. Bond && Unbond && Unbonding Period + + Validator operators must bond their liquid tokens to their validators. The validator voting power is proportional to the bonded tokens including both self-bonded tokens and tokens from other delegators. Validator operators can lower their own bonded tokens by sending unbond transactions. Delegators can also lower bonded token by sending unbond transactions. However, these unbonded token won't become liquid tokens immediately. After the unbond transactions are executed, the corresponding validator operators or delegators can't sending unbond transactions on the same validators again until the unbonding period is end. Usually the unbonding period is three weeks. Once the unbonding period is end, the unbonded token will become liquid token automatically. The unbonding period mechanism makes great contribution to the security of POS blockchain network. Besides, if the self-bonded token equals to zero, then the corresponding validator will be removed out of validator set. + +6. Redelegate + + Delegators can transfer their delegation from one validator to another one. Redelegation can be devided into two steps: ubond from first validator and bond to another validator. As we have talked above, ubond operation can't be completed immediately until unbonding period is end, which means delegators can't send another redelegation transactions immediately. + +7. Evidence && Slash + + The Byzantine-fault-tolerant POS blockchain network can work well assume that the Byzantine nodes possess less than 1/3 of total voting power. These Byzantine nodes must be punished. So it is necessary to collect the evidence of Byzantine behavior. According to the evidence, stake module will aotumatically slash a certain mount of token from corresponding validators and delegators. The slashed tokens are just burned. Besides, the Byzantine validators will be removed from the validator set and put into jail, which means their voting power is zero. During the jail period, these nodes are not event validator candidates . Once the jail period is end, they can send transactions to unjail themselves and become validator candidates again. + +8. Rewards + + As a delegator, the more bonded tokens it has on validator, the more rewards it will earn. For a validator operator, it will have extra rewards: validator commission. The rewards comes from token inflation and transaction fee. As for how to calculate the rewards and how to get the rewards, please refer to [mint](mint.md) and [distribution](distribution.md). + +## What users can do + +1. Create a full node + + Please refer to [full node](../get-started/Full-Node.md) to create a full node. + +2. Apply to be validator + + Firstly, you must have a wallet which has a certain amount of iris tokens. Here we assume you have import your wallet to iriscli key store. + + Then just send a create-validator transaction. This is an example command. + ``` + iriscli stake create-validator --amount=100iris --pubkey=$(iris tendermint show-validator) --moniker= --fee=0.004iris --chain-id= --from= --commission-max-change-rate=0.01 --commission-max-rate=0.2 --commission-rate=0.1 + ``` + The more tokens specified by `--amount`, the more probability your full node will be a real validator. Otherwise, it will just be validator candidate. + +3. Query your own validator + + Users can query their own validators by their wallet address. But firstly users have to convert their wallet addresses to validator operator address pattern: + ``` + iriscli keys show [key name] --bech=val + ``` + Example response: + ``` + NAME: TYPE: ADDRESS: PUBKEY: + faucet local fva1ljemm0yznz58qxxs8xyak7fashcfxf5l9pe40u fvp1addwnpepqtdme789cpm8zww058ndlhzpwst3s0mxnhdhu5uyps0wjucaufha605ek3w + ``` + Then, example command to query validator: + ``` + iriscli stake validator fva1ljemm0yznz58qxxs8xyak7fashcfxf5l9pe40u + ``` + Example response: + ```text + Validator + Operator Address: fva1ljemm0yznz58qxxs8xyak7fashcfxf5l9pe40u + Validator Consensus Pubkey: fvp1zcjduepq8fw9p4zfrl5fknrdd9tc2l24jnqel6waxlugn66y66dxasmeuzhsxl6m5e + Jailed: false + Status: Bonded + Tokens: 100.0000000000 + Delegator Shares: 100.0000000000 + Description: {node2 } + Bond Height: 0 + Unbonding Height: 0 + Minimum Unbonding Time: 1970-01-01 00:00:00 +0000 UTC + Commission: {{0.1000000000 0.2000000000 0.0100000000 0001-01-01 00:00:00 +0000 UTC}} + ``` + +4. Edit validator + + ``` + iriscli stake edit-validator --from= --chain-id= --fee=0.004iris --commission-rate=0.15 --moniker= + ``` + +5. Increase self-delegation + + ``` + iriscli stake delegate --address-validator= --chain-id= --from= --fee=0.004iris --amount=100iris + ``` + +6. Delegate tokens to other validators + + If you just want to be a delegator, you can skip the above steps. + ``` + iriscli stake delegate --address-validator= --chain-id= --from= --fee=0.004iris --amount=100iris + ``` + +7. Unbond tokens from a validator + + Unbond half of total bonded token on a given validator + ``` + iriscli stake unbond --address-validator= --chain-id= --from= --fee=0.004iris --amount=100iris --share-percent=0.5 + ``` + +8. Redelegate tokens to another validator + + Redelegate half of total bonded token on a given validator to another one + ``` + iriscli stake redelegate --chain-id= --from= --fee=0.004iris --address-validator-source= --address-validator-dest= --shares-percent=0.5 + ``` + +For other query stake state commands, please refer to [stake cli client](../cli-client/stake/README.md) diff --git a/docs/zh/cli-client/distribution/README.md b/docs/zh/cli-client/distribution/README.md index d158ef22d..39b9e0349 100644 --- a/docs/zh/cli-client/distribution/README.md +++ b/docs/zh/cli-client/distribution/README.md @@ -10,7 +10,7 @@ iriscli distribution [subcommand] ``` -打印所以子命令和参数 +打印子命令和参数 ``` iriscli distribution --help diff --git a/docs/zh/cli-client/gov/README.md b/docs/zh/cli-client/gov/README.md index 4f89d2701..fbdfd45e5 100644 --- a/docs/zh/cli-client/gov/README.md +++ b/docs/zh/cli-client/gov/README.md @@ -13,6 +13,11 @@ iriscli gov [command] ``` +打印子命令和参数 +``` +iriscli distribution --help +``` + ## 相关命令 | 命令 | 描述 | @@ -30,21 +35,6 @@ iriscli gov [command] | [deposit](deposit.md) | 充值保证金代币以激活提议 | | [vote](vote.md) | 为有效的提议投票，选项：Yes/No/NoWithVeto/Abstain | -## 标志 - -| 名称, 速记 | 默认值 | 描述 | 是否必须 | -| --------------- | ------- | ------------- | -------- | -| --help, -h | | help for gov | | - -## 全局标志 - -| 名称, 速记 | 默认值 | 描述 | 是否必须 | -| --------------- | -------------- | -------------------------------------- | -------- | -| --encoding, -e | hex | [string] Binary encoding (hex ¦ b64 ¦ btc) | | -| --home | $HOME/.iriscli | [string] directory for config and data | | -| --output, -o | text | [string] Output format (text ¦ json) | | -| --trace | | print out full stack trace on errors | | - ## 补充描述 1.任何用户都可以存入一些令牌来发起提案。存款达到一定值min_deposit后，进入投票期，否则将保留存款期。其他人可以在存款期内存入提案。一旦存款总额达到min_deposit，输入投票期。但是，如果冻结时间超过存款期间的max_deposit_period，则提案将被关闭。 diff --git a/docs/zh/cli-client/stake/README.md b/docs/zh/cli-client/stake/README.md index 5cd9e0b55..35af9ff4f 100644 --- a/docs/zh/cli-client/stake/README.md +++ b/docs/zh/cli-client/stake/README.md @@ -10,7 +10,7 @@ Stake模块提供了一系列查询staking状态和发送staking交易的命令 iriscli stake [subcommand] ``` -打印所以子命令和flags： +打印子命令和flags： ``` iriscli stake --help ``` diff --git a/docs/zh/features/stake.md b/docs/zh/features/stake.md index 2189c8edd..ca8014141 100644 --- a/docs/zh/features/stake.md +++ b/docs/zh/features/stake.md @@ -1,94 +1,7 @@ -# Delegators +# Stake用户手册 -## What is a delegator? -People that cannot, or do not want to run validator operations, can still participate in the staking process as delegators. Indeed, validators are not chosen based on their own stake -but based on their total stake, which is the sum of their own stake and of the stake that is delegated to them. This is an important property, as it makes delegators a safeguard against - validators that exhibit bad behavior. If a validator misbehaves, its delegators will move their Atoms away from it, thereby reducing its stake. Eventually, if a validator's stake falls - under the top 100 addresses with highest stake, it will exit the validator set. +## 介绍 -## States for a Delegator +本文简要介绍了stake模块的功能以及常见用户接口。 -Delegators have the same state as their validator. - - -Note that delegation are not necessarily bonded. Tokens of each delegator can be delegated and bonded, delegated and unbonding, delegated and unbonded, or loose. - -## Common operation for Delegators - -* Delegation - -To delegate some IRIS token to a validator, you could run the following command: -```$xslt -iriscli stake delegate --address-delegator= --address-validator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris --amount=10000000000000000000iris -``` -> Please notice that the amount is under unit iris-atto, 1iris=10^18 iris-atto - -* Query Delegations - -You could query your delegation amount with the following command: - -```$xslt -iriscli stake delegation --address-delegator= --address-validator= --chain-id=fuxi-3001 -``` - -The example output is the following: -```$xslt -Delegation -Delegator: faa1je9qyff4qate4e0kthum0p8v7q7z8lr7eczsv6 -Validator: faa1dmp6eyjw94u0wzc67qa03cmgl92qwqaph28lxq -Shares: 10000000000000000000/1Height: 215307 -``` - -> Please notice that the share amount is also correspond to iris-atto, 1iris=10^18 iris-atto - - -* Re-delegate - -Once a delegator has delegated his own IRIS to certain validator, he/she could change the destination of delegation at anytime. If the transaction is executed, the -delegation will be placed at the other's pool after 10 minutes. - -The redelegation operation is composed of two phases: - * redelegate begin - * redelegate complete - - To start, you should run the following command: -```$xslt -iriscli stake redelegate begin --addr-validator-dest= --addr-validator-source= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris --shares-percent=1.0 -``` - -Please note that you have to wait 10 minute to run the next command: - -```$xslt -iriscli stake redelegate complete --addr-validator-dest= --addr-validator-source= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris -``` - -The example output is the following: -```$xslt -Delegation -Delegator: faa1je9qyff4qate4e0kthum0p8v7q7z8lr7eczsv6 -Validator: faa1kepndxvjr6gnc8tjcnelp9hqz8jdcs8mvz7m86 -Shares: 10000000000000000000/1Height: 215459 -``` - -* Unbond Delegation - - -Once a delegator has delegated his own IRIS to certain validator, he/she could withdraw the delegation at anytime. If the transaction is executed, the -delegation will become liquid after 10 minutes. - -The redelegation operation is composed of two phases: - * unbond begin - * unbond complete - - To start, you should run the following command: -```$xslt -iriscli stake unbond begin --address-validator= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris --shares-percent=1.0 -``` - -Please note that you have to wait 10 minute to run the next command: - -```$xslt -iriscli stake unbond complete --address-validator= --address-delegator= --chain-id=fuxi-3001 --from=name --gas=2000000 --fee=40000000000000000iris -``` - -You could check that the balance of delegator has increased. \ No newline at end of file +## 核心概念 (TODO) \ No newline at end of file