Documentation Structure Change and Cleanup (#2808)
* Update docs/sdk/clients.md * organize ADR directory like tendermint * docs: move spec-proposals into spec/ * remove lotion, moved to website repo * move getting-started to cosmos-hub, and voyager to website * docs: move lite/ into clients/lite/ * move introduction/ content to website repo * move resources/ content to website repo * mv sdk/clients.md to clients/clients.md * mv validators to cosmos-hub/validators * move deprecated sdk/ content to _attic * sdk/modules.md is duplicate with modules/README.md * consolidate remianing sdk/ files into a single sdk.md * move examples/ to docs/examples/ * mv docs/cosmos-hub to docs/gaia * Add keys/accounts section to localnet docs
This commit is contained in:
gamarin2
Jack Zampolin
@@ -0,0 +1,19 @@
|
||||
# Gaia Documentation
|
||||
|
||||
Welcome to the `Gaia` docs. `Gaia` is the current name of the Cosmos SDK application for the Cosmos Hub.
|
||||
|
||||
## Join the Cosmos Hub public testnet
|
||||
|
||||
- [Install the `gaia` application](./installation.md)
|
||||
- [Join the current testnet](./join-testnet.md)
|
||||
- [Upgrade to a validator node](./validators/validator-setup.md)
|
||||
|
||||
## Setup your own `gaia` testnet
|
||||
|
||||
- [Setup your own `gaia` testnet](./networks.md)
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [Intro to validators](./validators/overview.md)
|
||||
- [Validator FAQ](./validators/validator-faq.md)
|
||||
- [Validator security considerations](./validators/security.md)
|
||||
@@ -0,0 +1,487 @@
|
||||
# Gaia client
|
||||
|
||||
## Gaia CLI
|
||||
|
||||
::: tip Note
|
||||
If you receive this error message:
|
||||
|
||||
```bash
|
||||
Must specify these options: --chain-id when --trust-node is false
|
||||
```
|
||||
|
||||
you must choose whether you wish to verify lite client proofs. If you trust the node which you are querying, you can simply pass `--trust-node=true` - otherwise you'll need to specify `--chain-id`.
|
||||
:::
|
||||
|
||||
`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.
|
||||
|
||||
### Keys
|
||||
|
||||
#### Key Types
|
||||
|
||||
There are three types of key representations that are used:
|
||||
|
||||
- `cosmos`
|
||||
- Derived from account keys generated by `gaiacli keys add`
|
||||
- Used to receive funds
|
||||
- e.g. `cosmos15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc`
|
||||
* `cosmosvaloper`
|
||||
* Used to associate a validator to it's operator
|
||||
* Used to invoke staking commands
|
||||
* e.g. `cosmosvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah`
|
||||
- `cosmospub`
|
||||
- Derived from account keys generated by `gaiacli keys add`
|
||||
- e.g. `cosmospub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm`
|
||||
- `cosmosvalconspub`
|
||||
- Generated when the node is created with `gaiad init`.
|
||||
- Get this value with `gaiad tendermint show-validator`
|
||||
- e.g. `cosmosvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf`
|
||||
|
||||
#### 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.
|
||||
|
||||
To generate a new key \(default _ed25519_ elliptic curve\):
|
||||
|
||||
```bash
|
||||
gaiacli keys add <account_name>
|
||||
```
|
||||
|
||||
Next, you will have to create a passphrase to protect the key on disk. The output of the above command will contain a _seed phrase_. Save the _seed phrase_ in a safe place in case you forget the password!
|
||||
|
||||
If you check your private keys, you'll now see `<account_name>`:
|
||||
|
||||
```bash
|
||||
gaiacli keys show <account_name>
|
||||
```
|
||||
|
||||
View the validator operator's address via:
|
||||
|
||||
```shell
|
||||
gaiacli keys show <account_name> --bech=val
|
||||
```
|
||||
|
||||
You can see all your available keys by typing:
|
||||
|
||||
```bash
|
||||
gaiacli keys list
|
||||
```
|
||||
|
||||
View the validator pubkey for your node by typing:
|
||||
|
||||
```bash
|
||||
gaiad tendermint show-validator
|
||||
```
|
||||
|
||||
Note that this is the Tendermint signing key, *not* the operator key you will use in delegation transactions.
|
||||
|
||||
::: danger Warning
|
||||
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.
|
||||
:::
|
||||
|
||||
#### Multisig public keys
|
||||
|
||||
You can generate and print a multisig public key by typing:
|
||||
|
||||
```bash
|
||||
gaiacli show --multisig-threshold K name1 name2 name3 [...]
|
||||
```
|
||||
|
||||
`K` is the minimum weight, e.g. minimum number of private keys that must have signed the transactions that carry the generated public key.
|
||||
|
||||
### 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 `cosmos` 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
|
||||
gaiacli query account <account_cosmos>
|
||||
```
|
||||
|
||||
::: warning Note
|
||||
When you query an account balance with zero tokens, you will get this error: `No account with address <account_cosmos> 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.
|
||||
|
||||
:::
|
||||
|
||||
### Send Tokens
|
||||
|
||||
The following command could be used to send coins from one account to another:
|
||||
|
||||
```bash
|
||||
gaiacli tx send \
|
||||
--amount=10faucetToken \
|
||||
--chain-id=<chain_id> \
|
||||
--from=<key_name> \
|
||||
--to=<destination_cosmos>
|
||||
```
|
||||
|
||||
::: warning Note
|
||||
The `--amount` flag accepts the format `--amount=<value|coin_name>`.
|
||||
:::
|
||||
|
||||
::: tip Note
|
||||
You may want to cap the maximum gas that can be consumed by the transaction via the `--gas` flag.
|
||||
If you pass `--gas=simulate`, the gas limit will be automatically estimated.
|
||||
Gas estimate might be inaccurate as state changes could occur in between the end of the simulation and the actual execution of a transaction, thus an adjustment is applied on top of the original estimate in order to ensure the transaction is broadcasted successfully. The adjustment can be controlled via the `--gas-adjustment` flag, whose default value is 1.0.
|
||||
:::
|
||||
|
||||
Now, view the updated balances of the origin and destination accounts:
|
||||
|
||||
```bash
|
||||
gaiacli query account <account_cosmos>
|
||||
gaiacli query account <destination_cosmos>
|
||||
```
|
||||
|
||||
You can also check your balance at a given block by using the `--block` flag:
|
||||
|
||||
```bash
|
||||
gaiacli query account <account_cosmos> --block=<block_height>
|
||||
```
|
||||
|
||||
You can simulate a transaction without actually broadcasting it by appending the `--dry-run` flag to the command line:
|
||||
|
||||
```bash
|
||||
gaiacli tx send \
|
||||
--amount=10faucetToken \
|
||||
--chain-id=<chain_id> \
|
||||
--from=<key_name> \
|
||||
--to=<destination_cosmosaccaddr> \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
Furthermore, you can build a transaction and print its JSON format to STDOUT by appending `--generate-only` to the list of the command line arguments:
|
||||
|
||||
```bash
|
||||
gaiacli tx send \
|
||||
--amount=10faucetToken \
|
||||
--chain-id=<chain_id> \
|
||||
--from=<key_name> \
|
||||
--to=<destination_cosmosaccaddr> \
|
||||
--generate-only > unsignedSendTx.json
|
||||
```
|
||||
|
||||
You can now sign the transaction file generated through the `--generate-only` flag by providing your key to the following command:
|
||||
|
||||
```bash
|
||||
gaiacli tx sign \
|
||||
--chain-id=<chain_id> \
|
||||
--from=<key_name>
|
||||
unsignedSendTx.json > signedSendTx.json
|
||||
```
|
||||
|
||||
You can validate the transaction's signagures by typing the following:
|
||||
|
||||
```bash
|
||||
gaiacli tx sign --validate-signatures signedSendTx.json
|
||||
```
|
||||
|
||||
You can broadcast the signed transaction to a node by providing the JSON file to the following command:
|
||||
|
||||
```
|
||||
gaiacli tx broadcast --node=<node> signedSendTx.json
|
||||
```
|
||||
|
||||
### Staking
|
||||
|
||||
#### Set up a Validator
|
||||
|
||||
Please refer to the [Validator Setup](../validators/validator-setup.md) 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).
|
||||
|
||||
##### Query Validators
|
||||
|
||||
You can query the list of all validators of a specific chain:
|
||||
|
||||
```bash
|
||||
gaiacli query stake validators
|
||||
```
|
||||
|
||||
If you want to get the information of a single validator you can check it with:
|
||||
|
||||
```bash
|
||||
gaiacli query stake validator <account_cosmosval>
|
||||
```
|
||||
|
||||
#### 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 tx stake delegate \
|
||||
--amount=10steak \
|
||||
--validator=<validator> \
|
||||
--from=<key_name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
`<validator>` is the operator address of the validator to which you intend to delegate. If you are running a local testnet, you can find this with:
|
||||
|
||||
```bash
|
||||
gaiacli keys show [name] --bech val
|
||||
```
|
||||
|
||||
where `[name]` is the name of the key you specified when you initialized `gaiad`.
|
||||
|
||||
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.
|
||||
|
||||
::: tip Note
|
||||
Don't use more `steak` thank you have! You can always get more by using the [Faucet](https://faucetcosmos.network/)!
|
||||
:::
|
||||
|
||||
##### Query Delegations
|
||||
|
||||
Once submitted a delegation to a validator, you can see it's information by using the following command:
|
||||
|
||||
```bash
|
||||
gaiacli query stake delegation \
|
||||
--address-delegator=<account_cosmos> \
|
||||
--validator=<account_cosmosval>
|
||||
```
|
||||
|
||||
Or if you want to check all your current delegations with disctinct validators:
|
||||
|
||||
```bash
|
||||
gaiacli query stake delegations <account_cosmos>
|
||||
```
|
||||
|
||||
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-fraction` (eg:`0.25`) with the corresponding flags.
|
||||
|
||||
```bash
|
||||
gaiacli tx stake unbond \
|
||||
--validator=<account_cosmosval> \
|
||||
--shares-fraction=0.5 \
|
||||
--from=<key_name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
The unbonding will be automatically completed when the unbonding period has passed.
|
||||
|
||||
##### Query Unbonding-Delegations
|
||||
|
||||
Once you begin an unbonding-delegation, you can see it's information by using the following command:
|
||||
|
||||
```bash
|
||||
gaiacli query stake unbonding-delegation \
|
||||
--address-delegator=<account_cosmos> \
|
||||
--validator=<account_cosmosval> \
|
||||
```
|
||||
|
||||
Or if you want to check all your current unbonding-delegations with disctinct validators:
|
||||
|
||||
```bash
|
||||
gaiacli query stake unbonding-delegations <account_cosmos>
|
||||
```
|
||||
|
||||
Additionally, as you can get all the unbonding-delegations from a particular validator:
|
||||
|
||||
```bash
|
||||
gaiacli query stake unbonding-delegations-from <account_cosmosval>
|
||||
```
|
||||
|
||||
To get previous unbonding-delegation(s) status on past blocks, try 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 tx stake redelegate \
|
||||
--addr-validator-source=<account_cosmosval> \
|
||||
--addr-validator-dest=<account_cosmosval> \
|
||||
--shares-fraction=50 \
|
||||
--from=<key_name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
Here you can also redelegate a specific `shares-amount` or a `shares-fraction` with the corresponding flags.
|
||||
|
||||
The redelegation will be automatically completed when the unbonding period has passed.
|
||||
|
||||
##### Query Redelegations
|
||||
|
||||
Once you begin an redelegation, you can see it's information by using the following command:
|
||||
|
||||
```bash
|
||||
gaiacli query stake redelegation \
|
||||
--address-delegator=<account_cosmos> \
|
||||
--addr-validator-source=<account_cosmosval> \
|
||||
--addr-validator-dest=<account_cosmosval> \
|
||||
```
|
||||
|
||||
Or if you want to check all your current unbonding-delegations with disctinct validators:
|
||||
|
||||
```bash
|
||||
gaiacli query stake redelegations <account_cosmos>
|
||||
```
|
||||
|
||||
Additionally, as you can get all the outgoing redelegations from a particular validator:
|
||||
|
||||
```bash
|
||||
gaiacli query stake redelegations-from <account_cosmosval>
|
||||
```
|
||||
|
||||
To get previous redelegation(s) status on past blocks, try adding the `--height` flag.
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
Parameters define high level settings for staking. You can get the current values by using:
|
||||
|
||||
```bash
|
||||
gaiacli query stake parameters
|
||||
```
|
||||
|
||||
With the above command you will get the values for:
|
||||
|
||||
- Unbonding time
|
||||
- Maximum numbers of validators
|
||||
- Coin denomination for staking
|
||||
|
||||
All these values will be subject to updates though a `governance` process by `ParameterChange` proposals.
|
||||
|
||||
#### Query Pool
|
||||
|
||||
A staking `Pool` defines the dynamic parameters of the current state. You can query them with the following command:
|
||||
|
||||
```bash
|
||||
gaiacli query stake pool
|
||||
```
|
||||
|
||||
With the `pool` command you will get the values for:
|
||||
|
||||
- Loose and bonded tokens
|
||||
- Token supply
|
||||
- Current anual inflation and the block in which the last inflation was processed
|
||||
- Last recorded bonded shares
|
||||
|
||||
##### Query Delegations To Validator
|
||||
|
||||
You can also query all of the delegations to a particular validator:
|
||||
```bash
|
||||
gaiacli query delegations-to <account_cosmosval>
|
||||
```
|
||||
|
||||
### 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](./../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 tx gov submit-proposal \
|
||||
--title=<title> \
|
||||
--description=<description> \
|
||||
--type=<Text/ParameterChange/SoftwareUpgrade> \
|
||||
--deposit=<40steak> \
|
||||
--from=<name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
##### Query proposals
|
||||
|
||||
Once created, you can now query information of the proposal:
|
||||
|
||||
```bash
|
||||
gaiacli query gov proposal --proposal-id=<proposal_id>
|
||||
```
|
||||
|
||||
Or query all available proposals:
|
||||
|
||||
```bash
|
||||
gaiacli query gov 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 tx gov deposit \
|
||||
--proposal-id=<proposal_id> \
|
||||
--deposit=<200steak> \
|
||||
--from=<name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
> _NOTE_: Proposals that don't meet this requirement will be deleted after `MaxDepositPeriod` is reached.
|
||||
|
||||
##### Query deposits
|
||||
|
||||
Once a new proposal is created, you can query all the deposits submitted to it:
|
||||
|
||||
```bash
|
||||
gaiacli query gov deposits --proposal-id=<proposal_id>
|
||||
```
|
||||
|
||||
You can also query a deposit submitted by a specific address:
|
||||
|
||||
```bash
|
||||
gaiacli query gov deposit \
|
||||
--proposal-id=<proposal_id> \
|
||||
--depositer=<account_cosmos>
|
||||
```
|
||||
|
||||
#### 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 tx gov vote \
|
||||
--proposal-id=<proposal_id> \
|
||||
--option=<Yes/No/NoWithVeto/Abstain> \
|
||||
--from=<name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
##### Query votes
|
||||
|
||||
Check the vote with the option you just submitted:
|
||||
|
||||
```bash
|
||||
gaiacli query gov vote \
|
||||
--proposal-id=<proposal_id> \
|
||||
--voter=<account_cosmos>
|
||||
```
|
||||
|
||||
You can also get all the previous votes submitted to the proposal with:
|
||||
|
||||
```bash
|
||||
gaiacli query gov votes --proposal-id=<proposal_id>
|
||||
```
|
||||
|
||||
#### Query proposal tally results
|
||||
|
||||
To check the current tally of a given proposal you can use the `tally` command:
|
||||
|
||||
```bash
|
||||
gaiacli query gov tally --proposal-id=<proposal_id>
|
||||
```
|
||||
@@ -0,0 +1,45 @@
|
||||
# Install Gaia
|
||||
|
||||
This guide will explain how to install the `gaiad` and `gaiacli` entrypoints onto your system. With these installed on a server, you can participate in the latest testnet as either a [Full Node](./join-testnet.md#run-a-full-node) or a [Validator](./validators/validator-setup.md).
|
||||
|
||||
## Install Go
|
||||
|
||||
Install `go` by following the [official docs](https://golang.org/doc/install). Remember to set your `$GOPATH`, `$GOBIN`, and `$PATH` environment variables, for example:
|
||||
|
||||
```bash
|
||||
mkdir -p $HOME/go/bin
|
||||
echo "export GOPATH=$HOME/go" >> ~/.bash_profile
|
||||
echo "export GOBIN=$GOPATH/bin" >> ~/.bash_profile
|
||||
echo "export PATH=$PATH:$GOBIN" >> ~/.bash_profile
|
||||
```
|
||||
|
||||
::: tip
|
||||
**Go 1.11+** is required for the Cosmos SDK.
|
||||
:::
|
||||
|
||||
## Install Cosmos SDK
|
||||
|
||||
Next, let's install the latest version of Gaia. Here we'll use the `master` branch, which contains the latest stable release.
|
||||
If necessary, make sure you `git checkout` the correct
|
||||
[released version](https://github.com/cosmos/cosmos-sdk/releases).
|
||||
|
||||
```bash
|
||||
mkdir -p $GOPATH/src/github.com/cosmos
|
||||
cd $GOPATH/src/github.com/cosmos
|
||||
git clone https://github.com/cosmos/cosmos-sdk
|
||||
cd cosmos-sdk && git checkout master
|
||||
make get_tools && make get_vendor_deps && make install
|
||||
```
|
||||
|
||||
> *NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed.
|
||||
|
||||
That will install the `gaiad` and `gaiacli` binaries. Verify that everything is OK:
|
||||
|
||||
```bash
|
||||
$ gaiad version
|
||||
$ gaiacli version
|
||||
```
|
||||
|
||||
## Run a Full Node
|
||||
|
||||
With the binaries installed, you can run [a full node on the latest testnet](./join-testnet.md).
|
||||
@@ -0,0 +1,135 @@
|
||||
# Join the Testnet
|
||||
|
||||
::: tip Current Testnet
|
||||
See the [testnet repo](https://github.com/cosmos/testnets) for
|
||||
information on the latest testnet, including the correct version
|
||||
of the Cosmos-SDK to use and details about the genesis file.
|
||||
:::
|
||||
|
||||
**Please ensure you have the [gaia binaries](./installation.md) installed.**
|
||||
|
||||
If you ran a full node on a previous testnet, please skip to [Upgrading From Previous Testnet](#upgrading-from-previous-testnet).
|
||||
|
||||
## Setting Up a New Node
|
||||
|
||||
These instructions are for setting up a brand new full node from scratch.
|
||||
|
||||
First, initialize the node and create the necessary config files:
|
||||
|
||||
```bash
|
||||
gaiad init
|
||||
```
|
||||
|
||||
::: warning Note
|
||||
Only ASCII characters are supported for the `--name`. Using Unicode characters will render your node unreachable.
|
||||
:::
|
||||
|
||||
You can edit this `name` later, in the `~/.gaiad/config/config.toml` file:
|
||||
|
||||
```toml
|
||||
# A custom human readable name for this node
|
||||
moniker = "<your_custom_name>"
|
||||
```
|
||||
|
||||
You can edit the `~/.gaiad/config/gaiad.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than a minimum fee:
|
||||
|
||||
```
|
||||
# This is a TOML config file.
|
||||
# For more information, see https://github.com/toml-lang/toml
|
||||
|
||||
##### main base config options #####
|
||||
|
||||
# Validators reject any tx from the mempool with less than the minimum fee per gas.
|
||||
minimum_fees = ""
|
||||
```
|
||||
|
||||
|
||||
Your full node has been initialized! Please skip to [Genesis & Seeds](#genesis-seeds).
|
||||
|
||||
## Upgrading From Previous Testnet
|
||||
|
||||
These instructions are for full nodes that have ran on previous testnets and would like to upgrade to the latest testnet.
|
||||
|
||||
### Reset Data
|
||||
|
||||
First, remove the outdated files and reset the data.
|
||||
|
||||
```bash
|
||||
rm $HOME/.gaiad/config/addrbook.json $HOME/.gaiad/config/genesis.json
|
||||
gaiad unsafe-reset-all
|
||||
```
|
||||
|
||||
Your node is now in a pristine state while keeping the original `priv_validator.json` and `config.toml`. If you had any sentry nodes or full nodes setup before,
|
||||
your node will still try to connect to them, but may fail if they haven't also
|
||||
been upgraded.
|
||||
|
||||
::: danger Warning
|
||||
Make sure that every node has a unique `priv_validator.json`. Do not copy the `priv_validator.json` from an old node to multiple new nodes. Running two nodes with the same `priv_validator.json` will cause you to double sign.
|
||||
:::
|
||||
|
||||
### Software Upgrade
|
||||
|
||||
Now it is time to upgrade the software:
|
||||
|
||||
```bash
|
||||
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
|
||||
git fetch --all && git checkout master
|
||||
make update_tools && make get_vendor_deps && make install
|
||||
```
|
||||
|
||||
::: tip
|
||||
*NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed.
|
||||
:::
|
||||
|
||||
Note we use `master` here since it contains the latest stable release.
|
||||
See the [testnet repo](https://github.com/cosmos/testnets)
|
||||
for details on which version is needed for which testnet,
|
||||
and the [SDK release page](https://github.com/cosmos/cosmos-sdk/releases)
|
||||
for details on each release.
|
||||
|
||||
Your full node has been cleanly upgraded!
|
||||
|
||||
## Genesis & Seeds
|
||||
|
||||
### Copy the Genesis File
|
||||
|
||||
Fetch the testnet's `genesis.json` file into `gaiad`'s config directory.
|
||||
|
||||
```bash
|
||||
mkdir -p $HOME/.gaiad/config
|
||||
curl https://raw.githubusercontent.com/cosmos/testnets/master/latest/genesis.json > $HOME/.gaiad/config/genesis.json
|
||||
```
|
||||
|
||||
Note we use the `latest` directory in the [testnets repo](https://github.com/cosmos/testnets)
|
||||
which contains details for the latest testnet. If you are connecting to a different testnet, ensure you get the right files.
|
||||
|
||||
### Add Seed Nodes
|
||||
|
||||
Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.gaiad/config/config.toml`. The `testnets` repo contains links to the seed nodes for each testnet. If you are looking to join the running testnet please [check the repository for details](https://github.com/cosmos/testnets) on which nodes to use.
|
||||
|
||||
If those seeds aren't working, you can find more seeds and persistent peers on the [Cosmos Explorer](https://explorer.cosmos.network/nodes). Open the the `Full Nodes` pane and select nodes that do not have private (`10.x.x.x`) or [local IP addresses](https://en.wikipedia.org/wiki/Private_network). The `Persistent Peer` field contains the connection string. For best results use 4-6.
|
||||
|
||||
You can also ask for peers on the [Validators Riot Room](https://riot.im/app/#/room/#cosmos-validators:matrix.org)
|
||||
|
||||
For more information on seeds and peers, you can [read this](https://github.com/tendermint/tendermint/blob/develop/docs/using-tendermint.md#peers).
|
||||
|
||||
## Run a Full Node
|
||||
|
||||
Start the full node with this command:
|
||||
|
||||
```bash
|
||||
gaiad start
|
||||
```
|
||||
|
||||
Check that everything is running smoothly:
|
||||
|
||||
```bash
|
||||
gaiacli status
|
||||
```
|
||||
|
||||
View the status of the network with the [Cosmos Explorer](https://explorecosmos.network). Once your full node syncs up to the current block height, you should see it appear on the [list of full nodes](https://explorecosmos.network/validators). If it doesn't show up, that's ok--the Explorer does not connect to every node.
|
||||
|
||||
|
||||
## Upgrade to Validator Node
|
||||
|
||||
You now have an active full node. What's the next step? You can upgrade your full node to become a Cosmos Validator. The top 100 validators have the ability to propose new blocks to the Cosmos Hub. Continue onto [the Validator Setup](./validators/validator-setup.md).
|
||||
@@ -0,0 +1,10 @@
|
||||
# Keys
|
||||
|
||||
See the [Tendermint specification](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/encoding.md#public-key-cryptography) for how we work with keys.
|
||||
|
||||
See `gaiacli keys --help`.
|
||||
|
||||
Also see the [testnet
|
||||
tutorial](https://github.com/cosmos/cosmos-sdk/tree/develop/cmd/gaia/testnets).
|
||||
|
||||
TODO: cleanup the UX and document this properly
|
||||
@@ -0,0 +1,29 @@
|
||||
# Ledger // Cosmos
|
||||
|
||||
### Ledger Support for account keys
|
||||
|
||||
`gaiacli` now supports derivation of account keys from a Ledger seed. To use this functionality you will need the following:
|
||||
|
||||
- A running `gaiad` instance connected to the network you wish to use.
|
||||
- A `gaiacli` instance configured to connect to your chosen `gaiad` instance.
|
||||
- A LedgerNano with the `ledger-cosmos` app installed
|
||||
* Install the Cosmos app onto your Ledger by following the instructions in the [`ledger-cosmos`](https://github.com/cosmos/ledger-cosmos/blob/master/docs/BUILD.md) repository.
|
||||
* A production-ready version of this app will soon be included in the [Ledger Apps Store](https://www.ledgerwallet.com/apps)
|
||||
|
||||
> **NOTE:** Cosmos keys are derived acording to the [BIP 44 Hierarchical Deterministic wallet spec](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). For more information on Cosmos derivation paths [see the hd package](https://github.com/cosmos/cosmos-sdk/blob/develop/crypto/keys/hd/hdpath.go#L30).
|
||||
|
||||
Once you have the Cosmos app installed on your Ledger, and the Ledger is accessible from the machine you are using `gaiacli` from you can create a new account key using the Ledger:
|
||||
|
||||
```bash
|
||||
$ gaiacli keys add {{ .Key.Name }} --ledger
|
||||
NAME: TYPE: ADDRESS: PUBKEY:
|
||||
{{ .Key.Name }} ledger cosmos1aw64xxr80lwqqdk8u2xhlrkxqaxamkr3e2g943 cosmospub1addwnpepqvhs678gh9aqrjc2tg2vezw86csnvgzqq530ujkunt5tkuc7lhjkz5mj629
|
||||
```
|
||||
|
||||
This key will only be accessible while the Ledger is plugged in and unlocked. To send some coins with this key, run the following:
|
||||
|
||||
```bash
|
||||
$ gaiacli tx send --from {{ .Key.Name }} --to {{ .Destination.AccAddr }} --chain-id=gaia-7000
|
||||
```
|
||||
|
||||
You will be asked to review and confirm the transaction on the Ledger. Once you do this you should see the result in the console! Now you can use your Ledger to manage your Atoms and Stake!
|
||||
@@ -0,0 +1,227 @@
|
||||
# Networks
|
||||
|
||||
There are a variety of ways to setup either local or remote networks with automation, detailed below.
|
||||
All the required files are found in the [networks directory](https://github.com/cosmos/cosmos-sdk/tree/develop/networks) and additionally the `local` or `remote` sub-directories.
|
||||
|
||||
## Local Testnet
|
||||
|
||||
From the [networks/local directory](https://github.com/cosmos/cosmos-sdk/tree/develop/networks/local):
|
||||
|
||||
### Requirements
|
||||
|
||||
- [Install gaia](./installation.md)
|
||||
- [Install docker](https://docs.docker.com/engine/installation/)
|
||||
- [Install docker-compose](https://docs.docker.com/compose/install/)
|
||||
|
||||
### Build
|
||||
|
||||
Build the `gaiad` binary and the `tendermint/gaiadnode` docker image.
|
||||
|
||||
Note the binary will be mounted into the container so it can be updated without
|
||||
rebuilding the image.
|
||||
|
||||
```
|
||||
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
|
||||
|
||||
# Build the linux binary in ./build
|
||||
make build-linux
|
||||
|
||||
# Build tendermint/gaiadnode image
|
||||
make build-docker-gaiadnode
|
||||
```
|
||||
|
||||
### Run a testnet
|
||||
|
||||
To start a 4 node testnet run:
|
||||
|
||||
```
|
||||
make localnet-start
|
||||
```
|
||||
|
||||
This command creates a 4-node network using the gaiadnode image.
|
||||
The ports for each node are found in this table:
|
||||
|
||||
| Node ID | P2P Port | RPC Port |
|
||||
| --------|-------|------|
|
||||
| `gaianode0` | `26656` | `26657` |
|
||||
| `gaianode1` | `26659` | `26660` |
|
||||
| `gaianode2` | `26661` | `26662` |
|
||||
| `gaianode3` | `26663` | `26664` |
|
||||
|
||||
To update the binary, just rebuild it and restart the nodes:
|
||||
|
||||
```
|
||||
make build-linux localnet-stop localnet-start
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The `make localnet-start` creates files for a 4-node testnet in `./build` by
|
||||
calling the `gaiad testnet` command. This outputs a handful of files in the
|
||||
`./build` directory:
|
||||
|
||||
```tree -L 2 build/
|
||||
build/
|
||||
├── gaiacli
|
||||
├── gaiad
|
||||
├── gentxs
|
||||
│ ├── node0.json
|
||||
│ ├── node1.json
|
||||
│ ├── node2.json
|
||||
│ └── node3.json
|
||||
├── node0
|
||||
│ ├── gaiacli
|
||||
│ │ ├── key_seed.json
|
||||
│ │ └── keys
|
||||
│ └── gaiad
|
||||
│ ├── ${LOG:-gaiad.log}
|
||||
│ ├── config
|
||||
│ └── data
|
||||
├── node1
|
||||
│ ├── gaiacli
|
||||
│ │ └── key_seed.json
|
||||
│ └── gaiad
|
||||
│ ├── ${LOG:-gaiad.log}
|
||||
│ ├── config
|
||||
│ └── data
|
||||
├── node2
|
||||
│ ├── gaiacli
|
||||
│ │ └── key_seed.json
|
||||
│ └── gaiad
|
||||
│ ├── ${LOG:-gaiad.log}
|
||||
│ ├── config
|
||||
│ └── data
|
||||
└── node3
|
||||
├── gaiacli
|
||||
│ └── key_seed.json
|
||||
└── gaiad
|
||||
├── ${LOG:-gaiad.log}
|
||||
├── config
|
||||
└── data
|
||||
```
|
||||
|
||||
Each `./build/nodeN` directory is mounted to the `/gaiad` directory in each container.
|
||||
|
||||
### Logging
|
||||
|
||||
Logs are saved under each `./build/nodeN/gaiad/gaia.log`. You can also watch logs
|
||||
directly via Docker, for example:
|
||||
|
||||
```
|
||||
docker logs -f gaiadnode0
|
||||
```
|
||||
|
||||
### Keys & Accounts
|
||||
|
||||
To interact with `gaiacli` and start querying state or creating txs, you use the
|
||||
`gaiacli` directory of any given node as your `home`, for example:
|
||||
|
||||
```shell
|
||||
gaiacli keys list --home ./build/node0/gaiacli
|
||||
```
|
||||
|
||||
Now that accounts exists, you may create new accounts and send those accounts
|
||||
funds!
|
||||
|
||||
::: tip
|
||||
**Note**: Each node's seed is located at `./build/nodeN/gaiacli/key_seed.json`.
|
||||
:::
|
||||
|
||||
### Special binaries
|
||||
|
||||
If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. For example:
|
||||
|
||||
```
|
||||
# Run with custom binary
|
||||
BINARY=gaiafoo make localnet-start
|
||||
```
|
||||
|
||||
## Remote Testnet
|
||||
|
||||
The following should be run from the [networks directory](https://github.com/cosmos/cosmos-sdk/tree/develop/networks).
|
||||
|
||||
### Terraform & Ansible
|
||||
|
||||
Automated deployments are done using [Terraform](https://www.terraform.io/) to create servers on AWS then
|
||||
[Ansible](http://www.ansible.com/) to create and manage testnets on those servers.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Install [Terraform](https://www.terraform.io/downloads.html) and [Ansible](http://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) on a Linux machine.
|
||||
- Create an [AWS API token](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) with EC2 create capability.
|
||||
- Create SSH keys
|
||||
|
||||
```
|
||||
export AWS_ACCESS_KEY_ID="2345234jk2lh4234"
|
||||
export AWS_SECRET_ACCESS_KEY="234jhkg234h52kh4g5khg34"
|
||||
export TESTNET_NAME="remotenet"
|
||||
export CLUSTER_NAME= "remotenetvalidators"
|
||||
export SSH_PRIVATE_FILE="$HOME/.ssh/id_rsa"
|
||||
export SSH_PUBLIC_FILE="$HOME/.ssh/id_rsa.pub"
|
||||
```
|
||||
|
||||
These will be used by both `terraform` and `ansible`.
|
||||
|
||||
### Create a remote network
|
||||
|
||||
```
|
||||
SERVERS=1 REGION_LIMIT=1 make validators-start
|
||||
```
|
||||
|
||||
The testnet name is what's going to be used in --chain-id, while the cluster name is the administrative tag in AWS for the servers. The code will create SERVERS amount of servers in each availability zone up to the number of REGION_LIMITs, starting at us-east-2. (us-east-1 is excluded.) The below BaSH script does the same, but sometimes it's more comfortable for input.
|
||||
|
||||
```
|
||||
./new-testnet.sh "$TESTNET_NAME" "$CLUSTER_NAME" 1 1
|
||||
```
|
||||
|
||||
### Quickly see the /status endpoint
|
||||
|
||||
```
|
||||
make validators-status
|
||||
```
|
||||
|
||||
### Delete servers
|
||||
|
||||
```
|
||||
make validators-stop
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
You can ship logs to Logz.io, an Elastic stack (Elastic search, Logstash and Kibana) service provider. You can set up your nodes to log there automatically. Create an account and get your API key from the notes on [this page](https://app.logz.io/#/dashboard/data-sources/Filebeat), then:
|
||||
|
||||
```
|
||||
yum install systemd-devel || echo "This will only work on RHEL-based systems."
|
||||
apt-get install libsystemd-dev || echo "This will only work on Debian-based systems."
|
||||
|
||||
go get github.com/mheese/journalbeat
|
||||
ansible-playbook -i inventory/digital_ocean.py -l remotenet logzio.yml -e LOGZIO_TOKEN=ABCDEFGHIJKLMNOPQRSTUVWXYZ012345
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
You can install the DataDog agent with:
|
||||
|
||||
```
|
||||
make datadog-install
|
||||
```
|
||||
|
||||
### Single-node testnet
|
||||
|
||||
To create a single node testnet:
|
||||
|
||||
```
|
||||
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
|
||||
|
||||
# Clear the build folder
|
||||
rm -rf ./build
|
||||
|
||||
# Build binary
|
||||
make build-linux
|
||||
|
||||
# Create configuration
|
||||
docker run -v `pwd`/build:/gaiad tendermint/gaiadnode testnet -o . --v 1
|
||||
|
||||
# Run the node
|
||||
docker run -v `pwd`/build:/gaiad tendermint/gaiadnode
|
||||
```
|
||||
@@ -0,0 +1,34 @@
|
||||
# Validators Overview
|
||||
|
||||
## Introduction
|
||||
|
||||
The [Cosmos Hub](/introduction/cosmos-hub.md) is based on [Tendermint](/introduction/tendermint.md), which relies on a set of validators that are responsible for committing new blocks in the blockchain. These validators participate in the consensus protocol by broadcasting votes which contain cryptographic signatures signed by each validator's private key.
|
||||
|
||||
Validator candidates can bond their own Atoms and have Atoms ["delegated"](/staking/delegators), or staked, to them by token holders. The Cosmos Hub will have 100 validators, but over time this will increase to 300 validators according to a predefined schedule. The validators are determined by who has the most stake delegated to them — the top 100 validator candidates with the most stake will become Cosmos validators.
|
||||
|
||||
Validators and their delegators will earn Atoms as block provisions and tokens as transaction fees through execution of the Tendermint consensus protocol. Initially, transaction fees will be paid in Atoms but in the future, any token in the Cosmos ecosystem will be valid as fee tender if it is whitelisted by governance. Note that validators can set commission on the fees their delegators receive as additional incentive.
|
||||
|
||||
If validators double sign, are frequently offline or do not participate in governance, their staked Atoms (including Atoms of users that delegated to them) can be slashed. The penalty depends on the severity of the violation.
|
||||
|
||||
## Hardware
|
||||
|
||||
There currently exists no appropriate cloud solution for validator key management. This may change in 2018 when cloud SGX becomes more widely available. For this reason, validators must set up a physical operation secured with restricted access. A good starting place, for example, would be co-locating in secure data centers.
|
||||
|
||||
Validators should expect to equip their datacenter location with redundant power, connectivity, and storage backups. Expect to have several redundant networking boxes for fiber, firewall and switching and then small servers with redundant hard drive and failover. Hardware can be on the low end of datacenter gear to start out with.
|
||||
|
||||
We anticipate that network requirements will be low initially. The current testnet requires minimal resources. Then bandwidth, CPU and memory requirements will rise as the network grows. Large hard drives are recommended for storing years of blockchain history.
|
||||
|
||||
## Set Up a Website
|
||||
|
||||
Set up a dedicated validator's website and signal your intention to become a validator on our [forum](https://forum.cosmos.network/t/validator-candidates-websites/127/3). This is important since delegators will want to have information about the entity they are delegating their Atoms to.
|
||||
|
||||
## Seek Legal Advice
|
||||
|
||||
Seek legal advice if you intend to run a Validator.
|
||||
|
||||
## Community
|
||||
|
||||
Discuss the finer details of being a validator on our community chat and forum:
|
||||
|
||||
* [Validator Chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org)
|
||||
* [Validator Forum](https://forum.cosmos.network/c/validating)
|
||||
@@ -0,0 +1,52 @@
|
||||
## Overview
|
||||
|
||||
Each validator candidate is encouraged to run its operations independently, as diverse setups increase the resilience of the network. Validator candidates should commence their setup phase now in order to be on time for launch.
|
||||
|
||||
## Key management - HSM
|
||||
|
||||
It is mission critical that an attacker cannot steal a validator's key. If this is possible, it puts the entire stake delegated to the compromised validator at risk. Hardware security modules are an important strategy for mitigating this risk.
|
||||
|
||||
HSM modules must support `ed25519` signatures for the hub. The YubiHSM2 supports `ed25519` and we expect to have an adapter library available in December 2017. The YubiHSM can protect a private key but cannot ensure in a secure setting that it won't sign the same block twice.
|
||||
|
||||
The Tendermint team is also working on extending our Ledger Nano S application to support validator signing. This app can store recent blocks and mitigate double signing attacks.
|
||||
|
||||
We will update this page when more key storage solutions become available.
|
||||
|
||||
## Sentry Nodes (DDOS Protection)
|
||||
|
||||
Validators are responsible for ensuring that the network can sustain denial of service attacks.
|
||||
|
||||
One recommended way to mitigate these risks is for validators to carefully structure their network topology in a so-called sentry node architecture.
|
||||
|
||||
Validator nodes should only connect to full-nodes they trust because they operate them themselves or are run by other validators they know socially. A validator node will typically run in a data center. Most data centers provide direct links the networks of major cloud providers. The validator can use those links to connect to sentry nodes in the cloud. This shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and may require new sentry nodes be spun up or activated to mitigate attacks on existing ones.
|
||||
|
||||
Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet based attacked cannot disturb them directly. This will ensure validator block proposals and votes always make it to the rest of the network.
|
||||
|
||||
To setup your sentry node architecture you can follow the instructions below:
|
||||
|
||||
Validators nodes should edit their config.toml:
|
||||
```bash
|
||||
# Comma separated list of nodes to keep persistent connections to
|
||||
# Do not add private peers to this list if you don't want them advertised
|
||||
persistent_peers =[list of sentry nodes]
|
||||
|
||||
# Set true to enable the peer-exchange reactor
|
||||
pex = false
|
||||
```
|
||||
|
||||
Sentry Nodes should edit their config.toml:
|
||||
```bash
|
||||
# Comma separated list of peer IDs to keep private (will not be gossiped to other peers)
|
||||
private_peer_ids = "ipaddress of validator nodes"
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
By default, uppercase environment variables with the following prefixes will replace lowercase command-line flags:
|
||||
|
||||
- `GA` (for Gaia flags)
|
||||
- `TM` (for Tendermint flags)
|
||||
- `BC` (for democli or basecli flags)
|
||||
|
||||
For example, the environment variable `GA_CHAIN_ID` will map to the command line flag `--chain-id`. Note that while explicit command-line flags will take precedence over environment variables, environment variables will take precedence over any of your configuration files. For this reason, it's imperative that you lock down your environment such that any critical parameters are defined as flags on the CLI or prevent modification of any environment variables.
|
||||
|
||||
@@ -0,0 +1,310 @@
|
||||
# Validator FAQ
|
||||
|
||||
::: warning Disclaimer
|
||||
This is work in progress. Mechanisms and values are susceptible to change.
|
||||
:::
|
||||
|
||||
## General Concepts
|
||||
|
||||
### What is a validator?
|
||||
|
||||
The [Cosmos Hub](/introduction/cosmos-hub.md) is based on [Tendermint](/introduction/tendermint.md), which relies on a set of [validators](/validators/overview.md) to secure the network. The role of validators is to run a full-node and participate in consensus by broadcasting votes which contain cryptographic signatures signed by their private key. Validators commit new blocks in the blockchain and receive revenue in exchange for their work. They must also participate in governance by voting on proposals. Validators are weighted according to their total stake.
|
||||
|
||||
### What is 'staking'?
|
||||
|
||||
The Cosmos Hub is a public Proof-Of-Stake (PoS) blockchain, meaning that validator's weight is determined by the amount of staking tokens (Atoms) bonded as collateral. These Atoms can be staked directly by the validator or delegated to them by Atom holders.
|
||||
|
||||
Any user in the system can declare its intention to become a validator by sending a `create-validator` transaction. From there, they become validators.
|
||||
|
||||
The weight (i.e. total stake) of a validator determines wether or not it is an active validator, and also how frequently this node will have to propose a block and how much revenue it will obtain. Initially, only the top 100 validators with the most weight will be active validators. If validators double sign, are frequently offline or do not participate in governance, their staked Atoms (including Atoms of users that delegated to them) can be destroyed, or 'slashed'.
|
||||
|
||||
### What is a full-node?
|
||||
|
||||
A full-node is a program that fully validates transactions and blocks of a blockchain. It is distinct from a light-node that only processes block headers and a small subset of transactions. Running a full-node requires more resources than a light-node but is necessary in order to be a validator. In practice, running a full-node only implies running a non-compromised and up-to-date version of the software with low network latency and without downtime.
|
||||
|
||||
Of course, it is possible and encouraged for any user to run full-nodes even if they do not plan to be validators.
|
||||
|
||||
### What is a delegator?
|
||||
|
||||
Delegators are Atom holders who cannot, or do not want to run validator operations themselves. Through [Cosmos Voyager](/getting-started/voyager.md), a user can delegate Atoms to a validator and obtain a part of its revenue in exchange (for more detail on how revenue is distributed, see **What is the incentive to stake?** and **What is a validator's commission?** sections below).
|
||||
|
||||
Because they share revenue with their validators, delegators also share responsibility. Should a validator misbehave, each of its delegators will be partially slashed in proportion to their stake. This is why delegators should perform due diligence on validators before delegating, as well as spreading their stake over multiple validators.
|
||||
|
||||
Delegators play a critical role in the system, as they are responsible for choosing validators. Being a delegator is not a passive role: Delegators should actively monitor the actions of their validators and participate in governance.
|
||||
|
||||
## Becoming a Validator
|
||||
|
||||
### How to become a validator?
|
||||
|
||||
Any participant in the network can signal that they want to become a validator by sending a `create-validator` transaction, where they must fill out the following parameters:
|
||||
|
||||
* Validator's PubKey: The private key associated with PubKey is used to sign _prevotes_ and _precommits_. This way, validators can have different accounts for validating and holding liquid funds.
|
||||
* Validator's Address: Application level address. This is the address used to identify your validator publicly. The private key associated with this address is used to bond, unbond, claim rewards, and participate in governance (in MVP only).
|
||||
* Validator's name (moniker)
|
||||
* Validator's website (Optional)
|
||||
* Validator's description (Optional)
|
||||
* Initial commission rate: The commission rate on block provisions, block rewards and fees charged to delegators
|
||||
* Maximum commission: The maximum commission rate which this validator can charge
|
||||
* Commission change rate: The maximum daily increase of the validator commission
|
||||
* Minimum self-bond amount: Minimum amount of Atoms the validator need to have bonded at all time. If the validator's self-bonded stake falls below this limit, its entire staking pool will unbond.
|
||||
* Initial self-bond amount: Initial amount of Atoms the validator wants to self-bond
|
||||
|
||||
Once a validator is created, Atom holders can delegate atoms to it, effectively adding stake to this pool. The total stake of an address is the combination of Atoms bonded by delegators and Atoms self-bonded by the entity which designated itself.
|
||||
|
||||
Out of all validators that signaled themselves, the 100 with the most stake are the ones who are designated as validators. They become **bonded validators** If a validator's total stake falls below the top 100 then that validator loses its validator privileges, it enters **unbonding mode** and, eventually, becomes **unbonded** . Over time, the maximum number of validators will increase, according to a predefined schedule:
|
||||
|
||||
* **Year 0:** 100
|
||||
* **Year 1:** 113
|
||||
* **Year 2:** 127
|
||||
* **Year 3:** 144
|
||||
* **Year 4:** 163
|
||||
* **Year 5:** 184
|
||||
* **Year 6:** 208
|
||||
* **Year 7:** 235
|
||||
* **Year 8:** 265
|
||||
* **Year 9:** 300
|
||||
* **Year 10:** 300
|
||||
|
||||
## Testnet
|
||||
|
||||
### How can I join the testnet?
|
||||
|
||||
The Testnet is a great environment to test your validator setup before launch.
|
||||
|
||||
We view testnet participation as a great way to signal to the community that you are ready and able to operate a validator. You can find all relevant information about the testnet [here](https://github.com/cosmos/cosmos-sdk/tree/develop/cmd/gaia/testnets) and [here](https://github.com/cosmos/testnets).
|
||||
|
||||
### What are the different types of keys?
|
||||
|
||||
In short, there are two types of keys:
|
||||
|
||||
* **Tendermint Key**: This is a unique key used to sign block hashes. It is associated with a public key `cosmosvalconspub`.
|
||||
* Generated when the node is created with gaiad init.
|
||||
* Get this value with `gaiad tendermint show-validator`
|
||||
e.g. `cosmosvalconspub1zcjduc3qcyj09qc03elte23zwshdx92jm6ce88fgc90rtqhjx8v0608qh5ssp0w94c`
|
||||
|
||||
* **Application keys**: These keys are created from the application and used to sign transactions. As a validator, you will probably use one key to sign staking-related transactions, and another key to sign governance-related transactions. Application keys are associated with a public key `cosmospub` and an address `cosmos`. Both are derived from account keys generated by `gaiacli keys add`.
|
||||
* Note: A validator's operator key is directly tied to an application key, but
|
||||
uses reserved prefixes solely for this purpose: `cosmosvaloper` and `cosmosvaloperpub`
|
||||
|
||||
### What are the different states a validator can be in?
|
||||
|
||||
After a validator is created with a `create-validator` transaction, it can be in three states:
|
||||
|
||||
- `bonded`: Validator is in the active set and participates in consensus. Validator is earning rewards and can be slashed for misbehaviour.
|
||||
- `unbonding`: Validator is not in the active set and does not participate in consensus. Validator is not earning rewards, but can still be slashed for misbehaviour. This is a transition state from `bonded` to `unbonded`. If validator does not send a `rebond` transaction while in `unbonding` mode, it will take three weeks for the state transition to complete.
|
||||
- `unbonded`: Validator is not in the active set, and therefore not signing blocs. Validator cannot be slashed, and does not earn any reward. It is still possible to delegate Atoms to this validator. Un-delegating from an `unbonded` validator is immediate.
|
||||
|
||||
Delegators have the same state as their validator.
|
||||
|
||||
*Note that delegation are not necessarily bonded. Atoms can be delegated and bonded, delegated and unbonding, delegated and unbonded, or liquid*
|
||||
|
||||
|
||||
### What is 'self-bond'? How can I increase my 'self-bond'?
|
||||
|
||||
### Is there a faucet?
|
||||
|
||||
If you want to obtain coins for the testnet, you can do so by using [this faucet](https://gaia.faucetcosmos.network/)
|
||||
|
||||
### Is there a minimum amount of Atoms that must be staked to be an active (=bonded) validator?
|
||||
|
||||
There is no minimum. The top 100 validators with the highest total stake (where total stake = self-bonded stake + delegators stake) are the active validators.
|
||||
|
||||
### How will delegators choose their validators?
|
||||
|
||||
Delegators are free to choose validators according to their own subjective criteria. This said, criteria anticipated to be important include:
|
||||
|
||||
* **Amount of self-bonded Atoms:** Number of Atoms a validator self-bonded to its staking pool. A validator with higher amount of self-bonded Atoms has more skin in the game, making it more liable for its actions.
|
||||
* **Amount of delegated Atoms:** Total number of Atoms delegated to a validator. A high stake shows that the community trusts this validator, but it also means that this validator is a bigger target for hackers. Indeed, hackers are incentivized to hack bigger validators as they receive a reward proportionate to the stake of the validator they can prove to have compromised. Validators are expected to become less and less attractive as their amount of delegated Atoms grows.
|
||||
* **Commission rate:** Commission applied on revenue by validators before it is distributed to their delegators
|
||||
* **Track record:** Delegators will likely look at the track record of the validators they plan to delegate to. This includes seniority, past votes on proposals, historical average uptime and how often the node was compromised.
|
||||
|
||||
Apart from these criteria that will be displayed in Cosmos Voyager, there will be a possibility for validators to signal a website address to complete their resume. Validators will need to build reputation one way or another to attract delegators. For example, it would be a good practice for validators to have their setup audited by third parties. Note though, that the Tendermint team will not approve or conduct any audit itself. For more on due diligence, see [this blog post](https://medium.com/@interchain_io/3d0faf10ce6f)
|
||||
|
||||
## Responsibilites
|
||||
|
||||
### Do validators need to be publicly identified?
|
||||
|
||||
No, they do not. Each delegator will value validators based on their own criteria. Validators will be able (and are advised) to register a website address when they nominate themselves so that they can advertise their operation as they see fit. Some delegators may prefer a website that clearly displays the team running the validator and their resume, while others might prefer anonymous validators with positive track records. Most likely both identified and anonymous validators will coexist in the validator set.
|
||||
|
||||
### What are the responsiblities of a validator?
|
||||
|
||||
Validators have two main responsibilities:
|
||||
|
||||
* **Be able to constantly run a correct version of the software:** validators need to make sure that their servers are always online and their private keys are not compromised.
|
||||
* **Actively participate in governance:** validators are required to vote on every proposal.
|
||||
|
||||
Additionally, validators are expected to be active members of the community. They should always be up-to-date with the current state of the ecosystem so that they can easily adapt to any change.
|
||||
|
||||
### What does 'participate in governance' entail?
|
||||
|
||||
Validators and delegators on the Cosmos Hub can vote on proposals to change operational parameters (such as the block gas limit), coordinate upgrades, as well as vote on amendments to the human-readable constitution that govern the Cosmos Hub.
|
||||
|
||||
Validators play a special role in the governance system. Being the pillars of the system, they are required to vote on every proposal. It is especially important since delegators who do not vote will inherit the vote of their validator. Each time a validator does not vote on a proposal, it will get slashed by a minimal amount.
|
||||
|
||||
### What does staking imply?
|
||||
|
||||
Staking Atoms can be thought of as a safety deposit on validation activities. When a validator or a delegator wants to retrieve part or all of their deposit, they send an unbonding transaction. Then, Atoms undergo a _three weeks unbonding period_ during which they are liable to being slashed for potential misbehaviors committed by the validator before the unbonding process started.
|
||||
|
||||
Validators, and by association delegators, receive block provisions, block rewards, fee rewards, and the right to participate in governance. If a validator misbehaves, a certain portion of its total stake is slashed (the severity of the penalty depends on the type of misbehavior). This means that every user that bonded Atoms to this validator gets penalized in proportion to its stake. Delegators are therefore incentivized to delegate to validators that they anticipate will function safely.
|
||||
|
||||
### Can a validator run away with its delegators' Atoms?
|
||||
|
||||
By delegating to a validator, a user delegates staking power. The more staking power a validator has, the more weight it has in the consensus and governance processes. This does not mean that the validator has custody of its delegators' Atoms. _By no means can a validator run away with its delegator's funds_.
|
||||
|
||||
Even though delegated funds cannot be stolen by their validators, delegators are still liable if their validators misbehave. In such case, each delegators' stake will be partially slashed in proportion to their relative stake.
|
||||
|
||||
### How often will a validator be chosen to propose the next block? Does it go up with the quantity of Atoms staked?
|
||||
|
||||
The validator that is selected to propose the next block is called proposer. Each proposer is selected deterministically, and the frequency of being chosen is equal to the relative total stake (where total stake = self-bonded stake + delegators stake) of the validator. For example, if the total bonded stake across all validators is 100 Atoms and a validator's total stake is 10 Atoms, then this validator will be chosen 10% of the time as the next proposer.
|
||||
|
||||
### Will validators of the Cosmos Hub ever be required to validate other zones in the Cosmos ecosystem?
|
||||
|
||||
Yes, they will. Initially, validators of the Cosmos hub will also validate the first public Ethermint zone. If governance decides so, validators of the Cosmos hub may be required to validate additional zones in the Cosmos ecosystem. As the case with the Ethermint Zone, for each additional zone compensation is to be provided in the form of block rewards and transaction fees.
|
||||
|
||||
## Incentives
|
||||
|
||||
### What is the incentive to stake?
|
||||
|
||||
Each member of a validator's staking pool earns different types of revenue:
|
||||
|
||||
* **Block provisions:** Native tokens of applications run by validators (e.g. Atoms on the Cosmos Hub) are inflated to produce block provisions. These provisions exist to incentivize Atom holders to bond their stake, as non-bonded Atom will be diluted over time.
|
||||
* **Block rewards:** For the Ethermint zone, block rewards are paid in Photons. Initial distribution of Photons will be hard spooned from Ethereum. This means Photons will be emitted 1:1 to Ether.
|
||||
* **Transaction fees:** The Cosmos Hub maintains a whitelist of token that are accepted as fee payment.
|
||||
|
||||
This total revenue is divided among validators' staking pools according to each validator's weight. Then, within each validator's staking pool the revenue is divided among delegators in proportion to each delegator's stake. Note that a commission on delegators' revenue is applied by the validator before it is distributed.
|
||||
|
||||
### What is the incentive to run a validator ?
|
||||
|
||||
Validators earn proportionally more revenue than their delegators because of commissions.
|
||||
|
||||
Validators also play a major role in governance. If a delegator does not vote, it inherits the vote from its validator. This gives validators a major responsibility in the ecosystem.
|
||||
|
||||
### What is a validator's commission?
|
||||
|
||||
Revenue received by a validator's pool is split between the validator and its delegators. The validator can apply a commission on the part of the revenue that goes to its delegators. This commission is set as a percentage. Each validator is free to set its initial commission, maximum daily commission change rate and maximum commission. The Cosmos Hub enforces the parameter that each validator sets. These parameters can only be defined when initially declaring candidacy, and may only be constrained further after being declared.
|
||||
|
||||
### How are block provisions distributed?
|
||||
|
||||
Block provisions are distributed proportionally to all validators relative to their total stake. This means that even though each validator gains atoms with each provision, all validators will still maintain equal weight.
|
||||
|
||||
Let us take an example where we have 10 validators with equal staking power and a commission rate of 1%. Let us also assume that the provision for a block is 1000 Atoms and that each validator has 20% of self-bonded Atoms. These tokens do not go directly to the proposer. Instead, they are evenly spread among validators. So now each validator's pool has 100 Atoms. These 100 Atoms will be distributed according to each participant's stake:
|
||||
|
||||
* Commission: `100*80%*1% = 0.8 Atoms`
|
||||
* Validator gets: `100\*20% + Commission = 20.8 Atoms`
|
||||
* All delegators get: `100\*80% - Commission = 79.2 Atoms`
|
||||
|
||||
Then, each delegator can claim its part of the 79.2 Atoms in proportion to their stake in the validator's staking pool. Note that the validator's commission is not applied on block provisions. Note that block rewards (paid in Photons) are distributed according to the same mechanism.
|
||||
|
||||
### How are fees distributed?
|
||||
|
||||
Fees are similarly distributed with the exception that the block proposer can get a bonus on the fees of the block it proposes if it includes more than the strict minimum of required precommits.
|
||||
|
||||
When a validator is selected to propose the next block, it must include at least 2/3 precommits for the previous block in the form of validator signatures. However, there is an incentive to include more than 2/3 precommits in the form of a bonus. The bonus is linear: it ranges from 1% if the proposer includes 2/3rd precommits (minimum for the block to be valid) to 5% if the proposer includes 100% precommits. Of course the proposer should not wait too long or other validators may timeout and move on to the next proposer. As such, validators have to find a balance between wait-time to get the most signatures and risk of losing out on proposing the next block. This mechanism aims to incentivize non-empty block proposals, better networking between validators as well as to mitigate censorship.
|
||||
|
||||
Let's take a concrete example to illustrate the aforementioned concept. In this example, there are 10 validators with equal stake. Each of them applies a 1% commission and has 20% of self-bonded Atoms. Now comes a successful block that collects a total of 1025.51020408 Atoms in fees.
|
||||
|
||||
First, a 2% tax is applied. The corresponding Atoms go to the reserve pool. Reserve pool's funds can be allocated through governance to fund bounties and upgrades.
|
||||
|
||||
* `2% \* 1025.51020408 = 20.51020408` Atoms go to the reserve pool.
|
||||
|
||||
1005 Atoms now remain. Let's assume that the proposer included 100% of the signatures in its block. It thus obtains the full bonus of 5%.
|
||||
|
||||
We have to solve this simple equation to find the reward R for each validator:
|
||||
|
||||
`9*R + R + R*5% = 1005 ⇔ R = 1005/10.05 = 100`
|
||||
|
||||
* For the proposer validator:
|
||||
* The pool obtains `R + R * 5%`: 105 Atoms
|
||||
* Commission: `105 * 80% * 1%` = 0.84 Atoms
|
||||
* Validator's reward: `105 * 20% + Commission` = 21.84 Atoms
|
||||
* Delegators' rewards: `105 * 80% - Commission` = 83.16 Atoms (each delegator will be able to claim its portion of these rewards in proportion to their stake)
|
||||
* For each non-proposer validator:
|
||||
* The pool obtains R: 100 Atoms
|
||||
* Commission: `100 * 80% * 1%` = 0.8 Atoms
|
||||
* Validator's reward: `100 * 20% + Commission` = 20.8 Atoms
|
||||
* Delegators' rewards: `100 * 80% - Commission` = 79.2 Atoms (each delegator will be able to claim its portion of these rewards in proportion to their stake)
|
||||
|
||||
### What are the slashing conditions?
|
||||
|
||||
If a validator misbehaves, its bonded stake along with its delegators' stake and will be slashed. The severity of the punishment depends on the type of fault. There are 3 main faults that can result in slashing of funds for a validator and its delegators:
|
||||
|
||||
* **Double signing:** If someone reports on chain A that a validator signed two blocks at the same height on chain A and chain B, this validator will get slashed on chain A
|
||||
* **Unavailability:** If a validator's signature has not been included in the last X blocks, the validator will get slashed by a marginal amount proportional to X. If X is above a certain limit Y, then the validator will get unbonded
|
||||
* **Non-voting:** If a validator did not vote on a proposal, its stake will receive a minor slash.
|
||||
|
||||
Note that even if a validator does not intentionally misbehave, it can still be slashed if its node crashes, looses connectivity, gets DDOSed, or if its private key is compromised.
|
||||
|
||||
### Do validators need to self-bond Atoms?
|
||||
|
||||
No, they do not. A validators total stake is equal to the sum of its own self-bonded stake and of its delegated stake. This means that a validator can compensate its low amount of self-bonded stake by attracting more delegators. This is why reputation is very important for validators.
|
||||
|
||||
Even though there is no obligation for validators to self-bond Atoms, delegators should want their validator to have self-bonded Atoms in their staking pool. In other words, validators should have skin in the game.
|
||||
|
||||
In order for delegators to have some guarantee about how much skin-in-the-game their validator has, the latter can signal a minimum amount of self-bonded Atoms. If a validator's self-bond goes below the limit that it predefined, this validator and all of its delegators will unbond.
|
||||
|
||||
### How to prevent concentration of stake in the hands of a few top validators?
|
||||
|
||||
For now the community is expected to behave in a smart and self-preserving way. When a mining pool in Bitcoin gets too much mining power the community usually stops contributing to that pool. The Cosmos Hub will rely on the same effect initially. In the future, other mechanisms will be deployed to smoothen this process as much as possible:
|
||||
|
||||
* **Penalty-free re-delegation:** This is to allow delegators to easily switch from one validator to another, in order to reduce validator stickiness.
|
||||
* **Hack bounty:** This is an incentive for the community to hack validators. There will be bounties proportionate to the size of the validator, so that a validator becomes a bigger target as its stake grows.
|
||||
* **UI warning:** Users will be warned by Cosmos Voyager if they want to delegate to a validator that already has a significant amount of staking power.
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### What are hardware requirements?
|
||||
|
||||
Validators should expect to provision one or more data center locations with redundant power, networking, firewalls, HSMs and servers.
|
||||
|
||||
We expect that a modest level of hardware specifications will be needed initially and that they might rise as network use increases. Participating in the testnet is the best way to learn more.
|
||||
|
||||
### What are software requirements?
|
||||
|
||||
In addition to running a Cosmos Hub node, validators should develop monitoring, alerting and management solutions.
|
||||
|
||||
### What are bandwidth requirements?
|
||||
|
||||
The Cosmos network has the capacity for very high throughput relative to chains like Ethereum or Bitcoin.
|
||||
|
||||
We recommend that the data center nodes only connect to trusted full-nodes in the cloud or other validators that know each other socially. This relieves the data center node from the burden of mitigating denial-of-service attacks.
|
||||
|
||||
Ultimately, as the network becomes more heavily used, multigigabyte per day bandwidth is very realistic.
|
||||
|
||||
### What does running a validator imply in terms of logistics?
|
||||
|
||||
A successful validator operation will require the efforts of multiple highly skilled individuals and continuous operational attention. This will be considerably more involved than running a bitcoin miner for instance.
|
||||
|
||||
### How to handle key management?
|
||||
|
||||
Validators should expect to run an HSM that supports ed25519 keys. Here are potential options:
|
||||
|
||||
* YubiHSM 2
|
||||
* Ledger Nano S
|
||||
* Ledger BOLOS SGX enclave
|
||||
* Thales nShield support
|
||||
|
||||
The Tendermint team does not recommend one solution above the other. The community is encouraged to bolster the effort to improve HSMs and the security of key management.
|
||||
|
||||
### What can validators expect in terms of operations?
|
||||
|
||||
Running effective operation is the key to avoiding unexpectedly unbonding or being slashed. This includes being able to respond to attacks, outages, as well as to maintain security and isolation in your data center.
|
||||
|
||||
### What are the maintenance requirements?
|
||||
|
||||
Validators should expect to perform regular software updates to accommodate upgrades and bug fixes. There will inevitably be issues with the network early in its bootstrapping phase that will require substantial vigilance.
|
||||
|
||||
### How can validators protect themselves from denial-of-service attacks?
|
||||
|
||||
Denial-of-service attacks occur when an attacker sends a flood of internet traffic to an IP address to prevent the server at the IP address from connecting to the internet.
|
||||
|
||||
An attacker scans the network, tries to learn the IP address of various validator nodes and disconnect them from communication by flooding them with traffic.
|
||||
|
||||
One recommended way to mitigate these risks is for validators to carefully structure their network topology in a so-called sentry node architecture.
|
||||
|
||||
Validator nodes should only connect to full-nodes they trust because they operate them themselves or are run by other validators they know socially. A validator node will typically run in a data center. Most data centers provide direct links the networks of major cloud providers. The validator can use those links to connect to sentry nodes in the cloud. This shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and may require new sentry nodes be spun up or activated to mitigate attacks on existing ones.
|
||||
|
||||
Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet based attacked cannot disturb them directly. This will ensure validator block proposals and votes always make it to the rest of the network.
|
||||
|
||||
It is expected that good operating procedures on that part of validators will completely mitigate these threats.
|
||||
|
||||
For more on sentry node architecture, see [this](https://forum.cosmos.network/t/sentry-node-architecture-overview/454).
|
||||
@@ -0,0 +1,167 @@
|
||||
# Validator Setup
|
||||
|
||||
::: tip
|
||||
Information on how to join the current testnet (`genesis.json` file and seeds) is held [in our `testnet` repo](https://github.com/cosmos/testnets/tree/master/latest). Please check there if you are looking to join our latest testnet.
|
||||
:::
|
||||
|
||||
Before setting up your validator node, make sure you've already gone through the [Full Node Setup](/docs/getting-started/full-node.md) guide.
|
||||
|
||||
## Running a Validator Node
|
||||
|
||||
[Validators](/validators/overview.md) are responsible for committing new blocks to the blockchain through voting. A validator's stake is slashed if they become unavailable or sign blocks at the same height. Please read about [Sentry Node Architecture](/validators/validator-faq.md#how-can-validators-protect-themselves-from-denial-of-service-attacks) to protect your node from DDOS attacks and to ensure high-availability.
|
||||
|
||||
::: danger Warning
|
||||
If you want to become a validator for the Hub's `mainnet`, you should [research security](/validators/security.md).
|
||||
:::
|
||||
|
||||
### Create Your Validator
|
||||
|
||||
Your `cosmosvalconspub` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
|
||||
|
||||
```bash
|
||||
gaiad tendermint show-validator
|
||||
```
|
||||
|
||||
Next, craft your `gaiacli tx stake create-validator` command:
|
||||
|
||||
::: warning Note
|
||||
Don't use more `steak` thank you have! You can always get more by using the [Faucet](https://faucetcosmos.network/)!
|
||||
:::
|
||||
|
||||
```bash
|
||||
gaiacli tx stake create-validator \
|
||||
--amount=5steak \
|
||||
--pubkey=$(gaiad tendermint show-validator) \
|
||||
--moniker="choose a moniker" \
|
||||
--chain-id=<chain_id> \
|
||||
--from=<key_name> \
|
||||
--commission-rate="0.10" \
|
||||
--commission-max-rate="0.20" \
|
||||
--commission-max-change-rate="0.01"
|
||||
```
|
||||
|
||||
__Note__: When specifying commission parameters, the `commission-max-change-rate`
|
||||
is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is
|
||||
a 100% rate increase, but only 1 percentage point.
|
||||
|
||||
::: tip
|
||||
Use `gaiacli tx stake create-validator -h` to get a list of all the available flags.
|
||||
:::
|
||||
|
||||
### Edit Validator Description
|
||||
|
||||
You can edit your validator's public description. This info is to identify your validator, and will be relied on by delegators to decide which validators to stake to. Make sure to provide input for every flag below, otherwise the field will default to empty (`--moniker` defaults to the machine name).
|
||||
|
||||
The `--identity` can be used as to verify identity with systems like Keybase or UPort. When using with Keybase `--identity` should be populated with a 16-digit string that is generated with a [keybase.io](https://keybase.io) account. It's a cryptographically secure method of verifying your identity across multiple online networks. The Keybase API allows us to retrieve your Keybase avatar. This is how you can add a logo to your validator profile.
|
||||
|
||||
```bash
|
||||
gaiacli tx stake edit-validator
|
||||
--moniker="choose a moniker" \
|
||||
--website="https://cosmos.network" \
|
||||
--identity=6A0D65E29A4CBC8E \
|
||||
--details="To infinity and beyond!" \
|
||||
--chain-id=<chain_id> \
|
||||
--from=<key_name> \
|
||||
--commission-rate="0.10"
|
||||
```
|
||||
|
||||
__Note__: The `commission-rate` value must adhere to the following invariants:
|
||||
|
||||
- Must be between 0 and the validator's `commission-max-rate`
|
||||
- Must not exceed the validator's `commission-max-change-rate` which is maximum
|
||||
% point change rate **per day**. In other words, a validator can only change
|
||||
its commission once per day and within `commission-max-change-rate` bounds.
|
||||
|
||||
### View Validator Description
|
||||
|
||||
View the validator's information with this command:
|
||||
|
||||
```bash
|
||||
gaiacli query stake validator <account_cosmos>
|
||||
```
|
||||
|
||||
### 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 query slashing signing-info <validator-pubkey>\
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
### Unjail Validator
|
||||
|
||||
When a validator is "jailed" for downtime, you must submit an `Unjail` transaction from the operator account in order to be able to get block proposer rewards again (depends on the zone fee distribution).
|
||||
|
||||
```bash
|
||||
gaiacli tx slashing unjail \
|
||||
--from=<key_name> \
|
||||
--chain-id=<chain_id>
|
||||
```
|
||||
|
||||
### Confirm Your Validator is Running
|
||||
|
||||
Your validator is active if the following command returns anything:
|
||||
|
||||
```bash
|
||||
gaiacli query tendermint-validator-set | grep "$(gaiad tendermint show-validator)"
|
||||
```
|
||||
|
||||
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.
|
||||
:::
|
||||
|
||||
## Common Problems
|
||||
|
||||
### Problem #1: My validator has `voting_power: 0`
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
gaiad start
|
||||
```
|
||||
|
||||
Wait for your full node to catch up to the latest block. Next, run the following command. Note that `<cosmos>` 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 tx slashing unjail <cosmos> --chain-id=<chain_id> --from=<from>
|
||||
```
|
||||
|
||||
::: danger Warning
|
||||
If you don't wait for `gaiad` to sync before running `unjail`, you will receive an error message telling you your validator is still jailed.
|
||||
:::
|
||||
|
||||
Lastly, check your validator again to see if your voting power is back.
|
||||
|
||||
```bash
|
||||
gaiacli status
|
||||
```
|
||||
|
||||
You may notice that your voting power is less than it used to be. That's because you got slashed for downtime!
|
||||
|
||||
### Problem #2: My `gaiad` crashes because of `too many open files`
|
||||
|
||||
The default number of files Linux can open (per-process) is `1024`. `gaiad` is known to open more than `1024` files. This causes the process to crash. A quick fix is to run `ulimit -n 4096` (increase the number of open files allowed) and then restart the process with `gaiad start`. If you are using `systemd` or another process manager to launch `gaiad` this may require some configuration at that level. A sample `systemd` file to fix this issue is below:
|
||||
|
||||
```toml
|
||||
# /etc/systemd/system/gaiad.service
|
||||
[Unit]
|
||||
Description=Cosmos Gaia Node
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=ubuntu
|
||||
WorkingDirectory=/home/ubuntu
|
||||
ExecStart=/home/ubuntu/go/bin/gaiad start
|
||||
Restart=on-failure
|
||||
RestartSec=3
|
||||
LimitNOFILE=4096
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
Reference in New Issue
Block a user