R4R: Update cli docs (#2076)

* Update cli docs, fixes #2026

* Fixed merge conflicts

* Updated chain_id
This commit is contained in:
Federico Kunze 2018-08-17 18:49:57 +02:00 committed by Christopher Goes
parent cf03076a0a
commit 466e0c04d5
2 changed files with 240 additions and 166 deletions

View File

@ -12,27 +12,25 @@
`gaiacli` is the command line interface to manage accounts and transactions on Cosmos testnets. Here is a list of useful `gaiacli` commands, including usage examples.
### Key Types
### Keys
#### Key Types
There are three types of key representations that are used:
- `cosmosaccaddr`
- Derived from account keys generated by `gaiacli keys add`
- Used to receive funds
- e.g. `cosmosaccaddr15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc`
- `cosmosaccpub`
- Derived from account keys generated by `gaiacli keys add`
- e.g. `cosmosaccpub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm`
- `cosmosvalpub`
- Generated when the node is created with `gaiad init`.
- Get this value with `gaiad tendermint show_validator`
- e.g. `cosmosvalpub1zcjduc3qcyj09qc03elte23zwshdx92jm6ce88fgc90rtqhjx8v0608qh5ssp0w94c`
### Generate Keys
#### Generate Keys
You'll need an account private and public key pair \(a.k.a. `sk, pk` respectively\) to be able to receive funds, send txs, bond tx, etc.
@ -66,10 +64,14 @@ gaiad tendermint show_validator
We strongly recommend _NOT_ using the same passphrase for multiple keys. The Tendermint team and the Interchain Foundation will not be responsible for the loss of funds.
:::
### Get Tokens
### Account
#### Get Tokens
The best way to get tokens is from the [Cosmos Testnet Faucet](https://faucetcosmos.network). If the faucet is not working for you, try asking [#cosmos-validators](https://riot.im/app/#/room/#cosmos-validators:matrix.org). The faucet needs the `cosmosaccaddr` from the account you wish to use for staking.
#### Query Account balance
After receiving tokens to your address, you can view your account's balance by typing:
```bash
@ -79,7 +81,6 @@ gaiacli account <account_cosmosaccaddr>
::: warning Note
When you query an account balance with zero tokens, you will get this error: `No account with address <account_cosmosaccaddr> was found in the state.` This can also happen if you fund the account before your node has fully synced with the chain. These are both normal.
We're working on improving our error messages!
:::
### Send Tokens
@ -87,7 +88,7 @@ We're working on improving our error messages!
```bash
gaiacli send \
--amount=10faucetToken \
--chain-id=gaia-7005 \
--chain-id=<chain_id> \
--name=<key_name> \
--to=<destination_cosmosaccaddr>
```
@ -109,20 +110,40 @@ You can also check your balance at a given block by using the `--block` flag:
gaiacli account <account_cosmosaccaddr> --block=<block_height>
```
### Delegate
### Staking
#### Set up a Validator
Please refer to the [Validator Setup](https://cosmos.network/docs/validators/validator-setup.html) section for a more complete guide on how to set up a validator-candidate.
#### Delegate to a Validator
On the upcoming mainnet, you can delegate `atom` to a validator. These [delegators](/resources/delegators-faq) can receive part of the validator's fee revenue. Read more about the [Cosmos Token Model](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
### Bond Tokens
##### Query Validators
On the testnet, we delegate `steak` instead of `atom`. Here's how you can bond tokens to a testnet validator:
You can query the list of all validators of a specific chain:
```bash
gaiacli stake validators
```
If you want to get the information of a single validator you can check it with:
```bash
gaiacli stake validator <account_cosmosaccaddr>
```
#### Bond Tokens
On the testnet, we delegate `steak` instead of `atom`. Here's how you can bond tokens to a testnet validator (*i.e.* delegate):
```bash
gaiacli stake delegate \
--amount=10steak \
--address-validator=$(gaiad tendermint show_validator) \
--name=<key_name> \
--chain-id=gaia-7005
--chain-id=<chain_id>
```
While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.
@ -131,33 +152,197 @@ While tokens are bonded, they are pooled with all the other bonded tokens in the
Don't use more `steak` thank you have! You can always get more by using the [Faucet](https://faucetcosmos.network/)!
:::
### Unbond Tokens
##### Query Delegations
If for any reason the validator misbehaves, or you want to unbond a certain amount of tokens, use this following command. You can unbond a specific amount of`shares`\(eg:`12.1`\) or all of them \(`MAX`\).
Once submitted a delegation to a validator, you can see it's information by using the following command:
```bash
gaiacli stake delegation \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=$(gaiad tendermint show-validator)
```
Or if you want to check all your current delegations with disctinct validators:
```bash
gaiacli stake delegations <account_cosmosaccaddr>
```
You can also get previous delegation(s) status by adding the `--height` flag.
#### Unbond Tokens
If for any reason the validator misbehaves, or you just want to unbond a certain amount of tokens, use this following command. You can unbond a specific `shares-amount` (eg:`12.1`\) or a `shares-percent` (eg:`25`) with the corresponding flags.
```bash
gaiacli stake unbond begin \
--address-validator=$(gaiad tendermint show_validator) \
--shares=MAX \
--name=<key_name> \
--chain-id=gaia-7005
--address-validator=$(gaiad tendermint show-validator) \
--shares-percent=100 \
--from=<key_name> \
--chain-id=<chain_id>
```
Later you must use the `gaiacli stake unbond complete` command to finish
unbonding at which point you can can check your balance and your stake
delegation to see that the unbonding went through successfully.
Later you must complete the unbonding process by using the `gaiacli stake unbond complete` command:
```bash
gaiacli account <account_cosmosaccaddr>
gaiacli stake delegation \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=$(gaiad tendermint show_validator) \
--chain-id=gaia-7005
gaiacli stake unbond complete \
--address-validator=$(gaiad tendermint show-validator) \
--from=<key_name> \
--chain-id=<chain_id>
```
## Light Client Daemon
##### Query Unbonding-Delegations
Once you begin an unbonding-delegation, you can see it's information by using the following command:
```bash
gaiacli stake unbonding-delegation \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=$(gaiad tendermint show-validator) \
```
Or if you want to check all your current unbonding-delegations with disctinct validators:
```bash
gaiacli stake unbonding-delegations <account_cosmosaccaddr>
```
You can also get previous unbonding-delegation(s) status by adding the `--height` flag.
#### Redelegate Tokens
A redelegation is a type delegation that allows you to bond illiquid tokens from one validator to another:
```bash
gaiacli stake redelegate begin \
--address-validator-source=$(gaiad tendermint show-validator) \
--address-validator-dest=<account_cosmosaccaddr> \
--shares-percent=50 \
--from=<key_name> \
--chain-id=<chain_id>
```
Here you can also redelegate a specific `shares-amount` or a `shares-percent` with the corresponding flags.
Later you must complete the redelegation process by using the `gaiacli stake redelegate complete` command:
```bash
gaiacli stake unbond complete \
--address-validator=$(gaiad tendermint show-validator) \
--from=<key_name> \
--chain-id=<chain_id>
```
##### Query Redelegations
Once you begin an redelegation, you can see it's information by using the following command:
```bash
gaiacli stake redelegation \
--address-delegator=<account_cosmosaccaddr> \
--address-validator-source=$(gaiad tendermint show-validator) \
--address-validator-dest=<account_cosmosaccaddr> \
```
Or if you want to check all your current unbonding-delegations with disctinct validators:
```bash
gaiacli stake redelegations <account_cosmosaccaddr>
```
You can also get previous redelegation(s) status by adding the `--height` flag.
### Governance
Governance is the process from which users in the Cosmos Hub can come to consensus on software upgrades, parameters of the mainnet or on custom text proposals. This is done through voting on proposals, which will be submitted by `Atom` holders on the mainnet.
Some considerations about the voting process:
- Voting is done by bonded `Atom` holders on a 1 bonded `Atom` 1 vote basis
- Delegators inherit the vote of their validator if they don't vote
- **Validators MUST vote on every proposal**. If a validator does not vote on a proposal, they will be **partially slashed**
- Votes are tallied at the end of the voting period (2 weeks on mainnet). Each address can vote multiple times to update its `Option` value (paying the transaction fee each time), only the last casted vote will count as valid
- Voters can choose between options `Yes`, `No`, `NoWithVeto` and `Abstain`
At the end of the voting period, a proposal is accepted if `(YesVotes/(YesVotes+NoVotes+NoWithVetoVotes))>1/2` and `(NoWithVetoVotes/(YesVotes+NoVotes+NoWithVetoVotes))<1/3`. It is rejected otherwise
For more information about the governance process and how it works, please check out the Governance module [specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/governance).
#### Create a Governance proposal
In order to create a governance proposal, you must submit an initial deposit along with the proposal details:
- `title`: Title of the proposal
- `description`: Description of the proposal
- `type`: Type of proposal. Must be of value _Text_ (types _SoftwareUpgrade_ and _ParameterChange_ not supported yet).
```bash
gaiacli gov submit-proposal \
--title=<title> \
--description=<description> \
--type=<Text/ParameterChange/SoftwareUpgrade> \
--proposer=<account_cosmosaccaddr> \
--deposit=<40steak> \
--from=<name> \
--chain-id=<chain_id>
```
##### Query proposals
Once created, you can now query information of the proposal:
```bash
gaiacli gov query-proposal \
--proposal-id=<proposal_id>
```
Or query all available proposals:
```bash
gaiacli gov query-proposals
```
You can also query proposals filtered by `voter` or `depositer` by using the corresponding flags.
#### Increase deposit
In order for a proposal to be broadcasted to the network, the amount deposited must be above a `minDeposit` value (default: `10 steak`). If the proposal you previously created didn't meet this requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period:
```bash
gaiacli gov deposit \
--proposal-id=<proposal_id> \
--depositer=<account_cosmosaccaddr> \
--deposit=<200steak> \
--from=<name> \
--chain-id=<chain_id>
```
> _NOTE_: Proposals that don't meet this requirement will be deleted after `MaxDepositPeriod` is reached.
#### Vote on a proposal
After a proposal's deposit reaches the `MinDeposit` value, the voting period opens. Bonded `Atom` holders can then cast vote on it:
```bash
gaiacli gov vote \
--proposal-id=<proposal_id> \
--voter=<account_cosmosaccaddr> \
--option=<Yes/No/NoWithVeto/Abstain> \
--from=<name> \
--chain-id=<chain_id>
```
##### Query vote
Check the vote with the option you just submitted:
```bash
gaiacli gov query-vote \
--proposal-id=<proposal_id> \
--voter=<account_cosmosaccaddr>
```
## Gaia-Lite
::: tip Note
🚧Documentation coming soon!
🚧 We are actively working on documentation for Gaia-lite.
:::

View File

@ -1,7 +1,7 @@
# Validator Setup
::: warning Current Testnet
The current testnet is `gaia-7005`.
The current testnet is `gaia-8000`.
:::
Before setting up your validator node, make sure you've already gone through the [Full Node Setup](/getting-started/full-node.md) guide.
@ -34,7 +34,7 @@ gaiacli stake create-validator \
--pubkey=$(gaiad tendermint show_validator) \
--address-validator=<account_cosmosaccaddr>
--moniker="choose a moniker" \
--chain-id=gaia-7005 \
--chain-id=<chain_id> \
--name=<key_name>
```
@ -51,7 +51,7 @@ gaiacli stake edit-validator
--website="https://cosmos.network" \
--identity=6A0D65E29A4CBC8E
--details="To infinity and beyond!"
--chain-id=gaia-7005 \
--chain-id=<chain_id> \
--name=<key_name>
```
@ -62,7 +62,26 @@ View the validator's information with this command:
```bash
gaiacli stake validator \
--address-validator=<account_cosmosaccaddr> \
--chain-id=gaia-7005
--chain-id=<chain_id>
```
### Track Validator Signing Information
In order to keep track of a validator's signatures in the past you can do so by using the `signing-info` command:
```bash
gaiacli stake signing-information <validator-pubkey>\
--chain-id=<chain_id>
```
### Unrevoke Validator
When a validator is `Revoked` for downtime, you must submit an `Unrevoke` transaction in order to be able to get block proposer rewards again (depends on the zone fee distribution).
```bash
gaiacli stake unrevoke \
--from=<key_name> \
--chain-id=<chain_id>
```
### Confirm Your Validator is Running
@ -75,7 +94,6 @@ gaiacli advanced tendermint validator-set | grep "$(gaiad tendermint show_valida
You should also be able to see your validator on the [Explorer](https://explorecosmos.network/validators). You are looking for the `bech32` encoded `address` in the `~/.gaiad/config/priv_validator.json` file.
::: warning Note
To be in the validator set, you need to have more total voting power than the 100th validator.
:::
@ -84,7 +102,7 @@ To be in the validator set, you need to have more total voting power than the 10
### Problem #1: My validator has `voting_power: 0`
Your validator has become auto-unbonded. In `gaia-7005`, we unbond validators if they do not vote on `50` of the last `100` blocks. Since blocks are proposed every ~2 seconds, a validator unresponsive for ~100 seconds will become unbonded. This usually happens when your `gaiad` process crashes.
Your validator has become auto-unbonded. In `gaia-8000`, we unbond validators if they do not vote on `50` of the last `100` blocks. Since blocks are proposed every ~2 seconds, a validator unresponsive for ~100 seconds will become unbonded. This usually happens when your `gaiad` process crashes.
Here's how you can return the voting power back to your validator. First, if `gaiad` is not running, start it up again:
@ -95,7 +113,7 @@ gaiad start
Wait for your full node to catch up to the latest block. Next, run the following command. Note that `<cosmosaccaddr>` is the address of your validator account, and `<name>` is the name of the validator account. You can find this info by running `gaiacli keys list`.
```bash
gaiacli stake unrevoke <cosmosaccaddr> --chain-id=gaia-7005 --name=<name>
gaiacli stake unrevoke <cosmosaccaddr> --chain-id=<chain_id> --name=<name>
```
::: danger Warning
@ -132,132 +150,3 @@ LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
```
## Delegating to a Validator
On the upcoming mainnet, you can delegate `Atom` to a validator. These [delegators](https://cosmos.network/resources/delegators) can receive part of the validator's fee revenue. Read more about the [Cosmos Token Model](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
### Bond Tokens
On the testnet, we delegate `steak` instead of `Atom`. Here's how you can bond tokens to a testnet validator:
```bash
gaiacli stake delegate \
--amount=10steak \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=<validator_cosmosaccaddr> \
--from=<key_name> \
--chain-id=gaia-7001
```
While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.
> _*NOTE:*_ Don't use more `steak` thank you have! You can always get more by using the [Faucet](https://gaia.faucetcosmos.network/)!
### Unbond Tokens
If for any reason the validator misbehaves, or you want to unbond a certain amount of tokens, use this following command. You can unbond a specific amount of`shares`\(eg:`12.1`\) or all of them \(`MAX`\).
```bash
gaiacli stake unbond \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=<validator_cosmosaccaddr> \
--shares=MAX \
--from=<key_name> \
--chain-id=gaia-7001
```
You can check your balance and your stake delegation to see that the unbonding went through successfully.
```bash
gaiacli account <account_cosmosaccaddr>
gaiacli stake delegation \
--address-delegator=<account_cosmosaccaddr> \
--address-validator=<validator_cosmosaccaddr> \
--chain-id=gaia-7001
```
## Governance
Governance is the process from which users in the Cosmos Hub can come to consensus on software upgrades, parameters of the mainnet or on custom text proposals. This is done through voting on proposals, which will be submitted by `Atom` holders on the mainnet.
Some considerations about the voting process:
- Voting is done by bonded `Atom` holders on a 1 bonded `Atom` 1 vote basis
- Delegators inherit the vote of their validator if they don't vote
- **Validators MUST vote on every proposal**. If a validator does not vote on a proposal, they will be **partially slashed**
- Votes are tallied at the end of the voting period (2 weeks on mainnet). Each address can vote multiple times to update its `Option` value (paying the transaction fee each time), only the last casted vote will count as valid
- Voters can choose between options `Yes`, `No`, `NoWithVeto` and `Abstain`
At the end of the voting period, a proposal is accepted if `(YesVotes/(YesVotes+NoVotes+NoWithVetoVotes))>1/2` and `(NoWithVetoVotes/(YesVotes+NoVotes+NoWithVetoVotes))<1/3`. It is rejected otherwise
For more information about the governance process and how it works, please check out the Governance module [specification](https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/governance).
### Create a Governance proposal
In order to create a governance proposal, you must submit an initial deposit along with the proposal details:
- `title`: Title of the proposal
- `description`: Description of the proposal
- `type`: Type of proposal. Must be of value _Text_ (types _SoftwareUpgrade_ and _ParameterChange_ not supported yet).
```bash
gaiacli gov submit-proposal \
--title=<title> \
--description=<description> \
--type=<Text/ParameterChange/SoftwareUpgrade> \
--proposer=<account_cosmosaccaddr> \
--deposit=<40steak> \
--from=<name> \
--chain-id=gaia-7001
```
### Increase deposit
In order for a proposal to be broadcasted to the network, the amount deposited must be above a `minDeposit` value (default: `10 steak`). If the proposal you previously created didn't meet this requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period:
```bash
gaiacli gov deposit \
--proposalID=<proposal_id> \
--depositer=<account_cosmosaccaddr> \
--deposit=<200steak> \
--from=<name> \
--chain-id=gaia-7001
```
> _NOTE_: Proposals that don't meet this requirement will be deleted after `MaxDepositPeriod` is reached.
#### Query proposal
Once created, you can now query information of the proposal:
```bash
gaiacli gov query-proposal \
--proposalID=<proposal_id> \
--chain-id=gaia-7001
```
### Vote on a proposal
After a proposal's deposit reaches the `MinDeposit` value, the voting period opens. Bonded `Atom` holders can then cast vote on it:
```bash
gaiacli gov vote \
--proposalID=<proposal_id> \
--voter=<account_cosmosaccaddr> \
--option=<Yes/No/NoWithVeto/Abstain> \
--from=<name> \
--chain-id=gaia-7001
```
#### Query vote
Check the vote with the option you just submitted:
```bash
gaiacli gov query-vote \
--proposalID=<proposal_id> \
--voter=<account_cosmosaccaddr> \
--chain-id=gaia-7001
```